@woosh/meep-engine 2.156.0 → 2.157.0

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

@@ -0,0 +1,169 @@
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
+
+/**
+ * Unconditionally stable MacCormack advection of a 3-component velocity field
+ * along a separate carrier field — the velocity counterpart of
+ * {@link v3_grid_advect_maccormack_scalar}, sharing one back-trace and one
+ * fused 3-channel sample per cell per pass.
+ *
+ * Scheme per component (Selle et al. 2008):
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src cells around the back-traced
+ *                  position (per component) — Selle's monotone limiter.
+ *
+ * The carrier is read only at each cell's own index (the trace origin), so
+ * `outputs` MAY alias the carrier arrays — the advection-reflection step
+ * advects the reflected field along the projected field that lives in the
+ * output buffers. `sources` and `forward_scratch` must be distinct from
+ * outputs and from each other.
+ *
+ * Solid destination cells pass their source value through unchanged.
+ *
+ * @param {Float32Array[]} outputs         `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} sources         `[src_x, src_y, src_z]`. NOT mutated.
+ * @param {Float32Array} carrier_x         Velocity driving the traces.
+ * @param {Float32Array} carrier_y
+ * @param {Float32Array} carrier_z
+ * @param {Float32Array[]} forward_scratch `[fwd_x, fwd_y, fwd_z]` working
+ *                                         buffers for û. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} solid               Required cell flags.
+ */
+export function v3_grid_advect_maccormack_velocity(outputs, sources, carrier_x, carrier_y, carrier_z, forward_scratch, res_x, res_y, res_z, time_delta, 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(forward_scratch.length, 3, "forward_scratch is a 3-component array");
+
+    const out_x = outputs[0];
+    const out_y = outputs[1];
+    const out_z = outputs[2];
+    const src_x = sources[0];
+    const src_y = sources[1];
+    const src_z = sources[2];
+    const fwd_x = forward_scratch[0];
+    const fwd_y = forward_scratch[1];
+    const fwd_z = forward_scratch[2];
+
+    const cell_count = res_x * res_y * res_z;
+
+    assert.greaterThanOrEqual(out_x.length, cell_count, "out_x covers grid");
+    assert.greaterThanOrEqual(src_x.length, cell_count, "src_x covers grid");
+    assert.greaterThanOrEqual(fwd_x.length, cell_count, "fwd_x covers grid");
+    assert.greaterThanOrEqual(carrier_x.length, cell_count, "carrier_x covers grid");
+
+    assert.notEqual(out_x, src_x, "out_x must not alias src_x");
+    assert.notEqual(out_x, fwd_x, "out_x must not alias fwd_x");
+    assert.notEqual(src_x, fwd_x, "src_x must not alias fwd_x");
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+    const sample = scratch_sample;
+
+    // ─── pass 1: forward SL step into the scratch trio ──────────────────────
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+                if (solid[c] !== 0) {
+                    fwd_x[c] = src_x[c];
+                    fwd_y[c] = src_y[c];
+                    fwd_z[c] = src_z[c];
+                    continue;
+                }
+                const s_x = x - carrier_x[c] * time_delta;
+                const s_y = y - carrier_y[c] * time_delta;
+                const s_z = z - carrier_z[c] * time_delta;
+                scs3d_sample_linear3(sample, src_x, src_y, src_z, res_x, res_y, res_z, s_x, s_y, s_z);
+                fwd_x[c] = sample[0];
+                fwd_y[c] = sample[1];
+                fwd_z[c] = sample[2];
+            }
+        }
+    }
+
+    // ─── pass 2: backward step, correction, monotone limit ──────────────────
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+                if (solid[c] !== 0) {
+                    out_x[c] = src_x[c];
+                    out_y[c] = src_y[c];
+                    out_z[c] = src_z[c];
+                    continue;
+                }
+
+                const vx = carrier_x[c] * time_delta;
+                const vy = carrier_y[c] * time_delta;
+                const vz = carrier_z[c] * time_delta;
+
+                scs3d_sample_linear3(sample, fwd_x, fwd_y, fwd_z, res_x, res_y, res_z, x + vx, y + vy, z + vz);
+                const corr_x = fwd_x[c] + 0.5 * (src_x[c] - sample[0]);
+                const corr_y = fwd_y[c] + 0.5 * (src_y[c] - sample[1]);
+                const corr_z = fwd_z[c] + 0.5 * (src_z[c] - sample[2]);
+
+                // Shared corner set for the per-component limiter.
+                const bx = clamp(x - vx, 0, last_x);
+                const by = clamp(y - vy, 0, last_y);
+                const bz = clamp(z - vz, 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 * slice_size;
+                const z1_off = z1 * slice_size;
+                const y0_off = y0 * res_x;
+                const y1_off = y1 * res_x;
+
+                const c000 = z0_off + y0_off + x0;
+                const c100 = z0_off + y0_off + x1;
+                const c010 = z0_off + y1_off + x0;
+                const c110 = z0_off + y1_off + x1;
+                const c001 = z1_off + y0_off + x0;
+                const c101 = z1_off + y0_off + x1;
+                const c011 = z1_off + y1_off + x0;
+                const c111 = z1_off + y1_off + x1;
+
+                out_x[c] = limit8(corr_x, src_x, c000, c100, c010, c110, c001, c101, c011, c111);
+                out_y[c] = limit8(corr_y, src_y, c000, c100, c010, c110, c001, c101, c011, c111);
+                out_z[c] = limit8(corr_z, src_z, c000, c100, c010, c110, c001, c101, c011, c111);
+            }
+        }
+    }
+}
+
+/**
+ * Clamp `value` to the min/max of eight cells of `data`.
+ */
+function limit8(value, data, c0, c1, c2, c3, c4, c5, c6, c7) {
+    let mn = data[c0];
+    let mx = mn;
+    let v = data[c1]; if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c2];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c3];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c4];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c5];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c6];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[c7];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    return value < mn ? mn : (value > mx ? mx : value);
+}
+
+/** Module-static sample destination — avoids per-cell allocation. */
+const scratch_sample = new Float32Array(3);

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

@@ -0,0 +1,36 @@
+/**
+ * Semi-Lagrangian advection of a 3-component velocity field along a separate
+ * carrier velocity field.
+ *
+ * For each cell, traces backward along the CARRIER for one timestep, then
+ * trilinearly samples each SOURCE component at the back-traced position (one
+ * fused 3-channel sample — indices and weights computed once per cell).
+ * Unconditionally stable for any `time_delta`.
+ *
+ * Generalizes {@link v3_grid_apply_advection_forward}, which hardwires
+ * carrier === sources (plain self-advection). The split matters for the
+ * advection-reflection scheme (Zehnder et al. 2018), where the REFLECTED
+ * field is transported along the PROJECTED field, and for the MacCormack
+ * corrector, which re-advects an intermediate result along the original
+ * carrier.
+ *
+ * Aliasing: `outputs[i]` MUST NOT alias `sources[i]` (the sampled data), but
+ * MAY alias `carrier_*` — the carrier is only point-read at each cell's own
+ * index before that cell's output is written, never sampled spatially.
+ *
+ * @param {Float32Array[]} outputs   `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} sources   `[src_x, src_y, src_z]`, read at back-traced
+ *                                   positions. Must not alias outputs.
+ * @param {Float32Array} carrier_x   Velocity field that drives the back-trace.
+ * @param {Float32Array} carrier_y
+ * @param {Float32Array} carrier_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta        Same units as velocity (grid cells / second).
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a
+ *                                   wall-free domain); solid cells get their
+ *                                   source value passed through unchanged.
+ */
+export function v3_grid_advect_sl_velocity(outputs: Float32Array[], sources: Float32Array[], carrier_x: Float32Array, carrier_y: Float32Array, carrier_z: Float32Array, res_x: number, res_y: number, res_z: number, time_delta: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_advect_sl_velocity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_advect_sl_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_advect_sl_velocity.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAdW,YAAY,EAAE,WACd,YAAY,EAAE,aAEd,YAAY,aACZ,YAAY,aACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,UAAU,QA+DpB"}

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

@@ -0,0 +1,100 @@
+import { assert } from "../../../../core/assert.js";
+import { scs3d_sample_linear3 } from "../../../graphics/texture/3d/scs3d_sample_linear3.js";
+
+/**
+ * Semi-Lagrangian advection of a 3-component velocity field along a separate
+ * carrier velocity field.
+ *
+ * For each cell, traces backward along the CARRIER for one timestep, then
+ * trilinearly samples each SOURCE component at the back-traced position (one
+ * fused 3-channel sample — indices and weights computed once per cell).
+ * Unconditionally stable for any `time_delta`.
+ *
+ * Generalizes {@link v3_grid_apply_advection_forward}, which hardwires
+ * carrier === sources (plain self-advection). The split matters for the
+ * advection-reflection scheme (Zehnder et al. 2018), where the REFLECTED
+ * field is transported along the PROJECTED field, and for the MacCormack
+ * corrector, which re-advects an intermediate result along the original
+ * carrier.
+ *
+ * Aliasing: `outputs[i]` MUST NOT alias `sources[i]` (the sampled data), but
+ * MAY alias `carrier_*` — the carrier is only point-read at each cell's own
+ * index before that cell's output is written, never sampled spatially.
+ *
+ * @param {Float32Array[]} outputs   `[out_x, out_y, out_z]`, mutated.
+ * @param {Float32Array[]} sources   `[src_x, src_y, src_z]`, read at back-traced
+ *                                   positions. Must not alias outputs.
+ * @param {Float32Array} carrier_x   Velocity field that drives the back-trace.
+ * @param {Float32Array} carrier_y
+ * @param {Float32Array} carrier_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta        Same units as velocity (grid cells / second).
+ * @param {Uint8Array} solid         Required cell flags (zero-filled for a
+ *                                   wall-free domain); solid cells get their
+ *                                   source value passed through unchanged.
+ */
+export function v3_grid_advect_sl_velocity(outputs, sources, carrier_x, carrier_y, carrier_z, res_x, res_y, res_z, time_delta, solid) {
+    assert.equal(outputs.length, 3, "outputs is a 3-component array");
+    assert.equal(sources.length, 3, "sources is a 3-component array");
+
+    const out_x = outputs[0];
+    const out_y = outputs[1];
+    const out_z = outputs[2];
+
+    const src_x = sources[0];
+    const src_y = sources[1];
+    const src_z = sources[2];
+
+    const cell_count = res_x * res_y * res_z;
+
+    assert.greaterThanOrEqual(out_x.length, cell_count, "out_x covers grid");
+    assert.greaterThanOrEqual(out_y.length, cell_count, "out_y covers grid");
+    assert.greaterThanOrEqual(out_z.length, cell_count, "out_z covers grid");
+    assert.greaterThanOrEqual(src_x.length, cell_count, "src_x covers grid");
+    assert.greaterThanOrEqual(src_y.length, cell_count, "src_y covers grid");
+    assert.greaterThanOrEqual(src_z.length, cell_count, "src_z covers grid");
+    assert.greaterThanOrEqual(carrier_x.length, cell_count, "carrier_x covers grid");
+    assert.greaterThanOrEqual(carrier_y.length, cell_count, "carrier_y covers grid");
+    assert.greaterThanOrEqual(carrier_z.length, cell_count, "carrier_z covers grid");
+
+    assert.notEqual(out_x, src_x, "out_x must not alias src_x");
+    assert.notEqual(out_y, src_y, "out_y must not alias src_y");
+    assert.notEqual(out_z, src_z, "out_z must not alias src_z");
+
+    const slice_size = res_x * res_y;
+    const sample = scratch_sample;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    out_x[c] = src_x[c];
+                    out_y[c] = src_y[c];
+                    out_z[c] = src_z[c];
+                    continue;
+                }
+
+                // Trace back along the carrier to where this parcel came from.
+                const s_x = x - carrier_x[c] * time_delta;
+                const s_y = y - carrier_y[c] * time_delta;
+                const s_z = z - carrier_z[c] * time_delta;
+
+                scs3d_sample_linear3(sample, src_x, src_y, src_z, res_x, res_y, res_z, s_x, s_y, s_z);
+                out_x[c] = sample[0];
+                out_y[c] = sample[1];
+                out_z[c] = sample[2];
+            }
+        }
+    }
+}
+
+/** Module-static sample destination — avoids per-cell allocation. */
+const scratch_sample = new Float32Array(3);

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

@@ -6,6 +6,12 @@
  * Stable for arbitrarily large `time_delta` (the trade-off is numerical diffusion;
  * the field gets blurrier each step).
  *
+ * The simulator itself now transports velocity via the generalized kernels —
+ * {@link v3_grid_advect_sl_velocity} (separate carrier, fused 3-channel
+ * sampling) and {@link v3_grid_advect_maccormack_velocity} (second-order).
+ * This kernel remains as the simple self-advection primitive: it is exactly
+ * `v3_grid_advect_sl_velocity(outputs, inputs, inputs...)`.
+ *
  * Inputs and outputs must be disjoint Float32Arrays of length `res_x * res_y * res_z`.
  * Cells flagged solid (non-zero in `solid`) keep their input value unchanged.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAXW,YAAY,EAAE,UACd,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA6DpB"}
+{"version":3,"file":"v3_grid_apply_advection_forward.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_advection_forward.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yDAXW,YAAY,EAAE,UACd,YAAY,EAAE,SAEd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA6DpB"}

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

@@ -9,6 +9,12 @@ import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_l
  * Stable for arbitrarily large `time_delta` (the trade-off is numerical diffusion;
  * the field gets blurrier each step).
  *
+ * The simulator itself now transports velocity via the generalized kernels —
+ * {@link v3_grid_advect_sl_velocity} (separate carrier, fused 3-channel
+ * sampling) and {@link v3_grid_advect_maccormack_velocity} (second-order).
+ * This kernel remains as the simple self-advection primitive: it is exactly
+ * `v3_grid_advect_sl_velocity(outputs, inputs, inputs...)`.
+ *
  * Inputs and outputs must be disjoint Float32Arrays of length `res_x * res_y * res_z`.
  * Cells flagged solid (non-zero in `solid`) keep their input value unchanged.
  *

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

@@ -11,8 +11,13 @@
  * conditions — missing neighbours are treated as equal to the cell itself, which
  * reduces the effective denominator.
  *
- * Solid cells (marked non-zero in `solid`) are skipped: their value in `output` is
- * left at the corresponding `x0` value.
+ * Solid cells get the same no-flux treatment on both sides of the wall:
+ *   - a solid cell is never updated — its value in `output` stays at `x0`;
+ *   - a fluid cell never gathers FROM a solid neighbour — the wall face is
+ *     reflective, exactly like a domain boundary face.
+ * Without the second half, a wall would act as an infinite source/sink for
+ * whatever value was frozen inside it, silently creating or destroying the
+ * diffused quantity.
  *
  * @param {Float32Array} output      Destination (size = res_x * res_y * res_z). Mutated.
  * @param {Float32Array} x0          Source values to diffuse. NOT mutated.

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_apply_diffusion.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_diffusion.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,gDAXW,YAAY,MACZ,YAAY,WACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,cACN,MAAM,SACN,UAAU,QA2EpB"}
+{"version":3,"file":"v3_grid_apply_diffusion.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_diffusion.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,gDAXW,YAAY,MACZ,YAAY,WACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,KACN,MAAM,cACN,MAAM,SACN,UAAU,QA2EpB"}

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

@@ -13,8 +13,13 @@ import { assert } from "../../../../core/assert.js";
  * conditions — missing neighbours are treated as equal to the cell itself, which
  * reduces the effective denominator.
  *
- * Solid cells (marked non-zero in `solid`) are skipped: their value in `output` is
- * left at the corresponding `x0` value.
+ * Solid cells get the same no-flux treatment on both sides of the wall:
+ *   - a solid cell is never updated — its value in `output` stays at `x0`;
+ *   - a fluid cell never gathers FROM a solid neighbour — the wall face is
+ *     reflective, exactly like a domain boundary face.
+ * Without the second half, a wall would act as an infinite source/sink for
+ * whatever value was frozen inside it, silently creating or destroying the
+ * diffused quantity.
  *
  * @param {Float32Array} output      Destination (size = res_x * res_y * res_z). Mutated.
  * @param {Float32Array} x0          Source values to diffuse. NOT mutated.
@@ -75,17 +80,17 @@ export function v3_grid_apply_diffusion(output, x0, scratch, res_x, res_y, res_z
                     let sum = 0;
                     let count = 0;
 
-                    if (x > 0)       { sum += prev[c - 1];          count++; }
-                    if (x < last_x)  { sum += prev[c + 1];          count++; }
-                    if (has_ym)      { sum += prev[c - res_x];      count++; }
-                    if (has_yp)      { sum += prev[c + res_x];      count++; }
-                    if (has_zm)      { sum += prev[c - slice_size]; count++; }
-                    if (has_zp)      { sum += prev[c + slice_size]; count++; }
+                    if (x > 0      && solid[c - 1] === 0)          { sum += prev[c - 1];          count++; }
+                    if (x < last_x && solid[c + 1] === 0)          { sum += prev[c + 1];          count++; }
+                    if (has_ym     && solid[c - res_x] === 0)      { sum += prev[c - res_x];      count++; }
+                    if (has_yp     && solid[c + res_x] === 0)      { sum += prev[c + res_x];      count++; }
+                    if (has_zm     && solid[c - slice_size] === 0) { sum += prev[c - slice_size]; count++; }
+                    if (has_zp     && solid[c + slice_size] === 0) { sum += prev[c + slice_size]; count++; }
 
-                    // Implicit Jacobi update with Neumann boundary correction:
-                    // missing neighbours contribute as if equal to the cell, which is
-                    // equivalent to dropping them from both the numerator and the
-                    // denominator factor on `a`.
+                    // Implicit Jacobi update with Neumann correction: missing
+                    // neighbours (out-of-bounds OR solid) contribute as if equal to
+                    // the cell, which is equivalent to dropping them from both the
+                    // numerator and the denominator factor on `a`.
                     next[c] = (x0[c] + a * sum) / (1 + a * count);
                 }
             }

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

@@ -0,0 +1,42 @@
+/**
+ * Vorticity confinement (Fedkiw, Stam, Jensen 2001 — "Visual Simulation of
+ * Smoke"): re-inject the small-scale rotational motion that coarse grids and
+ * dissipative transport smear away.
+ *
+ * Two passes:
+ *
+ *   1. ω = ∇×v by central differences (interior cells; boundary ring and
+ *      solid cells get ω = 0), |ω| alongside.
+ *   2. N = ∇|ω| / |∇|ω|| — unit vector pointing toward stronger vorticity —
+ *      and the confinement force f = ε·(N × ω) is deposited as
+ *      `v += f · dt`, pulling flow around existing vortex cores and thereby
+ *      sharpening them.
+ *
+ * The force vanishes where vorticity is spatially uniform (|∇|ω|| ≈ 0), so
+ * calm regions stay calm; the `magnitude_floor` guard skips the normalize
+ * when the gradient is numerically zero.
+ *
+ * Energy note: confinement ADDS energy by design. Pair it with
+ * {@link FluidSimulator#velocity_damping} (or rely on transport dissipation)
+ * — `epsilon_dt` values around `0.1–0.5 · dt` are typical for visual smoke.
+ *
+ * Cells in the boundary ring (x/y/z at 0 or max) receive no force — the
+ * one-sided curl there is unreliable and the open boundary makes amplified
+ * edge swirls visually wrong anyway.
+ *
+ * @param {Float32Array} vel_x  Mutated in place.
+ * @param {Float32Array} vel_y  Mutated in place.
+ * @param {Float32Array} vel_z  Mutated in place.
+ * @param {Float32Array} scratch_wx  ω_x working buffer. Length ≥ N. Mutated.
+ * @param {Float32Array} scratch_wy  ω_y working buffer. Mutated.
+ * @param {Float32Array} scratch_wz  ω_z working buffer. Mutated.
+ * @param {Float32Array} scratch_wmag  |ω| working buffer. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} epsilon_dt  Confinement strength ε multiplied by the
+ *     timestep — the caller folds dt so the kernel stays a pure grid pass.
+ * @param {Uint8Array} solid  Non-zero cells receive no curl and no force.
+ */
+export function v3_grid_apply_vorticity_confinement(vel_x: Float32Array, vel_y: Float32Array, vel_z: 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_grid_apply_vorticity_confinement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_apply_vorticity_confinement.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_apply_vorticity_confinement.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAdW,YAAY,SACZ,YAAY,SACZ,YAAY,cACZ,YAAY,cACZ,YAAY,cACZ,YAAY,gBACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SAEN,UAAU,QA0FpB"}

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

@@ -0,0 +1,131 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Vorticity confinement (Fedkiw, Stam, Jensen 2001 — "Visual Simulation of
+ * Smoke"): re-inject the small-scale rotational motion that coarse grids and
+ * dissipative transport smear away.
+ *
+ * Two passes:
+ *
+ *   1. ω = ∇×v by central differences (interior cells; boundary ring and
+ *      solid cells get ω = 0), |ω| alongside.
+ *   2. N = ∇|ω| / |∇|ω|| — unit vector pointing toward stronger vorticity —
+ *      and the confinement force f = ε·(N × ω) is deposited as
+ *      `v += f · dt`, pulling flow around existing vortex cores and thereby
+ *      sharpening them.
+ *
+ * The force vanishes where vorticity is spatially uniform (|∇|ω|| ≈ 0), so
+ * calm regions stay calm; the `magnitude_floor` guard skips the normalize
+ * when the gradient is numerically zero.
+ *
+ * Energy note: confinement ADDS energy by design. Pair it with
+ * {@link FluidSimulator#velocity_damping} (or rely on transport dissipation)
+ * — `epsilon_dt` values around `0.1–0.5 · dt` are typical for visual smoke.
+ *
+ * Cells in the boundary ring (x/y/z at 0 or max) receive no force — the
+ * one-sided curl there is unreliable and the open boundary makes amplified
+ * edge swirls visually wrong anyway.
+ *
+ * @param {Float32Array} vel_x  Mutated in place.
+ * @param {Float32Array} vel_y  Mutated in place.
+ * @param {Float32Array} vel_z  Mutated in place.
+ * @param {Float32Array} scratch_wx  ω_x working buffer. Length ≥ N. Mutated.
+ * @param {Float32Array} scratch_wy  ω_y working buffer. Mutated.
+ * @param {Float32Array} scratch_wz  ω_z working buffer. Mutated.
+ * @param {Float32Array} scratch_wmag  |ω| working buffer. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} epsilon_dt  Confinement strength ε multiplied by the
+ *     timestep — the caller folds dt so the kernel stays a pure grid pass.
+ * @param {Uint8Array} solid  Non-zero cells receive no curl and no force.
+ */
+export function v3_grid_apply_vorticity_confinement(
+    vel_x, vel_y, vel_z,
+    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(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+    assert.greaterThanOrEqual(scratch_wx.length, cell_count, "scratch_wx covers grid");
+    assert.greaterThanOrEqual(scratch_wy.length, cell_count, "scratch_wy covers grid");
+    assert.greaterThanOrEqual(scratch_wz.length, cell_count, "scratch_wz 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 slice = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    // ─── pass 1: ω = ∇×v and |ω| ────────────────────────────────────────────
+    // Boundary ring and solids get 0 — also serves as the ghost value for
+    // pass 2's gradient at interior cells adjacent to the ring.
+    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 z_off = z * slice;
+        for (let y = 1; y < last_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 1; x < last_x; x++) {
+                const c = z_off + y_off + x;
+                if (solid[c] !== 0) {
+                    continue;
+                }
+                const wx = 0.5 * ((vel_z[c + res_x] - vel_z[c - res_x]) - (vel_y[c + slice] - vel_y[c - slice]));
+                const wy = 0.5 * ((vel_x[c + slice] - vel_x[c - slice]) - (vel_z[c + 1] - vel_z[c - 1]));
+                const wz = 0.5 * ((vel_y[c + 1] - vel_y[c - 1]) - (vel_x[c + res_x] - vel_x[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 2: f = ε·(N × ω), N = ∇|ω|/|∇|ω|| ────────────────────────────
+    const magnitude_floor = 1e-10;
+
+    for (let z = 1; z < last_z; z++) {
+        const z_off = z * slice;
+        for (let y = 1; y < last_y; y++) {
+            const y_off = y * res_x;
+            for (let x = 1; x < last_x; x++) {
+                const c = z_off + y_off + 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 + slice] - scratch_wmag[c - slice]);
+
+                const g_len = Math.sqrt(gx * gx + gy * gy + gz * gz);
+                if (g_len < magnitude_floor) {
+                    continue;
+                }
+                const s = epsilon_dt / g_len;
+
+                // f = ε · (N × ω); deposit directly as Δv (dt already folded).
+                const wx = scratch_wx[c];
+                const wy = scratch_wy[c];
+                const wz = scratch_wz[c];
+                vel_x[c] += s * (gy * wz - gz * wy);
+                vel_y[c] += s * (gz * wx - gx * wz);
+                vel_z[c] += s * (gx * wy - gy * wx);
+            }
+        }
+    }
+}