@woosh/meep-engine 2.157.0 → 2.159.0

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

@@ -0,0 +1,236 @@
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { v3_grid_sample_scalar_masked } from "./v3_grid_sample_scalar_masked.js";
+import { v3_mac_clip_trace } from "./v3_mac_clip_trace.js";
+
+const scratch_clip = new Float32Array(3);
+
+/**
+ * Straight-line (loop-free, inlinable) test: is the cell containing the
+ * point solid? Same rounding/clamping as v3_mac_clip_trace. Kernels use this
+ * inline per trace and call the loop-bearing clip helper only on a hit — see
+ * the performance contract on {@link v3_mac_clip_trace}.
+ *
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @return {boolean}
+ */
+function end_in_solid(solid, res_x, res_y, res_z, px, py, pz) {
+    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;
+}
+
+
+/**
+ * Semi-Lagrangian advection of a cell-centered scalar by a MAC velocity
+ * field, solid-aware on both ends of the trace:
+ *
+ *   - the back-trace segment is CLIPPED against solid cells
+ *     ({@link v3_mac_clip_trace}) so a trace can neither sample inside a wall
+ *     nor tunnel through a thin one into a disconnected pocket;
+ *   - the sample at the (clipped) source position uses solid-MASKED
+ *     interpolation ({@link v3_grid_sample_scalar_masked}) so taps inside
+ *     walls — frozen values from whenever the cell solidified — contribute
+ *     nothing. Without this, walls slowly leak their frozen contents into
+ *     passing fluid and absorb dye from it (the stage-5 scalar-mass defect).
+ *
+ * The carrier velocity at each cell center is the average of the cell's two
+ * faces per axis (exact on the staggered layout). Solid destination cells
+ * pass their value through unchanged.
+ *
+ * @param {Float32Array} output  Cell-centered destination. Mutated.
+ * @param {Float32Array} input   Cell-centered source. Must not alias output.
+ * @param {Float32Array} vel_u   x-face velocities, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v   y-face velocities.
+ * @param {Float32Array} vel_w   z-face velocities.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid
+ */
+export function v3_mac_advect_sl_scalar(output, input, vel_u, vel_v, vel_w, res_x, res_y, res_z, time_delta, solid) {
+    assert.notEqual(output, input, "output must not alias input");
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(output.length, cell_count, "output covers grid");
+    assert.greaterThanOrEqual(input.length, cell_count, "input covers grid");
+
+    const cell_slice = res_x * res_y;
+    const sx = res_x + 1;
+    const v_slice = res_x * (res_y + 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 * 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) {
+                    output[c] = input[c];
+                    continue;
+                }
+                const cu = 0.5 * (vel_u[u_y + x] + vel_u[u_y + x + 1]);
+                const cv = 0.5 * (vel_v[v_lo + x] + vel_v[v_lo + res_x + x]);
+                const cw = 0.5 * (vel_w[w_lo + x] + vel_w[w_lo + cell_slice + x]);
+
+                let bx = x - cu * time_delta;
+                let by = y - cv * time_delta;
+                let bz = z - cw * time_delta;
+                if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, z, bx, by, bz);
+                    bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                }
+
+                output[c] = v3_grid_sample_scalar_masked(input, solid, res_x, res_y, res_z,
+                    bx, by, bz, input[c]);
+            }
+        }
+    }
+}
+
+/**
+ * Unconditionally stable MacCormack advection of a cell-centered scalar by a
+ * MAC velocity field — forward + backward semi-Lagrangian passes, error
+ * correction, and Selle's monotone min-max limiter. Solid-aware throughout:
+ * both passes clip their traces and sample solid-masked (see
+ * {@link v3_mac_advect_sl_scalar}), and the limiter takes its extrema over
+ * the FLUID corners around the back-traced position only — when none are
+ * fluid the corrected value is discarded in favour of the first-order
+ * forward result.
+ *
+ * @param {Float32Array} output           Destination. Mutated.
+ * @param {Float32Array} input            Source. NOT mutated.
+ * @param {Float32Array} forward_scratch  Working buffer for the forward pass.
+ * @param {Float32Array} vel_u
+ * @param {Float32Array} vel_v
+ * @param {Float32Array} vel_w
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid
+ */
+export function v3_mac_advect_maccormack_scalar(output, input, forward_scratch, vel_u, vel_v, vel_w, res_x, res_y, res_z, time_delta, solid) {
+    assert.notEqual(output, input, "output must not alias input");
+    assert.notEqual(output, forward_scratch, "output must not alias forward_scratch");
+    assert.notEqual(input, forward_scratch, "input must not alias forward_scratch");
+
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(forward_scratch.length, cell_count, "forward_scratch covers grid");
+
+    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;
+
+    const fwd = forward_scratch;
+
+    // ─── pass 1: forward SL step into the scratch ─────────────────────────────
+    v3_mac_advect_sl_scalar(fwd, input, vel_u, vel_v, vel_w, res_x, res_y, res_z, time_delta, solid);
+
+    // ─── pass 2: backward step, correction, monotone limit ──────────────────
+    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) {
+                    output[c] = input[c];
+                    continue;
+                }
+
+                const cu = 0.5 * (vel_u[u_y + x] + vel_u[u_y + x + 1]) * time_delta;
+                const cv = 0.5 * (vel_v[v_lo + x] + vel_v[v_lo + res_x + x]) * time_delta;
+                const cw = 0.5 * (vel_w[w_lo + x] + vel_w[w_lo + cell_slice + x]) * time_delta;
+
+                // Reverse probe through the forward result, clipped + masked.
+                let qx = x + cu;
+                let qy = y + cv;
+                let qz = z + cw;
+                if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, z, qx, qy, qz);
+                    qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                }
+                const backward = v3_grid_sample_scalar_masked(fwd, solid, res_x, res_y, res_z,
+                    qx, qy, qz, fwd[c]);
+
+                const corrected = fwd[c] + 0.5 * (input[c] - backward);
+
+                // Limiter bounds: extrema of the FLUID cells among the 8 around
+                // the (clipped) back-traced position.
+                let tx = x - cu;
+                let ty = y - cv;
+                let tz = z - cw;
+                if (end_in_solid(solid, res_x, res_y, res_z, tx, ty, tz)) {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, z, tx, ty, tz);
+                    tx = scratch_clip[0]; ty = scratch_clip[1]; tz = scratch_clip[2];
+                }
+                const bx = clamp(tx, 0, last_x);
+                const by = clamp(ty, 0, last_y);
+                const bz = clamp(tz, 0, last_z);
+                const x0 = bx | 0;
+                const y0 = by | 0;
+                const z0 = bz | 0;
+                const x1 = bx === x0 ? x0 : x0 + 1;
+                const y1 = by === y0 ? y0 : y0 + 1;
+                const z1 = bz === z0 ? z0 : z0 + 1;
+
+                const z0_off = z0 * cell_slice;
+                const z1_off = z1 * cell_slice;
+                const y0_off = y0 * res_x;
+                const y1_off = y1 * res_x;
+
+                let mn = Infinity;
+                let mx = -Infinity;
+                let t = z0_off + y0_off + x0;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z0_off + y0_off + x1;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z0_off + y1_off + x0;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z0_off + y1_off + x1;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z1_off + y0_off + x0;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z1_off + y0_off + x1;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z1_off + y1_off + x0;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+                t = z1_off + y1_off + x1;
+                if (solid[t] === 0) { const v = input[t]; if (v < mn) mn = v; if (v > mx) mx = v; }
+
+                if (mn === Infinity) {
+                    // No fluid corner to bound against — fall back to the
+                    // first-order forward value.
+                    output[c] = fwd[c];
+                    continue;
+                }
+
+                output[c] = corrected < mn ? mn : (corrected > mx ? mx : corrected);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Semi-Lagrangian advection of a MAC (face-centered) velocity field along a
+ * separate MAC carrier field.
+ *
+ * Each component is updated on its own face lattice: for every face, the full
+ * carrier velocity AT the face position is reconstructed (own component read
+ * directly, the two cross components trilinearly interpolated from their
+ * lattices — the classic MAC 4-face average falls out of the interpolation),
+ * the position is traced backward by `carrier · dt`, and the SOURCE component
+ * is sampled at the traced position on its own lattice.
+ *
+ * PINNED faces (either adjacent cell solid — see
+ * {@link v3_mac_compute_face_solid}) pass their source value through
+ * unchanged: their velocity is a boundary condition owned by the projection,
+ * not transported state.
+ *
+ * Back-traces are CLIPPED against solid cells ({@link v3_mac_clip_trace}):
+ * a trace stops at the wall instead of sampling momentum from inside it or
+ * from a disconnected pocket on the far side. Sampling the face lattices
+ * near walls needs no masking — pinned faces hold valid boundary values.
+ *
+ * Position convention (cell-center coordinates): x-face `(i, j, k)` sits at
+ * `(i − 0.5, j, k)`; sampling component grids therefore offsets by +0.5 on
+ * the component's own axis. All positions clamp at the lattice edges.
+ *
+ * Aliasing: `outputs[i]` must not alias `sources[i]`, and outputs must not
+ * alias ANY carrier lattice — the per-face carrier reconstruction samples the
+ * OTHER components' lattices spatially, so an output lattice written earlier
+ * in the kernel would be re-read as carrier data later. Pass a copy when the
+ * carrier is the field being advected into (the simulator's reflection path
+ * does exactly that).
+ *
+ * @param {Float32Array[]} outputs  `[out_u, out_v, out_w]` face grids. Mutated.
+ * @param {Float32Array[]} sources  `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier  `[car_u, car_v, car_w]`. Drives the traces.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x  Pinned-face masks, one per lattice.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid         Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_sl_velocity(outputs: Float32Array[], sources: Float32Array[], carrier: Float32Array[], res_x: number, res_y: number, res_z: number, time_delta: number, face_solid_x: Uint8Array, face_solid_y: Uint8Array, face_solid_z: Uint8Array, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_advect_sl_velocity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_sl_velocity.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,mDAZW,YAAY,EAAE,WACd,YAAY,EAAE,WACd,YAAY,EAAE,SACd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,gBACN,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,UAAU,QAwKpB"}

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

@@ -0,0 +1,217 @@
+import { assert } from "../../../../core/assert.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+import { v3_mac_clip_trace } from "./v3_mac_clip_trace.js";
+
+const scratch_clip = new Float32Array(3);
+
+/**
+ * Semi-Lagrangian advection of a MAC (face-centered) velocity field along a
+ * separate MAC carrier field.
+ *
+ * Each component is updated on its own face lattice: for every face, the full
+ * carrier velocity AT the face position is reconstructed (own component read
+ * directly, the two cross components trilinearly interpolated from their
+ * lattices — the classic MAC 4-face average falls out of the interpolation),
+ * the position is traced backward by `carrier · dt`, and the SOURCE component
+ * is sampled at the traced position on its own lattice.
+ *
+ * PINNED faces (either adjacent cell solid — see
+ * {@link v3_mac_compute_face_solid}) pass their source value through
+ * unchanged: their velocity is a boundary condition owned by the projection,
+ * not transported state.
+ *
+ * Back-traces are CLIPPED against solid cells ({@link v3_mac_clip_trace}):
+ * a trace stops at the wall instead of sampling momentum from inside it or
+ * from a disconnected pocket on the far side. Sampling the face lattices
+ * near walls needs no masking — pinned faces hold valid boundary values.
+ *
+ * Position convention (cell-center coordinates): x-face `(i, j, k)` sits at
+ * `(i − 0.5, j, k)`; sampling component grids therefore offsets by +0.5 on
+ * the component's own axis. All positions clamp at the lattice edges.
+ *
+ * Aliasing: `outputs[i]` must not alias `sources[i]`, and outputs must not
+ * alias ANY carrier lattice — the per-face carrier reconstruction samples the
+ * OTHER components' lattices spatially, so an output lattice written earlier
+ * in the kernel would be re-read as carrier data later. Pass a copy when the
+ * carrier is the field being advected into (the simulator's reflection path
+ * does exactly that).
+ *
+ * @param {Float32Array[]} outputs  `[out_u, out_v, out_w]` face grids. Mutated.
+ * @param {Float32Array[]} sources  `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier  `[car_u, car_v, car_w]`. Drives the traces.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x  Pinned-face masks, one per lattice.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid         Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_sl_velocity(outputs, sources, carrier, res_x, res_y, res_z, time_delta, face_solid_x, face_solid_y, face_solid_z, solid) {
+    assert.equal(outputs.length, 3, "outputs is a 3-component array");
+    assert.equal(sources.length, 3, "sources is a 3-component array");
+    assert.equal(carrier.length, 3, "carrier is a 3-component array");
+
+    const out_u = outputs[0], out_v = outputs[1], out_w = outputs[2];
+    const src_u = sources[0], src_v = sources[1], src_w = sources[2];
+    const car_u = carrier[0], car_v = carrier[1], car_w = carrier[2];
+
+    assert.notEqual(out_u, src_u, "out_u must not alias src_u");
+    assert.notEqual(out_v, src_v, "out_v must not alias src_v");
+    assert.notEqual(out_w, src_w, "out_w must not alias src_w");
+
+    const sx = res_x + 1;
+    const sy = res_y + 1;
+    const sz = res_z + 1;
+    const cell_slice = res_x * res_y;
+    const u_slice = sx * res_y;
+    const v_slice = res_x * sy;
+    const last_cx = res_x - 1;
+    const last_cy = res_y - 1;
+    const last_cz = res_z - 1;
+
+    // Cross-component carrier reconstruction: a face position is grid-aligned
+    // in both cross axes, so the "trilinear sample" of the other lattice
+    // degenerates to the classic MAC 4-tap average with fixed ¼ weights —
+    // computed inline below instead of paying the general sampler. Only the
+    // tap index along the face's own axis needs edge clamping (the face
+    // lattice extends half a cell past the cross lattice there); the trilinear
+    // clamp the sampler would apply reduces to the same duplicated tap.
+
+    // ─── u (x-faces) ─────────────────────────────────────────────────────────
+    for (let z = 0; z < res_z; z++) {
+        const f_z = z * u_slice;
+        const v_z = z * v_slice;
+        const w_z = z * cell_slice;
+        for (let y = 0; y < res_y; y++) {
+            const f_y = f_z + y * sx;
+            const v_lo = v_z + y * res_x;
+            const v_hi = v_lo + res_x;
+            const w_lo = w_z + y * res_x;
+            const w_hi = w_lo + cell_slice;
+            for (let x = 0; x <= res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_x[f] !== 0) {
+                    out_u[f] = src_u[f];
+                    continue;
+                }
+                // Cross taps straddle the face in x: cells x−1 and x, clamped
+                // to the cross lattice's x range [0, res_x−1].
+                const xa = x > 0 ? x - 1 : 0;
+                const xb = x < res_x ? x : last_cx;
+                const cu = car_u[f];
+                const cv = 0.25 * (car_v[v_lo + xa] + car_v[v_lo + xb] + car_v[v_hi + xa] + car_v[v_hi + xb]);
+                const cw = 0.25 * (car_w[w_lo + xa] + car_w[w_lo + xb] + car_w[w_hi + xa] + car_w[w_hi + xb]);
+                // Face position is (x − 0.5, y, z) in cell coords. Inline the
+                // end-cell fluid test (see v3_mac_clip_trace performance
+                // contract); the loop-bearing clip helper runs only on a hit.
+                const ex = x - 0.5 - cu * time_delta;
+                const ey = y - cv * time_delta;
+                const ez = z - cw * time_delta;
+                let ecx = (ex + 0.5) | 0;
+                let ecy = (ey + 0.5) | 0;
+                let ecz = (ez + 0.5) | 0;
+                if (ecx < 0) ecx = 0; else if (ecx >= res_x) ecx = last_cx;
+                if (ecy < 0) ecy = 0; else if (ecy >= res_y) ecy = last_cy;
+                if (ecz < 0) ecz = 0; else if (ecz >= res_z) ecz = last_cz;
+                if (solid[ecz * cell_slice + ecy * res_x + ecx] === 0) {
+                    out_u[f] = scs3d_sample_linear(src_u, sx, res_y, res_z, ex + 0.5, ey, ez);
+                } else {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z,
+                        x - 0.5, y, z, ex, ey, ez);
+                    out_u[f] = scs3d_sample_linear(src_u, sx, res_y, res_z,
+                        scratch_clip[0] + 0.5, scratch_clip[1], scratch_clip[2]);
+                }
+            }
+        }
+    }
+
+    // ─── v (y-faces) ─────────────────────────────────────────────────────────
+    for (let z = 0; z < res_z; z++) {
+        const f_z = z * v_slice;
+        const u_z = z * u_slice;
+        const w_z = z * cell_slice;
+        for (let y = 0; y <= res_y; y++) {
+            const f_y = f_z + y * res_x;
+            const ya = y > 0 ? y - 1 : 0;
+            const yb = y < res_y ? y : last_cy;
+            const u_lo = u_z + ya * sx;
+            const u_hi = u_z + yb * sx;
+            const w_lo = w_z + ya * res_x;
+            const w_hi = w_z + yb * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_y[f] !== 0) {
+                    out_v[f] = src_v[f];
+                    continue;
+                }
+                const cu = 0.25 * (car_u[u_lo + x] + car_u[u_lo + x + 1] + car_u[u_hi + x] + car_u[u_hi + x + 1]);
+                const cv = car_v[f];
+                const cw = 0.25 * (car_w[w_lo + x] + car_w[w_lo + x + cell_slice] + car_w[w_hi + x] + car_w[w_hi + x + cell_slice]);
+                const ex = x - cu * time_delta;
+                const ey = y - 0.5 - cv * time_delta;
+                const ez = z - cw * time_delta;
+                let ecx = (ex + 0.5) | 0;
+                let ecy = (ey + 0.5) | 0;
+                let ecz = (ez + 0.5) | 0;
+                if (ecx < 0) ecx = 0; else if (ecx >= res_x) ecx = last_cx;
+                if (ecy < 0) ecy = 0; else if (ecy >= res_y) ecy = last_cy;
+                if (ecz < 0) ecz = 0; else if (ecz >= res_z) ecz = last_cz;
+                if (solid[ecz * cell_slice + ecy * res_x + ecx] === 0) {
+                    out_v[f] = scs3d_sample_linear(src_v, res_x, sy, res_z, ex, ey + 0.5, ez);
+                } else {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z,
+                        x, y - 0.5, z, ex, ey, ez);
+                    out_v[f] = scs3d_sample_linear(src_v, res_x, sy, res_z,
+                        scratch_clip[0], scratch_clip[1] + 0.5, scratch_clip[2]);
+                }
+            }
+        }
+    }
+
+    // ─── w (z-faces) ─────────────────────────────────────────────────────────
+    for (let z = 0; z <= res_z; z++) {
+        const f_z = z * cell_slice;
+        const za = z > 0 ? z - 1 : 0;
+        const zb = z < res_z ? z : last_cz;
+        const u_lo = za * u_slice;
+        const u_hi = zb * u_slice;
+        const v_lo = za * v_slice;
+        const v_hi = zb * v_slice;
+        for (let y = 0; y < res_y; y++) {
+            const f_y = f_z + y * res_x;
+            const u_row_lo = u_lo + y * sx;
+            const u_row_hi = u_hi + y * sx;
+            const v_row_lo = v_lo + y * res_x;
+            const v_row_hi = v_hi + y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_z[f] !== 0) {
+                    out_w[f] = src_w[f];
+                    continue;
+                }
+                const cu = 0.25 * (car_u[u_row_lo + x] + car_u[u_row_lo + x + 1] + car_u[u_row_hi + x] + car_u[u_row_hi + x + 1]);
+                const cv = 0.25 * (car_v[v_row_lo + x] + car_v[v_row_lo + x + res_x] + car_v[v_row_hi + x] + car_v[v_row_hi + x + res_x]);
+                const cw = car_w[f];
+                const ex = x - cu * time_delta;
+                const ey = y - cv * time_delta;
+                const ez = z - 0.5 - cw * time_delta;
+                let ecx = (ex + 0.5) | 0;
+                let ecy = (ey + 0.5) | 0;
+                let ecz = (ez + 0.5) | 0;
+                if (ecx < 0) ecx = 0; else if (ecx >= res_x) ecx = last_cx;
+                if (ecy < 0) ecy = 0; else if (ecy >= res_y) ecy = last_cy;
+                if (ecz < 0) ecz = 0; else if (ecz >= res_z) ecz = last_cz;
+                if (solid[ecz * cell_slice + ecy * res_x + ecx] === 0) {
+                    out_w[f] = scs3d_sample_linear(src_w, res_x, res_y, sz, ex, ey, ez + 0.5);
+                } else {
+                    v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z,
+                        x, y, z - 0.5, ex, ey, ez);
+                    out_w[f] = scs3d_sample_linear(src_w, res_x, res_y, sz,
+                        scratch_clip[0], scratch_clip[1], scratch_clip[2] + 0.5);
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * 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: Float32Array, vel_v: Float32Array, vel_w: Float32Array, face_solid_x: Uint8Array, face_solid_y: Uint8Array, face_solid_z: Uint8Array, scratch_cu: Float32Array, scratch_cv: Float32Array, scratch_cw: Float32Array, scratch_wx: Float32Array, scratch_wy: Float32Array, scratch_wz: Float32Array, scratch_wmag: Float32Array, res_x: number, res_y: number, res_z: number, epsilon_dt: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_apply_vorticity_confinement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_apply_vorticity_confinement.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,0DApBW,YAAY,SACZ,YAAY,SACZ,YAAY,gBACZ,UAAU,gBACV,UAAU,gBACV,UAAU,cACV,YAAY,cAEZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA8HpB"}