@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/fluid/FluidField.d.ts

@@ -1,8 +1,16 @@
 /**
- * Cell-centered 3D Eulerian grid for the fluid simulator.
+ * 3D Eulerian grid for the fluid simulator — MAC (marker-and-cell) staggered
+ * layout: pressure, solids and scalars live at cell centers; each velocity
+ * component lives on the cell FACES normal to it (Harlow & Welch 1965).
  *
- * 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.
+ * Staggering makes the discrete divergence and pressure gradient exact
+ * adjoints, so projection drives divergence to actual zero (no collocated
+ * operator-mismatch floor, no projection-invisible checkerboard modes) and
+ * solid boundaries pin the exact normal face velocity (true no-penetration).
+ *
+ * Holds three face-centered velocity components, a per-cell `solid` mask, and any
+ * number of user-defined cell-centered passive scalar attributes 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,
@@ -20,16 +28,24 @@
  */
 export class FluidField {
     /**
-     * Velocity X component, length = cell count. Cell-centered, indexed by
-     * `z * res_x * res_y + y * res_x + x`.
+     * Velocity X component on x-faces. Length `(res_x+1) * res_y * res_z`,
+     * indexed by `z * (res_x+1) * res_y + y * (res_x+1) + x` with
+     * `x ∈ [0, res_x]`. Face `(x, y, z)` sits between cells `(x−1, y, z)` and
+     * `(x, y, z)` — at grid-space position `(x − 0.5, y, z)` in the
+     * cell-center coordinate frame.
      * @type {Float32Array|null}
      */
     velocity_x: Float32Array | null;
     /**
+     * Velocity Y component on y-faces. Length `res_x * (res_y+1) * res_z`,
+     * indexed by `z * res_x * (res_y+1) + y * res_x + x` with `y ∈ [0, res_y]`.
      * @type {Float32Array|null}
      */
     velocity_y: Float32Array | null;
     /**
+     * Velocity Z component on z-faces. Length `res_x * res_y * (res_z+1)`,
+     * indexed by `z * res_x * res_y + y * res_x + x` with `z ∈ [0, res_z]`
+     * (the face slice size equals the cell slice size).
      * @type {Float32Array|null}
      */
     velocity_z: Float32Array | null;
@@ -62,14 +78,53 @@ export class FluidField {
      * consulting the {@link solid} array.
      *
      * 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.
+     * mutation. The simulator runs that recompute once per step (after effectors,
+     * which may splat solids) and at the top of every direct 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. {@link shift} also refreshes it after migrating the
+     * solid mask.
      *
      * @type {Uint8Array|null}
      */
     solid_neighbour_mask: Uint8Array | null;
+    /**
+     * Per-face "pinned" mask for x-faces: `1` where either adjacent cell is
+     * solid — the face's normal velocity is a boundary condition (0 for
+     * static solids), not a degree of freedom. Same length and indexing as
+     * {@link velocity_x}. Baked by {@link recomputeSolidNeighbourMask} via
+     * {@link v3_mac_compute_face_solid}; domain-edge faces stay 0 (open).
+     * @type {Uint8Array|null}
+     */
+    face_solid_x: Uint8Array | null;
+    /**
+     * y-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_y: Uint8Array | null;
+    /**
+     * z-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_z: Uint8Array | null;
+    /**
+     * Per-cell pressure-Laplacian diagonal, baked alongside
+     * {@link solid_neighbour_mask} by the same kernel pass:
+     *
+     *     diag = (# fluid neighbours) + (# open faces)
+     *
+     * where an open face is one on the domain edge (out-of-bounds neighbour).
+     * The domain edge is an OPEN boundary — ghost pressure 0 — so flow can
+     * vent through it; solid faces are reflecting (Neumann) and drop out of
+     * the diagonal. A solid cell, or a fluid cell sealed on all six faces,
+     * has `diag = 0`, which is the solvers' single skip test. Sealed domains
+     * are built explicitly by lining the boundary with solid cells.
+     *
+     * Same freshness contract as {@link solid_neighbour_mask}.
+     *
+     * @type {Uint8Array|null}
+     */
+    pressure_diag: Uint8Array | null;
     /**
      * 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
@@ -176,7 +231,11 @@ export class FluidField {
      */
     cellIndex(x: number, y: number, z: number): number;
     /**
-     * Set the velocity at an integer grid cell.
+     * Set the velocity of an integer grid cell: each component is written to
+     * BOTH faces of the cell along its axis, so sampling at the cell centre
+     * reads back exactly `(vx, vy, vz)`. Adjacent cells share faces — the
+     * later write wins on a shared face, exactly like overlapping
+     * cell-centered writes used to.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -186,7 +245,9 @@ export class FluidField {
      */
     setVelocityAt(x: number, y: number, z: number, vx: number, vy: number, vz: number): void;
     /**
-     * Add to the velocity at an integer grid cell (impulse).
+     * Add to the velocity of an integer grid cell (impulse). Deposits each
+     * component onto BOTH faces of the cell along its axis; the centre-sampled
+     * velocity increases by exactly `(dvx, dvy, dvz)`.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -219,8 +280,11 @@ export class FluidField {
      */
     isSolidAt(x: number, y: number, z: number): boolean;
     /**
-     * Sample velocity at a fractional grid position (positions outside the grid are
-     * clamped). Writes into `out` and returns it.
+     * Sample velocity at a fractional grid position in CELL-CENTER coordinates
+     * (positions outside the grid are clamped). Each component is trilinearly
+     * interpolated on its own staggered face lattice — x-face `i` sits at
+     * `x = i − 0.5`, so the component is sampled at `x + 0.5` in face-index
+     * space, and likewise per axis. Writes into `out` and returns it.
      * @param {Float32Array|number[]} out  Length-3 destination.
      * @param {number} x
      * @param {number} y
@@ -263,14 +327,15 @@ export class FluidField {
      */
     hash(): number;
     /**
-     * Rebuild {@link solid_neighbour_mask} from the current {@link solid} buffer.
+     * Rebuild {@link solid_neighbour_mask} and {@link pressure_diag} 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.
+     * O(N) — two byte-writes per cell, six byte-reads per cell. Called by the
+     * simulator once per step and at the top of each direct project() call, 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}.
+     * Encoding: see {@link solid_neighbour_mask} and {@link pressure_diag}.
      */
     recomputeSolidNeighbourMask(): void;
     /**
@@ -288,13 +353,20 @@ export class FluidField {
      * `(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."
+     * The solid mask is migrated like every other buffer — solids are anchored to
+     * world space exactly like the fluid they bound, so a wall must stay where the
+     * world says it is when the grid hops a cell. Newly scrolled-in cells become
+     * fluid (`0`): the field knows nothing about un-simulated space, and "empty
+     * until a voxelizer says otherwise" is the only honest default. Callers that
+     * voxelize scene geometry can keep overwriting the mask each tick — the
+     * migrated values are then simply replaced. (Earlier behaviour cleared the
+     * whole mask on shift, which made every grid hop simulate one tick with no
+     * walls anywhere — fluid leaked through geometry until the caller re-splatted.)
+     *
+     * The derived {@link solid_neighbour_mask} is refreshed here too, so the field
+     * stays self-consistent for direct kernel users; the simulator's per-step
+     * refresh makes this redundant in the ECS path but shifts are rare (once per
+     * cell crossing) and the pass is one byte-write per cell.
      *
      * @param {number} shift_x  integer
      * @param {number} shift_y  integer

package/src/engine/physics/fluid/FluidField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;OAEG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cAmBC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAOhB;IAED;;;;;;;;OAQG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;OAQG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;OASG;IACH,oCASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QAyChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}
+{"version":3,"file":"FluidField.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidField.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAQI;;;;;;;OAOG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;OAIG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;OAKG;IACH,YAFU,YAAY,GAAC,IAAI,CAET;IAElB;;;;;;OAMG;IACH,OAFU,UAAU,GAAC,IAAI,CAEZ;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,sBAFU,UAAU,GAAC,IAAI,CAEG;IAE5B;;;;;;;OAOG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;OAGG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,eAFU,UAAU,GAAC,IAAI,CAEJ;IAErB;;;;;;;;;;;;;OAaG;IACH,UAFU,YAAY,kBAAc,IAAI,CAExB;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,yBAFU,OAAO,CAEe;IAShC;;;;;;OAMG;IACH,qBAJW,MAAM,SACN,MAAM,SACN,MAAM,QAWhB;IAED;;;OAGG;IACH,iBAHY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAKnC;IAED;;;OAGG;IACH,aAHY,MAAM,CAKjB;IAED;;;;;;;;;OASG;IACH,gBAHW,MAAM,GACL,MAAM,CAejB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,oBAJW,MAAM,GACL,YAAY,GAAC,IAAI,CAM5B;IAED;;OAEG;IACH,uBAFY;QAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,CAIjD;IAED;;;OAGG;IACH,cA6BC;IAED;;;;;;OAMG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAajB;IAED;;;;;;;;;;;;OAYG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAgBhB;IAED;;;;;;;;;;OAUG;IACH,iBAPW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAgBhB;IAED;;;;;;OAMG;IACH,kCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,YACN,OAAO,QAIjB;IAED;;;;;OAKG;IACH,aALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,OAAO,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,oBANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAUhC;IAED;;;;;;;OAOG;IACH,mBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAMjB;IAED;;;;;;;;;;OAUG;IACH,cAHW,UAAU,GACT,OAAO,CAqDlB;IAED;;;;;;;;;;;OAWG;IACH,QAFY,MAAM,CAajB;IAED;;;;;;;;;;OAUG;IACH,oCAgBC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAJW,MAAM,WACN,MAAM,WACN,MAAM,QA0ChB;IAED;;;;OAIG;IACH,cASC;;CACJ"}