@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,511 +1,511 @@
-import { assert } from "../../../../core/assert.js";
-
-/**
- * Popcount table for the 6-bit neighbour mask. Used to detect open faces:
- * a cell whose Laplacian diagonal exceeds its fluid-neighbour count touches
- * the domain edge (open boundary), which decides the null-space handling.
- *
- * @type {Uint8Array}
- */
-const POPCOUNT_6 = (function () {
-    const t = new Uint8Array(64);
-    for (let i = 0; i < 64; i++) {
-        let c = 0;
-        for (let b = 0; b < 6; b++) if (i & (1 << b)) c++;
-        t[i] = c;
-    }
-    return t;
-})();
-
-/**
- * MIC(0) modification weight. Bridson's recommendation is 0.97; the factor scales
- * how much "would-have-been-fill-in" we re-add onto the diagonal. Lower → closer
- * to plain IC(0). Higher → stronger preconditioning but riskier (can produce a
- * non-SPD matrix). 0.97 is the canonical sweet spot from the literature.
- *
- * @type {number}
- */
-const MIC_TAU = 0.97;
-
-/**
- * Diagonal safeguard threshold. If the computed Cholesky diagonal element falls
- * below `MIC_SIGMA * A_diag`, we discard the IC factorization for that cell and
- * fall back to `e = A_diag` (i.e. Jacobi for that cell). Prevents `1/sqrt(small)`
- * from blowing up.
- *
- * @type {number}
- */
-const MIC_SIGMA = 0.25;
-
-/**
- * Pressure Poisson solver: Modified Incomplete Cholesky preconditioned Conjugate
- * Gradient — MIC(0)-PCG.
- *
- * Solves `A * p = -div(v)` where A is the 7-point discrete Laplacian over fluid
- * cells (same matrix as {@link v3_grid_solve_pressure} — that function's SOR
- * update is exactly the splitting `A * p = -div`). Per cell:
- *
- *     A[c, c]  = diag[c] = (# fluid neighbours) + (# open faces)
- *     A[c, c'] = -1 if c' is a fluid neighbour of c, else 0
- *
- * Open faces (out-of-bounds neighbours — the domain edge) carry a Dirichlet
- * ghost pressure of 0: they enlarge the diagonal without adding an
- * off-diagonal entry, exactly like a fluid neighbour whose pressure is pinned
- * at zero. Solid faces are Neumann: absent from both. See
- * {@link v3_grid_compute_solid_neighbour_mask} for the boundary model.
- *
- * PCG converges in roughly `O(√κ)` iterations where κ is the spectral condition
- * number of `M⁻¹A`. The MIC(0) preconditioner reduces κ from `O(N²)` (raw
- * Laplacian) to `O(N)`, so a single PCG iter does a lot more useful work than
- * a single SOR sweep.
- *
- * **Empirical finding (V8 / Node, single-thread, this implementation).** Each
- * PCG iter involves ~8 separate per-cell passes (As compute, axpy×2,
- * mean-subtract, fwd+bwd triangular solves, dot, s update) vs SOR's 2. In
- * native code each pass is bandwidth-bound and per-iter ratio approaches the
- * textbook 2× — yielding the canonical 1.5–2× wall-time win for PCG. In V8,
- * per-pass loop overhead dominates; the actual per-iter ratio is closer to
- * 4-6× and PCG ends up SLOWER than SOR at iso-quality on production grids:
- *
- *     res=64:  SOR  16 iter  /  75 ms,  max|div| 3.09e-1
- *              PCG   8 iter  / 181 ms,  max|div| 3.72e-3   (PCG 2.4× slower)
- *
- *     res=128: SOR  32 iter  / 862 ms,  max|div| 8.74e-1
- *              PCG   8 iter  /1452 ms,  max|div| 5.65e-3   (PCG 1.7× slower)
- *
- * (Reproduce via `bench: MIC-PCG vs SOR` in bench.spec.js.)
- *
- * Where PCG still wins: **convergence depth**. At the SAME iter count it
- * produces dramatically lower residual divergence (84× better max|div| at
- * 64³, 247× at 128³). If you need quality below the cell-centered operator
- * floor SOR plateaus at — e.g. quantitative pressure inspection, or
- * extreme-impulse scenes where the SOR floor is visible — PCG is the answer.
- * For visual-fluids steady state, **leave the default at SOR**.
- *
- * If this code is ever ported to WASM SIMD or WebGPU the perf comparison
- * flips: per-iter overhead becomes negligible in those environments and the
- * theoretical 1.5–2× PCG win re-emerges. Worth re-running the bench then.
- *
- * Algorithm (Bridson "Fluid Simulation for Computer Graphics" §5.6, Saad
- * §10.2):
- *
- *     1.  build_preconditioner: walk fluid cells in lex order, computing
- *         precon[c] = 1 / sqrt(e[c]) where e[c] is the modified Cholesky
- *         diagonal. Backward neighbours (-x, -y, -z) contribute to the
- *         subtraction.
- *
- *     2.  r₀ = -div - A * p₀     (initial residual; p₀ is the warm-start)
- *         z₀ = M⁻¹ * r₀          (apply preconditioner — two triangular solves)
- *         s₀ = z₀
- *         σ₀ = r₀ · z₀
- *
- *     3.  For k = 0, 1, …, max_iter-1:
- *             A·sₖ
- *             α = σₖ / (sₖ · A·sₖ)
- *             p ← p + α·sₖ
- *             r ← r - α·A·sₖ
- *             z ← M⁻¹ · r
- *             σₖ₊₁ = r · z
- *             β = σₖ₊₁ / σₖ
- *             s ← z + β·s
- *
- * Preconditioner apply is a forward sweep (L·y = r) followed by a backward
- * sweep (Lᵀ·z = y). Both sweeps are O(N) and inherently sequential — they're
- * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
- * substantial reformulation. On single-thread JS that's not a concern.
- *
- * Null space: when NO fluid cell touches the domain edge (a fully sealed
- * domain — every boundary cell solid), A is the pure-Neumann Laplacian and has
- * the constant vector in its null space. The residual is then projected onto
- * the mean-zero subspace after every update, the standard fluids practice
- * (Bridson §5.5) — without it alpha explodes once the search direction aligns
- * with the null space. With ANY open face the system is non-singular and the
- * projection is skipped (subtracting the mean there would solve a different
- * right-hand side). Caveat: a sealed sub-region inside an otherwise open
- * domain is still locally singular; its constant mode is harmless to the open
- * region but convergence inside that pocket is not guaranteed — split fields
- * rather than simulating disconnected sealed rooms in one volume.
- *
- * Cells with `diag[c] === 0` — solid cells and fluid sealed on all six faces —
- * are excluded from the system: their pressure stays at whatever it was
- * (typically 0), their entries in r, z, s, As stay 0, and they contribute
- * nothing to dot products.
- *
- * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
- *     or with the previous step's solution to warm-start.
- * @param {Float32Array|Float16Array} divergence  From `v3_grid_compute_divergence`.
- * @param {number} res_x
- * @param {number} res_y
- * @param {number} res_z
- * @param {number} max_iterations  Cap. The solve also exits as soon as the
- *     tolerance is met (below), or via the implicit-zero dot product guards.
- * @param {number} relative_tolerance  Convergence exit: stop when
- *     `max|r| <= relative_tolerance * max|−div|` over fluid cells (residual
- *     measured after the null-space mean subtraction, where that applies).
- *     `0` disables the tolerance exit — the solve then runs to
- *     `max_iterations` exactly as the pre-tolerance implementation did.
- *     Production use: the cap is sized for the cold-start worst case, and the
- *     warm-started steady state exits in a fraction of it; without this exit
- *     every warm frame pays the cold-start budget for no quality gain.
- * @param {Uint8Array} neighbour_mask  From `v3_grid_compute_solid_neighbour_mask`.
- * @param {Uint8Array} diag  Laplacian diagonal per cell, baked by the same
- *     kernel as `neighbour_mask`.
- * @param {Float32Array} scratch_r  Length ≥ rx*ry*rz. Residual.
- * @param {Float32Array} scratch_z  Length ≥ rx*ry*rz. Preconditioned residual.
- * @param {Float32Array} scratch_s  Length ≥ rx*ry*rz. Search direction.
- * @param {Float32Array} scratch_As  Length ≥ rx*ry*rz. A applied to s.
- * @param {Float32Array} scratch_precon  Length ≥ rx*ry*rz. Preconditioner
- *     diagonal (1/sqrt(e_c) per fluid cell, 0 for solid).
- */
-export function v3_grid_solve_pressure_pcg(
-    pressure, divergence,
-    res_x, res_y, res_z,
-    max_iterations, relative_tolerance,
-    neighbour_mask, diag,
-    scratch_r, scratch_z, scratch_s, scratch_As, scratch_precon
-) {
-    const cells = res_x * res_y * res_z;
-
-    assert.notEqual(pressure, divergence, "pressure must not alias divergence");
-    assert.greaterThanOrEqual(pressure.length, cells, "pressure covers grid");
-    assert.greaterThanOrEqual(divergence.length, cells, "divergence covers grid");
-    assert.greaterThanOrEqual(neighbour_mask.length, cells, "neighbour_mask covers grid");
-    assert.greaterThanOrEqual(diag.length, cells, "diag covers grid");
-    assert.greaterThanOrEqual(scratch_r.length, cells, "scratch_r covers grid");
-    assert.greaterThanOrEqual(scratch_z.length, cells, "scratch_z covers grid");
-    assert.greaterThanOrEqual(scratch_s.length, cells, "scratch_s covers grid");
-    assert.greaterThanOrEqual(scratch_As.length, cells, "scratch_As covers grid");
-    assert.greaterThanOrEqual(scratch_precon.length, cells, "scratch_precon covers grid");
-    assert.isNonNegativeInteger(max_iterations, "max_iterations");
-    assert.isNumber(relative_tolerance, "relative_tolerance");
-    assert.greaterThanOrEqual(relative_tolerance, 0, "relative_tolerance");
-
-    if (max_iterations === 0) {
-        return;
-    }
-
-    const rx = res_x;
-    const slice = res_x * res_y;
-
-    const precon = scratch_precon;
-    const r = scratch_r;
-    const z = scratch_z;
-    const s = scratch_s;
-    const As = scratch_As;
-
-    // Count degrees of freedom and detect open faces. A DOF is any cell with
-    // diag > 0. `has_open` (any cell whose diagonal exceeds its fluid-neighbour
-    // count) decides the null-space treatment — see the class of comment above.
-    let fluid_count = 0;
-    let has_open = false;
-    for (let c = 0; c < cells; c++) {
-        const d = diag[c];
-        if (d === 0) continue;
-        fluid_count++;
-        if (d > POPCOUNT_6[neighbour_mask[c] & 63]) {
-            has_open = true;
-        }
-    }
-    if (fluid_count === 0) {
-        return;
-    }
-
-    // ─── 1. Build MIC(0) preconditioner ─────────────────────────────────────
-    //
-    // Walk fluid cells in lex order; for each, compute the modified Cholesky
-    // diagonal e[c] from the backward (-x, -y, -z) fluid neighbours and store
-    // precon[c] = 1 / sqrt(e[c]). Solid / sealed cells keep precon = 0.
-    //
-    // The "modified" piece adds tau * (off-direction terms) back onto the
-    // diagonal — it compensates for fill-in that plain IC(0) drops, and makes
-    // PCG converge in O(√N) instead of O(N²/³).
-    precon.fill(0);
-    for (let c = 0; c < cells; c++) {
-        const a_diag = diag[c];
-        if (a_diag === 0) {
-            continue;
-        }
-        const mask = neighbour_mask[c];
-        let e = a_diag;
-
-        if (mask & 1) {  // -x backward neighbour is fluid
-            const c_prev = c - 1;
-            const p_prev = precon[c_prev];
-            const p_prev_sq = p_prev * p_prev;
-            // (A[c, c_prev] * precon[c_prev])^2 = precon_prev^2 since A = -1.
-            e -= p_prev_sq;
-            // Modification: tau * A[c, c_prev] * (off-direction A entries from c_prev) * precon_prev^2.
-            // A[c, c_prev] = -1. Off-directions from c_prev pointing away from c
-            // are +y (bit 3 of c_prev's mask) and +z (bit 5).
-            const m_prev = neighbour_mask[c_prev];
-            const off = ((m_prev >> 3) & 1) + ((m_prev >> 5) & 1);
-            // Contribution: tau * (-1) * (-(off)) * precon_prev^2 = tau * off * precon_prev^2
-            e -= MIC_TAU * off * p_prev_sq;
-        }
-        if (mask & 4) {  // -y
-            const c_prev = c - rx;
-            const p_prev = precon[c_prev];
-            const p_prev_sq = p_prev * p_prev;
-            e -= p_prev_sq;
-            const m_prev = neighbour_mask[c_prev];
-            // Off-directions from c_prev: +x (bit 1), +z (bit 5).
-            const off = ((m_prev >> 1) & 1) + ((m_prev >> 5) & 1);
-            e -= MIC_TAU * off * p_prev_sq;
-        }
-        if (mask & 16) {  // -z
-            const c_prev = c - slice;
-            const p_prev = precon[c_prev];
-            const p_prev_sq = p_prev * p_prev;
-            e -= p_prev_sq;
-            const m_prev = neighbour_mask[c_prev];
-            // Off-directions from c_prev: +x (bit 1), +y (bit 3).
-            const off = ((m_prev >> 1) & 1) + ((m_prev >> 3) & 1);
-            e -= MIC_TAU * off * p_prev_sq;
-        }
-
-        // Safeguard: if e dropped below sigma*A_diag, the factorization is
-        // becoming non-SPD-friendly; fall back to plain Jacobi for this cell.
-        if (e < MIC_SIGMA * a_diag) {
-            e = a_diag;
-        }
-        precon[c] = 1 / Math.sqrt(e);
-    }
-
-    // ─── 2. r = -div - A * pressure  (initial residual) ─────────────────────
-
-    // max|b| over fluid cells anchors the relative tolerance exit.
-    let max_b = 0;
-    for (let c = 0; c < cells; c++) {
-        const a_diag = diag[c];
-        if (a_diag === 0) {
-            r[c] = 0;
-            continue;
-        }
-        const b_abs = Math.abs(divergence[c]);
-        if (b_abs > max_b) max_b = b_abs;
-        const mask = neighbour_mask[c];
-        let Ap = a_diag * pressure[c];
-        if (mask & 1)  Ap -= pressure[c - 1];
-        if (mask & 2)  Ap -= pressure[c + 1];
-        if (mask & 4)  Ap -= pressure[c - rx];
-        if (mask & 8)  Ap -= pressure[c + rx];
-        if (mask & 16) Ap -= pressure[c - slice];
-        if (mask & 32) Ap -= pressure[c + slice];
-        r[c] = -divergence[c] - Ap;
-    }
-    const tolerance = relative_tolerance * max_b;
-
-    const r0_worst = has_open
-        ? max_abs_dof(r, diag, cells)
-        : subtract_mean_fluid(r, diag, cells, fluid_count);
-    if (r0_worst <= tolerance) {
-        // Warm start already within tolerance — nothing to refine. (With
-        // relative_tolerance = 0 this only triggers on an exactly-zero
-        // residual, matching the historical behaviour.)
-        return;
-    }
-
-    // ─── 3. z = M⁻¹ * r, s = z, sigma = r · z ───────────────────────────────
-
-    apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
-
-    let sigma = 0;
-    for (let c = 0; c < cells; c++) {
-        s[c] = z[c];
-        sigma += r[c] * z[c];
-    }
-
-    if (sigma === 0) {
-        // Initial residual was already zero (or pathological). Either way,
-        // nothing to do.
-        return;
-    }
-
-    // ─── 4. PCG outer loop ──────────────────────────────────────────────────
-
-    for (let iter = 0; iter < max_iterations; iter++) {
-
-        // As = A * s, accumulating s · As in the same pass.
-        let s_dot_As = 0;
-        for (let c = 0; c < cells; c++) {
-            const a_diag = diag[c];
-            if (a_diag === 0) {
-                As[c] = 0;
-                continue;
-            }
-            const mask = neighbour_mask[c];
-            let val = a_diag * s[c];
-            if (mask & 1)  val -= s[c - 1];
-            if (mask & 2)  val -= s[c + 1];
-            if (mask & 4)  val -= s[c - rx];
-            if (mask & 8)  val -= s[c + rx];
-            if (mask & 16) val -= s[c - slice];
-            if (mask & 32) val -= s[c + slice];
-            As[c] = val;
-            s_dot_As += s[c] * val;
-        }
-
-        if (s_dot_As === 0) {
-            // Degenerate search direction; stop.
-            break;
-        }
-
-        const alpha = sigma / s_dot_As;
-
-        // pressure += alpha * s
-        // r        -= alpha * As
-        for (let c = 0; c < cells; c++) {
-            pressure[c] += alpha * s[c];
-            r[c]        -= alpha * As[c];
-        }
-        // Sealed domain: project r back onto the mean-zero (range(A)) subspace
-        // — round-off accumulates a constant component each iter; without this,
-        // alpha explodes within ~8 iters once s aligns with the null space.
-        // Open domain: A is non-singular, no projection — just measure max|r|.
-        const r_worst = has_open
-            ? max_abs_dof(r, diag, cells)
-            : subtract_mean_fluid(r, diag, cells, fluid_count);
-
-        if (r_worst <= tolerance) {
-            // Converged to the requested tolerance — pressure is already
-            // updated for this iteration, stop paying for more sweeps.
-            break;
-        }
-
-        // z = M⁻¹ * r
-        apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
-
-        // sigma_new = r · z
-        let sigma_new = 0;
-        for (let c = 0; c < cells; c++) {
-            sigma_new += r[c] * z[c];
-        }
-
-        if (sigma_new === 0) {
-            break;
-        }
-
-        const beta = sigma_new / sigma;
-
-        // s = z + beta * s
-        for (let c = 0; c < cells; c++) {
-            s[c] = z[c] + beta * s[c];
-        }
-
-        sigma = sigma_new;
-    }
-}
-
-/**
- * Subtract the mean (over fluid cells) from a buffer in place. Used to project
- * a vector onto range(A) = mean-zero subspace; required for CG to converge on
- * a system with a non-trivial null space (pure Neumann pressure Poisson —
- * i.e. a fully sealed domain).
- *
- * @param {Float32Array} v
- * @param {Uint8Array} diag
- * @param {number} cells
- * @param {number} fluid_count
- * @return {number} max|v[c]| over fluid cells AFTER the subtraction — the
- *     residual max-norm the tolerance exit checks, measured for free in the
- *     subtraction pass.
- */
-function subtract_mean_fluid(v, diag, cells, fluid_count) {
-    let sum = 0;
-    for (let c = 0; c < cells; c++) {
-        if (diag[c] !== 0) sum += v[c];
-    }
-    const mean = sum / fluid_count;
-    let worst = 0;
-    for (let c = 0; c < cells; c++) {
-        if (diag[c] !== 0) {
-            const nv = v[c] - mean;
-            v[c] = nv;
-            const a = Math.abs(nv);
-            if (a > worst) worst = a;
-        }
-    }
-    return worst;
-}
-
-/**
- * max|v[c]| over fluid cells. The open-domain counterpart of
- * {@link subtract_mean_fluid}'s return value — no projection needed when the
- * system is non-singular, only the residual norm for the tolerance exit.
- *
- * @param {Float32Array} v
- * @param {Uint8Array} diag
- * @param {number} cells
- * @return {number}
- */
-function max_abs_dof(v, diag, cells) {
-    let worst = 0;
-    for (let c = 0; c < cells; c++) {
-        if (diag[c] !== 0) {
-            const a = Math.abs(v[c]);
-            if (a > worst) worst = a;
-        }
-    }
-    return worst;
-}
-
-/**
- * Apply the MIC(0) preconditioner: solve M · z = r where M = L · Lᵀ.
- *
- * Two sequential sweeps:
- *   - forward (L · y = r): walk fluid cells in lex order, using backward
- *     fluid neighbours' already-computed y values.
- *   - backward (Lᵀ · z = y): walk in reverse lex order, using forward
- *     fluid neighbours' already-computed z values.
- *
- * Both write into `z` in place; the forward pass stores y in z, the backward
- * pass overwrites with the final z. Solid / sealed cells stay at 0 throughout.
- *
- * For our normalized Laplacian (A = -1 off-diagonal, `diag` diagonal), the
- * L factor has L[c, c-1] = -precon[c-1] etc., L[c, c] = 1/precon[c], so each
- * triangular solve degenerates to ~4 floating-point ops per cell.
- *
- * @param {Float32Array} r
- * @param {Float32Array} z
- * @param {Float32Array} precon
- * @param {Uint8Array} mask_array
- * @param {Uint8Array} diag
- * @param {number} cells
- * @param {number} rx
- * @param {number} slice
- */
-function apply_preconditioner(r, z, precon, mask_array, diag, cells, rx, slice) {
-    // Forward solve L · y = r. Store y in z (we won't read z[c'] for c' > c).
-    for (let c = 0; c < cells; c++) {
-        if (diag[c] === 0) {
-            z[c] = 0;
-            continue;
-        }
-        const mask = mask_array[c];
-        let t = r[c];
-        // L[c, c-1] = -precon[c-1] when -x neighbour fluid → subtracting L·y is
-        // adding precon[c-1] * y[c-1].
-        if (mask & 1)  t += precon[c - 1]     * z[c - 1];
-        if (mask & 4)  t += precon[c - rx]    * z[c - rx];
-        if (mask & 16) t += precon[c - slice] * z[c - slice];
-        // L[c, c] = 1 / precon[c] → dividing by it is multiplying by precon[c].
-        z[c] = t * precon[c];
-    }
-
-    // Backward solve Lᵀ · z = y, in place. When we read z[c+1], z[c+rx],
-    // z[c+slice], those were written in this same backward pass (higher
-    // indices, processed first in reverse).
-    for (let c = cells - 1; c >= 0; c--) {
-        if (diag[c] === 0) {
-            continue;
-        }
-        const mask = mask_array[c];
-        let t = z[c]; // = y[c] from forward pass
-        // L[c+1, c] = -precon[c] when c+1's -x neighbour (= c) is fluid, which
-        // is equivalent to "c's +x neighbour (= c+1) is fluid", i.e. mask & 2.
-        if (mask & 2)  t += precon[c] * z[c + 1];
-        if (mask & 8)  t += precon[c] * z[c + rx];
-        if (mask & 32) t += precon[c] * z[c + slice];
-        z[c] = t * precon[c];
-    }
-}
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Popcount table for the 6-bit neighbour mask. Used to detect open faces:
+ * a cell whose Laplacian diagonal exceeds its fluid-neighbour count touches
+ * the domain edge (open boundary), which decides the null-space handling.
+ *
+ * @type {Uint8Array}
+ */
+const POPCOUNT_6 = (function () {
+    const t = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) {
+        let c = 0;
+        for (let b = 0; b < 6; b++) if (i & (1 << b)) c++;
+        t[i] = c;
+    }
+    return t;
+})();
+
+/**
+ * MIC(0) modification weight. Bridson's recommendation is 0.97; the factor scales
+ * how much "would-have-been-fill-in" we re-add onto the diagonal. Lower → closer
+ * to plain IC(0). Higher → stronger preconditioning but riskier (can produce a
+ * non-SPD matrix). 0.97 is the canonical sweet spot from the literature.
+ *
+ * @type {number}
+ */
+const MIC_TAU = 0.97;
+
+/**
+ * Diagonal safeguard threshold. If the computed Cholesky diagonal element falls
+ * below `MIC_SIGMA * A_diag`, we discard the IC factorization for that cell and
+ * fall back to `e = A_diag` (i.e. Jacobi for that cell). Prevents `1/sqrt(small)`
+ * from blowing up.
+ *
+ * @type {number}
+ */
+const MIC_SIGMA = 0.25;
+
+/**
+ * Pressure Poisson solver: Modified Incomplete Cholesky preconditioned Conjugate
+ * Gradient — MIC(0)-PCG.
+ *
+ * Solves `A * p = -div(v)` where A is the 7-point discrete Laplacian over fluid
+ * cells (same matrix as {@link v3_grid_solve_pressure} — that function's SOR
+ * update is exactly the splitting `A * p = -div`). Per cell:
+ *
+ *     A[c, c]  = diag[c] = (# fluid neighbours) + (# open faces)
+ *     A[c, c'] = -1 if c' is a fluid neighbour of c, else 0
+ *
+ * Open faces (out-of-bounds neighbours — the domain edge) carry a Dirichlet
+ * ghost pressure of 0: they enlarge the diagonal without adding an
+ * off-diagonal entry, exactly like a fluid neighbour whose pressure is pinned
+ * at zero. Solid faces are Neumann: absent from both. See
+ * {@link v3_grid_compute_solid_neighbour_mask} for the boundary model.
+ *
+ * PCG converges in roughly `O(√κ)` iterations where κ is the spectral condition
+ * number of `M⁻¹A`. The MIC(0) preconditioner reduces κ from `O(N²)` (raw
+ * Laplacian) to `O(N)`, so a single PCG iter does a lot more useful work than
+ * a single SOR sweep.
+ *
+ * **Empirical finding (V8 / Node, single-thread, this implementation).** Each
+ * PCG iter involves ~8 separate per-cell passes (As compute, axpy×2,
+ * mean-subtract, fwd+bwd triangular solves, dot, s update) vs SOR's 2. In
+ * native code each pass is bandwidth-bound and per-iter ratio approaches the
+ * textbook 2× — yielding the canonical 1.5–2× wall-time win for PCG. In V8,
+ * per-pass loop overhead dominates; the actual per-iter ratio is closer to
+ * 4-6× and PCG ends up SLOWER than SOR at iso-quality on production grids:
+ *
+ *     res=64:  SOR  16 iter  /  75 ms,  max|div| 3.09e-1
+ *              PCG   8 iter  / 181 ms,  max|div| 3.72e-3   (PCG 2.4× slower)
+ *
+ *     res=128: SOR  32 iter  / 862 ms,  max|div| 8.74e-1
+ *              PCG   8 iter  /1452 ms,  max|div| 5.65e-3   (PCG 1.7× slower)
+ *
+ * (Reproduce via `bench: MIC-PCG vs SOR` in bench.spec.js.)
+ *
+ * Where PCG still wins: **convergence depth**. At the SAME iter count it
+ * produces dramatically lower residual divergence (84× better max|div| at
+ * 64³, 247× at 128³). If you need quality below the cell-centered operator
+ * floor SOR plateaus at — e.g. quantitative pressure inspection, or
+ * extreme-impulse scenes where the SOR floor is visible — PCG is the answer.
+ * For visual-fluids steady state, **leave the default at SOR**.
+ *
+ * If this code is ever ported to WASM SIMD or WebGPU the perf comparison
+ * flips: per-iter overhead becomes negligible in those environments and the
+ * theoretical 1.5–2× PCG win re-emerges. Worth re-running the bench then.
+ *
+ * Algorithm (Bridson "Fluid Simulation for Computer Graphics" §5.6, Saad
+ * §10.2):
+ *
+ *     1.  build_preconditioner: walk fluid cells in lex order, computing
+ *         precon[c] = 1 / sqrt(e[c]) where e[c] is the modified Cholesky
+ *         diagonal. Backward neighbours (-x, -y, -z) contribute to the
+ *         subtraction.
+ *
+ *     2.  r₀ = -div - A * p₀     (initial residual; p₀ is the warm-start)
+ *         z₀ = M⁻¹ * r₀          (apply preconditioner — two triangular solves)
+ *         s₀ = z₀
+ *         σ₀ = r₀ · z₀
+ *
+ *     3.  For k = 0, 1, …, max_iter-1:
+ *             A·sₖ
+ *             α = σₖ / (sₖ · A·sₖ)
+ *             p ← p + α·sₖ
+ *             r ← r - α·A·sₖ
+ *             z ← M⁻¹ · r
+ *             σₖ₊₁ = r · z
+ *             β = σₖ₊₁ / σₖ
+ *             s ← z + β·s
+ *
+ * Preconditioner apply is a forward sweep (L·y = r) followed by a backward
+ * sweep (Lᵀ·z = y). Both sweeps are O(N) and inherently sequential — they're
+ * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
+ * substantial reformulation. On single-thread JS that's not a concern.
+ *
+ * Null space: when NO fluid cell touches the domain edge (a fully sealed
+ * domain — every boundary cell solid), A is the pure-Neumann Laplacian and has
+ * the constant vector in its null space. The residual is then projected onto
+ * the mean-zero subspace after every update, the standard fluids practice
+ * (Bridson §5.5) — without it alpha explodes once the search direction aligns
+ * with the null space. With ANY open face the system is non-singular and the
+ * projection is skipped (subtracting the mean there would solve a different
+ * right-hand side). Caveat: a sealed sub-region inside an otherwise open
+ * domain is still locally singular; its constant mode is harmless to the open
+ * region but convergence inside that pocket is not guaranteed — split fields
+ * rather than simulating disconnected sealed rooms in one volume.
+ *
+ * Cells with `diag[c] === 0` — solid cells and fluid sealed on all six faces —
+ * are excluded from the system: their pressure stays at whatever it was
+ * (typically 0), their entries in r, z, s, As stay 0, and they contribute
+ * nothing to dot products.
+ *
+ * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
+ *     or with the previous step's solution to warm-start.
+ * @param {Float32Array|Float16Array} divergence  From `v3_grid_compute_divergence`.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} max_iterations  Cap. The solve also exits as soon as the
+ *     tolerance is met (below), or via the implicit-zero dot product guards.
+ * @param {number} relative_tolerance  Convergence exit: stop when
+ *     `max|r| <= relative_tolerance * max|−div|` over fluid cells (residual
+ *     measured after the null-space mean subtraction, where that applies).
+ *     `0` disables the tolerance exit — the solve then runs to
+ *     `max_iterations` exactly as the pre-tolerance implementation did.
+ *     Production use: the cap is sized for the cold-start worst case, and the
+ *     warm-started steady state exits in a fraction of it; without this exit
+ *     every warm frame pays the cold-start budget for no quality gain.
+ * @param {Uint8Array} neighbour_mask  From `v3_grid_compute_solid_neighbour_mask`.
+ * @param {Uint8Array} diag  Laplacian diagonal per cell, baked by the same
+ *     kernel as `neighbour_mask`.
+ * @param {Float32Array} scratch_r  Length ≥ rx*ry*rz. Residual.
+ * @param {Float32Array} scratch_z  Length ≥ rx*ry*rz. Preconditioned residual.
+ * @param {Float32Array} scratch_s  Length ≥ rx*ry*rz. Search direction.
+ * @param {Float32Array} scratch_As  Length ≥ rx*ry*rz. A applied to s.
+ * @param {Float32Array} scratch_precon  Length ≥ rx*ry*rz. Preconditioner
+ *     diagonal (1/sqrt(e_c) per fluid cell, 0 for solid).
+ */
+export function v3_grid_solve_pressure_pcg(
+    pressure, divergence,
+    res_x, res_y, res_z,
+    max_iterations, relative_tolerance,
+    neighbour_mask, diag,
+    scratch_r, scratch_z, scratch_s, scratch_As, scratch_precon
+) {
+    const cells = res_x * res_y * res_z;
+
+    assert.notEqual(pressure, divergence, "pressure must not alias divergence");
+    assert.greaterThanOrEqual(pressure.length, cells, "pressure covers grid");
+    assert.greaterThanOrEqual(divergence.length, cells, "divergence covers grid");
+    assert.greaterThanOrEqual(neighbour_mask.length, cells, "neighbour_mask covers grid");
+    assert.greaterThanOrEqual(diag.length, cells, "diag covers grid");
+    assert.greaterThanOrEqual(scratch_r.length, cells, "scratch_r covers grid");
+    assert.greaterThanOrEqual(scratch_z.length, cells, "scratch_z covers grid");
+    assert.greaterThanOrEqual(scratch_s.length, cells, "scratch_s covers grid");
+    assert.greaterThanOrEqual(scratch_As.length, cells, "scratch_As covers grid");
+    assert.greaterThanOrEqual(scratch_precon.length, cells, "scratch_precon covers grid");
+    assert.isNonNegativeInteger(max_iterations, "max_iterations");
+    assert.isNumber(relative_tolerance, "relative_tolerance");
+    assert.greaterThanOrEqual(relative_tolerance, 0, "relative_tolerance");
+
+    if (max_iterations === 0) {
+        return;
+    }
+
+    const rx = res_x;
+    const slice = res_x * res_y;
+
+    const precon = scratch_precon;
+    const r = scratch_r;
+    const z = scratch_z;
+    const s = scratch_s;
+    const As = scratch_As;
+
+    // Count degrees of freedom and detect open faces. A DOF is any cell with
+    // diag > 0. `has_open` (any cell whose diagonal exceeds its fluid-neighbour
+    // count) decides the null-space treatment — see the class of comment above.
+    let fluid_count = 0;
+    let has_open = false;
+    for (let c = 0; c < cells; c++) {
+        const d = diag[c];
+        if (d === 0) continue;
+        fluid_count++;
+        if (d > POPCOUNT_6[neighbour_mask[c] & 63]) {
+            has_open = true;
+        }
+    }
+    if (fluid_count === 0) {
+        return;
+    }
+
+    // ─── 1. Build MIC(0) preconditioner ─────────────────────────────────────
+    //
+    // Walk fluid cells in lex order; for each, compute the modified Cholesky
+    // diagonal e[c] from the backward (-x, -y, -z) fluid neighbours and store
+    // precon[c] = 1 / sqrt(e[c]). Solid / sealed cells keep precon = 0.
+    //
+    // The "modified" piece adds tau * (off-direction terms) back onto the
+    // diagonal — it compensates for fill-in that plain IC(0) drops, and makes
+    // PCG converge in O(√N) instead of O(N²/³).
+    precon.fill(0);
+    for (let c = 0; c < cells; c++) {
+        const a_diag = diag[c];
+        if (a_diag === 0) {
+            continue;
+        }
+        const mask = neighbour_mask[c];
+        let e = a_diag;
+
+        if (mask & 1) {  // -x backward neighbour is fluid
+            const c_prev = c - 1;
+            const p_prev = precon[c_prev];
+            const p_prev_sq = p_prev * p_prev;
+            // (A[c, c_prev] * precon[c_prev])^2 = precon_prev^2 since A = -1.
+            e -= p_prev_sq;
+            // Modification: tau * A[c, c_prev] * (off-direction A entries from c_prev) * precon_prev^2.
+            // A[c, c_prev] = -1. Off-directions from c_prev pointing away from c
+            // are +y (bit 3 of c_prev's mask) and +z (bit 5).
+            const m_prev = neighbour_mask[c_prev];
+            const off = ((m_prev >> 3) & 1) + ((m_prev >> 5) & 1);
+            // Contribution: tau * (-1) * (-(off)) * precon_prev^2 = tau * off * precon_prev^2
+            e -= MIC_TAU * off * p_prev_sq;
+        }
+        if (mask & 4) {  // -y
+            const c_prev = c - rx;
+            const p_prev = precon[c_prev];
+            const p_prev_sq = p_prev * p_prev;
+            e -= p_prev_sq;
+            const m_prev = neighbour_mask[c_prev];
+            // Off-directions from c_prev: +x (bit 1), +z (bit 5).
+            const off = ((m_prev >> 1) & 1) + ((m_prev >> 5) & 1);
+            e -= MIC_TAU * off * p_prev_sq;
+        }
+        if (mask & 16) {  // -z
+            const c_prev = c - slice;
+            const p_prev = precon[c_prev];
+            const p_prev_sq = p_prev * p_prev;
+            e -= p_prev_sq;
+            const m_prev = neighbour_mask[c_prev];
+            // Off-directions from c_prev: +x (bit 1), +y (bit 3).
+            const off = ((m_prev >> 1) & 1) + ((m_prev >> 3) & 1);
+            e -= MIC_TAU * off * p_prev_sq;
+        }
+
+        // Safeguard: if e dropped below sigma*A_diag, the factorization is
+        // becoming non-SPD-friendly; fall back to plain Jacobi for this cell.
+        if (e < MIC_SIGMA * a_diag) {
+            e = a_diag;
+        }
+        precon[c] = 1 / Math.sqrt(e);
+    }
+
+    // ─── 2. r = -div - A * pressure  (initial residual) ─────────────────────
+
+    // max|b| over fluid cells anchors the relative tolerance exit.
+    let max_b = 0;
+    for (let c = 0; c < cells; c++) {
+        const a_diag = diag[c];
+        if (a_diag === 0) {
+            r[c] = 0;
+            continue;
+        }
+        const b_abs = Math.abs(divergence[c]);
+        if (b_abs > max_b) max_b = b_abs;
+        const mask = neighbour_mask[c];
+        let Ap = a_diag * pressure[c];
+        if (mask & 1)  Ap -= pressure[c - 1];
+        if (mask & 2)  Ap -= pressure[c + 1];
+        if (mask & 4)  Ap -= pressure[c - rx];
+        if (mask & 8)  Ap -= pressure[c + rx];
+        if (mask & 16) Ap -= pressure[c - slice];
+        if (mask & 32) Ap -= pressure[c + slice];
+        r[c] = -divergence[c] - Ap;
+    }
+    const tolerance = relative_tolerance * max_b;
+
+    const r0_worst = has_open
+        ? max_abs_dof(r, diag, cells)
+        : subtract_mean_fluid(r, diag, cells, fluid_count);
+    if (r0_worst <= tolerance) {
+        // Warm start already within tolerance — nothing to refine. (With
+        // relative_tolerance = 0 this only triggers on an exactly-zero
+        // residual, matching the historical behaviour.)
+        return;
+    }
+
+    // ─── 3. z = M⁻¹ * r, s = z, sigma = r · z ───────────────────────────────
+
+    apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
+
+    let sigma = 0;
+    for (let c = 0; c < cells; c++) {
+        s[c] = z[c];
+        sigma += r[c] * z[c];
+    }
+
+    if (sigma === 0) {
+        // Initial residual was already zero (or pathological). Either way,
+        // nothing to do.
+        return;
+    }
+
+    // ─── 4. PCG outer loop ──────────────────────────────────────────────────
+
+    for (let iter = 0; iter < max_iterations; iter++) {
+
+        // As = A * s, accumulating s · As in the same pass.
+        let s_dot_As = 0;
+        for (let c = 0; c < cells; c++) {
+            const a_diag = diag[c];
+            if (a_diag === 0) {
+                As[c] = 0;
+                continue;
+            }
+            const mask = neighbour_mask[c];
+            let val = a_diag * s[c];
+            if (mask & 1)  val -= s[c - 1];
+            if (mask & 2)  val -= s[c + 1];
+            if (mask & 4)  val -= s[c - rx];
+            if (mask & 8)  val -= s[c + rx];
+            if (mask & 16) val -= s[c - slice];
+            if (mask & 32) val -= s[c + slice];
+            As[c] = val;
+            s_dot_As += s[c] * val;
+        }
+
+        if (s_dot_As === 0) {
+            // Degenerate search direction; stop.
+            break;
+        }
+
+        const alpha = sigma / s_dot_As;
+
+        // pressure += alpha * s
+        // r        -= alpha * As
+        for (let c = 0; c < cells; c++) {
+            pressure[c] += alpha * s[c];
+            r[c]        -= alpha * As[c];
+        }
+        // Sealed domain: project r back onto the mean-zero (range(A)) subspace
+        // — round-off accumulates a constant component each iter; without this,
+        // alpha explodes within ~8 iters once s aligns with the null space.
+        // Open domain: A is non-singular, no projection — just measure max|r|.
+        const r_worst = has_open
+            ? max_abs_dof(r, diag, cells)
+            : subtract_mean_fluid(r, diag, cells, fluid_count);
+
+        if (r_worst <= tolerance) {
+            // Converged to the requested tolerance — pressure is already
+            // updated for this iteration, stop paying for more sweeps.
+            break;
+        }
+
+        // z = M⁻¹ * r
+        apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
+
+        // sigma_new = r · z
+        let sigma_new = 0;
+        for (let c = 0; c < cells; c++) {
+            sigma_new += r[c] * z[c];
+        }
+
+        if (sigma_new === 0) {
+            break;
+        }
+
+        const beta = sigma_new / sigma;
+
+        // s = z + beta * s
+        for (let c = 0; c < cells; c++) {
+            s[c] = z[c] + beta * s[c];
+        }
+
+        sigma = sigma_new;
+    }
+}
+
+/**
+ * Subtract the mean (over fluid cells) from a buffer in place. Used to project
+ * a vector onto range(A) = mean-zero subspace; required for CG to converge on
+ * a system with a non-trivial null space (pure Neumann pressure Poisson —
+ * i.e. a fully sealed domain).
+ *
+ * @param {Float32Array} v
+ * @param {Uint8Array} diag
+ * @param {number} cells
+ * @param {number} fluid_count
+ * @return {number} max|v[c]| over fluid cells AFTER the subtraction — the
+ *     residual max-norm the tolerance exit checks, measured for free in the
+ *     subtraction pass.
+ */
+function subtract_mean_fluid(v, diag, cells, fluid_count) {
+    let sum = 0;
+    for (let c = 0; c < cells; c++) {
+        if (diag[c] !== 0) sum += v[c];
+    }
+    const mean = sum / fluid_count;
+    let worst = 0;
+    for (let c = 0; c < cells; c++) {
+        if (diag[c] !== 0) {
+            const nv = v[c] - mean;
+            v[c] = nv;
+            const a = Math.abs(nv);
+            if (a > worst) worst = a;
+        }
+    }
+    return worst;
+}
+
+/**
+ * max|v[c]| over fluid cells. The open-domain counterpart of
+ * {@link subtract_mean_fluid}'s return value — no projection needed when the
+ * system is non-singular, only the residual norm for the tolerance exit.
+ *
+ * @param {Float32Array} v
+ * @param {Uint8Array} diag
+ * @param {number} cells
+ * @return {number}
+ */
+function max_abs_dof(v, diag, cells) {
+    let worst = 0;
+    for (let c = 0; c < cells; c++) {
+        if (diag[c] !== 0) {
+            const a = Math.abs(v[c]);
+            if (a > worst) worst = a;
+        }
+    }
+    return worst;
+}
+
+/**
+ * Apply the MIC(0) preconditioner: solve M · z = r where M = L · Lᵀ.
+ *
+ * Two sequential sweeps:
+ *   - forward (L · y = r): walk fluid cells in lex order, using backward
+ *     fluid neighbours' already-computed y values.
+ *   - backward (Lᵀ · z = y): walk in reverse lex order, using forward
+ *     fluid neighbours' already-computed z values.
+ *
+ * Both write into `z` in place; the forward pass stores y in z, the backward
+ * pass overwrites with the final z. Solid / sealed cells stay at 0 throughout.
+ *
+ * For our normalized Laplacian (A = -1 off-diagonal, `diag` diagonal), the
+ * L factor has L[c, c-1] = -precon[c-1] etc., L[c, c] = 1/precon[c], so each
+ * triangular solve degenerates to ~4 floating-point ops per cell.
+ *
+ * @param {Float32Array} r
+ * @param {Float32Array} z
+ * @param {Float32Array} precon
+ * @param {Uint8Array} mask_array
+ * @param {Uint8Array} diag
+ * @param {number} cells
+ * @param {number} rx
+ * @param {number} slice
+ */
+function apply_preconditioner(r, z, precon, mask_array, diag, cells, rx, slice) {
+    // Forward solve L · y = r. Store y in z (we won't read z[c'] for c' > c).
+    for (let c = 0; c < cells; c++) {
+        if (diag[c] === 0) {
+            z[c] = 0;
+            continue;
+        }
+        const mask = mask_array[c];
+        let t = r[c];
+        // L[c, c-1] = -precon[c-1] when -x neighbour fluid → subtracting L·y is
+        // adding precon[c-1] * y[c-1].
+        if (mask & 1)  t += precon[c - 1]     * z[c - 1];
+        if (mask & 4)  t += precon[c - rx]    * z[c - rx];
+        if (mask & 16) t += precon[c - slice] * z[c - slice];
+        // L[c, c] = 1 / precon[c] → dividing by it is multiplying by precon[c].
+        z[c] = t * precon[c];
+    }
+
+    // Backward solve Lᵀ · z = y, in place. When we read z[c+1], z[c+rx],
+    // z[c+slice], those were written in this same backward pass (higher
+    // indices, processed first in reverse).
+    for (let c = cells - 1; c >= 0; c--) {
+        if (diag[c] === 0) {
+            continue;
+        }
+        const mask = mask_array[c];
+        let t = z[c]; // = y[c] from forward pass
+        // L[c+1, c] = -precon[c] when c+1's -x neighbour (= c) is fluid, which
+        // is equivalent to "c's +x neighbour (= c+1) is fluid", i.e. mask & 2.
+        if (mask & 2)  t += precon[c] * z[c + 1];
+        if (mask & 8)  t += precon[c] * z[c + rx];
+        if (mask & 32) t += precon[c] * z[c + slice];
+        z[c] = t * precon[c];
+    }
+}