@woosh/meep-engine 2.156.0 → 2.158.0

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

@@ -1,36 +1,19 @@
 import { assert } from "../../../../core/assert.js";
 
-/**
- * Popcount lookup for the 6-bit neighbour mask. Index = mask value (0–63 used in
- * practice; the table is sized 64 so the read is a single bounded indexed access).
- * Values are the SOR denominator (number of fluid neighbours) for each mask.
- *
- * @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;
-})();
-
 /**
  * Solve the pressure Poisson equation `∇²p = div(v)` by red-black Successive
- * Over-Relaxation (SOR), gated by a pre-baked per-cell neighbour mask.
+ * Over-Relaxation (SOR), gated by pre-baked per-cell neighbour data.
  *
  * Per cell, the update is:
  *
- *     p_jacobi(c) = ( sum_of_fluid_neighbour_pressures - div(c) ) / count
+ *     p_jacobi(c) = ( sum_of_fluid_neighbour_pressures - div(c) ) / diag(c)
  *     p(c) = (1 - ω) * p(c) + ω * p_jacobi(c)
  *
- * "Which neighbours count as fluid" is determined entirely by `neighbour_mask`,
- * a Uint8Array allocated and populated by {@link FluidField} via
- * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
+ * Which faces participate is determined entirely by `neighbour_mask` and
+ * `diag`, both produced by {@link v3_grid_compute_solid_neighbour_mask}
+ * (via {@link FluidField.recomputeSolidNeighbourMask}):
  *
- *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid — read its pressure
  *     bit 1 (= 2)   : +x neighbour is fluid
  *     bit 2 (= 4)   : -y neighbour is fluid
  *     bit 3 (= 8)   : +y neighbour is fluid
@@ -39,14 +22,19 @@ const POPCOUNT_6 = (function () {
  *     bit 7 (= 128) : this cell is itself solid (consumed by
  *                     {@link v3_grid_subtract_pressure_gradient}, ignored here)
  *
- * The low 6 bits are the fluid-neighbour set. A solid cell encodes as `128` and
- * an isolated fluid cell as `0`, so the inner loop's `(mask & 63) === 0 ? skip`
- * covers both self-solid AND fluid-with-no-fluid-neighbours in one comparison.
- * This eliminates six boundary checks plus six solid-neighbour checks per cell
- * per iteration, replacing them with a single mask read and six bit-tests on a
- * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
- * implicit — the recompute step writes 0 into the boundary-facing bit, so the
- * SOR loop never reads out-of-range memory.
+ *     diag(c) = (# fluid neighbours) + (# open faces)
+ *
+ * Boundary semantics fall out of the encoding:
+ *   - SOLID face (in-bounds neighbour with the bit clear): Neumann/reflecting —
+ *     absent from both the sum and `diag`.
+ *   - OPEN face (out-of-bounds neighbour): Dirichlet ghost `p = 0` — absent
+ *     from the sum (a zero contribution) but counted in `diag`. The domain
+ *     edge therefore behaves as an open boundary; sealed domains are built by
+ *     lining the edge with solid cells.
+ *
+ * `diag === 0` covers "this cell is solid" AND "this fluid cell is sealed on
+ * all six faces" with a single comparison, so the inner loop pays one byte
+ * read and one test per skipped cell and never reads out-of-range memory.
  *
  * Cells are visited in two passes per iteration: first "red" (`(x+y+z) % 2 === 0`)
  * then "black". Adjacent cells have opposite colour, so each pass reads only
@@ -62,18 +50,21 @@ const POPCOUNT_6 = (function () {
  * @param {number} res_z
  * @param {number} iterations  Number of red-black sweeps.
  * @param {number} omega  SOR relaxation factor in (0, 2). Near-optimal values
- *     come from {@link optimal_sor_omega}.
- * @param {Uint8Array} neighbour_mask  Length ≥ res_x*res_y*res_z. Each byte
- *     encodes the fluid-neighbour bitmask (see above). MUST be recomputed
- *     whenever the underlying solid mask changes.
+ *     come from {@link sor_optimal_omega}.
+ * @param {Uint8Array} neighbour_mask  Length ≥ res_x*res_y*res_z. Fluid-neighbour
+ *     bitmask (see above). MUST be recomputed whenever the underlying solid
+ *     mask changes.
+ * @param {Uint8Array} diag  Length ≥ res_x*res_y*res_z. Laplacian diagonal per
+ *     cell, baked by the same kernel as `neighbour_mask`.
  */
-export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z, iterations, omega, neighbour_mask) {
+export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z, iterations, omega, neighbour_mask, diag) {
     const cell_count = res_x * res_y * res_z;
 
     assert.notEqual(pressure, divergence, "pressure must not alias divergence");
     assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
     assert.greaterThanOrEqual(divergence.length, cell_count, "divergence covers grid");
     assert.greaterThanOrEqual(neighbour_mask.length, cell_count, "neighbour_mask covers grid");
+    assert.greaterThanOrEqual(diag.length, cell_count, "diag covers grid");
     assert.isNonNegativeInteger(iterations, "iterations");
     assert.greaterThan(omega, 0, "omega");
     assert.lessThan(omega, 2, "omega");
@@ -84,6 +75,7 @@ export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z
 
     const slice_size = res_x * res_y;
     const one_minus_omega = 1 - omega;
+    const omega_sixth = omega / 6;
 
     for (let iter = 0; iter < iterations; iter++) {
 
@@ -104,11 +96,24 @@ export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z
                         const c = z_off + y_off + x;
 
                         const mask = neighbour_mask[c];
-                        if ((mask & 63) === 0) {
-                            // No fluid neighbours: solid cell (bit 7 set) OR isolated
-                            // fluid. Either way, no degrees of freedom — skip. Cells
-                            // that reach past here have bit 7 clear, so `mask` indexes
-                            // POPCOUNT_6 (sized 64) in range.
+                        if (mask === 63) {
+                            // Full-interior fluid cell (all six neighbours fluid,
+                            // which implies diag === 6): branch-free body with a
+                            // constant diagonal and no diag-array read. The
+                            // overwhelmingly common case on open fields — ~91% of
+                            // cells at 64³ — measured 37% faster per sweep there
+                            // and within noise at small shallow grids.
+                            const sum = pressure[c - 1] + pressure[c + 1]
+                                + pressure[c - res_x] + pressure[c + res_x]
+                                + pressure[c - slice_size] + pressure[c + slice_size];
+                            pressure[c] = one_minus_omega * pressure[c] + omega_sixth * (sum - divergence[c]);
+                            continue;
+                        }
+
+                        const count = diag[c];
+                        if (count === 0) {
+                            // No degrees of freedom: solid cell or fluid sealed on
+                            // all six faces. Skip.
                             continue;
                         }
 
@@ -120,7 +125,6 @@ export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z
                         if (mask & 16) sum += pressure[c - slice_size];
                         if (mask & 32) sum += pressure[c + slice_size];
 
-                        const count = POPCOUNT_6[mask];
                         const p_target = (sum - divergence[c]) / count;
                         pressure[c] = one_minus_omega * pressure[c] + omega * p_target;
                     }

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

@@ -3,12 +3,18 @@
  * Gradient — MIC(0)-PCG.
  *
  * Solves `A * p = -div(v)` where A is the 7-point discrete Laplacian over fluid
- * cells (same sign convention as {@link v3_grid_solve_pressure} — that
- * function's SOR update is exactly the splitting `A * p = -div`). Per cell:
+ * 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]  = number of fluid neighbours (= popcount(neighbour_mask[c]))
+ *     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
@@ -69,10 +75,22 @@
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
- * fluid (mask = 0), both identified by `(mask & 63) === 0` — 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.
+ * 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.
@@ -80,9 +98,19 @@
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {number} max_iterations  Cap. Converged early-exits via implicit-zero
- *     dot product (sigma reaches 0 or numerical noise).
+ * @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.
@@ -90,5 +118,5 @@
  * @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: Float32Array | Float16Array, divergence: Float32Array | Float16Array, res_x: number, res_y: number, res_z: number, max_iterations: number, neighbour_mask: Uint8Array, scratch_r: Float32Array, scratch_z: Float32Array, scratch_s: Float32Array, scratch_As: Float32Array, scratch_precon: Float32Array): void;
+export function v3_grid_solve_pressure_pcg(pressure: Float32Array | Float16Array, divergence: Float32Array | Float16Array, res_x: number, res_y: number, res_z: number, max_iterations: number, relative_tolerance: number, neighbour_mask: Uint8Array, diag: Uint8Array, scratch_r: Float32Array, scratch_z: Float32Array, scratch_s: Float32Array, scratch_As: Float32Array, scratch_precon: Float32Array): void;
 //# sourceMappingURL=v3_grid_solve_pressure_pcg.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,qDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,kBAEN,UAAU,aACV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QA0NtB"}
+{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuHG;AACH,qDA1BW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,sBAEN,MAAM,kBAQN,UAAU,QACV,UAAU,aAEV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QAgPtB"}

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

@@ -1,9 +1,9 @@
 import { assert } from "../../../../core/assert.js";
 
 /**
- * Popcount table for the 6-bit neighbour mask — same encoding used by
- * {@link v3_grid_solve_pressure}. Indexed by the mask byte (0-63), value is the
- * SOR / Laplacian denominator = number of fluid neighbours.
+ * 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}
  */
@@ -42,12 +42,18 @@ const MIC_SIGMA = 0.25;
  * Gradient — MIC(0)-PCG.
  *
  * Solves `A * p = -div(v)` where A is the 7-point discrete Laplacian over fluid
- * cells (same sign convention as {@link v3_grid_solve_pressure} — that
- * function's SOR update is exactly the splitting `A * p = -div`). Per cell:
+ * 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]  = number of fluid neighbours (= popcount(neighbour_mask[c]))
+ *     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
@@ -108,10 +114,22 @@ const MIC_SIGMA = 0.25;
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
- * fluid (mask = 0), both identified by `(mask & 63) === 0` — 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.
+ * 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.
@@ -119,9 +137,19 @@ const MIC_SIGMA = 0.25;
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {number} max_iterations  Cap. Converged early-exits via implicit-zero
- *     dot product (sigma reaches 0 or numerical noise).
+ * @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.
@@ -132,8 +160,8 @@ const MIC_SIGMA = 0.25;
 export function v3_grid_solve_pressure_pcg(
     pressure, divergence,
     res_x, res_y, res_z,
-    max_iterations,
-    neighbour_mask,
+    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;
@@ -142,12 +170,15 @@ export function v3_grid_solve_pressure_pcg(
     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;
@@ -162,24 +193,18 @@ export function v3_grid_solve_pressure_pcg(
     const s = scratch_s;
     const As = scratch_As;
 
-    // Count fluid cells for the null-space projection (mean subtraction). With
-    // all-Neumann boundary conditions and no Dirichlet anchor, the discrete
-    // Laplacian has a 1-D null space (constant pressure). Plain (P)CG drifts
-    // along that direction — iterates can explode within ~10 sweeps even
-    // though the residual stays small in the orthogonal complement. Projecting
-    // r back onto the mean-zero subspace after every update keeps the search
-    // direction perpendicular to the null space and lets PCG converge as
-    // theory predicts.
-    //
-    // (Standard fluids practice — see Bridson §5.5. The alternative is to pin
-    // one cell to a Dirichlet value and exclude it from the system, but mean
-    // subtraction has the same effect with simpler bookkeeping.)
-    // A cell is a degree of freedom iff it has ≥1 fluid neighbour, i.e. any of
-    // the low 6 bits set. Solid cells (bit 7) and isolated fluid (all-zero) are
-    // both excluded by masking off bit 7 with & 63.
+    // 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++) {
-        if ((neighbour_mask[c] & 63) !== 0) fluid_count++;
+        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;
@@ -189,18 +214,18 @@ export function v3_grid_solve_pressure_pcg(
     //
     // 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 / isolated cells keep precon = 0.
+    // 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 mask = neighbour_mask[c];
-        if ((mask & 63) === 0) {
+        const a_diag = diag[c];
+        if (a_diag === 0) {
             continue;
         }
-        const a_diag = POPCOUNT_6[mask];
+        const mask = neighbour_mask[c];
         let e = a_diag;
 
         if (mask & 1) {  // -x backward neighbour is fluid
@@ -248,13 +273,18 @@ export function v3_grid_solve_pressure_pcg(
 
     // ─── 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 mask = neighbour_mask[c];
-        if ((mask & 63) === 0) {
+        const a_diag = diag[c];
+        if (a_diag === 0) {
             r[c] = 0;
             continue;
         }
-        let Ap = POPCOUNT_6[mask] * pressure[c];
+        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];
@@ -263,11 +293,21 @@ export function v3_grid_solve_pressure_pcg(
         if (mask & 32) Ap -= pressure[c + slice];
         r[c] = -divergence[c] - Ap;
     }
-    subtract_mean_fluid(r, neighbour_mask, cells, fluid_count);
+    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, cells, rx, slice);
+    apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
 
     let sigma = 0;
     for (let c = 0; c < cells; c++) {
@@ -288,12 +328,13 @@ export function v3_grid_solve_pressure_pcg(
         // As = A * s, accumulating s · As in the same pass.
         let s_dot_As = 0;
         for (let c = 0; c < cells; c++) {
-            const mask = neighbour_mask[c];
-            if ((mask & 63) === 0) {
+            const a_diag = diag[c];
+            if (a_diag === 0) {
                 As[c] = 0;
                 continue;
             }
-            let val = POPCOUNT_6[mask] * s[c];
+            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];
@@ -317,13 +358,22 @@ export function v3_grid_solve_pressure_pcg(
             pressure[c] += alpha * s[c];
             r[c]        -= alpha * As[c];
         }
-        // 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.
-        subtract_mean_fluid(r, neighbour_mask, cells, fluid_count);
+        // 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, cells, rx, slice);
+        apply_preconditioner(r, z, precon, neighbour_mask, diag, cells, rx, slice);
 
         // sigma_new = r · z
         let sigma_new = 0;
@@ -346,6 +396,59 @@ export function v3_grid_solve_pressure_pcg(
     }
 }
 
+/**
+ * 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ᵀ.
  *
@@ -356,9 +459,9 @@ export function v3_grid_solve_pressure_pcg(
  *     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 cells stay at 0 throughout.
+ * pass overwrites with the final z. Solid / sealed cells stay at 0 throughout.
  *
- * For our normalized Laplacian (A = -1 off-diagonal, popcount diagonal), the
+ * 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.
  *
@@ -366,39 +469,19 @@ export function v3_grid_solve_pressure_pcg(
  * @param {Float32Array} z
  * @param {Float32Array} precon
  * @param {Uint8Array} mask_array
+ * @param {Uint8Array} diag
  * @param {number} cells
  * @param {number} rx
  * @param {number} slice
  */
-/**
- * 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).
- *
- * @param {Float32Array} v
- * @param {Uint8Array} mask_array
- * @param {number} cells
- * @param {number} fluid_count
- */
-function subtract_mean_fluid(v, mask_array, cells, fluid_count) {
-    let sum = 0;
-    for (let c = 0; c < cells; c++) {
-        if ((mask_array[c] & 63) !== 0) sum += v[c];
-    }
-    const mean = sum / fluid_count;
-    for (let c = 0; c < cells; c++) {
-        if ((mask_array[c] & 63) !== 0) v[c] -= mean;
-    }
-}
-
-function apply_preconditioner(r, z, precon, mask_array, cells, rx, 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++) {
-        const mask = mask_array[c];
-        if ((mask & 63) === 0) {
+        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].
@@ -413,10 +496,10 @@ function apply_preconditioner(r, z, precon, mask_array, cells, rx, slice) {
     // 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--) {
-        const mask = mask_array[c];
-        if ((mask & 63) === 0) {
+        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.