@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/fluid/FluidSimulator.js

@@ -1,12 +1,14 @@
 import { assert } from "../../../core/assert.js";
-import { optimal_sor_omega } from "./solver/optimal_sor_omega.js";
-import { v3_grid_apply_advection_forward } from "./solver/v3_grid_apply_advection_forward.js";
+import { sor_optimal_omega } from "../../../core/math/linalg/sor_optimal_omega.js";
 import { v3_grid_apply_diffusion } from "./solver/v3_grid_apply_diffusion.js";
-import { v3_grid_apply_scalar_advection } from "./solver/v3_grid_apply_scalar_advection.js";
-import { v3_grid_compute_divergence } from "./solver/v3_grid_compute_divergence.js";
 import { v3_grid_solve_pressure } from "./solver/v3_grid_solve_pressure.js";
 import { v3_grid_solve_pressure_pcg } from "./solver/v3_grid_solve_pressure_pcg.js";
-import { v3_grid_subtract_pressure_gradient } from "./solver/v3_grid_subtract_pressure_gradient.js";
+import { v3_mac_advect_maccormack_velocity } from "./solver/v3_mac_advect_maccormack_velocity.js";
+import { v3_mac_advect_sl_velocity } from "./solver/v3_mac_advect_sl_velocity.js";
+import { v3_mac_advect_sl_scalar } from "./solver/v3_mac_advect_scalar.js";
+import { v3_mac_apply_vorticity_confinement } from "./solver/v3_mac_apply_vorticity_confinement.js";
+import { v3_mac_compute_divergence } from "./solver/v3_mac_compute_divergence.js";
+import { v3_mac_subtract_pressure_gradient } from "./solver/v3_mac_subtract_pressure_gradient.js";
 
 /**
  * Pressure solver selection. Both solve the same A·p = -div system over the
@@ -31,7 +33,34 @@ export const PressureSolver = {
 };
 
 /**
- * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
+ * VELOCITY transport scheme selection. Passive scalars always use
+ * semi-Lagrangian transport regardless of this setting — gather-form
+ * MacCormack is non-conservative (the corrector re-adds roughly double the
+ * gather bias; measured 1.7x total dye mass in one second of a sealed
+ * vortex, independent of wall handling), and scalar conservation is a hard
+ * requirement, not a preference.
+ *
+ *   - `"semi-lagrangian"` — first-order back-trace + trilinear gather (Stam
+ *     1999). Cheapest; strongly dissipative — a vortex loses half its kinetic
+ *     energy per second at production settings (see quality.spec.js).
+ *
+ *   - `"maccormack"` — unconditionally stable MacCormack (Selle et al. 2008):
+ *     a forward and a backward semi-Lagrangian pass with error correction and
+ *     a monotone min-max limiter. Second-order accurate in space and time.
+ *     Allocates 3 additional face-lattice scratch buffers.
+ *
+ * @enum {string}
+ */
+export const AdvectionScheme = {
+    SEMI_LAGRANGIAN: "semi-lagrangian",
+    MACCORMACK: "maccormack",
+};
+
+/**
+ * 3D incompressible-flow solver on a MAC (staggered) grid — Stam's stable-
+ * fluids step structure (1999/2003) with face-centered velocity (Harlow &
+ * Welch 1965), an exact discrete Helmholtz projection, and optional
+ * advection-reflection / MacCormack transport.
  *
  * Holds tuning knobs plus transient working memory (per-step velocity snapshots,
  * divergence, ping-pong scratch). None of that working memory carries information
@@ -41,12 +70,16 @@ export const PressureSolver = {
  * the field). Scratch is cached by cell-count so per-step allocation stays at zero.
  *
  * Per step:
- *   1. Apply external forces (effectors mutate field velocity).
+ *   1. Apply external forces (effectors mutate field velocity), then the
+ *      optional exponential velocity damping.
  *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
- *   3. Project (pressure solve + gradient subtract) to enforce ∇·v ≈ 0.
- *   4. Self-advect velocity (semi-Lagrangian back-trace).
- *   5. Project again (advection introduces small divergence).
- *   6. For each scalar attribute on the field: optionally diffuse, then advect.
+ *   3-5. Transport block — either the Stam reference sequence
+ *      project₁ → advect → project₂, or (default) the advection-reflection
+ *      form of the same two projections (see {@link advection_reflection}).
+ *      Advection itself is semi-Lagrangian or MacCormack per
+ *      {@link advection_scheme}.
+ *   6. For each scalar attribute on the field: optionally diffuse, then
+ *      advect (always semi-Lagrangian — see {@link AdvectionScheme}).
  *
  * Pressure is warm-started from the previous step's solution (`field.pressure`),
  * which converges much faster than starting from zero once the flow reaches a
@@ -69,6 +102,25 @@ export const PressureSolver = {
  */
 export const PRESSURE_ITERATIONS_FLOOR = 8;
 
+/**
+ * Relative convergence tolerance handed to the MIC-PCG pressure solve: the
+ * solver stops as soon as `max|r| <= tolerance * max|−div|`. The iteration
+ * cap from {@link FluidSimulator#resolvePressureIterations} is sized for the
+ * cold-start worst case; warm-started production frames converge much
+ * earlier, and without a tolerance exit every warm frame would pay the full
+ * cold-start budget for no quality gain.
+ *
+ * 1e-3 sits below visual-fluids noticeability and below the collocated
+ * operator-mismatch floor that dominates post-projection divergence (see
+ * quality.spec.js) — iterating past it buys nothing visible.
+ *
+ * SOR has no equivalent exit: it never computes its residual (doing so would
+ * add a pass per sweep), so its cost is governed by the iteration count alone.
+ *
+ * @type {number}
+ */
+export const PCG_RELATIVE_TOLERANCE = 1e-3;
+
 export class FluidSimulator {
 
     /**
@@ -97,6 +149,34 @@ export class FluidSimulator {
      */
     scalar_diffusion_iterations = 4;
 
+    /**
+     * Exponential velocity damping rate, per second. Each step multiplies the
+     * whole velocity field by `exp(-velocity_damping * dt)` right after
+     * effectors run. `0` (default) disables — no pass is made.
+     *
+     * Why it exists: the solver has no other dissipation mechanism that bounds
+     * energy under sustained forcing. Incompressible projection cannot oppose
+     * a uniform body force (a uniform field is divergence-free), so a bare
+     * `force` on a {@link GlobalFluidEffector} accelerates the fluid without
+     * limit — there is no terminal state. A small damping rate gives constant
+     * forcing a terminal velocity of approximately
+     * `acceleration / velocity_damping` and makes transient gusts decay back
+     * to calm.
+     *
+     * Relationship to {@link GlobalFluidEffector#drag}: the effector's drag
+     * is the same operation expressed as SCENE CONTENT — it relaxes toward a
+     * configurable ambient wind and travels with the effector entity. This
+     * knob is the SOLVER-level stability primitive: it exists even when no
+     * effectors are wired, and always relaxes toward zero. Use the effector
+     * for atmosphere design; use this to guarantee boundedness.
+     *
+     * The exponential form is frame-rate independent: two half-steps damp
+     * exactly as much as one full step.
+     *
+     * @type {number}
+     */
+    velocity_damping = 0;
+
     /**
      * Which pressure solver to use. `PressureSolver.SOR` (default) is the
      * baseline red-black Successive Over-Relaxation. `PressureSolver.MICPCG`
@@ -115,6 +195,80 @@ export class FluidSimulator {
      */
     pressure_solver = PressureSolver.SOR;
 
+    /**
+     * Vorticity-confinement strength ε, per second (Fedkiw et al. 2001). Each
+     * step deposits `ε·dt·(N × ω)` as a velocity increment, sharpening vortex
+     * cores that coarse grids and dissipative transport smear away. `0`
+     * (default) disables — no pass is made.
+     *
+     * Confinement ADDS energy by design; pair non-zero values with
+     * {@link velocity_damping} so gusts still decay. Visual-smoke territory
+     * starts around `ε ≈ 5–30` at 60 Hz (epsilon_dt 0.1–0.5).
+     *
+     * Cost when enabled: two extra O(N) passes (curl + force) using existing
+     * scratch — no allocations.
+     *
+     * @type {number}
+     */
+    vorticity_confinement = 0;
+
+    /**
+     * Which transport scheme advects VELOCITY — see {@link AdvectionScheme}
+     * (scalars are always semi-Lagrangian; see the enum docstring for why).
+     *
+     * **Default MacCormack.** On the MAC grid with solid-clipped traces it is
+     * measured long-horizon stable (sealed-vortex energy peaks at 0.96x its
+     * initial over 10 s, monotone decay thereafter) and retains dramatically
+     * more energy than first-order transport: 0.80 vs 0.53 KE after one
+     * second (quality.spec.js scenario 2b).
+     *
+     * Do NOT combine with {@link advection_reflection}: the energy-preserving
+     * reflection re-injects the corrector overshoots and the pair pumps
+     * energy without bound (10 s peak 3.7x — measured both with and without
+     * trace clipping). Reflection is the companion for SEMI_LAGRANGIAN.
+     *
+     * @type {string}
+     */
+    advection_scheme = AdvectionScheme.MACCORMACK;
+
+    /**
+     * Replace the plain "project → advect → project" sequence with the
+     * advection-reflection scheme (Zehnder, Narain, Thomaszewski 2018):
+     *
+     *     ũ  = advect(u, u, dt/2)        — half-step self-advection
+     *     u½ = project(ũ)
+     *     û  = 2·u½ − ũ                  — energy-preserving reflection
+     *     u′ = advect(û, u½, dt/2)       — transport the REFLECTED field
+     *                                       along the PROJECTED one
+     *     u₁ = project(u′)
+     *
+     * Same two pressure solves as the default double-projection Stam step,
+     * and two half-dt advections instead of one full-dt one — measured cost
+     * ~+70% of step() at 32×8×32 on the MAC lattices (each half-step pays the
+     * cross-component carrier sampling). The reflection replaces the
+     * energy-DISSIPATING first projection with an energy-PRESERVING
+     * reflection about the divergence-free subspace.
+     *
+     * With semi-Lagrangian advection this is measured stable (sealed-vortex
+     * kinetic energy never exceeds its initial over 10 s) while retaining
+     * visibly more swirl — peak vorticity 0.74 vs 0.68 after one second
+     * (quality.spec.js scenario 2b). Do NOT combine with MacCormack — the
+     * reflection re-injects the corrector overshoots (10 s energy peak
+     * 3.7x); see {@link advection_scheme}.
+     *
+     * Only consulted when {@link project_before_advection} is true — the
+     * scheme is defined around the mid-step projection. With
+     * `project_before_advection = false` this flag is ignored.
+     *
+     * Default OFF: the default velocity scheme is MacCormack, with which the
+     * reflection is unstable (see {@link advection_scheme}). Enable it when
+     * running SEMI_LAGRANGIAN velocity transport — that pairing is measured
+     * stable and retains visibly more swirl than plain SL.
+     *
+     * @type {boolean}
+     */
+    advection_reflection = false;
+
     /**
      * Run the pressure projection *before* self-advection in addition to after.
      *
@@ -178,13 +332,12 @@ export class FluidSimulator {
     pressure_iteration_scale = 0.25;
 
     // ────────────────────────────────────────────────────────────────────────────
-    // Transient scratch — overwritten before read on every step. Cached by
-    // cell-count so we don't allocate per step. Their value never crosses a step
-    // boundary; if it did it would belong on the field (see `field.pressure`).
+    // Transient scratch — overwritten before read on every step. Cached and
+    // grown monotonically so we don't allocate per step. Their value never
+    // crosses a step boundary; if it did it would belong on the field (see
+    // `field.pressure`). Velocity-shaped buffers are sized per face lattice.
     // ────────────────────────────────────────────────────────────────────────────
 
-    #scratch_cells = 0;
-
     /** @type {Float32Array|null} */ #prev_x = null;
     /** @type {Float32Array|null} */ #prev_y = null;
     /** @type {Float32Array|null} */ #prev_z = null;
@@ -200,23 +353,46 @@ export class FluidSimulator {
     /** @type {Float32Array|null} */ #pcg_As = null;
     /** @type {Float32Array|null} */ #pcg_precon = null;
 
+    // Auxiliary velocity trio (allocated lazily, face-lattice sized): the
+    // reflection scheme's ũ snapshot / carrier copy, and vorticity
+    // confinement's curl scratch — the uses never overlap in time.
+    /** @type {Float32Array|null} */ #aux_x = null;
+    /** @type {Float32Array|null} */ #aux_y = null;
+    /** @type {Float32Array|null} */ #aux_z = null;
+
+    // MacCormack forward-pass trio (allocated lazily, face-lattice sized).
+    // Deliberately separate from #aux: in the reflection path #aux holds the
+    // carrier during the very advection that needs this scratch.
+    /** @type {Float32Array|null} */ #mc_x = null;
+    /** @type {Float32Array|null} */ #mc_y = null;
+    /** @type {Float32Array|null} */ #mc_z = null;
+
     /**
-     * Grow the cached scratch buffers if the requested size exceeds what's allocated.
-     * Idempotent and monotonic — never shrinks. Called at the top of {@link step} and
-     * {@link project} so user code never has to think about it.
-     * @param {number} cell_count
+     * Grow the cached scratch buffers to fit the field's lattices. The prev
+     * trio and the diffusion scratch are sized per FACE grid (the largest of
+     * which also covers every cell-count use); divergence and scalar scratch
+     * are cell-count. Idempotent and monotonic — never shrinks. Called at the
+     * top of {@link step} so user code never has to think about it.
+     * @param {FluidField} field
      */
-    #ensure_scratch(cell_count) {
-        if (this.#scratch_cells >= cell_count) {
-            return;
+    #ensure_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        const n_cell = field.cellCount();
+        const n_face_max = Math.max(n_u, n_v, n_w);
+
+        if (this.#prev_x === null || this.#prev_x.length < n_u) this.#prev_x = new Float32Array(n_u);
+        if (this.#prev_y === null || this.#prev_y.length < n_v) this.#prev_y = new Float32Array(n_v);
+        if (this.#prev_z === null || this.#prev_z.length < n_w) this.#prev_z = new Float32Array(n_w);
+        if (this.#diffusion_scratch === null || this.#diffusion_scratch.length < n_face_max) {
+            this.#diffusion_scratch = new Float32Array(n_face_max);
         }
-        this.#scratch_cells = cell_count;
-        this.#prev_x = new Float32Array(cell_count);
-        this.#prev_y = new Float32Array(cell_count);
-        this.#prev_z = new Float32Array(cell_count);
-        this.#divergence = new Float32Array(cell_count);
-        this.#diffusion_scratch = new Float32Array(cell_count);
-        this.#scalar_scratch = new Float32Array(cell_count);
+        if (this.#scalar_scratch === null || this.#scalar_scratch.length < n_cell) {
+            this.#scalar_scratch = new Float32Array(n_cell);
+        }
+        // #divergence is dtype-tracked separately by #ensure_divergence_matches.
     }
 
     /**
@@ -236,6 +412,72 @@ export class FluidSimulator {
         this.#pcg_precon = new Float32Array(cell_count);
     }
 
+    /**
+     * Lazily allocate the auxiliary velocity trio (face-lattice sized) used by
+     * the reflection scheme and vorticity confinement. Idempotent and
+     * monotonic.
+     * @param {FluidField} field
+     */
+    #ensure_aux_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        if (this.#aux_x === null || this.#aux_x.length < n_u) this.#aux_x = new Float32Array(n_u);
+        if (this.#aux_y === null || this.#aux_y.length < n_v) this.#aux_y = new Float32Array(n_v);
+        if (this.#aux_z === null || this.#aux_z.length < n_w) this.#aux_z = new Float32Array(n_w);
+    }
+
+    /**
+     * Lazily allocate the MacCormack forward-pass trio (face-lattice sized).
+     * Idempotent and monotonic.
+     * @param {FluidField} field
+     */
+    #ensure_mc_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        if (this.#mc_x === null || this.#mc_x.length < n_u) this.#mc_x = new Float32Array(n_u);
+        if (this.#mc_y === null || this.#mc_y.length < n_v) this.#mc_y = new Float32Array(n_v);
+        if (this.#mc_z === null || this.#mc_z.length < n_w) this.#mc_z = new Float32Array(n_w);
+    }
+
+    /**
+     * Advect the field's velocity from `sources` along the given carrier, into
+     * the field's velocity buffers, using the configured
+     * {@link advection_scheme}. The carrier may alias the field's own velocity
+     * arrays; sources must not.
+     *
+     * @param {FluidField} field
+     * @param {number[]} res
+     * @param {number} dt
+     * @param {Float32Array[]} sources  `[src_u, src_v, src_w]` face grids
+     * @param {Float32Array[]} carrier  `[car_u, car_v, car_w]` face grids
+     */
+    #advect_velocity(field, res, dt, sources, carrier) {
+        const outputs = [field.velocity_x, field.velocity_y, field.velocity_z];
+        if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
+            this.#ensure_mc_scratch(field);
+            v3_mac_advect_maccormack_velocity(
+                outputs, sources, carrier,
+                [this.#mc_x, this.#mc_y, this.#mc_z],
+                res[0], res[1], res[2],
+                dt,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                field.solid
+            );
+        } else {
+            v3_mac_advect_sl_velocity(
+                outputs, sources, carrier,
+                res[0], res[1], res[2],
+                dt,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                field.solid
+            );
+        }
+    }
+
     /**
      * Re-allocate the divergence scratch buffer if its element type doesn't match
      * the field's pressure type. Lets `half_precision_pressure` on the field carry
@@ -282,31 +524,45 @@ export class FluidSimulator {
      * because tests and external code may need to project on demand (e.g., after
      * splatting an out-of-band impulse). `field.pressure` is read as the warm-start
      * initial guess and written with the new solution.
+     *
+     * Refreshes the field's solid-neighbour mask itself, so direct callers never
+     * have to remember invalidation after mutating solids. {@link step} refreshes
+     * the mask once for the whole step and uses the private no-recompute variant
+     * for both of its projections.
+     *
      * @param {FluidField} field
      */
     project(field) {
-        this.#ensure_scratch(field.cellCount());
+        field.recomputeSolidNeighbourMask();
+        this.#project_with_current_mask(field);
+    }
+
+    /**
+     * Projection body — assumes the field's derived masks (cell neighbour
+     * mask, pressure diagonal, face pins) are already fresh.
+     *
+     * On the MAC layout this is an exact discrete Helmholtz projection: the
+     * face-difference divergence and the face gradient compose to exactly the
+     * 7-point Laplacian the solvers invert, so post-projection divergence is
+     * zero up to solver residual — including beside walls.
+     *
+     * @param {FluidField} field
+     */
+    #project_with_current_mask(field) {
         this.#ensure_divergence_matches(field);
 
         const res = field.getResolution();
-        const solid = field.solid;
         const iterations = this.resolvePressureIterations(res[0], res[1], res[2]);
 
         if (iterations === 0) {
             return;
         }
 
-        // Pre-bake the per-cell neighbourhood mask consumed by the pressure SOR
-        // loop. One O(N) byte-pass amortized across `iterations` SOR sweeps;
-        // saves six boundary checks plus six solid-neighbour checks per cell per
-        // iteration. See FluidField.solid_neighbour_mask.
-        field.recomputeSolidNeighbourMask();
-
-        v3_grid_compute_divergence(
+        v3_mac_compute_divergence(
             this.#divergence,
             field.velocity_x, field.velocity_y, field.velocity_z,
             res[0], res[1], res[2],
-            solid
+            field.solid
         );
 
         if (this.pressure_solver === PressureSolver.MICPCG) {
@@ -314,8 +570,8 @@ export class FluidSimulator {
             v3_grid_solve_pressure_pcg(
                 field.pressure, this.#divergence,
                 res[0], res[1], res[2],
-                iterations,
-                field.solid_neighbour_mask,
+                iterations, PCG_RELATIVE_TOLERANCE,
+                field.solid_neighbour_mask, field.pressure_diag,
                 this.#pcg_r, this.#pcg_z, this.#pcg_s, this.#pcg_As, this.#pcg_precon
             );
         } else {
@@ -323,35 +579,47 @@ export class FluidSimulator {
                 field.pressure, this.#divergence,
                 res[0], res[1], res[2],
                 iterations,
-                optimal_sor_omega(res[0], res[1], res[2]),
-                field.solid_neighbour_mask
+                sor_optimal_omega(res[0], res[1], res[2]),
+                field.solid_neighbour_mask, field.pressure_diag
             );
         }
 
-        v3_grid_subtract_pressure_gradient(
+        v3_mac_subtract_pressure_gradient(
             field.velocity_x, field.velocity_y, field.velocity_z,
             field.pressure,
-            res[0], res[1], res[2],
-            field.solid_neighbour_mask
+            field.face_solid_x, field.face_solid_y, field.face_solid_z,
+            res[0], res[1], res[2]
         );
     }
 
     /**
-     * Diffuse a single velocity component in-place, using `source_copy_buf` as the
-     * "before" snapshot and `#diffusion_scratch` as the ping-pong scratch.
-     * @param {Float32Array} component
+     * Diffuse a single velocity component (one face lattice) in-place, using
+     * `source_copy_buf` as the "before" snapshot and `#diffusion_scratch` as
+     * the ping-pong scratch. The face-pin mask plays the diffusion kernel's
+     * "solid" role: pinned faces are frozen and act as no-flux neighbours.
+     *
+     * The shared scratch buffers can be larger than this lattice (they are
+     * sized to the largest one); the kernel's internal whole-buffer copies
+     * require exact-length views.
+     *
+     * @param {Float32Array} component  Face lattice, exact length.
      * @param {Float32Array} source_copy_buf
-     * @param {number[]} res
-     * @param {Uint8Array} solid
+     * @param {number} dim_x
+     * @param {number} dim_y
+     * @param {number} dim_z
+     * @param {Uint8Array} face_solid
      */
-    #diffuse_velocity_component(component, source_copy_buf, res, solid) {
-        source_copy_buf.set(component);
+    #diffuse_velocity_component(component, source_copy_buf, dim_x, dim_y, dim_z, face_solid) {
+        const n = component.length;
+        const copy = source_copy_buf.length === n ? source_copy_buf : source_copy_buf.subarray(0, n);
+        const scratch = this.#diffusion_scratch.length === n ? this.#diffusion_scratch : this.#diffusion_scratch.subarray(0, n);
+        copy.set(component);
         v3_grid_apply_diffusion(
-            component, source_copy_buf, this.#diffusion_scratch,
-            res[0], res[1], res[2],
+            component, copy, scratch,
+            dim_x, dim_y, dim_z,
             this.velocity_diffusion_rate,
             this.velocity_diffusion_iterations,
-            solid
+            face_solid
         );
     }
 
@@ -385,46 +653,137 @@ export class FluidSimulator {
         const cell_count = field.cellCount();
         assert.greaterThan(cell_count, 0, "field has not been built");
 
-        this.#ensure_scratch(cell_count);
+        this.#ensure_scratch(field);
 
         const res = field.getResolution();
+        const n_u = field.velocity_x.length;
+        const n_v = field.velocity_y.length;
+        const n_w = field.velocity_z.length;
 
         // 1. External forces.
         for (let i = 0; i < effectors.length; i++) {
             effectors[i].apply(field, time_delta, world_to_grid);
         }
 
+        // Refresh the pre-baked derived masks (cell neighbour mask, pressure
+        // diagonal, face pins) ONCE for the whole step — after effectors (a
+        // custom effector may splat solids), before anything that consumes
+        // them. Both projections below reuse them. Faces that just became
+        // pinned have their velocity zeroed here (static-wall default);
+        // already-pinned faces keep whatever boundary condition their solid's
+        // owner wrote (FluidObstacleSystem writes moving-wall velocities).
+        field.recomputeSolidNeighbourMask();
+
         const solid = field.solid;
 
-        // 2. Velocity diffusion (viscosity). Cheap to skip when disabled.
-        if (this.velocity_diffusion_rate > 0 && this.velocity_diffusion_iterations > 0) {
-            this.#diffuse_velocity_component(field.velocity_x, this.#prev_x, res, solid);
-            this.#diffuse_velocity_component(field.velocity_y, this.#prev_y, res, solid);
-            this.#diffuse_velocity_component(field.velocity_z, this.#prev_z, res, solid);
+        // 1b. Velocity damping — the solver's only energy sink under sustained
+        //     forcing. Pinned faces are SKIPPED: their value is the wall's
+        //     boundary condition, not fluid momentum.
+        if (this.velocity_damping > 0) {
+            const decay = Math.exp(-this.velocity_damping * time_delta);
+            const vu = field.velocity_x;
+            const vv = field.velocity_y;
+            const vw = field.velocity_z;
+            const pin_u = field.face_solid_x;
+            const pin_v = field.face_solid_y;
+            const pin_w = field.face_solid_z;
+            for (let i = 0; i < n_u; i++) {
+                if (pin_u[i] === 0) vu[i] *= decay;
+            }
+            for (let i = 0; i < n_v; i++) {
+                if (pin_v[i] === 0) vv[i] *= decay;
+            }
+            for (let i = 0; i < n_w; i++) {
+                if (pin_w[i] === 0) vw[i] *= decay;
+            }
+        }
+
+        // 1c. Vorticity confinement — an additional force term that sharpens
+        //     vortex cores (see the knob's docstring). Needs the fresh face
+        //     pins; uses the prev + aux trios and the diffusion scratch as
+        //     working memory, all overwritten by later phases anyway.
+        if (this.vorticity_confinement > 0) {
+            this.#ensure_aux_scratch(field);
+            v3_mac_apply_vorticity_confinement(
+                field.velocity_x, field.velocity_y, field.velocity_z,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                this.#prev_x, this.#prev_y, this.#prev_z,
+                this.#aux_x, this.#aux_y, this.#aux_z, this.#diffusion_scratch,
+                res[0], res[1], res[2],
+                this.vorticity_confinement * time_delta,
+                solid
+            );
         }
 
-        // 3. Project to enforce incompressibility before advection. Skipping this
-        //    is a perf knob (~halves the pressure cost) at the price of advection
-        //    seeing a slightly-divergent input. See `project_before_advection`.
-        if (this.project_before_advection) {
-            this.project(field);
+        // 2. Velocity diffusion (viscosity). Cheap to skip when disabled. Each
+        //    face lattice diffuses with its own dimensions; the face-pin masks
+        //    make walls no-flux exactly like solid cells used to.
+        if (this.velocity_diffusion_rate > 0 && this.velocity_diffusion_iterations > 0) {
+            this.#diffuse_velocity_component(field.velocity_x, this.#prev_x, res[0] + 1, res[1], res[2], field.face_solid_x);
+            this.#diffuse_velocity_component(field.velocity_y, this.#prev_y, res[0], res[1] + 1, res[2], field.face_solid_y);
+            this.#diffuse_velocity_component(field.velocity_z, this.#prev_z, res[0], res[1], res[2] + 1, field.face_solid_z);
         }
 
-        // 4. Self-advect velocity (semi-Lagrangian back-trace through the projected field).
-        this.#prev_x.set(field.velocity_x);
-        this.#prev_y.set(field.velocity_y);
-        this.#prev_z.set(field.velocity_z);
+        // 3-5. Transport block: project + self-advect (+ optional reflection).
+        const prev = [this.#prev_x, this.#prev_y, this.#prev_z];
+
+        if (this.project_before_advection && this.advection_reflection) {
+            // Advection-reflection (Zehnder et al. 2018), half-step form — see
+            // the `advection_reflection` docstring. Same two projections as the
+            // plain path; two half-dt advections instead of one full-dt one.
+            const half_dt = 0.5 * time_delta;
+
+            // ũ = advect(u, u, dt/2)
+            this.#prev_x.set(field.velocity_x);
+            this.#prev_y.set(field.velocity_y);
+            this.#prev_z.set(field.velocity_z);
+            this.#advect_velocity(field, res, half_dt, prev, prev);
+
+            // Snapshot ũ.
+            this.#ensure_aux_scratch(field);
+            this.#aux_x.set(field.velocity_x);
+            this.#aux_y.set(field.velocity_y);
+            this.#aux_z.set(field.velocity_z);
+
+            // u½ = project(ũ)
+            this.#project_with_current_mask(field);
+
+            // û = 2·u½ − ũ — the reflection about the divergence-free subspace,
+            // per face lattice.
+            const ax = this.#aux_x, ay = this.#aux_y, az = this.#aux_z;
+            const fx = field.velocity_x, fy = field.velocity_y, fz = field.velocity_z;
+            const px = this.#prev_x, py = this.#prev_y, pz = this.#prev_z;
+            for (let i = 0; i < n_u; i++) px[i] = 2 * fx[i] - ax[i];
+            for (let i = 0; i < n_v; i++) py[i] = 2 * fy[i] - ay[i];
+            for (let i = 0; i < n_w; i++) pz[i] = 2 * fz[i] - az[i];
+
+            // u′ = advect(û, u½, dt/2). The advection kernels sample the
+            // carrier's OTHER lattices spatially, so the carrier must not
+            // alias the outputs — copy u½ into the aux trio (ũ there is dead,
+            // already folded into û).
+            this.#aux_x.set(fx);
+            this.#aux_y.set(fy);
+            this.#aux_z.set(fz);
+            this.#advect_velocity(field, res, half_dt, prev, [ax, ay, az]);
+
+            // u₁ = project(u′)
+            this.#project_with_current_mask(field);
+        } else {
+            // Stam reference sequence: project₁ (optional) → advect → project₂.
+            if (this.project_before_advection) {
+                this.#project_with_current_mask(field);
+            }
 
-        v3_grid_apply_advection_forward(
-            [field.velocity_x, field.velocity_y, field.velocity_z],
-            [this.#prev_x, this.#prev_y, this.#prev_z],
-            res[0], res[1], res[2],
-            time_delta,
-            solid
-        );
+            this.#prev_x.set(field.velocity_x);
+            this.#prev_y.set(field.velocity_y);
+            this.#prev_z.set(field.velocity_z);
+            this.#advect_velocity(field, res, time_delta, prev, prev);
 
-        // 5. Re-project after advection.
-        this.project(field);
+            // Re-project after advection. Solids cannot have changed since the
+            // top-of-step mask refresh (only the simulator has touched the
+            // field), so the masks are still fresh.
+            this.#project_with_current_mask(field);
+        }
 
         // 6. Transport each passive scalar by the now-finalized velocity field.
         const scalars = field.getScalarAttributes();
@@ -433,8 +792,13 @@ export class FluidSimulator {
 
             if (this.scalar_diffusion_rate > 0 && this.scalar_diffusion_iterations > 0) {
                 this.#scalar_scratch.set(attr.data);
+                // The diffusion scratch is face-lattice sized; the kernel's
+                // internal whole-buffer copies need an exact cell-count view.
+                const ping_pong = this.#diffusion_scratch.length === cell_count
+                    ? this.#diffusion_scratch
+                    : this.#diffusion_scratch.subarray(0, cell_count);
                 v3_grid_apply_diffusion(
-                    attr.data, this.#scalar_scratch, this.#diffusion_scratch,
+                    attr.data, this.#scalar_scratch, ping_pong,
                     res[0], res[1], res[2],
                     this.scalar_diffusion_rate,
                     this.scalar_diffusion_iterations,
@@ -443,7 +807,10 @@ export class FluidSimulator {
             }
 
             this.#scalar_scratch.set(attr.data);
-            v3_grid_apply_scalar_advection(
+            // Scalars are ALWAYS semi-Lagrangian, independent of
+            // advection_scheme — gather-MacCormack is non-conservative (see
+            // the AdvectionScheme docstring).
+            v3_mac_advect_sl_scalar(
                 attr.data, this.#scalar_scratch,
                 field.velocity_x, field.velocity_y, field.velocity_z,
                 res[0], res[1], res[2],