@woosh/meep-engine 2.138.19 → 2.139.0

package/src/engine/physics/fluid/FluidField.js

@@ -1,122 +1,566 @@
+import { assert } from "../../../core/assert.js";
+import { combine_hash } from "../../../core/collection/array/combine_hash.js";
+import { is_typed_array_equals } from "../../../core/collection/array/typed/is_typed_array_equals.js";
+import { sparse_typed_array_hash } from "../../../core/collection/array/typed/sparse_typed_array_hash.js";
+import { scs3d_sample_linear } from "../../graphics/texture/3d/scs3d_sample_linear.js";
+import { v3_grid_compute_solid_neighbour_mask } from "./solver/v3_grid_compute_solid_neighbour_mask.js";
+import { v3_grid_patch_edges_uniform } from "./solver/v3_grid_patch_edges_uniform.js";
+import { v3_grid_shift_in_place } from "./solver/v3_grid_shift_in_place.js";
 
+/**
+ * Cell-centered 3D Eulerian grid for the fluid simulator.
+ *
+ * Holds three velocity components (x, y, z), an optional per-cell `solid` mask, and any
+ * number of user-defined passive scalar attributes that get transported by the flow.
+ *
+ * Holds only state whose value carries information across step boundaries. The
+ * simulator's transient working memory (per-step velocity snapshots, divergence,
+ * diffusion / scalar ping-pong scratch) lives on the simulator. `pressure` is the
+ * one exception: it's warm-started each step from the previous solve, so its value
+ * is genuine cross-step state and belongs here.
+ *
+ * All typed array references are STABLE for the lifetime of the field. External
+ * consumers can safely cache references returned from {@link getScalarData},
+ * {@link velocity_x}, etc.
+ *
+ * @see "Real-Time Fluid Dynamics for Games" (Stam, 2003)
+ * @see GDC 2019 talk "Wind Simulation in God of War" (Rupert Renard) for the wider
+ *      effector-driven design pattern this package is moving toward.
+ */
+export class FluidField {
+
+    /**
+     * Grid dimensions in cells, `[x, y, z]`.
+     * @type {[number, number, number]}
+     */
+    #resolution = [0, 0, 0];
 
-class FluidAttribute {
-    name = "unnamed"
     /**
+     * Velocity X component, length = cell count. Cell-centered, indexed by
+     * `z * res_x * res_y + y * res_x + x`.
+     * @type {Float32Array|null}
+     */
+    velocity_x = null;
+
+    /**
+     * @type {Float32Array|null}
+     */
+    velocity_y = null;
+
+    /**
+     * @type {Float32Array|null}
+     */
+    velocity_z = null;
+
+    /**
+     * Per-cell solid flag. `0` = fluid, non-zero = solid (wall). Always allocated by
+     * {@link build} (zero-filled — every cell defaults to fluid). The solver and every
+     * effector read this unconditionally, so the array is part of the field's
+     * uniform shape, not an optional add-on.
+     * @type {Uint8Array|null}
+     */
+    solid = null;
+
+    /**
+     * Per-cell pre-baked neighbourhood mask consumed by the pressure SOR loop.
+     * One byte per cell encoding which of the 6 cardinal neighbours are 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
+     *     bit 4 (= 16) : -z neighbour is fluid
+     *     bit 5 (= 32) : +z neighbour is fluid
      *
-     * @type {Float32Array}
+     * Solid cells themselves are encoded as `mask = 0` so the SOR loop's
+     * `if (mask === 0) continue` skip handles both "this cell is solid" and
+     * "this fluid cell is isolated" with a single comparison instead of one
+     * solid-self-check plus six solid-neighbour-checks plus six boundary checks.
+     *
+     * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
+     * mutation. The simulator runs that recompute at the top of every project()
+     * call so callers never have to remember to invalidate it; the per-step cost
+     * is one O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
+     * iterations per call.
+     *
+     * @type {Uint8Array|null}
      */
-    data = null
-}
+    solid_neighbour_mask = null;
 
-/**
- * Represents a space where fluid simulation happens
- *
- * @see 2019 GDC talk by Runard Rupert "Wind Simulation in God of War" https://www.youtube.com/watch?v=dDgyBKkSf7A
- * @see Inspired by GDC talk "Interactive Wind and Vegetation in 'God of War'" - https://www.youtube.com/watch?v=MKX45_riWQA
- */
-export class FluidField {
+    /**
+     * Pressure field from the most recent projection. Owned by the field rather than
+     * the simulator because the simulator warm-starts each solve from the previous
+     * result — step N+1 depends on the value step N wrote here. If this lived on the
+     * simulator, replacing the simulator instance between steps would silently degrade
+     * convergence at the same iteration count.
+     *
+     * Storage type is {@link Float32Array} by default, or {@link Float16Array} when
+     * {@link half_precision_pressure} is enabled before build — see that field for
+     * the bandwidth-vs-quality trade-off.
+     *
+     * Safe to read for debug visualisation. Don't mutate.
+     * @type {Float32Array|Float16Array|null}
+     */
+    pressure = null;
 
-    #attributes = [];
+    /**
+     * Allocate {@link pressure} as {@link Float16Array} instead of {@link Float32Array}.
+     *
+     * **Currently slower in V8 — keep `false`.** The intent of this option is to
+     * halve the memory bandwidth on the pressure SOR sweep (the simulator's
+     * hottest, bandwidth-bound loop). On hardware with F16C the per-cell f16↔f32
+     * conversion is ~1 cycle and the bandwidth saving wins. In V8 as of Node 24
+     * the conversion path is not yet specialized — each read of `pressure[i]`
+     * goes through a slow generic Float16 unboxing routine, and the result is
+     * the opposite of what you'd expect: bench at 64³ shows **49% slower** with
+     * f16, at 128³ **28% slower** (see `bench: half_precision_pressure on/off`
+     * in bench.spec.js). The bandwidth-savings story still holds in principle;
+     * it'll likely become a real win once V8 adds inline support for
+     * Float16Array access (the typed array landed in Node 24 / TC39 Stage 4 only
+     * recently).
+     *
+     * Cost when it does win: Float16 has ~3 decimal digits of precision. The SOR
+     * iterate rounds to f16 on every write, so iteration error can't fall below
+     * ~10⁻³ relative. Bench currently shows max|div| within 8% of the f32
+     * baseline at 64³ and 128³ — acceptable for visual sim but not for
+     * quantitative pressure use.
+     *
+     * Must be set before {@link build}.
+     *
+     * The simulator's internal divergence scratch follows this type automatically
+     * (re-allocated to match `pressure.constructor` on each project call).
+     *
+     * @type {boolean}
+     */
+    half_precision_pressure = false;
 
+    /**
+     * @type {{ name: string, data: Float32Array }[]}
+     */
+    #scalar_attributes = [];
 
-    #size = [0, 0, 0]
-    #resolution = [0, 0, 0]
+    #built = false;
 
-    buffer = null;
+    /**
+     * Set the grid dimensions in cells. Must be called before {@link build}; throws if
+     * the field is already built.
+     * @param {number} res_x positive integer
+     * @param {number} res_y positive integer
+     * @param {number} res_z positive integer
+     */
+    setResolution(res_x, res_y, res_z) {
+        assert.notOk(this.#built, "resolution cannot be changed after build()");
+        assert.isPositiveInteger(res_x, "res_x");
+        assert.isPositiveInteger(res_y, "res_y");
+        assert.isPositiveInteger(res_z, "res_z");
+
+        this.#resolution[0] = res_x;
+        this.#resolution[1] = res_y;
+        this.#resolution[2] = res_z;
+    }
 
-    addAttribute(name) {
-        const attribute = new FluidAttribute();
-        attribute.name = name;
+    /**
+     * @return {[number, number, number]} A reference to the internal resolution array.
+     *                                    Do not mutate.
+     */
+    getResolution() {
+        return this.#resolution;
+    }
 
-        const index = this.#attributes.length;
+    /**
+     * @return {number} `res_x * res_y * res_z`. Zero until {@link setResolution} is
+     *                  called.
+     */
+    cellCount() {
+        return this.#resolution[0] * this.#resolution[1] * this.#resolution[2];
+    }
 
-        this.#attributes.push(attribute);
+    /**
+     * Register a passive scalar attribute (density, temperature, dye, etc.) that will be
+     * advected by the velocity field each step. Idempotent — re-adding an existing name
+     * returns the existing index.
+     *
+     * Must be called before {@link build}.
+     *
+     * @param {string} name
+     * @return {number} index of the attribute (use with {@link setScalarAtIndex})
+     */
+    addScalar(name) {
+        assert.notOk(this.#built, "addScalar cannot be called after build()");
+        assert.isString(name, "name");
+        assert.greaterThan(name.length, 0, "name must be non-empty");
+
+        const existing = this.#scalar_attributes.findIndex(a => a.name === name);
+        if (existing !== -1) {
+            return existing;
+        }
 
+        const index = this.#scalar_attributes.length;
+        this.#scalar_attributes.push({ name, data: null });
         return index;
     }
 
-    #findAttribute(name) {
-        return this.#attributes.find(a => a.name === name);
+    /**
+     * @param {string} name
+     * @return {number} index the attribute was registered with, or -1 if not present.
+     */
+    scalarIndex(name) {
+        return this.#scalar_attributes.findIndex(a => a.name === name);
     }
 
     /**
-     *
      * @param {string} name
-     * @return {Float32Array}
+     * @return {Float32Array|null} live buffer for the named scalar, or null if not
+     *                             registered.
      */
-    getAttributeData(name) {
-        return this.#findAttribute(name)?.data;
+    getScalarData(name) {
+        const a = this.#scalar_attributes.find(a => a.name === name);
+        return a === undefined ? null : a.data;
     }
 
-    getAttributeCount() {
-        return this.#attributes.length;
+    /**
+     * @return {{ name: string, data: Float32Array }[]} Live reference; do not mutate.
+     */
+    getScalarAttributes() {
+        return this.#scalar_attributes;
     }
 
     /**
-     *
-     * @param {ArrayBuffer} buffer
-     * @param {number} offset
+     * Allocate all buffers. Must be called before any read/write. After this point,
+     * resolution and attribute set are frozen.
      */
-    attachBuffer(buffer, offset = 0) {
+    build() {
+        assert.notOk(this.#built, "build() called twice");
+        assert.greaterThanOrEqual(this.#resolution[0], 1, "setResolution(...) must be called before build()");
 
-        const attribute_count = this.#attributes.length;
+        const cell_count = this.cellCount();
 
-        const cell_count = this.#resolution[0] * this.#resolution[1] * this.#resolution[2];
+        this.velocity_x = new Float32Array(cell_count);
+        this.velocity_y = new Float32Array(cell_count);
+        this.velocity_z = new Float32Array(cell_count);
+        this.solid = new Uint8Array(cell_count);
+        this.solid_neighbour_mask = new Uint8Array(cell_count);
+        const PressureCtor = this.half_precision_pressure ? Float16Array : Float32Array;
+        this.pressure = new PressureCtor(cell_count);
 
-        for (let i = 0; i < attribute_count; i++) {
-            const attribute = this.#attributes[i];
+        for (const attr of this.#scalar_attributes) {
+            attr.data = new Float32Array(cell_count);
+        }
 
-            const array = new Float32Array(buffer, offset + i * cell_count * 4, cell_count);
+        this.#built = true;
+    }
 
+    /**
+     * Linear cell index for integer grid coordinates.
+     * @param {number} x integer in [0, res_x)
+     * @param {number} y integer in [0, res_y)
+     * @param {number} z integer in [0, res_z)
+     * @return {number} flat index `z * res_x * res_y + y * res_x + x`
+     */
+    cellIndex(x, y, z) {
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+        assert.greaterThanOrEqual(x, 0, "x");
+        assert.lessThan(x, res_x, "x");
+        assert.greaterThanOrEqual(y, 0, "y");
+        assert.lessThan(y, res_y, "y");
+        assert.greaterThanOrEqual(z, 0, "z");
+        assert.lessThan(z, res_z, "z");
+        return z * res_x * res_y + y * res_x + x;
+    }
 
-            attribute.data = array;
-        }
+    /**
+     * Set the velocity at an integer grid cell.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} vx
+     * @param {number} vy
+     * @param {number} vz
+     */
+    setVelocityAt(x, y, z, vx, vy, vz) {
+        const c = this.cellIndex(x, y, z);
+        this.velocity_x[c] = vx;
+        this.velocity_y[c] = vy;
+        this.velocity_z[c] = vz;
+    }
 
-        this.buffer = buffer;
+    /**
+     * Add to the velocity at an integer grid cell (impulse).
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} dvx
+     * @param {number} dvy
+     * @param {number} dvz
+     */
+    addVelocityAt(x, y, z, dvx, dvy, dvz) {
+        const c = this.cellIndex(x, y, z);
+        this.velocity_x[c] += dvx;
+        this.velocity_y[c] += dvy;
+        this.velocity_z[c] += dvz;
     }
 
-    setAttributeAt(attribute_index, x, y, z, value) {
+    /**
+     * @param {number} attribute_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} value
+     */
+    setScalarAtIndex(attribute_index, x, y, z, value) {
+        assert.greaterThanOrEqual(attribute_index, 0, "attribute_index");
+        assert.lessThan(attribute_index, this.#scalar_attributes.length, "attribute_index");
+        const c = this.cellIndex(x, y, z);
+        this.#scalar_attributes[attribute_index].data[c] = value;
+    }
 
-        const attribute = this.#attributes[attribute_index];
+    /**
+     * Mark a cell as solid (wall) or fluid.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {boolean} is_solid
+     */
+    setSolidAt(x, y, z, is_solid) {
+        this.solid[this.cellIndex(x, y, z)] = is_solid ? 1 : 0;
+    }
 
-        const data = attribute.data;
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {boolean} true if the cell is marked solid.
+     */
+    isSolidAt(x, y, z) {
+        return this.solid[this.cellIndex(x, y, z)] !== 0;
+    }
 
-        data[z * this.#resolution[0] * this.#resolution[1] + y * this.#resolution[0] + x] = value;
+    /**
+     * Sample velocity at a fractional grid position (positions outside the grid are
+     * clamped). Writes into `out` and returns it.
+     * @param {Float32Array|number[]} out  Length-3 destination.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    sampleVelocity(out, x, y, z) {
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+        out[0] = scs3d_sample_linear(this.velocity_x, res_x, res_y, res_z, x, y, z);
+        out[1] = scs3d_sample_linear(this.velocity_y, res_x, res_y, res_z, x, y, z);
+        out[2] = scs3d_sample_linear(this.velocity_z, res_x, res_y, res_z, x, y, z);
+        return out;
+    }
 
+    /**
+     * Sample a scalar attribute at a fractional grid position.
+     * @param {string} name
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {number} trilinearly-interpolated value at `(x, y, z)`.
+     */
+    sampleScalar(name, x, y, z) {
+        const data = this.getScalarData(name);
+        assert.notNull(data, `scalar attribute '${name}'`);
+        return scs3d_sample_linear(data, this.#resolution[0], this.#resolution[1], this.#resolution[2], x, y, z);
     }
 
-    build() {
-        const attribute_count = this.#attributes.length;
+    /**
+     * Strict value equality. Two fields are equal iff they have the same resolution,
+     * the same set of scalar attributes (matched by name AND index), and the same
+     * buffer contents in `velocity_*`, `solid`, `pressure`, and each scalar. Pre-build
+     * fields compare by resolution + attribute names only (their buffers are null).
+     *
+     * O(N) — walks every cell. Use {@link hash} for change-detection on hot paths.
+     *
+     * @param {FluidField} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof FluidField)) {
+            return false;
+        }
+
+        if (this.#resolution[0] !== other.#resolution[0]
+            || this.#resolution[1] !== other.#resolution[1]
+            || this.#resolution[2] !== other.#resolution[2]) {
+            return false;
+        }
+
+        if (this.#built !== other.#built) {
+            return false;
+        }
 
-        const cell_count = this.#resolution[0] * this.#resolution[1] * this.#resolution[2];
+        const my_attrs = this.#scalar_attributes;
+        const other_attrs = other.#scalar_attributes;
+        if (my_attrs.length !== other_attrs.length) {
+            return false;
+        }
+        for (let i = 0; i < my_attrs.length; i++) {
+            if (my_attrs[i].name !== other_attrs[i].name) {
+                return false;
+            }
+        }
 
-        const data_buffer = new ArrayBuffer(cell_count * attribute_count * 4);
+        if (!this.#built) {
+            // Buffers are null on both sides; resolution + names already matched.
+            return true;
+        }
 
-        this.attachBuffer(data_buffer);
+        if (!is_typed_array_equals(this.velocity_x, other.velocity_x)
+            || !is_typed_array_equals(this.velocity_y, other.velocity_y)
+            || !is_typed_array_equals(this.velocity_z, other.velocity_z)) {
+            return false;
+        }
+        if (!is_typed_array_equals(this.solid, other.solid)) {
+            return false;
+        }
+        if (!is_typed_array_equals(this.pressure, other.pressure)) {
+            return false;
+        }
+        for (let i = 0; i < my_attrs.length; i++) {
+            if (!is_typed_array_equals(my_attrs[i].data, other_attrs[i].data)) {
+                return false;
+            }
+        }
+        return true;
     }
 
-    set size(v) {
-        const width = v[0];
-        const height = v[1];
-        const depth = v[2];
+    /**
+     * Fast hash suitable for change-detection. Combines the resolution and a *sparse*
+     * sample of the velocity_x buffer — {@link sparse_typed_array_hash} only inspects
+     * the first ~1024 cells with stride enough to take ~31 samples, regardless of how
+     * large the field is. The hash will catch most local edits to the velocity field
+     * but is not a content-perfect fingerprint; for that, fall through to
+     * {@link equals}.
+     *
+     * Constant-time relative to grid size in the common case.
+     *
+     * @return {number}
+     */
+    hash() {
+        const velocity_sample = this.#built
+            ? sparse_typed_array_hash(this.velocity_x, 0, this.velocity_x.length)
+            : 0;
+        return combine_hash(
+            this.#resolution[0],
+            this.#resolution[1],
+            this.#resolution[2],
+            this.#scalar_attributes.length,
+            velocity_sample
+        );
+    }
 
-        this.#size[0] = width;
-        this.#size[1] = height;
-        this.#size[2] = depth
+    /**
+     * Rebuild {@link solid_neighbour_mask} from the current {@link solid} buffer.
+     *
+     * O(N) — one byte-write per cell, six byte-reads per cell. Called by the
+     * simulator at the top of each project so callers never have to remember to
+     * invalidate the mask after mutating solids; the cost is amortized across the
+     * SOR sweep's many iterations.
+     *
+     * Encoding: see {@link solid_neighbour_mask}.
+     */
+    recomputeSolidNeighbourMask() {
+        if (!this.#built) {
+            return;
+        }
+        v3_grid_compute_solid_neighbour_mask(
+            this.solid_neighbour_mask,
+            this.solid,
+            this.#resolution[0], this.#resolution[1], this.#resolution[2]
+        );
     }
 
-    set resolution(v) {
-        const width = v[0];
-        const height = v[1];
-        const depth = v[2];
+    /**
+     * Translate the field's contents by `(shift_x, shift_y, shift_z)` grid cells —
+     * called when the field's world-space origin moves, so the fluid data (anchored
+     * to world space) follows. Every owned buffer (velocity_x/y/z, solid, pressure,
+     * each scalar attribute) is shifted, then the newly-exposed edges are patched
+     * via {@link v3_grid_patch_edges_uniform} (zero-gradient Neumann extrapolation —
+     * "the field is locally uniform").
+     *
+     * Direction convention matches the primitive: positive shift means the grid's
+     * world origin moved in that direction, so each cell takes the value previously
+     * at its `+shift` neighbour.
+     *
+     * `(0, 0, 0)` is a no-op; |shift| ≥ res on any axis zero-fills (no valid source
+     * left to replicate from). Pre-build fields (buffers null) are no-op'd.
+     *
+     * The solid mask is NOT migrated — it's cleared. Solids are out of scope for the
+     * shift machinery: the contract is that the caller re-voxelizes scene geometry
+     * and splats updated solid cells back into the field before the next simulation
+     * tick. Migrating the existing mask would either lie about where the walls are
+     * (if scene geometry moved) or produce double-bookkeeping problems if the caller
+     * also re-voxelizes. Clearing keeps the contract obvious: "between a shift and
+     * the next step, the field has no solids until you write them."
+     *
+     * @param {number} shift_x  integer
+     * @param {number} shift_y  integer
+     * @param {number} shift_z  integer
+     */
+    shift(shift_x, shift_y, shift_z) {
+        if (!this.#built) {
+            return;
+        }
+        if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+            return;
+        }
+
+        const rx = this.#resolution[0];
+        const ry = this.#resolution[1];
+        const rz = this.#resolution[2];
+
+        // Velocity components.
+        v3_grid_shift_in_place(this.velocity_x, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_x, rx, ry, rz, shift_x, shift_y, shift_z);
+
+        v3_grid_shift_in_place(this.velocity_y, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_y, rx, ry, rz, shift_x, shift_y, shift_z);
 
-        this.#resolution[0] = width;
-        this.#resolution[1] = height;
-        this.#resolution[2] = depth
+        v3_grid_shift_in_place(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
+
+        // Solid mask — cleared, not migrated. Caller is expected to re-voxelize and
+        // splat solids before the next simulation tick (see method docstring).
+        // The derived neighbour mask is cleared too; the simulator's next project()
+        // will repopulate it from the (potentially re-splatted) solid mask.
+        this.solid.fill(0);
+        this.solid_neighbour_mask.fill(0);
+
+        // Pressure (warm-start state, carried across steps).
+        v3_grid_shift_in_place(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
+
+        // Scalar attributes.
+        for (let i = 0; i < this.#scalar_attributes.length; i++) {
+            const data = this.#scalar_attributes[i].data;
+            v3_grid_shift_in_place(data, rx, ry, rz, shift_x, shift_y, shift_z);
+            v3_grid_patch_edges_uniform(data, rx, ry, rz, shift_x, shift_y, shift_z);
+        }
     }
 
-    get resolution() {
-        return this.#resolution;
+    /**
+     * Zero velocity, pressure, and all scalar attributes. Solid mask is preserved.
+     * Pressure is cleared to drop the warm-start (otherwise the next step's solve
+     * begins from a stale solution that no longer matches the zero velocity).
+     */
+    clear() {
+        assert.ok(this.#built, "build() must be called before clear()");
+        this.velocity_x.fill(0);
+        this.velocity_y.fill(0);
+        this.velocity_z.fill(0);
+        this.pressure.fill(0);
+        for (const attr of this.#scalar_attributes) {
+            attr.data.fill(0);
+        }
     }
 }