@woosh/meep-engine 2.157.0 → 2.158.0

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

@@ -1,15 +1,14 @@
 import { assert } from "../../../core/assert.js";
 import { sor_optimal_omega } from "../../../core/math/linalg/sor_optimal_omega.js";
-import { v3_grid_advect_maccormack_scalar } from "./solver/v3_grid_advect_maccormack_scalar.js";
-import { v3_grid_advect_maccormack_velocity } from "./solver/v3_grid_advect_maccormack_velocity.js";
-import { v3_grid_advect_sl_velocity } from "./solver/v3_grid_advect_sl_velocity.js";
 import { v3_grid_apply_diffusion } from "./solver/v3_grid_apply_diffusion.js";
-import { v3_grid_apply_vorticity_confinement } from "./solver/v3_grid_apply_vorticity_confinement.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
@@ -34,7 +33,12 @@ export const PressureSolver = {
 };
 
 /**
- * Velocity / scalar transport scheme selection.
+ * 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
@@ -42,10 +46,8 @@ export const PressureSolver = {
  *
  *   - `"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 at
- *     ~2× the advection cost — and advection is the minority of step() cost
- *     next to pressure, so the end-to-end price is small. Allocates 3
- *     additional N-sized scratch buffers, shared with the reflection scheme.
+ *     a monotone min-max limiter. Second-order accurate in space and time.
+ *     Allocates 3 additional face-lattice scratch buffers.
  *
  * @enum {string}
  */
@@ -55,7 +57,10 @@ export const AdvectionScheme = {
 };
 
 /**
- * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
+ * 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
@@ -73,8 +78,8 @@ export const AdvectionScheme = {
  *      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
- *      with the same 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
@@ -151,13 +156,19 @@ export class FluidSimulator {
      *
      * 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 constant
-     * {@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, which is what wind-field
-     * use cases want (drive with {@link AmbientWindFluidEffector} for a
-     * specific ambient target instead of a force).
+     * 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.
@@ -202,25 +213,23 @@ export class FluidSimulator {
     vorticity_confinement = 0;
 
     /**
-     * Which transport scheme advects velocity and scalars — see
-     * {@link AdvectionScheme}.
-     *
-     * **Default semi-Lagrangian — MacCormack is gated on a MAC-staggered
-     * grid.** On the current collocated discretization the projection has an
-     * operator-mismatch floor (high-frequency divergence it cannot see, let
-     * alone remove — quality.spec.js scenario 7), and MacCormack's
-     * anti-diffusive corrector amplifies exactly that residue instead of
-     * letting first-order smearing absorb it. Measured on the sealed-vortex
-     * scenario: kinetic energy transiently grows to **1.9×** within 10 s
-     * (vs SL's monotone decay), and a passive scalar's total mass inflates
-     * **1.8×** in one second of orbiting. The kernels are correct in
-     * isolation (their specs transport clean fields sharply and monotonely) —
-     * it is the interaction with the collocated pressure floor that is
-     * unstable. Flip this on once the grid is staggered.
+     * 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.SEMI_LAGRANGIAN;
+    advection_scheme = AdvectionScheme.MACCORMACK;
 
     /**
      * Replace the plain "project → advect → project" sequence with the
@@ -235,25 +244,30 @@ export class FluidSimulator {
      *
      * Same two pressure solves as the default double-projection Stam step,
      * and two half-dt advections instead of one full-dt one — measured cost
-     * +20% of step() at 32×8×32. The reflection replaces the
+     * ~+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.
      *
-     * Default ON: with semi-Lagrangian advection this is measured stable
-     * (sealed-vortex kinetic energy never exceeds 0.99× its initial over
-     * 10 s) while retaining visibly more swirl — peak vorticity 0.73 vs 0.62
-     * after one second (quality.spec.js scenario 2b). With MacCormack it
-     * compounds the collocated-floor amplification (3.4× energy growth) —
-     * see {@link advection_scheme}; that combination should wait for MAC
-     * staggering.
+     * 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 = true;
+    advection_reflection = false;
 
     /**
      * Run the pressure projection *before* self-advection in addition to after.
@@ -318,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;
@@ -340,31 +353,46 @@ export class FluidSimulator {
     /** @type {Float32Array|null} */ #pcg_As = null;
     /** @type {Float32Array|null} */ #pcg_precon = null;
 
-    // Auxiliary velocity trio (allocated lazily): MacCormack's forward-pass
-    // scratch AND the reflection scheme's ũ snapshot — the two uses never
-    // overlap in time within a step.
-    #aux_scratch_cells = 0;
+    // 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.
     }
 
     /**
@@ -385,53 +413,66 @@ export class FluidSimulator {
     }
 
     /**
-     * Lazily allocate the auxiliary velocity trio (3 N-sized Float32 buffers)
-     * used by MacCormack advection and the reflection scheme. Idempotent and
+     * Lazily allocate the auxiliary velocity trio (face-lattice sized) used by
+     * the reflection scheme and vorticity confinement. Idempotent and
      * monotonic.
-     * @param {number} cell_count
+     * @param {FluidField} field
      */
-    #ensure_aux_scratch(cell_count) {
-        if (this.#aux_scratch_cells >= cell_count) {
-            return;
-        }
-        this.#aux_scratch_cells = cell_count;
-        this.#aux_x = new Float32Array(cell_count);
-        this.#aux_y = new Float32Array(cell_count);
-        this.#aux_z = new Float32Array(cell_count);
+    #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 (it is point-read only); sources must not.
+     * arrays; sources must not.
      *
      * @param {FluidField} field
      * @param {number[]} res
      * @param {number} dt
-     * @param {Float32Array[]} sources    `[src_x, src_y, src_z]`
-     * @param {Float32Array} carrier_x
-     * @param {Float32Array} carrier_y
-     * @param {Float32Array} carrier_z
+     * @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_x, carrier_y, carrier_z) {
+    #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_aux_scratch(field.cellCount());
-            v3_grid_advect_maccormack_velocity(
-                outputs, sources,
-                carrier_x, carrier_y, carrier_z,
-                [this.#aux_x, this.#aux_y, this.#aux_z],
+            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_grid_advect_sl_velocity(
-                outputs, sources,
-                carrier_x, carrier_y, carrier_z,
+            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
             );
         }
@@ -497,26 +538,31 @@ export class FluidSimulator {
     }
 
     /**
-     * Projection body — assumes `field.solid_neighbour_mask` is already fresh.
+     * 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_scratch(field.cellCount());
         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;
         }
 
-        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) {
@@ -538,30 +584,42 @@ export class FluidSimulator {
             );
         }
 
-        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
         );
     }
 
@@ -595,57 +653,75 @@ 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;
+
         // 1b. Velocity damping — the solver's only energy sink under sustained
-        //     forcing. Solid cells are included in the multiply (their velocity
-        //     is 0, so damping them is a no-op and the loop stays branch-free).
+        //     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 vx = field.velocity_x;
-            const vy = field.velocity_y;
-            const vz = field.velocity_z;
-            for (let i = 0; i < cell_count; i++) {
-                vx[i] *= decay;
-                vy[i] *= decay;
-                vz[i] *= decay;
+            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). Uses the prev trio and
-        //     the diffusion scratch as working memory; both are overwritten by
-        //     later phases anyway.
+        //     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) {
-            v3_grid_apply_vorticity_confinement(
+            this.#ensure_aux_scratch(field);
+            v3_mac_apply_vorticity_confinement(
                 field.velocity_x, field.velocity_y, field.velocity_z,
-                this.#prev_x, this.#prev_y, this.#prev_z, this.#diffusion_scratch,
+                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,
-                field.solid
+                solid
             );
         }
 
-        // Refresh the pre-baked solid-neighbour mask ONCE for the whole step —
-        // after effectors (a custom effector may splat solids), before anything
-        // that consumes it. Both projections below reuse it, saving an O(N)
-        // byte pass versus recomputing per projection.
-        field.recomputeSolidNeighbourMask();
-
-        const solid = field.solid;
-
-        // 2. Velocity diffusion (viscosity). Cheap to skip when disabled.
+        // 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, 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);
+            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);
         }
 
         // 3-5. Transport block: project + self-advect (+ optional reflection).
@@ -656,17 +732,15 @@ export class FluidSimulator {
             // 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;
-            const n = cell_count;
 
             // ũ = 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, this.#prev_x, this.#prev_y, this.#prev_z);
+            this.#advect_velocity(field, res, half_dt, prev, prev);
 
-            // Snapshot ũ (after the advect — MacCormack uses the same aux trio
-            // as its forward scratch during the kernel).
-            this.#ensure_aux_scratch(n);
+            // 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);
@@ -674,19 +748,23 @@ export class FluidSimulator {
             // u½ = project(ũ)
             this.#project_with_current_mask(field);
 
-            // û = 2·u½ − ũ — the reflection about the divergence-free subspace.
+            // û = 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; i++) {
-                px[i] = 2 * fx[i] - ax[i];
-                py[i] = 2 * fy[i] - ay[i];
-                pz[i] = 2 * fz[i] - az[i];
-            }
-
-            // u′ = advect(û, u½, dt/2). Output aliases the carrier (the field's
-            // own velocity) — allowed, the carrier is point-read only.
-            this.#advect_velocity(field, res, half_dt, prev, fx, fy, fz);
+            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);
@@ -699,11 +777,11 @@ export class FluidSimulator {
             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, this.#prev_x, this.#prev_y, this.#prev_z);
+            this.#advect_velocity(field, res, time_delta, prev, prev);
 
             // Re-project after advection. Solids cannot have changed since the
             // top-of-step mask refresh (only the simulator has touched the
-            // field), so the mask is still fresh.
+            // field), so the masks are still fresh.
             this.#project_with_current_mask(field);
         }
 
@@ -714,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,
@@ -724,25 +807,16 @@ export class FluidSimulator {
             }
 
             this.#scalar_scratch.set(attr.data);
-            if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
-                // #diffusion_scratch is free here (the optional diffusion above
-                // has fully consumed it) — reuse it as the forward-pass buffer.
-                v3_grid_advect_maccormack_scalar(
-                    attr.data, this.#scalar_scratch, this.#diffusion_scratch,
-                    field.velocity_x, field.velocity_y, field.velocity_z,
-                    res[0], res[1], res[2],
-                    time_delta,
-                    solid
-                );
-            } else {
-                v3_grid_apply_scalar_advection(
-                    attr.data, this.#scalar_scratch,
-                    field.velocity_x, field.velocity_y, field.velocity_z,
-                    res[0], res[1], res[2],
-                    time_delta,
-                    solid
-                );
-            }
+            // 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],
+                time_delta,
+                solid
+            );
         }
     }
 }