A periodic plane · three redundant labels · one moving layer

Carry a coordinate frame with the water.
Rechart it before it folds away.

A single Clebsch pair can locally encode a velocity, but its two transported scalar contours may squeeze together or become too fine for a grid. This version instead carries three ambient-coordinate labels and three conjugate weights. The redundancy lets us change the chart while preserving the visible velocity.

Wander into the live grid ↓

THE REPRESENTATION

u^\flat=d\phi+\sum_{a=1}^{3}\lambda_a\,dB^a

u=(u^\flat)^\sharp

Here B = (X,Y,Z). On a triangle mesh these are initially the three coordinates of each vertex. On this periodic square we use the coordinates of a standard embedded torus, so no label jumps across a seam.

HEIGHT / DENSITYh(x,y,t)

Water column carried by the flux hu. Pressure comes from its gradient.

BERNOULLI POTENTIALφ(x,y,t)

Its differential dφ supplies the exact, curl-free part of the velocity one-form.

THREE LABEL WEIGHTSλ(x,y,t) ∈ ℝ³

Three transported coefficients weight the differentials of the ambient labels.

THREE MATERIAL LABELSB(x,y,t) ∈ ℝ³

Initially vertex XYZ. Their level sets move with the water until we deliberately rechart.

Why combine these ideas?

Shallow water gives the labels a physical job to do.

The random-field playground can show Clebsch assembly and pressure projection without choosing a time evolution. Here the labels travel with an actual layer: velocity moves them, height changes under mass flux, and the Bernoulli potential responds to gravity.

FOR OCEAN-LIKE FLOWSMaterial structure matters.

Vorticity and tracers can persist as water moves over long distances; a label-based state makes that material viewpoint explicit.

FOR CURVED SURFACESThe representation separates roles.

One-forms measure circulation, vectors move parcels, and the metric converts between them—useful bookkeeping before moving from a plane to a sphere or mesh.

FOR PERIODIC OR HOLED DOMAINSLocal labels are not the whole state.

Global harmonic periods still have to be stored or evolved. This flat example sets them to zero so the local transport can be read first.

THE IMPORTANT CHANGE OF PROBLEM

Do not project shallow water to zero divergence.

In the random-flow lab, subtracting $dp$ is a useful incompressible comparison. In shallow water, convergence and divergence are physical: they raise and lower the water column. Pressure acts through the evolution of φ while the continuity equation evolves h.

\partial_t h+\operatorname{div}(hu)=0

D_t\phi=\tfrac12|u|^2-g(h-H)

On a torus, the velocity state may also carry two harmonic periods. This planar lab sets them to zero; a topology-aware solver must retain and audit them separately.

THE NUMERICAL REPAIR

Rechart the representation, not the fluid.

Transport eventually distorts any finite-resolution label grid. At a rechart time, the solver first saves the current one-form, resets B to the ambient XYZ coordinate functions, and solves for new weights λ. Height, material dye, and physical time do not reset.

r=u^\flat-d\phi,\qquad B\leftarrow(X,Y,Z)

\lambda=\arg\min_{\tilde\lambda}\|\tilde\lambda\|^2\quad\text{s.t.}\quad\sum_a\tilde\lambda_a\,dB^a=r

The “rechart defect” below is the relative RMS change in velocity caused by this discrete solve. It should remain near machine precision immediately after a reset. This is a gauge change, not a pressure projection and not remeshing.

What this prototype actually claims

A readable numerical experiment, not yet a production surface solver.

The lab couples a conservative periodic height update to semi-Lagrangian Clebsch transport. It is useful for seeing the variables and the recharting problem. It should not be read as evidence that all of the geometric and conservation issues are finished.

IMPLEMENTED HEREA periodic shallow-water layer.

Height obeys a conservative face-flux update. The Clebsch labels and dye follow the reconstructed velocity, φ receives the pressure term, and mass and representation defects are measured.

DELIBERATELY OMITTEDThe hard surface cases.

No curved triangle mesh, bathymetry, Coriolis force, wet/dry front, shock treatment, viscosity, or nonzero harmonic circulation appears in this square experiment.

FUTURE SOLVER WORKPreserve more than a picture.

A serious mesh version needs DEC/FEM mass matrices, a coupled conservative time integrator, topology-aware harmonic state, robust chart resets, and benchmark tests for energy, potential vorticity, and Kelvin circulation.

How to read the grid

01
Begin with one B channel.
X, Y, and Z are ordinary scalar fields. Use the channel buttons to see the three components of the redundant label map.
02
Assemble the label one-form.
The three pieces add: $\lambda_XdB^X+\lambda_YdB^Y+\lambda_ZdB^Z$ .
03
Follow, then reset, the chart.
Play long enough to distort the labels. “Rechart now” restores ambient XYZ while retaining the reconstructed velocity.
04
Compare the fragile pair.
Switch to “single α,β pair” to see what was previously doing too many jobs at once.

So which things are vectors?

u and the mass flux hu are vectors. The displayed bars visualize the covectors dφ and ΣλₐdBᵃ. Each Bᵃ and λₐ is still a scalar field; the three-component bookkeeping index is not a tangent-vector index.

Why draw a covector as bars?

A covector assigns a number to every test displacement. Its kernel is the line of displacements on which that number is zero. Parallel bars make that kernel visible; their normal points in the measuring direction.

Does XYZ mean the velocity lives in ℝ³?

No. The label map uses three ambient scalar functions, but each differential is restricted to the two-dimensional tangent plane. The reconstructed one-form is tangent. On a mesh, discrete gradients of vertex XYZ supply a redundant spanning frame on each face.

What is still omitted?

This periodic example fixes both harmonic circulations to zero. Vorticity cannot reconstruct those two torus periods; a complete torus solver must store or evolve them. A real surface solver also needs mesh mass matrices, intrinsic gradient/divergence operators, tangent transport, and conservative wet/dry handling.

LIVE PERIODIC GRIDheight h − H with no glyphs

ready

Color is Eulerian height.It is a water-column value at each fixed cell, not paint glued to a parcel.

Arrows are optional grid samples.Their anchors stay fixed while their direction and length change; they are not particles.

Dye is the material view.Select dye to watch a scalar carried by the reconstructed velocity.

LABEL CHANNEL

FIXED-GRID GLYPHS

Uncluttered scalar view. Choose a glyph layer to sample vectors or covectors on the fixed grid.

time0

mass drift—

energy—

divergence RMS—

vorticity RMS—

ζ − curl(label term)—

recharts—

last velocity defect—

label-frame quality—

STATE FIELD SLICESλ and B show the selected X/Y/Z channel.

Initial state

Representation

Resolutionperiodic cells per direction56 × 56 Time stepsemi-Lagrangian material update0.0015 Gravity gheight-pressure strength9.81 Mean depth Hreference water column1.00 Clebsch strengthinitial rotational label term0.16 Rechart interval0 disables automatic chart resets180 steps

POINT PROBE · CLICK THE GRIDx = 0.62 · y = 0.54

h—

λ vector—

B vector—

ζ/h—

u^\flat(\delta x)=u_x\,\delta x^x+u_y\,\delta x^y

—

Test displacement δxrotate the vector fed to the covector25°

Choose a point to inspect the exact and label pieces.

The careful version

Scalar channels → one-form → vector → transport → rechart.

Clebsch notation is compact because it suppresses both type conversions and representation choices. Expand them, and the numerical reason for three channels becomes much less mysterious.

0-FORMS · SCALARS

φ, λ₁…λ₃, B¹…B³, h

Each channel assigns one number to every grid point. The three-component label index is separate from the surface tangent coordinates.

φ(x,y), λₐ(x,y), Bᵃ(x,y), h(x,y)

take d

1-FORMS · COVECTORS

dφ + ΣλₐdBᵃ

Each dBᵃ measures a tangent displacement. The weighted sum is one surface one-form.

u♭(δx) ∈ ℝ

raise ♯

VECTORS

u

The metric turns the measuring one-form into the arrow that transports water and labels.

ẋ = u(x,t)

WHERE DOES ROTATION COME FROM?

The crossing of two scalar foliations.

d u^\flat=\sum_{a=1}^{3}d\lambda_a\wedge dB^a

The exact piece disappears because $d^2\phi=0$ . Each channel contributes a two-form; on an oriented surface this can also be displayed as a signed scalar density or a normal pseudovector.

VECTOR VS. COVECTOR

Same two numbers here; different jobs.

vector u

Consumes time and produces displacement.

covector u♭

Consumes displacement and produces a number.

In Cartesian coordinates with the identity metric, $u_i=\delta_{ij}u^j$ copies the components. On a curved or stretched mesh, the metric changes them.

THE SHALLOW-WATER SYSTEM IN GENERALIZED CLEBSCH VARIABLES

The labels move; height compresses; φ pays the Bernoulli bill.

$D_t=\partial_t+u\cdot\nabla$ . The lab semi-Lagrangian-advects all three B and λ channels, advances h with conservative periodic face fluxes, and evolves φ by a Bernoulli equation. Weak filtering handles unresolved grid scales; recharting separately repairs a distorted representation while auditing the velocity it preserves.

$D_t\lambda_a=0,\qquad D_tB^a=0$
Between rechart events, all six scalar channels move with the parcels.
$D_t\phi=\tfrac12|u|^2-g(h-H)$
Kinetic and pressure terms update the exact potential.
$\partial_t h+\nabla\cdot(hu)=0$
Height is a density, so it changes under compression.
$u=\left(d\phi+\sum_a\lambda_a dB^a\right)^\sharp$
The one-form is rebuilt from the exact part and redundant label frame.
$B\leftarrow X,\quad \lambda\leftarrow(dX)^{+}(u^\flat-d\phi)$
Reset the labels to ambient coordinates and refit only their weights.

Carry a coordinate frame with the water.Rechart it before it folds away.