← Vector field tour
LESSON D · RUNNABLE BASELINEToward shallow water

A first ripple · a periodic plane · visible conservation checks

Start with a ripple
you can account for.

Drop a small height pulse into a shallow layer. Gravity pulls the surface back toward level, horizontal motion carries the disturbance outward, and the two effects trade energy. This intentionally small model lets us watch that exchange before adding coastlines, curved geometry, nonlinear transport, or Clebsch variables.

BASELINE EQUATIONS uⁿ⁺¹ = uⁿ − Δt g G hⁿ hⁿ⁺¹ = hⁿ − Δt H D uⁿ⁺¹ qⁿ⁺¹(x) = qⁿ(x − Δt u) diagnostic only

D = −Gᵀ under the uniform vertex mass. The adjointness defect below tests the implementation rather than asking you to trust the notation.

Why ocean modelers begin here

The ocean is deep to us, but thin compared with a planet.

When the vertical scale is small relative to the horizontal scale, depth-averaged equations capture long waves and large horizontal currents without resolving the full three-dimensional water column.

WAVESHeight and velocity talk to each other.

A raised surface creates a pressure gradient; the resulting flow redistributes the water.

CURRENTSDivergence becomes physical.

Convergence piles water up and divergence draws it down, so incompressible projection would erase the mechanism we want to study.

SURFACESThe same story can live on curved geometry.

A later solver replaces this periodic square by a surface mesh and adds metric, topology, boundaries, rotation, and bathymetry carefully.

In this lab: linear gravity waves on a flat periodic domain. The dye and seeded vortex are visual diagnostics, not a claim of complete ocean physics.

RUNNING NOWh at vertices + u in vertex tangent framesphysical = { h, u } · diagnostic = { q }

Directly visual and continuous with the integrability lessons. Pressure adds a gradient, so initially irrotational velocity stays curl-free.

→
DERIVED, NEVER HIDDENα on oriented edgesαᵢⱼ = ½(uᵢ + uⱼ) · eᵢⱼ

Use this transfer for flux and circulation audits. It is a representation map, not a claim that vertex vectors are already 1-forms.

→
RESEARCH BRANCHvorticity ζ + divergence δ (or streamfunction ψ)ζ = curl u · n

A vorticity-based formulation exposes rotational modes and global harmonic content differently. The “seed vortex” button makes the missing mode visible before students replace the state.

LIVE STATEheight perturbation + vertex velocity
CFL —
time0
mass drift—
energy—
curl RMS—
G/D adjoint defect—
DIAGNOSTIC HISTORYcyan = energy · pink = |mass drift|
WHEN THE RIPPLE IS TRUSTWORTHY

Change the description without losing the story.

A vorticity/divergence, streamfunction, or Clebsch state should still reconstruct velocity, preserve global harmonic modes, and provide the edge flux used by continuity. Keep the same manufactured tests while swapping only the representation in the middle.

  1. A
    Replace the state.

    Store ζ and δ (or ψ), plus the two harmonic periods on a torus.

  2. B
    Reconstruct u.

    Use the Hodge split and report the residual and gauge conditions.

  3. C
    Reuse the contracts.

    Mass drift, energy, curl, adjointness, and edge flux must still be visible.