@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/fluid/solver/v3_mac_apply_vorticity_confinement.js

@@ -0,0 +1,165 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Vorticity confinement (Fedkiw, Stam, Jensen 2001) for a MAC velocity field.
+ *
+ * Three passes:
+ *
+ *   1. average the face velocities to cell centers (exact on the staggered
+ *      layout: two faces per axis),
+ *   2. ω = ∇×v and |ω| at centers by central differences (interior cells;
+ *      the boundary ring and solid cells get 0),
+ *   3. the confinement force f = ε·(N × ω), N = ∇|ω|/|∇|ω||, is computed per
+ *      cell and scattered to the cell's six faces at half weight each —
+ *      interior faces accumulate halves from both neighbours, recovering the
+ *      face-centered average of the cell forces. Pinned faces (adjacent
+ *      solid) receive nothing.
+ *
+ * See {@link v3_grid_apply_vorticity_confinement} for the scheme rationale
+ * and the energy note (confinement ADDS energy; pair with damping).
+ *
+ * @param {Float32Array} vel_u  Mutated in place, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v  Mutated in place.
+ * @param {Float32Array} vel_w  Mutated in place.
+ * @param {Uint8Array} face_solid_x  Pinned-face masks.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Float32Array} scratch_cu  Cell-count working buffers (callers may
+ *     pass larger, e.g. face-sized, arrays). All mutated.
+ * @param {Float32Array} scratch_cv
+ * @param {Float32Array} scratch_cw
+ * @param {Float32Array} scratch_wx
+ * @param {Float32Array} scratch_wy
+ * @param {Float32Array} scratch_wz
+ * @param {Float32Array} scratch_wmag
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} epsilon_dt  Confinement strength ε times the timestep.
+ * @param {Uint8Array} solid
+ */
+export function v3_mac_apply_vorticity_confinement(
+    vel_u, vel_v, vel_w,
+    face_solid_x, face_solid_y, face_solid_z,
+    scratch_cu, scratch_cv, scratch_cw,
+    scratch_wx, scratch_wy, scratch_wz, scratch_wmag,
+    res_x, res_y, res_z,
+    epsilon_dt,
+    solid
+) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(scratch_cu.length, cell_count, "scratch_cu covers grid");
+    assert.greaterThanOrEqual(scratch_wmag.length, cell_count, "scratch_wmag covers grid");
+    assert.isNumber(epsilon_dt, "epsilon_dt");
+    assert.greaterThanOrEqual(epsilon_dt, 0, "epsilon_dt");
+
+    if (epsilon_dt === 0) {
+        return;
+    }
+
+    const cell_slice = res_x * res_y;
+    const sx = res_x + 1;
+    const v_slice = res_x * (res_y + 1);
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    // ─── pass 1: face → center averages ─────────────────────────────────────
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const u_z = z * sx * res_y;
+        const v_z = z * v_slice;
+        for (let y = 0; y < res_y; y++) {
+            const c_y = c_z + y * res_x;
+            const u_y = u_z + y * sx;
+            const v_lo = v_z + y * res_x;
+            const w_lo = c_z + y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const c = c_y + x;
+                if (solid[c] !== 0) {
+                    scratch_cu[c] = 0;
+                    scratch_cv[c] = 0;
+                    scratch_cw[c] = 0;
+                    continue;
+                }
+                scratch_cu[c] = 0.5 * (vel_u[u_y + x] + vel_u[u_y + x + 1]);
+                scratch_cv[c] = 0.5 * (vel_v[v_lo + x] + vel_v[v_lo + res_x + x]);
+                scratch_cw[c] = 0.5 * (vel_w[w_lo + x] + vel_w[w_lo + cell_slice + x]);
+            }
+        }
+    }
+
+    // ─── pass 2: ω = ∇×v and |ω| at centers ─────────────────────────────────
+    scratch_wx.fill(0, 0, cell_count);
+    scratch_wy.fill(0, 0, cell_count);
+    scratch_wz.fill(0, 0, cell_count);
+    scratch_wmag.fill(0, 0, cell_count);
+
+    for (let z = 1; z < last_z; z++) {
+        const c_z = z * cell_slice;
+        for (let y = 1; y < last_y; y++) {
+            const c_y = c_z + y * res_x;
+            for (let x = 1; x < last_x; x++) {
+                const c = c_y + x;
+                if (solid[c] !== 0) {
+                    continue;
+                }
+                const wx = 0.5 * ((scratch_cw[c + res_x] - scratch_cw[c - res_x]) - (scratch_cv[c + cell_slice] - scratch_cv[c - cell_slice]));
+                const wy = 0.5 * ((scratch_cu[c + cell_slice] - scratch_cu[c - cell_slice]) - (scratch_cw[c + 1] - scratch_cw[c - 1]));
+                const wz = 0.5 * ((scratch_cv[c + 1] - scratch_cv[c - 1]) - (scratch_cu[c + res_x] - scratch_cu[c - res_x]));
+                scratch_wx[c] = wx;
+                scratch_wy[c] = wy;
+                scratch_wz[c] = wz;
+                scratch_wmag[c] = Math.sqrt(wx * wx + wy * wy + wz * wz);
+            }
+        }
+    }
+
+    // ─── pass 3: f = ε·(N × ω) per cell, scattered to faces ─────────────────
+    const magnitude_floor = 1e-10;
+
+    for (let z = 1; z < last_z; z++) {
+        const c_z = z * cell_slice;
+        const u_z = z * sx * res_y;
+        const v_z = z * v_slice;
+        for (let y = 1; y < last_y; y++) {
+            const c_y = c_z + y * res_x;
+            const u_y = u_z + y * sx;
+            const v_lo = v_z + y * res_x;
+            const w_lo = c_z + y * res_x;
+            for (let x = 1; x < last_x; x++) {
+                const c = c_y + x;
+                if (solid[c] !== 0) {
+                    continue;
+                }
+
+                const gx = 0.5 * (scratch_wmag[c + 1] - scratch_wmag[c - 1]);
+                const gy = 0.5 * (scratch_wmag[c + res_x] - scratch_wmag[c - res_x]);
+                const gz = 0.5 * (scratch_wmag[c + cell_slice] - scratch_wmag[c - cell_slice]);
+
+                const g_len = Math.sqrt(gx * gx + gy * gy + gz * gz);
+                if (g_len < magnitude_floor) {
+                    continue;
+                }
+                const s = epsilon_dt / g_len;
+
+                const wx = scratch_wx[c];
+                const wy = scratch_wy[c];
+                const wz = scratch_wz[c];
+                const fx = 0.5 * s * (gy * wz - gz * wy);
+                const fy = 0.5 * s * (gz * wx - gx * wz);
+                const fz = 0.5 * s * (gx * wy - gy * wx);
+
+                const u_l = u_y + x;
+                if (face_solid_x[u_l] === 0) vel_u[u_l] += fx;
+                if (face_solid_x[u_l + 1] === 0) vel_u[u_l + 1] += fx;
+                const v_b = v_lo + x;
+                if (face_solid_y[v_b] === 0) vel_v[v_b] += fy;
+                if (face_solid_y[v_b + res_x] === 0) vel_v[v_b + res_x] += fy;
+                const w_n = w_lo + x;
+                if (face_solid_z[w_n] === 0) vel_w[w_n] += fz;
+                if (face_solid_z[w_n + cell_slice] === 0) vel_w[w_n + cell_slice] += fz;
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_mac_clip_trace.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Clip a semi-Lagrangian trace segment against solid cells.
+ *
+ * Back-traces (and MacCormack's forward probes) are straight segments from a
+ * known-fluid start position toward an end position computed from the carrier
+ * velocity. When the end lands inside a solid cell, sampling there reads
+ * frozen in-wall values — the source of scalar bleed through walls and of
+ * velocity tunnelling into disconnected pockets. This helper walks the
+ * segment back by bisection until the end point is in fluid again.
+ *
+ * Positions are in CELL-CENTER coordinates: cell `(i, j, k)` spans
+ * `[i−0.5, i+0.5)` per axis, so the cell containing a point is `round(p)`,
+ * clamped to the grid (consistent with the samplers' clamped reads —
+ * out-of-grid points belong to the nearest edge cell).
+ *
+ * Four bisection iterations resolve the boundary to 1/16 of the segment —
+ * sub-cell precision at production CFL (segments span ≲ 1.5 cells). A
+ * re-entrant segment (exits fluid, crosses a thin wall, re-enters) clips at
+ * one of its boundaries rather than the first — acceptable at these segment
+ * lengths, and strictly better than sampling inside the wall.
+ *
+ * The result is written into `out[0..2]`. If the end point is already in
+ * fluid the end coordinates are written unchanged.
+ *
+ * PERFORMANCE CONTRACT: this function contains a loop, which keeps V8 from
+ * inlining it — a per-face call costs several times the entire surrounding
+ * advection body (measured 8.6× on the SL kernel). Hot kernels must inline
+ * the "is the end cell fluid?" test themselves (the `(p + 0.5) | 0` + clamp
+ * + one byte load below) and call this helper only on the rare wall hit.
+ *
+ * @param {Float32Array|number[]} out  length-3 destination for the clipped end.
+ * @param {Uint8Array} solid           Cell-centered solid flags.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} start_x  Known-fluid segment start (cell-center coords).
+ * @param {number} start_y
+ * @param {number} start_z
+ * @param {number} end_x    Desired segment end.
+ * @param {number} end_y
+ * @param {number} end_z
+ */
+export function v3_mac_clip_trace(out: Float32Array | number[], solid: Uint8Array, res_x: number, res_y: number, res_z: number, start_x: number, start_y: number, start_z: number, end_x: number, end_y: number, end_z: number): void;
+//# sourceMappingURL=v3_mac_clip_trace.d.ts.map

package/src/engine/physics/fluid/solver/v3_mac_clip_trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_clip_trace.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_clip_trace.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,uCAZW,YAAY,GAAC,MAAM,EAAE,SACrB,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QA4BhB"}

package/src/engine/physics/fluid/solver/v3_mac_clip_trace.js

@@ -0,0 +1,95 @@
+/**
+ * Clip a semi-Lagrangian trace segment against solid cells.
+ *
+ * Back-traces (and MacCormack's forward probes) are straight segments from a
+ * known-fluid start position toward an end position computed from the carrier
+ * velocity. When the end lands inside a solid cell, sampling there reads
+ * frozen in-wall values — the source of scalar bleed through walls and of
+ * velocity tunnelling into disconnected pockets. This helper walks the
+ * segment back by bisection until the end point is in fluid again.
+ *
+ * Positions are in CELL-CENTER coordinates: cell `(i, j, k)` spans
+ * `[i−0.5, i+0.5)` per axis, so the cell containing a point is `round(p)`,
+ * clamped to the grid (consistent with the samplers' clamped reads —
+ * out-of-grid points belong to the nearest edge cell).
+ *
+ * Four bisection iterations resolve the boundary to 1/16 of the segment —
+ * sub-cell precision at production CFL (segments span ≲ 1.5 cells). A
+ * re-entrant segment (exits fluid, crosses a thin wall, re-enters) clips at
+ * one of its boundaries rather than the first — acceptable at these segment
+ * lengths, and strictly better than sampling inside the wall.
+ *
+ * The result is written into `out[0..2]`. If the end point is already in
+ * fluid the end coordinates are written unchanged.
+ *
+ * PERFORMANCE CONTRACT: this function contains a loop, which keeps V8 from
+ * inlining it — a per-face call costs several times the entire surrounding
+ * advection body (measured 8.6× on the SL kernel). Hot kernels must inline
+ * the "is the end cell fluid?" test themselves (the `(p + 0.5) | 0` + clamp
+ * + one byte load below) and call this helper only on the rare wall hit.
+ *
+ * @param {Float32Array|number[]} out  length-3 destination for the clipped end.
+ * @param {Uint8Array} solid           Cell-centered solid flags.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} start_x  Known-fluid segment start (cell-center coords).
+ * @param {number} start_y
+ * @param {number} start_z
+ * @param {number} end_x    Desired segment end.
+ * @param {number} end_y
+ * @param {number} end_z
+ */
+export function v3_mac_clip_trace(out, solid, res_x, res_y, res_z, start_x, start_y, start_z, end_x, end_y, end_z) {
+    if (!point_in_solid(solid, res_x, res_y, res_z, end_x, end_y, end_z)) {
+        out[0] = end_x;
+        out[1] = end_y;
+        out[2] = end_z;
+        return;
+    }
+
+    // Bisect t ∈ [t_fluid, t_solid] on p(t) = start + t·(end − start).
+    let t_fluid = 0;
+    let t_solid = 1;
+    for (let i = 0; i < 4; i++) {
+        const t = 0.5 * (t_fluid + t_solid);
+        const px = start_x + t * (end_x - start_x);
+        const py = start_y + t * (end_y - start_y);
+        const pz = start_z + t * (end_z - start_z);
+        if (point_in_solid(solid, res_x, res_y, res_z, px, py, pz)) {
+            t_solid = t;
+        } else {
+            t_fluid = t;
+        }
+    }
+
+    out[0] = start_x + t_fluid * (end_x - start_x);
+    out[1] = start_y + t_fluid * (end_y - start_y);
+    out[2] = start_z + t_fluid * (end_z - start_z);
+}
+
+/**
+ * Whether the cell containing the point (clamped to the grid) is solid.
+ *
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} px  cell-center coordinates
+ * @param {number} py
+ * @param {number} pz
+ * @return {boolean}
+ */
+function point_in_solid(solid, res_x, res_y, res_z, px, py, pz) {
+    // (p + 0.5) | 0 is round-half-up for p ≥ −0.5 and truncates toward zero
+    // below that — the subsequent clamp makes both behaviours land on the
+    // same edge cell, so the result matches Math.round + clamp everywhere
+    // it matters, at a fraction of the cost.
+    let x = (px + 0.5) | 0;
+    let y = (py + 0.5) | 0;
+    let z = (pz + 0.5) | 0;
+    if (x < 0) x = 0; else if (x >= res_x) x = res_x - 1;
+    if (y < 0) y = 0; else if (y >= res_y) y = res_y - 1;
+    if (z < 0) z = 0; else if (z >= res_z) z = res_z - 1;
+    return solid[z * res_x * res_y + y * res_x + x] !== 0;
+}

package/src/engine/physics/fluid/solver/v3_mac_compute_divergence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Divergence of a MAC (staggered, face-centered) velocity field into a
+ * cell-centered scalar field:
+ *
+ *     div(c) = (u[x+1] − u[x]) + (v[y+1] − v[y]) + (w[z+1] − w[z])     (h = 1)
+ *
+ * The defining advantage over the collocated central-difference form: this
+ * divergence is the EXACT adjoint of {@link v3_mac_subtract_pressure_gradient}
+ * composed with the 7-point Laplacian in {@link v3_grid_solve_pressure} —
+ * an exact pressure solve drives this divergence to exactly zero. No
+ * operator-mismatch floor, no projection-invisible checkerboard mode, no
+ * boundary special cases (boundary faces exist and carry real outflow).
+ *
+ * PINNED faces (either adjacent cell solid) are read at face value — their
+ * stored velocity IS the wall's normal velocity (see
+ * {@link v3_mac_compute_face_solid}): zero for static solids, the wall's
+ * speed for moving ones. A moving wall therefore appears here as divergence
+ * in the adjacent fluid cells, and the pressure solve turns that into the
+ * push/suction the wall exerts — the standard MAC moving-boundary mechanism.
+ * Stray writes into pinned faces cannot masquerade as wall motion: the face
+ * mask rebuild zeroes velocities on every unpinned→pinned transition, and
+ * all transport/effector kernels skip pinned faces.
+ *
+ * Solid cells get divergence 0 — they are not degrees of freedom.
+ *
+ * Face grid layout: see {@link v3_mac_compute_face_solid}.
+ *
+ * @param {Float32Array} divergence  Destination, cell-centered. Mutated.
+ * @param {Float32Array} vel_u       x-face velocities, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v       y-face velocities, res_x·(res_y+1)·res_z.
+ * @param {Float32Array} vel_w       z-face velocities, res_x·res_y·(res_z+1).
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid         Cell-centered solid flags.
+ */
+export function v3_mac_compute_divergence(divergence: Float32Array, vel_u: Float32Array, vel_v: Float32Array, vel_w: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_compute_divergence.d.ts.map

package/src/engine/physics/fluid/solver/v3_mac_compute_divergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_compute_divergence.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_compute_divergence.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,sDATW,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,QAwCpB"}

package/src/engine/physics/fluid/solver/v3_mac_compute_divergence.js

@@ -0,0 +1,77 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Divergence of a MAC (staggered, face-centered) velocity field into a
+ * cell-centered scalar field:
+ *
+ *     div(c) = (u[x+1] − u[x]) + (v[y+1] − v[y]) + (w[z+1] − w[z])     (h = 1)
+ *
+ * The defining advantage over the collocated central-difference form: this
+ * divergence is the EXACT adjoint of {@link v3_mac_subtract_pressure_gradient}
+ * composed with the 7-point Laplacian in {@link v3_grid_solve_pressure} —
+ * an exact pressure solve drives this divergence to exactly zero. No
+ * operator-mismatch floor, no projection-invisible checkerboard mode, no
+ * boundary special cases (boundary faces exist and carry real outflow).
+ *
+ * PINNED faces (either adjacent cell solid) are read at face value — their
+ * stored velocity IS the wall's normal velocity (see
+ * {@link v3_mac_compute_face_solid}): zero for static solids, the wall's
+ * speed for moving ones. A moving wall therefore appears here as divergence
+ * in the adjacent fluid cells, and the pressure solve turns that into the
+ * push/suction the wall exerts — the standard MAC moving-boundary mechanism.
+ * Stray writes into pinned faces cannot masquerade as wall motion: the face
+ * mask rebuild zeroes velocities on every unpinned→pinned transition, and
+ * all transport/effector kernels skip pinned faces.
+ *
+ * Solid cells get divergence 0 — they are not degrees of freedom.
+ *
+ * Face grid layout: see {@link v3_mac_compute_face_solid}.
+ *
+ * @param {Float32Array} divergence  Destination, cell-centered. Mutated.
+ * @param {Float32Array} vel_u       x-face velocities, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v       y-face velocities, res_x·(res_y+1)·res_z.
+ * @param {Float32Array} vel_w       z-face velocities, res_x·res_y·(res_z+1).
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid         Cell-centered solid flags.
+ */
+export function v3_mac_compute_divergence(divergence, vel_u, vel_v, vel_w, res_x, res_y, res_z, solid) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(divergence.length, cell_count, "divergence covers grid");
+    assert.greaterThanOrEqual(vel_u.length, (res_x + 1) * res_y * res_z, "vel_u covers grid");
+    assert.greaterThanOrEqual(vel_v.length, res_x * (res_y + 1) * res_z, "vel_v covers grid");
+    assert.greaterThanOrEqual(vel_w.length, res_x * res_y * (res_z + 1), "vel_w covers grid");
+    assert.greaterThanOrEqual(solid.length, cell_count, "solid covers grid");
+
+    const cell_slice = res_x * res_y;
+    const sx = res_x + 1;
+
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const u_z = z * sx * res_y;
+        const v_z = z * res_x * (res_y + 1);
+
+        for (let y = 0; y < res_y; y++) {
+            const c_y = c_z + y * res_x;
+            const u_y = u_z + y * sx;
+            const v_lo = v_z + y * res_x;
+            const v_hi = v_lo + res_x;
+            const w_lo = c_z + y * res_x;              // z-face slice size == cell slice
+            const w_hi = w_lo + cell_slice;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = c_y + x;
+
+                if (solid[c] !== 0) {
+                    divergence[c] = 0;
+                    continue;
+                }
+
+                divergence[c] = (vel_u[u_y + x + 1] - vel_u[u_y + x])
+                    + (vel_v[v_hi + x] - vel_v[v_lo + x])
+                    + (vel_w[w_hi + x] - vel_w[w_lo + x]);
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_mac_compute_face_solid.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bake the per-face "pinned" masks for a MAC (staggered) velocity layout,
+ * zeroing the velocity of faces that just BECAME pinned.
+ *
+ * A face is PINNED (`1`) when either adjacent cell is solid: its normal
+ * velocity is a BOUNDARY CONDITION, not a degree of freedom. The stored value
+ * of a pinned face is the wall's normal velocity — `0` for static solids,
+ * non-zero for moving ones ({@link FluidObstacleSystem} writes those). Every
+ * fluid kernel honours the contract: the divergence reads pinned values (a
+ * moving wall pushes fluid), the pressure-gradient subtraction and advection
+ * leave them untouched, effectors and damping skip them.
+ *
+ * Transition rules, applied per face as the masks are rebuilt:
+ *
+ *   - unpinned → pinned: the face velocity is ZEROED — the static-wall
+ *     default, and the guard that keeps stale fluid velocity from
+ *     masquerading as wall motion. A solid author who wants a moving wall
+ *     writes the face velocity AFTER this recompute (the obstacle system
+ *     does exactly that).
+ *   - pinned → pinned: the value is PRESERVED — boundary conditions written
+ *     by the solid's owner survive subsequent recomputes.
+ *   - pinned → unpinned: the value is preserved too — fluid uncovered by a
+ *     retreating wall inherits the wall's velocity, which is the physically
+ *     sensible seed (and free wake generation).
+ *
+ * Domain-edge faces (between a cell and the outside) are NOT pinned — the
+ * domain boundary is open (ghost pressure 0; see
+ * {@link v3_grid_compute_solid_neighbour_mask}) and flow vents through it.
+ *
+ * Face grids and their indexing:
+ *
+ *     face_x : (res_x+1) × res_y × res_z, index z·(res_x+1)·res_y + y·(res_x+1) + x
+ *              face (x, y, z) sits between cells (x−1, y, z) and (x, y, z)
+ *     face_y : res_x × (res_y+1) × res_z, index z·res_x·(res_y+1) + y·res_x + x
+ *     face_z : res_x × res_y × (res_z+1), index z·res_x·res_y + y·res_x + x
+ *
+ * O(faces) — two byte-reads per interior face plus the in-place transition
+ * comparison. Mask outputs are fully replaced.
+ *
+ * @param {Uint8Array} face_x  Pin mask, length ≥ (res_x+1)·res_y·res_z. Mutated.
+ * @param {Uint8Array} face_y  Pin mask, length ≥ res_x·(res_y+1)·res_z. Mutated.
+ * @param {Uint8Array} face_z  Pin mask, length ≥ res_x·res_y·(res_z+1). Mutated.
+ * @param {Float32Array} vel_u  x-face velocities — zeroed on 0→1 pin transition.
+ * @param {Float32Array} vel_v  y-face velocities.
+ * @param {Float32Array} vel_w  z-face velocities.
+ * @param {Uint8Array} solid   Cell-centered solid flags. Non-zero = solid.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_mac_compute_face_solid(face_x: Uint8Array, face_y: Uint8Array, face_z: Uint8Array, vel_u: Float32Array, vel_v: Float32Array, vel_w: Float32Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number): void;
+//# sourceMappingURL=v3_mac_compute_face_solid.d.ts.map

package/src/engine/physics/fluid/solver/v3_mac_compute_face_solid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_compute_face_solid.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_compute_face_solid.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,kDAXW,UAAU,UACV,UAAU,UACV,UAAU,SACV,YAAY,SACZ,YAAY,SACZ,YAAY,SACZ,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAgFhB"}

package/src/engine/physics/fluid/solver/v3_mac_compute_face_solid.js

@@ -0,0 +1,131 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Bake the per-face "pinned" masks for a MAC (staggered) velocity layout,
+ * zeroing the velocity of faces that just BECAME pinned.
+ *
+ * A face is PINNED (`1`) when either adjacent cell is solid: its normal
+ * velocity is a BOUNDARY CONDITION, not a degree of freedom. The stored value
+ * of a pinned face is the wall's normal velocity — `0` for static solids,
+ * non-zero for moving ones ({@link FluidObstacleSystem} writes those). Every
+ * fluid kernel honours the contract: the divergence reads pinned values (a
+ * moving wall pushes fluid), the pressure-gradient subtraction and advection
+ * leave them untouched, effectors and damping skip them.
+ *
+ * Transition rules, applied per face as the masks are rebuilt:
+ *
+ *   - unpinned → pinned: the face velocity is ZEROED — the static-wall
+ *     default, and the guard that keeps stale fluid velocity from
+ *     masquerading as wall motion. A solid author who wants a moving wall
+ *     writes the face velocity AFTER this recompute (the obstacle system
+ *     does exactly that).
+ *   - pinned → pinned: the value is PRESERVED — boundary conditions written
+ *     by the solid's owner survive subsequent recomputes.
+ *   - pinned → unpinned: the value is preserved too — fluid uncovered by a
+ *     retreating wall inherits the wall's velocity, which is the physically
+ *     sensible seed (and free wake generation).
+ *
+ * Domain-edge faces (between a cell and the outside) are NOT pinned — the
+ * domain boundary is open (ghost pressure 0; see
+ * {@link v3_grid_compute_solid_neighbour_mask}) and flow vents through it.
+ *
+ * Face grids and their indexing:
+ *
+ *     face_x : (res_x+1) × res_y × res_z, index z·(res_x+1)·res_y + y·(res_x+1) + x
+ *              face (x, y, z) sits between cells (x−1, y, z) and (x, y, z)
+ *     face_y : res_x × (res_y+1) × res_z, index z·res_x·(res_y+1) + y·res_x + x
+ *     face_z : res_x × res_y × (res_z+1), index z·res_x·res_y + y·res_x + x
+ *
+ * O(faces) — two byte-reads per interior face plus the in-place transition
+ * comparison. Mask outputs are fully replaced.
+ *
+ * @param {Uint8Array} face_x  Pin mask, length ≥ (res_x+1)·res_y·res_z. Mutated.
+ * @param {Uint8Array} face_y  Pin mask, length ≥ res_x·(res_y+1)·res_z. Mutated.
+ * @param {Uint8Array} face_z  Pin mask, length ≥ res_x·res_y·(res_z+1). Mutated.
+ * @param {Float32Array} vel_u  x-face velocities — zeroed on 0→1 pin transition.
+ * @param {Float32Array} vel_v  y-face velocities.
+ * @param {Float32Array} vel_w  z-face velocities.
+ * @param {Uint8Array} solid   Cell-centered solid flags. Non-zero = solid.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_mac_compute_face_solid(face_x, face_y, face_z, vel_u, vel_v, vel_w, solid, res_x, res_y, res_z) {
+    const cells = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(face_x.length, (res_x + 1) * res_y * res_z, "face_x covers grid");
+    assert.greaterThanOrEqual(face_y.length, res_x * (res_y + 1) * res_z, "face_y covers grid");
+    assert.greaterThanOrEqual(face_z.length, res_x * res_y * (res_z + 1), "face_z covers grid");
+    assert.greaterThanOrEqual(vel_u.length, (res_x + 1) * res_y * res_z, "vel_u covers grid");
+    assert.greaterThanOrEqual(vel_v.length, res_x * (res_y + 1) * res_z, "vel_v covers grid");
+    assert.greaterThanOrEqual(vel_w.length, res_x * res_y * (res_z + 1), "vel_w covers grid");
+    assert.greaterThanOrEqual(solid.length, cells, "solid covers grid");
+
+    const cell_slice = res_x * res_y;
+
+    // x-faces.
+    const sx = res_x + 1;
+    for (let z = 0; z < res_z; z++) {
+        const cz = z * cell_slice;
+        const fz = z * sx * res_y;
+        for (let y = 0; y < res_y; y++) {
+            const cy = cz + y * res_x;
+            const fy = fz + y * sx;
+            // Domain-edge faces are open, never pinned.
+            face_x[fy] = 0;
+            face_x[fy + res_x] = 0;
+            for (let x = 1; x < res_x; x++) {
+                const f = fy + x;
+                const pinned = (solid[cy + x - 1] !== 0 || solid[cy + x] !== 0) ? 1 : 0;
+                if (pinned === 1 && face_x[f] === 0) {
+                    vel_u[f] = 0;
+                }
+                face_x[f] = pinned;
+            }
+        }
+    }
+
+    // y-faces.
+    for (let z = 0; z < res_z; z++) {
+        const cz = z * cell_slice;
+        const fz = z * res_x * (res_y + 1);
+        for (let x = 0; x < res_x; x++) {
+            face_y[fz + x] = 0;
+            face_y[fz + res_y * res_x + x] = 0;
+        }
+        for (let y = 1; y < res_y; y++) {
+            const cy_below = cz + (y - 1) * res_x;
+            const cy_above = cz + y * res_x;
+            const fy = fz + y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const f = fy + x;
+                const pinned = (solid[cy_below + x] !== 0 || solid[cy_above + x] !== 0) ? 1 : 0;
+                if (pinned === 1 && face_y[f] === 0) {
+                    vel_v[f] = 0;
+                }
+                face_y[f] = pinned;
+            }
+        }
+    }
+
+    // z-faces (face slice size equals the cell slice size).
+    for (let y = 0; y < res_y; y++) {
+        const row = y * res_x;
+        for (let x = 0; x < res_x; x++) {
+            face_z[row + x] = 0;
+            face_z[res_z * cell_slice + row + x] = 0;
+        }
+    }
+    for (let z = 1; z < res_z; z++) {
+        const c_below = (z - 1) * cell_slice;
+        const c_above = z * cell_slice;
+        const fz = z * cell_slice;
+        for (let i = 0; i < cell_slice; i++) {
+            const f = fz + i;
+            const pinned = (solid[c_below + i] !== 0 || solid[c_above + i] !== 0) ? 1 : 0;
+            if (pinned === 1 && face_z[f] === 0) {
+                vel_w[f] = 0;
+            }
+            face_z[f] = pinned;
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_mac_subtract_pressure_gradient.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Subtract the pressure gradient from a MAC velocity field in place — the
+ * face-exact counterpart of the collocated
+ * {@link v3_grid_subtract_pressure_gradient}:
+ *
+ *     u(face) −= p(right cell) − p(left cell)        (h = 1)
+ *
+ * Per face:
+ *   - both adjacent cells fluid: subtract the pressure difference.
+ *   - PINNED face (either adjacent cell solid): SKIPPED — its stored value is
+ *     the wall's normal-velocity boundary condition (0 for static solids,
+ *     the wall speed for movers; see {@link v3_mac_compute_face_solid}) and
+ *     must survive the projection. Stray deposits are prevented upstream:
+ *     the mask rebuild zeroes faces on every unpinned→pinned transition and
+ *     every transport/effector kernel skips pinned faces.
+ *   - domain-edge face (open boundary): the missing cell is the Dirichlet
+ *     ghost p = 0, so interior pressure vents flow out through the face.
+ *
+ * Together with {@link v3_mac_compute_divergence} and the unchanged 7-point
+ * solve this forms an exact discrete Helmholtz projection: solve error aside,
+ * post-projection divergence is zero — including immediately beside walls,
+ * which the collocated form could only approximate.
+ *
+ * Face grid layout: see {@link v3_mac_compute_face_solid}.
+ *
+ * @param {Float32Array} vel_u  Mutated in place, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v  Mutated in place, res_x·(res_y+1)·res_z.
+ * @param {Float32Array} vel_w  Mutated in place, res_x·res_y·(res_z+1).
+ * @param {Float32Array|Float16Array} pressure  Cell-centered, from the solve.
+ * @param {Uint8Array} face_solid_x  From {@link v3_mac_compute_face_solid}.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_mac_subtract_pressure_gradient(vel_u: Float32Array, vel_v: Float32Array, vel_w: Float32Array, pressure: Float32Array | Float16Array, face_solid_x: Uint8Array, face_solid_y: Uint8Array, face_solid_z: Uint8Array, res_x: number, res_y: number, res_z: number): void;
+//# sourceMappingURL=v3_mac_subtract_pressure_gradient.d.ts.map

package/src/engine/physics/fluid/solver/v3_mac_subtract_pressure_gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,yDAXW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,eAAa,gBACzB,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAmEhB"}