@woosh/meep-engine 2.157.0 → 2.158.0

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

@@ -19,7 +19,12 @@ export namespace PressureSolver {
     let MICPCG: string;
 }
 /**
- * Velocity / scalar transport scheme selection.
+ * 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
@@ -27,10 +32,8 @@ export namespace PressureSolver {
  *
  *   - `"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 at
- *     ~2× the advection cost — and advection is the minority of step() cost
- *     next to pressure, so the end-to-end price is small. Allocates 3
- *     additional N-sized scratch buffers, shared with the reflection scheme.
+ *     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 {
@@ -38,7 +41,10 @@ export namespace AdvectionScheme {
     let MACCORMACK: string;
 }
 /**
- * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
+ * 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
@@ -56,8 +62,8 @@ export namespace AdvectionScheme {
  *      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
- *      with the same 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
@@ -127,13 +133,19 @@ export class FluidSimulator {
      *
      * 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 constant
-     * {@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, which is what wind-field
-     * use cases want (drive with {@link AmbientWindFluidEffector} for a
-     * specific ambient target instead of a force).
+     * 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.
@@ -175,21 +187,19 @@ export class FluidSimulator {
      */
     vorticity_confinement: number;
     /**
-     * Which transport scheme advects velocity and scalars — see
-     * {@link AdvectionScheme}.
-     *
-     * **Default semi-Lagrangian — MacCormack is gated on a MAC-staggered
-     * grid.** On the current collocated discretization the projection has an
-     * operator-mismatch floor (high-frequency divergence it cannot see, let
-     * alone remove — quality.spec.js scenario 7), and MacCormack's
-     * anti-diffusive corrector amplifies exactly that residue instead of
-     * letting first-order smearing absorb it. Measured on the sealed-vortex
-     * scenario: kinetic energy transiently grows to **1.9×** within 10 s
-     * (vs SL's monotone decay), and a passive scalar's total mass inflates
-     * **1.8×** in one second of orbiting. The kernels are correct in
-     * isolation (their specs transport clean fields sharply and monotonely) —
-     * it is the interaction with the collocated pressure floor that is
-     * unstable. Flip this on once the grid is staggered.
+     * 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}
      */
@@ -207,22 +217,27 @@ export class FluidSimulator {
      *
      * Same two pressure solves as the default double-projection Stam step,
      * and two half-dt advections instead of one full-dt one — measured cost
-     * +20% of step() at 32×8×32. The reflection replaces the
+     * ~+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.
      *
-     * Default ON: with semi-Lagrangian advection this is measured stable
-     * (sealed-vortex kinetic energy never exceeds 0.99× its initial over
-     * 10 s) while retaining visibly more swirl — peak vorticity 0.73 vs 0.62
-     * after one second (quality.spec.js scenario 2b). With MacCormack it
-     * compounds the collocated-floor amplification (3.4× energy growth) —
-     * see {@link advection_scheme}; that combination should wait for MAC
-     * staggering.
+     * 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;

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":";;;;;;;;;;;;;;;6BA4BU,MAAM;;;;;;;;;;;;;;;;;;;8BAqBN,MAAM;;;;;AAOhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;;;;;;;;;OAeG;IACH,iBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;;;;OAcG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAFU,MAAM,CAEmC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,sBAFU,OAAO,CAEW;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,0BAFU,OAAO,CAEe;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,0BAFU,MAAM,CAEgB;IA4IhC;;;;;;;;;;;;OAYG;IACH,iCALW,MAAM,SACN,MAAM,SACN,MAAM,GACL,MAAM,CAUjB;IAED;;;;;;;;;;;;OAYG;IACH,iCAGC;IAuED;;;;;;;;;;;;;OAaG;IACH,oCAVW,MAAM,aAEN,uBAAuB,iBACvB,YAAY,GAAC,MAAM,EAAE,QA4K/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"}