@woosh/meep-engine 2.155.0 → 2.157.0

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

@@ -1,12 +1,11 @@
 /**
- * Bake a per-cell neighbourhood mask describing which of the 6 cardinal
- * neighbours of each cell are "fluid" (in-bounds AND non-solid). Consumed by
- * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
- * and solid-neighbour checks entirely.
+ * Bake the per-cell neighbourhood data consumed by the pressure solvers and
+ * the gradient subtraction: a 6-bit fluid-neighbour mask and the 7-point
+ * Laplacian diagonal.
  *
- * Encoding (one byte per cell):
+ * Mask encoding (one byte per cell):
  *
- *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
  *     bit 1 (= 2)   : +x neighbour is fluid
  *     bit 2 (= 4)   : -y neighbour is fluid
  *     bit 3 (= 8)   : +y neighbour is fluid
@@ -14,24 +13,35 @@
  *     bit 5 (= 32)  : +z neighbour is fluid
  *     bit 7 (= 128) : this cell is itself solid
  *
- * The low 6 bits are the fluid-neighbour set; bit 7 flags the cell as solid.
- * A solid cell encodes as exactly `128` — bit 7 set, every neighbour bit clear
- * — and an isolated fluid cell (no fluid neighbours) as `0`. Both therefore
- * satisfy `(mask & 63) === 0`, so the SOR / PCG loops' "no fluid neighbours →
- * skip" branch is a single `(mask & 63) === 0` comparison that covers
- * "self-solid" and "fluid but no fluid neighbours" alike. The dedicated bit 7
- * additionally lets {@link v3_grid_subtract_pressure_gradient} tell solid cells
- * (zero the velocity) apart from isolated fluid (leave it) without the original
- * `solid` array.
- *
- * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
- * fully replaces whatever was in `mask` before; no need to zero-init.
- *
- * @param {Uint8Array} mask  Destination. Length ≥ res_x*res_y*res_z.
- * @param {Uint8Array} solid  Source. Length ≥ res_x*res_y*res_z. Non-zero = solid.
+ * Diagonal encoding (one byte per cell): the pressure-Laplacian diagonal
+ * coefficient — the number of faces that participate in the solve:
+ *
+ *     diag = (# fluid neighbours) + (# open faces)
+ *
+ * where an OPEN face is one whose neighbour lies outside the grid. The domain
+ * edge is an open boundary: outside pressure is the ghost value `0`
+ * (Dirichlet), so the face counts toward the diagonal while contributing
+ * nothing to the stencil sum — flow can exit the grid and the Poisson system
+ * is non-singular whenever any fluid cell touches the edge. A SOLID face is a
+ * Neumann (reflecting) boundary: dropped from both the sum and the diagonal.
+ * Sealed domains are therefore built explicitly, by lining the boundary with
+ * solid cells — there is no "closed box" mode on the open edge itself.
+ *
+ * A solid cell encodes as mask `128` / diag `0`. `diag === 0` is the solvers'
+ * single "no degrees of freedom — skip" test: it covers self-solid AND fluid
+ * sealed on all six faces alike. A fluid cell whose neighbours are all solid
+ * but which touches the domain edge still has `diag > 0` — it drains through
+ * the open face.
+ *
+ * O(N) — two byte-writes per cell, up to six byte-reads per cell. Outputs
+ * fully replace previous contents; no need to zero-init.
+ *
+ * @param {Uint8Array} mask   Destination, fluid-neighbour bits. Length ≥ N.
+ * @param {Uint8Array} diag   Destination, Laplacian diagonal (0–6). Length ≥ N.
+ * @param {Uint8Array} solid  Source. Length ≥ N. Non-zero = solid.
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
  */
-export function v3_grid_compute_solid_neighbour_mask(mask: Uint8Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number): void;
+export function v3_grid_compute_solid_neighbour_mask(mask: Uint8Array, diag: Uint8Array, solid: Uint8Array, res_x: number, res_y: number, res_z: number): void;
 //# sourceMappingURL=v3_grid_compute_solid_neighbour_mask.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_compute_solid_neighbour_mask.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,2DANW,UAAU,SACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QAqChB"}
+{"version":3,"file":"v3_grid_compute_solid_neighbour_mask.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_compute_solid_neighbour_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,2DAPW,UAAU,QACV,UAAU,SACV,UAAU,SACV,MAAM,SACN,MAAM,SACN,MAAM,QA4ChB"}

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

@@ -1,14 +1,13 @@
 import { assert } from "../../../../core/assert.js";
 
 /**
- * Bake a per-cell neighbourhood mask describing which of the 6 cardinal
- * neighbours of each cell are "fluid" (in-bounds AND non-solid). Consumed by
- * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
- * and solid-neighbour checks entirely.
+ * Bake the per-cell neighbourhood data consumed by the pressure solvers and
+ * the gradient subtraction: a 6-bit fluid-neighbour mask and the 7-point
+ * Laplacian diagonal.
  *
- * Encoding (one byte per cell):
+ * Mask encoding (one byte per cell):
  *
- *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
  *     bit 1 (= 2)   : +x neighbour is fluid
  *     bit 2 (= 4)   : -y neighbour is fluid
  *     bit 3 (= 8)   : +y neighbour is fluid
@@ -16,28 +15,40 @@ import { assert } from "../../../../core/assert.js";
  *     bit 5 (= 32)  : +z neighbour is fluid
  *     bit 7 (= 128) : this cell is itself solid
  *
- * The low 6 bits are the fluid-neighbour set; bit 7 flags the cell as solid.
- * A solid cell encodes as exactly `128` — bit 7 set, every neighbour bit clear
- * — and an isolated fluid cell (no fluid neighbours) as `0`. Both therefore
- * satisfy `(mask & 63) === 0`, so the SOR / PCG loops' "no fluid neighbours →
- * skip" branch is a single `(mask & 63) === 0` comparison that covers
- * "self-solid" and "fluid but no fluid neighbours" alike. The dedicated bit 7
- * additionally lets {@link v3_grid_subtract_pressure_gradient} tell solid cells
- * (zero the velocity) apart from isolated fluid (leave it) without the original
- * `solid` array.
+ * Diagonal encoding (one byte per cell): the pressure-Laplacian diagonal
+ * coefficient — the number of faces that participate in the solve:
  *
- * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
- * fully replaces whatever was in `mask` before; no need to zero-init.
+ *     diag = (# fluid neighbours) + (# open faces)
  *
- * @param {Uint8Array} mask  Destination. Length ≥ res_x*res_y*res_z.
- * @param {Uint8Array} solid  Source. Length ≥ res_x*res_y*res_z. Non-zero = solid.
+ * where an OPEN face is one whose neighbour lies outside the grid. The domain
+ * edge is an open boundary: outside pressure is the ghost value `0`
+ * (Dirichlet), so the face counts toward the diagonal while contributing
+ * nothing to the stencil sum — flow can exit the grid and the Poisson system
+ * is non-singular whenever any fluid cell touches the edge. A SOLID face is a
+ * Neumann (reflecting) boundary: dropped from both the sum and the diagonal.
+ * Sealed domains are therefore built explicitly, by lining the boundary with
+ * solid cells — there is no "closed box" mode on the open edge itself.
+ *
+ * A solid cell encodes as mask `128` / diag `0`. `diag === 0` is the solvers'
+ * single "no degrees of freedom — skip" test: it covers self-solid AND fluid
+ * sealed on all six faces alike. A fluid cell whose neighbours are all solid
+ * but which touches the domain edge still has `diag > 0` — it drains through
+ * the open face.
+ *
+ * O(N) — two byte-writes per cell, up to six byte-reads per cell. Outputs
+ * fully replace previous contents; no need to zero-init.
+ *
+ * @param {Uint8Array} mask   Destination, fluid-neighbour bits. Length ≥ N.
+ * @param {Uint8Array} diag   Destination, Laplacian diagonal (0–6). Length ≥ N.
+ * @param {Uint8Array} solid  Source. Length ≥ N. Non-zero = solid.
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
  */
-export function v3_grid_compute_solid_neighbour_mask(mask, solid, res_x, res_y, res_z) {
+export function v3_grid_compute_solid_neighbour_mask(mask, diag, solid, res_x, res_y, res_z) {
     const cells = res_x * res_y * res_z;
     assert.greaterThanOrEqual(mask.length, cells, "mask covers grid");
+    assert.greaterThanOrEqual(diag.length, cells, "diag covers grid");
     assert.greaterThanOrEqual(solid.length, cells, "solid covers grid");
 
     const slice = res_x * res_y;
@@ -49,24 +60,30 @@ export function v3_grid_compute_solid_neighbour_mask(mask, solid, res_x, res_y,
         const z_off = z * slice;
         const has_zm = z > 0;
         const has_zp = z < last_z;
+        // Open faces contributed by the y/z position are constant per row.
+        const open_z = (has_zm ? 0 : 1) + (has_zp ? 0 : 1);
         for (let y = 0; y < res_y; y++) {
             const y_off = z_off + y * res_x;
             const has_ym = y > 0;
             const has_yp = y < last_y;
+            const open_yz = open_z + (has_ym ? 0 : 1) + (has_yp ? 0 : 1);
             for (let x = 0; x < res_x; x++) {
                 const c = y_off + x;
                 if (solid[c] !== 0) {
                     mask[c] = 128; // bit 7 = this cell is solid; neighbour bits stay clear
+                    diag[c] = 0;
                     continue;
                 }
                 let m = 0;
-                if (x > 0      && solid[c - 1] === 0)     m |= 1;
-                if (x < last_x && solid[c + 1] === 0)     m |= 2;
-                if (has_ym     && solid[c - res_x] === 0) m |= 4;
-                if (has_yp     && solid[c + res_x] === 0) m |= 8;
-                if (has_zm     && solid[c - slice] === 0) m |= 16;
-                if (has_zp     && solid[c + slice] === 0) m |= 32;
+                let d = open_yz + (x > 0 ? 0 : 1) + (x < last_x ? 0 : 1);
+                if (x > 0      && solid[c - 1] === 0)     { m |= 1;  d++; }
+                if (x < last_x && solid[c + 1] === 0)     { m |= 2;  d++; }
+                if (has_ym     && solid[c - res_x] === 0) { m |= 4;  d++; }
+                if (has_yp     && solid[c + res_x] === 0) { m |= 8;  d++; }
+                if (has_zm     && solid[c - slice] === 0) { m |= 16; d++; }
+                if (has_zp     && solid[c + slice] === 0) { m |= 32; d++; }
                 mask[c] = m;
+                diag[c] = d;
             }
         }
     }

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

@@ -0,0 +1,31 @@
+/**
+ * Fill the edges exposed by {@link v3_grid_shift_in_place} (with the same
+ * `(shift_x, shift_y, shift_z)`) with a constant value.
+ *
+ * Companion to {@link v3_grid_patch_edges_uniform}: that one replicates the
+ * adjacent valid data (zero-gradient extrapolation — right for velocity,
+ * pressure, scalars), this one writes a known constant — right for masks and
+ * label grids where "newly scrolled-in region" has a definite meaning, e.g.
+ * `0` = fluid for the solid mask (scrolled-in space is empty until a
+ * voxelizer says otherwise).
+ *
+ * Axes are patched independently in x → y → z order; corner cells shared by
+ * several axis-edges are simply written more than once with the same value.
+ *
+ * No-ops:
+ *   - All shifts zero → nothing to patch.
+ *   - `|shift| >= res` on any axis → the shift primitive already zero-filled
+ *     the buffer; for a non-zero `value` the caller wanted constant-fill
+ *     anyway, so fill the whole buffer.
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer; same value passed to v3_grid_shift_in_place
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ * @param {number} value    constant written into every exposed cell
+ */
+export function v3_grid_patch_edges_constant(buffer: Float32Array | Uint8Array, res_x: number, res_y: number, res_z: number, shift_x: number, shift_y: number, shift_z: number, value: number): void;
+//# sourceMappingURL=v3_grid_patch_edges_constant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_patch_edges_constant.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_patch_edges_constant.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qDATW,YAAY,GAAC,UAAU,SACvB,MAAM,SACN,MAAM,SACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,SACN,MAAM,QAgBhB"}

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

@@ -0,0 +1,77 @@
+/**
+ * Fill the edges exposed by {@link v3_grid_shift_in_place} (with the same
+ * `(shift_x, shift_y, shift_z)`) with a constant value.
+ *
+ * Companion to {@link v3_grid_patch_edges_uniform}: that one replicates the
+ * adjacent valid data (zero-gradient extrapolation — right for velocity,
+ * pressure, scalars), this one writes a known constant — right for masks and
+ * label grids where "newly scrolled-in region" has a definite meaning, e.g.
+ * `0` = fluid for the solid mask (scrolled-in space is empty until a
+ * voxelizer says otherwise).
+ *
+ * Axes are patched independently in x → y → z order; corner cells shared by
+ * several axis-edges are simply written more than once with the same value.
+ *
+ * No-ops:
+ *   - All shifts zero → nothing to patch.
+ *   - `|shift| >= res` on any axis → the shift primitive already zero-filled
+ *     the buffer; for a non-zero `value` the caller wanted constant-fill
+ *     anyway, so fill the whole buffer.
+ *
+ * @param {Float32Array|Uint8Array} buffer
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} shift_x  integer; same value passed to v3_grid_shift_in_place
+ * @param {number} shift_y  integer
+ * @param {number} shift_z  integer
+ * @param {number} value    constant written into every exposed cell
+ */
+export function v3_grid_patch_edges_constant(buffer, res_x, res_y, res_z, shift_x, shift_y, shift_z, value) {
+    if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+        return;
+    }
+
+    if (Math.abs(shift_x) >= res_x || Math.abs(shift_y) >= res_y || Math.abs(shift_z) >= res_z) {
+        // Whole grid was exposed; every cell takes the constant.
+        buffer.fill(value, 0, res_x * res_y * res_z);
+        return;
+    }
+
+    if (shift_x !== 0) patch_x(buffer, res_x, res_y, res_z, shift_x, value);
+    if (shift_y !== 0) patch_y(buffer, res_x, res_y, res_z, shift_y, value);
+    if (shift_z !== 0) patch_z(buffer, res_x, res_y, res_z, shift_z, value);
+}
+
+function patch_x(buf, rx, ry, rz, shift, value) {
+    const slice = rx * ry;
+    const n = Math.abs(shift);
+    // Exposed: x in [rx - n, rx) for positive shift, [0, n) for negative.
+    const x_start = shift > 0 ? rx - n : 0;
+    for (let z = 0; z < rz; z++) {
+        const z_off = z * slice;
+        for (let y = 0; y < ry; y++) {
+            const row = z_off + y * rx;
+            buf.fill(value, row + x_start, row + x_start + n);
+        }
+    }
+}
+
+function patch_y(buf, rx, ry, rz, shift, value) {
+    const slice = rx * ry;
+    const n = Math.abs(shift);
+    // Exposed rows are contiguous within each slice: y in [ry - n, ry) or [0, n).
+    const y_start = shift > 0 ? ry - n : 0;
+    for (let z = 0; z < rz; z++) {
+        const start = z * slice + y_start * rx;
+        buf.fill(value, start, start + n * rx);
+    }
+}
+
+function patch_z(buf, rx, ry, rz, shift, value) {
+    const slice = rx * ry;
+    const n = Math.abs(shift);
+    // Exposed slices are one contiguous block: z in [rz - n, rz) or [0, n).
+    const z_start = shift > 0 ? rz - n : 0;
+    buf.fill(value, z_start * slice, (z_start + n) * slice);
+}

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

@@ -1,17 +1,17 @@
 /**
  * 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
@@ -20,14 +20,19 @@
  *     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
@@ -43,10 +48,12 @@
  * @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: Float32Array | Float16Array, divergence: Float32Array | Float16Array, res_x: number, res_y: number, res_z: number, iterations: number, omega: number, neighbour_mask: Uint8Array): void;
+export function v3_grid_solve_pressure(pressure: Float32Array | Float16Array, divergence: Float32Array | Float16Array, res_x: number, res_y: number, res_z: number, iterations: number, omega: number, neighbour_mask: Uint8Array, diag: Uint8Array): void;
 //# sourceMappingURL=v3_grid_solve_pressure.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QAiEpB"}
+{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,iDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QAGV,UAAU,QA8EpB"}

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"}