@woosh/meep-engine 2.157.0 → 2.158.0

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

@@ -0,0 +1,104 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Subtract the pressure gradient from a MAC velocity field in place — the
+ * face-exact counterpart of the collocated
+ * {@link v3_grid_subtract_pressure_gradient}:
+ *
+ *     u(face) −= p(right cell) − p(left cell)        (h = 1)
+ *
+ * Per face:
+ *   - both adjacent cells fluid: subtract the pressure difference.
+ *   - PINNED face (either adjacent cell solid): SKIPPED — its stored value is
+ *     the wall's normal-velocity boundary condition (0 for static solids,
+ *     the wall speed for movers; see {@link v3_mac_compute_face_solid}) and
+ *     must survive the projection. Stray deposits are prevented upstream:
+ *     the mask rebuild zeroes faces on every unpinned→pinned transition and
+ *     every transport/effector kernel skips pinned faces.
+ *   - domain-edge face (open boundary): the missing cell is the Dirichlet
+ *     ghost p = 0, so interior pressure vents flow out through the face.
+ *
+ * Together with {@link v3_mac_compute_divergence} and the unchanged 7-point
+ * solve this forms an exact discrete Helmholtz projection: solve error aside,
+ * post-projection divergence is zero — including immediately beside walls,
+ * which the collocated form could only approximate.
+ *
+ * Face grid layout: see {@link v3_mac_compute_face_solid}.
+ *
+ * @param {Float32Array} vel_u  Mutated in place, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v  Mutated in place, res_x·(res_y+1)·res_z.
+ * @param {Float32Array} vel_w  Mutated in place, res_x·res_y·(res_z+1).
+ * @param {Float32Array|Float16Array} pressure  Cell-centered, from the solve.
+ * @param {Uint8Array} face_solid_x  From {@link v3_mac_compute_face_solid}.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_mac_subtract_pressure_gradient(vel_u, vel_v, vel_w, pressure, face_solid_x, face_solid_y, face_solid_z, res_x, res_y, res_z) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(vel_u.length, (res_x + 1) * res_y * res_z, "vel_u covers grid");
+    assert.greaterThanOrEqual(vel_v.length, res_x * (res_y + 1) * res_z, "vel_v covers grid");
+    assert.greaterThanOrEqual(vel_w.length, res_x * res_y * (res_z + 1), "vel_w covers grid");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+
+    const cell_slice = res_x * res_y;
+    const sx = res_x + 1;
+
+    // x-faces.
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const f_z = z * sx * res_y;
+        for (let y = 0; y < res_y; y++) {
+            const c_y = c_z + y * res_x;
+            const f_y = f_z + y * sx;
+            for (let x = 0; x <= res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_x[f] !== 0) {
+                    // Boundary condition — preserved, not zeroed.
+                    continue;
+                }
+                const p_left = x === 0 ? 0 : pressure[c_y + x - 1];
+                const p_right = x === res_x ? 0 : pressure[c_y + x];
+                vel_u[f] -= p_right - p_left;
+            }
+        }
+    }
+
+    // y-faces.
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const f_z = z * res_x * (res_y + 1);
+        for (let y = 0; y <= res_y; y++) {
+            const f_y = f_z + y * res_x;
+            const c_below = c_z + (y - 1) * res_x;
+            const c_above = c_z + y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_y[f] !== 0) {
+                    continue;
+                }
+                const p_below = y === 0 ? 0 : pressure[c_below + x];
+                const p_above = y === res_y ? 0 : pressure[c_above + x];
+                vel_v[f] -= p_above - p_below;
+            }
+        }
+    }
+
+    // z-faces.
+    for (let z = 0; z <= res_z; z++) {
+        const f_z = z * cell_slice;
+        const c_near = (z - 1) * cell_slice;
+        const c_far = z * cell_slice;
+        for (let i = 0; i < cell_slice; i++) {
+            const f = f_z + i;
+            if (face_solid_z[f] !== 0) {
+                continue;
+            }
+            const p_near = z === 0 ? 0 : pressure[c_near + i];
+            const p_far = z === res_z ? 0 : pressure[c_far + i];
+            vel_w[f] -= p_far - p_near;
+        }
+    }
+}

package/src/engine/physics/fluid/effector/AmbientWindFluidEffector.d.ts

@@ -1,41 +0,0 @@
-/**
- * Drives every fluid cell toward a target ambient wind velocity — the standard
- * way to model prevailing wind in a scrolling wind volume.
- *
- * Unlike {@link GlobalFluidEffector} (which integrates a constant ACCELERATION
- * and therefore grows the velocity without bound — incompressible projection
- * cannot oppose a uniform force), this effector relaxes the field toward a
- * fixed VELOCITY:
- *
- *     v ← v + α · (target − v),   α = 1 − exp(−rate · dt)
- *
- * The fixed point is exactly `target`; gusts and wakes splatted on top decay
- * back toward the ambient wind at `rate` per second. The exponential form is
- * frame-rate independent — two half-steps relax exactly as much as one full
- * step.
- *
- * `velocity` is in WORLD units per second. The `world_to_grid` matrix's linear
- * part converts it into the target field's grid-cell units at apply time, so
- * the same effector instance produces the same world-space wind on fields of
- * different `cell_size`.
- *
- * Solid cells are left untouched — the projection zeroes them anyway, and
- * skipping the write keeps the solid mask authoritative for effectors too.
- */
-export class AmbientWindFluidEffector extends AbstractFluidEffector {
-    /**
-     * Target wind velocity in WORLD units per second.
-     * @type {[number, number, number]}
-     */
-    velocity: [number, number, number];
-    /**
-     * Relaxation rate toward {@link velocity}, per second. Higher = stiffer
-     * wind that re-asserts itself quickly after disturbances; lower = gusts
-     * and wakes linger. At rate `r`, a disturbance decays to ~37% in `1/r`
-     * seconds. `0` disables the effector.
-     * @type {number}
-     */
-    rate: number;
-}
-import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
-//# sourceMappingURL=AmbientWindFluidEffector.d.ts.map

package/src/engine/physics/fluid/effector/AmbientWindFluidEffector.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AmbientWindFluidEffector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/effector/AmbientWindFluidEffector.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAEI;;;OAGG;IACH,UAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEb;IAErB;;;;;;OAMG;IACH,MAFU,MAAM,CAEP;CAgFZ;sCAzHqC,4BAA4B"}

package/src/engine/physics/fluid/effector/AmbientWindFluidEffector.js

@@ -1,124 +0,0 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-import { AbstractFluidEffector } from "./AbstractFluidEffector.js";
-
-/**
- * Drives every fluid cell toward a target ambient wind velocity — the standard
- * way to model prevailing wind in a scrolling wind volume.
- *
- * Unlike {@link GlobalFluidEffector} (which integrates a constant ACCELERATION
- * and therefore grows the velocity without bound — incompressible projection
- * cannot oppose a uniform force), this effector relaxes the field toward a
- * fixed VELOCITY:
- *
- *     v ← v + α · (target − v),   α = 1 − exp(−rate · dt)
- *
- * The fixed point is exactly `target`; gusts and wakes splatted on top decay
- * back toward the ambient wind at `rate` per second. The exponential form is
- * frame-rate independent — two half-steps relax exactly as much as one full
- * step.
- *
- * `velocity` is in WORLD units per second. The `world_to_grid` matrix's linear
- * part converts it into the target field's grid-cell units at apply time, so
- * the same effector instance produces the same world-space wind on fields of
- * different `cell_size`.
- *
- * Solid cells are left untouched — the projection zeroes them anyway, and
- * skipping the write keeps the solid mask authoritative for effectors too.
- */
-export class AmbientWindFluidEffector extends AbstractFluidEffector {
-
-    /**
-     * Target wind velocity in WORLD units per second.
-     * @type {[number, number, number]}
-     */
-    velocity = [0, 0, 0];
-
-    /**
-     * Relaxation rate toward {@link velocity}, per second. Higher = stiffer
-     * wind that re-asserts itself quickly after disturbances; lower = gusts
-     * and wakes linger. At rate `r`, a disturbance decays to ~37% in `1/r`
-     * seconds. `0` disables the effector.
-     * @type {number}
-     */
-    rate = 1;
-
-    /**
-     * @param {FluidField} field
-     * @param {number} dt
-     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine; only the
-     *                                               linear (upper-left 3×3) part is
-     *                                               used since velocity is a direction.
-     */
-    apply(field, dt, world_to_grid) {
-        if (this.rate <= 0 || dt <= 0) {
-            return;
-        }
-
-        const wx = this.velocity[0];
-        const wy = this.velocity[1];
-        const wz = this.velocity[2];
-
-        // Direction-transform the world-space target into grid units.
-        const m = world_to_grid;
-        const tx = m[0] * wx + m[4] * wy + m[8]  * wz;
-        const ty = m[1] * wx + m[5] * wy + m[9]  * wz;
-        const tz = m[2] * wx + m[6] * wy + m[10] * wz;
-
-        // Exact exponential relaxation factor for this dt.
-        const alpha = 1 - Math.exp(-this.rate * dt);
-
-        const vx = field.velocity_x;
-        const vy = field.velocity_y;
-        const vz = field.velocity_z;
-        const solid = field.solid;
-        const n = field.cellCount();
-
-        for (let i = 0; i < n; i++) {
-            if (solid[i] !== 0) {
-                continue;
-            }
-            vx[i] += alpha * (tx - vx[i]);
-            vy[i] += alpha * (ty - vy[i]);
-            vz[i] += alpha * (tz - vz[i]);
-        }
-    }
-
-    /**
-     * @param {AbstractFluidEffector} other
-     * @return {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-        if (!(other instanceof AmbientWindFluidEffector)) {
-            return false;
-        }
-        return this.rate === other.rate
-            && this.velocity[0] === other.velocity[0]
-            && this.velocity[1] === other.velocity[1]
-            && this.velocity[2] === other.velocity[2];
-    }
-
-    /**
-     * @return {number}
-     */
-    hash() {
-        return combine_hash(
-            computeHashFloat(this.velocity[0]),
-            computeHashFloat(this.velocity[1]),
-            computeHashFloat(this.velocity[2]),
-            computeHashFloat(this.rate)
-        );
-    }
-
-    /**
-     * Position-free — applies to every cell of any field. Infinite bounds means
-     * the broad-phase will never cull this effector.
-     * @param {AABB3} out
-     */
-    getBoundingBox(out) {
-        out.setInfiniteBounds();
-    }
-}