Replay a caller-admitted fluid domain to one absolute step of its fixed clock.
The equations
The Arakawa C grid stores depth h at cell centres over bed elevation b and horizontal velocity on faces between cells. With free surface eta = b + h, each step approximates:
∂u/∂t = −g·∂η/∂x − k·u (x momentum, on x faces)
∂v/∂t = −g·∂η/∂z − k·v (z momentum, on z faces)
∂h/∂t = −∂(h·u)/∂x − ∂(h·v)/∂z + q (continuity, at cell centres)
k is linear drag and q is the declared source/drain volume rate per unit area. Momentum omits advection, so this gravity-wave approximation does not resolve full Navier-Stokes flow or breaking waves.
Continuity uses first-order upwind flux u * h_donor * dz * dt on x faces and the analogous x-span expression on z faces. Each shared face enters neighboring updates with opposite signs; sources, drains and open edges supply the explicit ledger terms. Binary64 accumulation and the final depth clamp can introduce balance error.
Face and outflow rules
Equal computed bed + depth elevations give zero pressure difference. An unchanged lake also needs closed edges, no effective sources/drains and representable arithmetic; multiplying depth by area then dividing can round even with zero flux.
Each cell's requested drain and face outflow is scaled against its pre-source held volume. One donor supplies each face's scale, preserving a shared face flux; sources are added afterward and do not fund this step's outgoing limiter.
A side at or below dryDepth blocks the face when its computed elevation is at least the other side's elevation. Subthreshold depth is still part of that elevation.
Wall edges and faces touching solid cells have zero velocity.
Open edges use a dry ghost at the interior bed height. An inward velocity has a ghost donor and contributes zero volume; outward flux is recorded in outflowVolume.
Stability
The validator compares the gravity-wave Courant expression at referenceDepth with one:
dt · √(g · referenceDepth) · √(1/dx² + 1/dz²) ≤ 1
fluidCourantNumber evaluates this expression directly. The validator's greater-than comparison misses derived NaN, and sources can raise depths beyond referenceDepth without another check, so passing admission does not prove stability throughout replay.
Determinism
Every call starts from the supplied depths with zero face velocities and retains no inter-call state. Unchanged inputs and arithmetic therefore follow the same operation order regardless of prior seeks. This is an in-process replay property, not observed Windows/POSIX byte identity or a GPU equivalence claim.
The caller must run validateFluidDomain; replay does not repeat array, scalar, flow-site or budget admission. Sources and drains use step-start times in [start, end), with null end unbounded. A drain requests its full step volume only when the pre-update free surface exceeds sillLevel; the sill does not cap removal at that height.
Drag divides the pressure-updated velocity by 1 + dt * drag. For finite positive damping this reduces magnitude without reversing sign; damping and other intermediate products are not independently checked.
Throws for a noninteger, negative or over-budget step and for non-finite depth/face velocities remaining after an update. Step zero skips that finite scan. The assignment updated > 0 ? updated : 0 also turns NaN into zero before the scan, and clock, source/drain/outflow ledgers and final volume have no finite-result gate. Extreme finite flow products can therefore corrupt totals without a named refusal.
Replay a caller-admitted fluid domain to one absolute step of its fixed clock.
The equations
The Arakawa C grid stores depth h at cell centres over bed elevation b and horizontal velocity on faces between cells. With free surface eta = b + h, each step approximates:
kis linear drag andqis the declared source/drain volume rate per unit area. Momentum omits advection, so this gravity-wave approximation does not resolve full Navier-Stokes flow or breaking waves.Continuity uses first-order upwind flux
u * h_donor * dz * dton x faces and the analogous x-span expression on z faces. Each shared face enters neighboring updates with opposite signs; sources, drains and open edges supply the explicit ledger terms. Binary64 accumulation and the final depth clamp can introduce balance error.Face and outflow rules
bed + depthelevations give zero pressure difference. An unchanged lake also needs closed edges, no effective sources/drains and representable arithmetic; multiplying depth by area then dividing can round even with zero flux.Stability
The validator compares the gravity-wave Courant expression at referenceDepth with one:
fluidCourantNumberevaluates this expression directly. The validator's greater-than comparison misses derived NaN, and sources can raise depths beyond referenceDepth without another check, so passing admission does not prove stability throughout replay.Determinism
Every call starts from the supplied depths with zero face velocities and retains no inter-call state. Unchanged inputs and arithmetic therefore follow the same operation order regardless of prior seeks. This is an in-process replay property, not observed Windows/POSIX byte identity or a GPU equivalence claim.
The caller must run
validateFluidDomain; replay does not repeat array, scalar, flow-site or budget admission. Sources and drains use step-start times in [start, end), with null end unbounded. A drain requests its full step volume only when the pre-update free surface exceeds sillLevel; the sill does not cap removal at that height.Drag divides the pressure-updated velocity by
1 + dt * drag. For finite positive damping this reduces magnitude without reversing sign; damping and other intermediate products are not independently checked.Throws for a noninteger, negative or over-budget step and for non-finite depth/face velocities remaining after an update. Step zero skips that finite scan. The assignment
updated > 0 ? updated : 0also turns NaN into zero before the scan, and clock, source/drain/outflow ledgers and final volume have no finite-result gate. Extreme finite flow products can therefore corrupt totals without a named refusal.