ContourDynamics.jl

Appearance

ContourDynamics.jlLagrangian Vortex Patch Simulations

Track vortex boundaries, not grid points — contour dynamics and surgery for 2D Euler, SQG, QG, and N-layer quasi-geostrophic flows in Julia

Get Started
Theory & Method
API Reference
View on GitHub
🌀

2D Euler, SQG & QG Kernels

Exact log(r) antiderivative for Euler. Regularized 1/r with arcsinh antiderivative for SQG. K₀(r/Ld) with singular subtraction and 5-point Gauss-Legendre for QG. N-layer coupling via eigenmode decomposition — all without numerical diffusion.

Learn the math

✂️

Contour Surgery

Full Dritschel algorithm — adaptive node redistribution, automated reconnection (merge & split) via spatial indexing, and filament removal for arbitrarily long integrations.

Try a tutorial

🔁

Doubly-Periodic Domains

Ewald summation with precomputed Fourier coefficients, lazy thread-safe caching, and automatic node wrapping. Supports beta-plane PV staircases for geophysical applications.

See periodic example

📊

Analytical Diagnostics

Energy, enstrophy, circulation, angular momentum, and ellipse moments computed directly from contour geometry via Green's theorem — no interpolation, no gridding.

View diagnostics API

🔌

Ecosystem Integration

Package extensions for DifferentialEquations.jl, Makie.jl, RecordedArrays.jl, and JLD2.jl — plug into the broader Julia ecosystem.

⚡

High Performance

StaticArrays for node positions, multi-threaded velocity and energy computation, O(log C) spatial indexing for surgery, and zero-allocation time stepping.

🚀

GPU Acceleration

Pass dev=GPU() to offload velocity computations to an NVIDIA GPU via CUDA.jl. Surgery and diagnostics continue on CPU — no code changes required beyond the constructor arguments.

Try a tutorial

Quick Start ​

julia
using ContourDynamics

# Create a circular vortex patch and set up the problem
prob = Problem(; contours=[circular_patch(1.0, 128, 2π)], dt=0.01)

# Evolve with RK4 + surgery
evolve!(prob; nsteps=1000)

# Check conserved quantities
println("Energy: $(energy(prob))")
println("Circulation: $(circulation(prob))")

GPU Acceleration

Pass dev=:gpu to run velocity computations on an NVIDIA GPU:

julia
using CUDA
prob = Problem(; contours=[circular_patch(1.0, 128, 2π)], dt=0.01, dev=:gpu)

See the tutorial for details.

Installation ​

julia
using Pkg
Pkg.add("ContourDynamics")

Requires Julia 1.10 or later.

What is Contour Dynamics? ​

Contour dynamics is a Lagrangian numerical method for simulating inviscid, incompressible vortex flows. Instead of solving the vorticity equation on a grid, the method tracks the boundaries of uniform potential vorticity (PV) patches.

The key idea: for piecewise-constant PV distributions, the velocity at any point can be written as a boundary integral over the contour edges:

u(x)=∑jqj2π∮CjG(|x−x′|)×dx′

where G is the Green's function (−log⁡r for 2D Euler, −1/r for SQG, K0(r/Ld) for QG). Each segment integral is computed analytically (Euler, SQG) or with high-order quadrature (QG), so the method introduces no numerical diffusion.

Contour surgery (Dritschel, 1988) extends this to long-time integrations by automatically handling topological changes — vortex mergers, contour splitting, and filament removal — that would otherwise cause the contour to develop unresolvable complexity.

When to use contour dynamics ​

Contour dynamics is ideal when:

  • You need sharp PV-interface advection without grid-scale numerical diffusion

  • The flow is well-described by piecewise-constant PV (vortex patches, PV staircases)

  • You want to study vortex mergers, filamentation, and long-time dynamics

  • You're working in 2D Euler, SQG, or quasi-geostrophic settings

It is less suitable for smooth PV distributions (use spectral/pseudospectral methods) or 3D flows.