@woosh/meep-engine 2.156.0 → 2.158.0

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

@@ -19,7 +19,32 @@ export namespace PressureSolver {
     let MICPCG: string;
 }
 /**
- * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
+ * VELOCITY transport scheme selection. Passive scalars always use
+ * semi-Lagrangian transport regardless of this setting — gather-form
+ * MacCormack is non-conservative (the corrector re-adds roughly double the
+ * gather bias; measured 1.7x total dye mass in one second of a sealed
+ * vortex, independent of wall handling), and scalar conservation is a hard
+ * requirement, not a preference.
+ *
+ *   - `"semi-lagrangian"` — first-order back-trace + trilinear gather (Stam
+ *     1999). Cheapest; strongly dissipative — a vortex loses half its kinetic
+ *     energy per second at production settings (see quality.spec.js).
+ *
+ *   - `"maccormack"` — unconditionally stable MacCormack (Selle et al. 2008):
+ *     a forward and a backward semi-Lagrangian pass with error correction and
+ *     a monotone min-max limiter. Second-order accurate in space and time.
+ *     Allocates 3 additional face-lattice scratch buffers.
+ */
+export type AdvectionScheme = string;
+export namespace AdvectionScheme {
+    let SEMI_LAGRANGIAN: string;
+    let MACCORMACK: string;
+}
+/**
+ * 3D incompressible-flow solver on a MAC (staggered) grid — Stam's stable-
+ * fluids step structure (1999/2003) with face-centered velocity (Harlow &
+ * Welch 1965), an exact discrete Helmholtz projection, and optional
+ * advection-reflection / MacCormack transport.
  *
  * Holds tuning knobs plus transient working memory (per-step velocity snapshots,
  * divergence, ping-pong scratch). None of that working memory carries information
@@ -29,12 +54,16 @@ export namespace PressureSolver {
  * the field). Scratch is cached by cell-count so per-step allocation stays at zero.
  *
  * Per step:
- *   1. Apply external forces (effectors mutate field velocity).
+ *   1. Apply external forces (effectors mutate field velocity), then the
+ *      optional exponential velocity damping.
  *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
- *   3. Project (pressure solve + gradient subtract) to enforce ∇·v ≈ 0.
- *   4. Self-advect velocity (semi-Lagrangian back-trace).
- *   5. Project again (advection introduces small divergence).
- *   6. For each scalar attribute on the field: optionally diffuse, then advect.
+ *   3-5. Transport block — either the Stam reference sequence
+ *      project₁ → advect → project₂, or (default) the advection-reflection
+ *      form of the same two projections (see {@link advection_reflection}).
+ *      Advection itself is semi-Lagrangian or MacCormack per
+ *      {@link advection_scheme}.
+ *   6. For each scalar attribute on the field: optionally diffuse, then
+ *      advect (always semi-Lagrangian — see {@link AdvectionScheme}).
  *
  * Pressure is warm-started from the previous step's solution (`field.pressure`),
  * which converges much faster than starting from zero once the flow reaches a
@@ -56,6 +85,24 @@ export namespace PressureSolver {
  * @type {number}
  */
 export const PRESSURE_ITERATIONS_FLOOR: number;
+/**
+ * Relative convergence tolerance handed to the MIC-PCG pressure solve: the
+ * solver stops as soon as `max|r| <= tolerance * max|−div|`. The iteration
+ * cap from {@link FluidSimulator#resolvePressureIterations} is sized for the
+ * cold-start worst case; warm-started production frames converge much
+ * earlier, and without a tolerance exit every warm frame would pay the full
+ * cold-start budget for no quality gain.
+ *
+ * 1e-3 sits below visual-fluids noticeability and below the collocated
+ * operator-mismatch floor that dominates post-projection divergence (see
+ * quality.spec.js) — iterating past it buys nothing visible.
+ *
+ * SOR has no equivalent exit: it never computes its residual (doing so would
+ * add a pass per sweep), so its cost is governed by the iteration count alone.
+ *
+ * @type {number}
+ */
+export const PCG_RELATIVE_TOLERANCE: number;
 export class FluidSimulator {
     /**
      * Implicit-diffusion coefficient (= viscosity * dt-like scaling). 0 disables.
@@ -79,6 +126,33 @@ export class FluidSimulator {
      * @type {number}
      */
     scalar_diffusion_iterations: number;
+    /**
+     * Exponential velocity damping rate, per second. Each step multiplies the
+     * whole velocity field by `exp(-velocity_damping * dt)` right after
+     * effectors run. `0` (default) disables — no pass is made.
+     *
+     * Why it exists: the solver has no other dissipation mechanism that bounds
+     * energy under sustained forcing. Incompressible projection cannot oppose
+     * a uniform body force (a uniform field is divergence-free), so a bare
+     * `force` on a {@link GlobalFluidEffector} accelerates the fluid without
+     * limit — there is no terminal state. A small damping rate gives constant
+     * forcing a terminal velocity of approximately
+     * `acceleration / velocity_damping` and makes transient gusts decay back
+     * to calm.
+     *
+     * Relationship to {@link GlobalFluidEffector#drag}: the effector's drag
+     * is the same operation expressed as SCENE CONTENT — it relaxes toward a
+     * configurable ambient wind and travels with the effector entity. This
+     * knob is the SOLVER-level stability primitive: it exists even when no
+     * effectors are wired, and always relaxes toward zero. Use the effector
+     * for atmosphere design; use this to guarantee boundedness.
+     *
+     * The exponential form is frame-rate independent: two half-steps damp
+     * exactly as much as one full step.
+     *
+     * @type {number}
+     */
+    velocity_damping: number;
     /**
      * Which pressure solver to use. `PressureSolver.SOR` (default) is the
      * baseline red-black Successive Over-Relaxation. `PressureSolver.MICPCG`
@@ -96,6 +170,77 @@ export class FluidSimulator {
      * @type {string}
      */
     pressure_solver: string;
+    /**
+     * Vorticity-confinement strength ε, per second (Fedkiw et al. 2001). Each
+     * step deposits `ε·dt·(N × ω)` as a velocity increment, sharpening vortex
+     * cores that coarse grids and dissipative transport smear away. `0`
+     * (default) disables — no pass is made.
+     *
+     * Confinement ADDS energy by design; pair non-zero values with
+     * {@link velocity_damping} so gusts still decay. Visual-smoke territory
+     * starts around `ε ≈ 5–30` at 60 Hz (epsilon_dt 0.1–0.5).
+     *
+     * Cost when enabled: two extra O(N) passes (curl + force) using existing
+     * scratch — no allocations.
+     *
+     * @type {number}
+     */
+    vorticity_confinement: number;
+    /**
+     * Which transport scheme advects VELOCITY — see {@link AdvectionScheme}
+     * (scalars are always semi-Lagrangian; see the enum docstring for why).
+     *
+     * **Default MacCormack.** On the MAC grid with solid-clipped traces it is
+     * measured long-horizon stable (sealed-vortex energy peaks at 0.96x its
+     * initial over 10 s, monotone decay thereafter) and retains dramatically
+     * more energy than first-order transport: 0.80 vs 0.53 KE after one
+     * second (quality.spec.js scenario 2b).
+     *
+     * Do NOT combine with {@link advection_reflection}: the energy-preserving
+     * reflection re-injects the corrector overshoots and the pair pumps
+     * energy without bound (10 s peak 3.7x — measured both with and without
+     * trace clipping). Reflection is the companion for SEMI_LAGRANGIAN.
+     *
+     * @type {string}
+     */
+    advection_scheme: string;
+    /**
+     * Replace the plain "project → advect → project" sequence with the
+     * advection-reflection scheme (Zehnder, Narain, Thomaszewski 2018):
+     *
+     *     ũ  = advect(u, u, dt/2)        — half-step self-advection
+     *     u½ = project(ũ)
+     *     û  = 2·u½ − ũ                  — energy-preserving reflection
+     *     u′ = advect(û, u½, dt/2)       — transport the REFLECTED field
+     *                                       along the PROJECTED one
+     *     u₁ = project(u′)
+     *
+     * Same two pressure solves as the default double-projection Stam step,
+     * and two half-dt advections instead of one full-dt one — measured cost
+     * ~+70% of step() at 32×8×32 on the MAC lattices (each half-step pays the
+     * cross-component carrier sampling). The reflection replaces the
+     * energy-DISSIPATING first projection with an energy-PRESERVING
+     * reflection about the divergence-free subspace.
+     *
+     * With semi-Lagrangian advection this is measured stable (sealed-vortex
+     * kinetic energy never exceeds its initial over 10 s) while retaining
+     * visibly more swirl — peak vorticity 0.74 vs 0.68 after one second
+     * (quality.spec.js scenario 2b). Do NOT combine with MacCormack — the
+     * reflection re-injects the corrector overshoots (10 s energy peak
+     * 3.7x); see {@link advection_scheme}.
+     *
+     * Only consulted when {@link project_before_advection} is true — the
+     * scheme is defined around the mid-step projection. With
+     * `project_before_advection = false` this flag is ignored.
+     *
+     * Default OFF: the default velocity scheme is MacCormack, with which the
+     * reflection is unstable (see {@link advection_scheme}). Enable it when
+     * running SEMI_LAGRANGIAN velocity transport — that pairing is measured
+     * stable and retains visibly more swirl than plain SL.
+     *
+     * @type {boolean}
+     */
+    advection_reflection: boolean;
     /**
      * Run the pressure projection *before* self-advection in addition to after.
      *
@@ -175,6 +320,12 @@ export class FluidSimulator {
      * because tests and external code may need to project on demand (e.g., after
      * splatting an out-of-band impulse). `field.pressure` is read as the warm-start
      * initial guess and written with the new solution.
+     *
+     * Refreshes the field's solid-neighbour mask itself, so direct callers never
+     * have to remember invalidation after mutating solids. {@link step} refreshes
+     * the mask once for the whole step and uses the private no-recompute variant
+     * for both of its projections.
+     *
      * @param {FluidField} field
      */
     project(field: FluidField): void;

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

@@ -1 +1 @@
-{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BAyBU,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA+EhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;OAMG;IACH,iCAkDC;IAqBD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QAyF/B;;CACJ"}
+{"version":3,"file":"FluidSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/fluid/FluidSimulator.js"],"names":[],"mappings":";;;;;;;;;;;;;;;6BA2BU,MAAM;;;;;;;;;;;;;;;;;;;;;;8BAwBN,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,MAAM,CAE2B;AAE3C;IAEI;;;OAGG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,+BAFU,MAAM,CAEkB;IAElC;;;;;OAKG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;OAcG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;;;;;;;OAgBG;IACH,kBAFU,MAAM,CAE8B;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,sBAFU,OAAO,CAEY;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IAuKhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;;;;;;;OAYG;IACH,iCAGC;IAwFD;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QA4L/B;;CACJ"}