@woosh/meep-engine 3.21.0 → 3.22.0

package/src/engine/physics/cloth/solver/constraint/cloth_leash_row.js

@@ -0,0 +1,346 @@
+import {
+    CVA_F_X,
+    CVA_F_Y,
+    CVA_F_Z,
+    CVA_H_XX,
+    CVA_H_XY,
+    CVA_H_XZ,
+    CVA_H_YY,
+    CVA_H_YZ,
+    CVA_H_ZZ,
+    CVA_TRUST
+} from "../cloth_vertex_accumulator.js";
+import { CLOTH_STRETCH_EPSILON } from "./cloth_stretch_row.js";
+
+/**
+ * # Leash — the distance-to-a-point row
+ *
+ *     C(x) = ‖x_i − s‖ − r
+ *     ∂C/∂x_i = (x_i − s)/‖x_i − s‖ = n
+ *
+ * **This is both of §6's leash rows.** The slack row and the tether row have
+ * the same `C`, the same clamp and the same stiffness; they differ only in
+ * where `s` and `r` come from:
+ *
+ * | | `s` | `r` |
+ * |---|---|---|
+ * | slack | the particle's **animated position** | `slack · d_geo,i` |
+ * | tether (LRA) | the **anchor's** position | `d_geo,i` |
+ *
+ * So they are one module, parameterised by mode, exactly as
+ * `physics/constraint/solve_constraints.js` does for its 6-DOF joints at the
+ * velocity level, and exactly as `cloth_stretch_row.js` covers both the fabric
+ * row and its strain limit. A cape wants both, because they ask different
+ * questions: slack asks how loosely the cloth is leashed to the animation, the
+ * tether asks how far the fabric may extend from where it hangs (§6).
+ *
+ * §3.4's pin falls out too, with no third row and no branch: a particle whose
+ * `d_geo` is zero has a slack radius of zero, and `‖x_i − s‖ ≤ 0` under this
+ * clamp *is* a weld.
+ *
+ * ## The row is hard, and one-sided, structurally
+ *
+ * Neither a stiffness nor a pair of clamps is stored, because neither varies.
+ * A leash is `hard` in §6's table — its penalty lives in the measured band and
+ * its multiplier carries the load — and it is a *bound* rather than a spring,
+ * so it may only pull inwards. That is why this is the row that survives a low
+ * iteration budget: it is enforced almost exactly in one iteration, which is
+ * what §7 P2 means by long-range attachments making low iteration counts
+ * viable.
+ *
+ * ## Which way the clamp goes, and why §6's table has it backwards
+ *
+ * The solver applies `f -= fc·g`, so a **positive** `fc` on a distance row
+ * pulls the two ends together — that is what `cloth_stretch_row.js` means when
+ * it adds geometric stiffness for a row "in tension" at `fc > 0`. A row that
+ * bounds a distance from *above* must therefore be allowed positive force and
+ * no negative force: `f_min = 0, f_max = +∞`.
+ *
+ * §6's table gives slack, tether and strain limit `(−∞, 0]` instead, which
+ * under this convention is the force that pushes them apart — it would drive
+ * the particle *away* from its leash centre and the row would never bind.
+ * `cloth_leash_row.spec.js` demonstrates the correct sign directly; the
+ * table's own collision and self-collision rows are consistent with it once
+ * you notice that a collision row writes `C` with the opposite sense. The
+ * precise rule, which the table's "push-only / pull-only" gloss elides, is:
+ * `[0, +∞)` admits only forces that **reduce** `C`, and `(−∞, 0]` only forces
+ * that **increase** it.
+ *
+ * ## Coincident with the target
+ *
+ * `‖x − s‖` is not differentiable at zero. Below {@link CLOTH_STRETCH_EPSILON}
+ * the row is skipped, which is the standard guard and is also exactly when it
+ * has nothing to do — a particle sitting on its own leash centre is where the
+ * row was trying to put it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Evaluate one leash row's constraint value and its gradient.
+ *
+ * This is the definition the accumulation loop below inlines, and the one the
+ * finite-difference spec checks — there is no second copy of the arithmetic.
+ *
+ * @param {Float64Array|number[]} gradient out, `∂C/∂x`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @returns {number} `C`
+ */
+export function cloth_leash_evaluate(gradient, gradient_offset, state, row) {
+    const self = state.leash_particle[row] * 3;
+    const target = row * 3;
+
+    const position = state.position;
+    const leash_target = state.leash_target;
+
+    const dx = position[self] - leash_target[target];
+    const dy = position[self + 1] - leash_target[target + 1];
+    const dz = position[self + 2] - leash_target[target + 2];
+
+    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (length < CLOTH_STRETCH_EPSILON) {
+        gradient[gradient_offset] = 0;
+        gradient[gradient_offset + 1] = 0;
+        gradient[gradient_offset + 2] = 0;
+
+        return length - state.leash_radius[row];
+    }
+
+    const inverse = 1 / length;
+
+    gradient[gradient_offset] = dx * inverse;
+    gradient[gradient_offset + 1] = dy * inverse;
+    gradient[gradient_offset + 2] = dz * inverse;
+
+    return length - state.leash_radius[row];
+}
+
+/**
+ * Add every leash row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_leash_accumulate(accumulator, state, particle) {
+    const offset = state.leash_adjacency_offset;
+
+    const start = offset[particle];
+    const end = offset[particle + 1];
+
+    if (start === end) {
+        return;
+    }
+
+    const adjacency = state.leash_adjacency;
+    const radius = state.leash_radius;
+    const lambda = state.leash_lambda;
+    const penalty = state.leash_penalty;
+    const leash_target = state.leash_target;
+    const position = state.position;
+
+    const self = particle * 3;
+
+    const x = position[self];
+    const y = position[self + 1];
+    const z = position[self + 2];
+
+    let f_x = accumulator[CVA_F_X];
+    let f_y = accumulator[CVA_F_Y];
+    let f_z = accumulator[CVA_F_Z];
+
+    let h_xx = accumulator[CVA_H_XX];
+    let h_yy = accumulator[CVA_H_YY];
+    let h_zz = accumulator[CVA_H_ZZ];
+    let h_xy = accumulator[CVA_H_XY];
+    let h_xz = accumulator[CVA_H_XZ];
+    let h_yz = accumulator[CVA_H_YZ];
+
+    let trust = accumulator[CVA_TRUST];
+
+    for (let i = start; i < end; i++) {
+        const row = adjacency[i];
+
+        const target = row * 3;
+
+        const dx = x - leash_target[target];
+        const dy = y - leash_target[target + 1];
+        const dz = z - leash_target[target + 2];
+
+        const length_squared = dx * dx + dy * dy + dz * dz;
+
+        if (length_squared < CLOTH_STRETCH_EPSILON * CLOTH_STRETCH_EPSILON) {
+            continue;
+        }
+
+        const k = penalty[row];
+
+        const length = Math.sqrt(length_squared);
+
+        const unclamped = k * (length - radius[row]) + lambda[row];
+
+        if (unclamped <= 0) {
+            // Inside the leash and carrying no accumulated force: the row is
+            // clamped out, contributes neither force nor curvature, and — this
+            // is the part that matters — must not narrow the trust region
+            // either. A particle resting near its own leash centre would
+            // otherwise cap every step at its distance from that centre and
+            // freeze for reasons that have nothing to do with the rows doing
+            // the work.
+            continue;
+        }
+
+        const inverse = 1 / length;
+
+        if (length < trust) {
+            trust = length;
+        }
+
+        const g_x = dx * inverse;
+        const g_y = dy * inverse;
+        const g_z = dz * inverse;
+
+        f_x -= unclamped * g_x;
+        f_y -= unclamped * g_y;
+        f_z -= unclamped * g_z;
+
+        // Geometric stiffness, positive part only. The row is in tension
+        // whenever it is active at all — that is what the clamp above means —
+        // so the `(fc/L)·(I − ggᵀ)` term is positive semidefinite here without
+        // a second test. `MEASUREMENTS.md` §5.1 for what dropping it costs.
+        const s = unclamped * inverse;
+
+        h_xx += s * (1 - g_x * g_x) + k * g_x * g_x;
+        h_yy += s * (1 - g_y * g_y) + k * g_y * g_y;
+        h_zz += s * (1 - g_z * g_z) + k * g_z * g_z;
+        h_xy += (k - s) * g_x * g_y;
+        h_xz += (k - s) * g_x * g_z;
+        h_yz += (k - s) * g_y * g_z;
+    }
+
+    accumulator[CVA_F_X] = f_x;
+    accumulator[CVA_F_Y] = f_y;
+    accumulator[CVA_F_Z] = f_z;
+
+    accumulator[CVA_H_XX] = h_xx;
+    accumulator[CVA_H_YY] = h_yy;
+    accumulator[CVA_H_ZZ] = h_zz;
+    accumulator[CVA_H_XY] = h_xy;
+    accumulator[CVA_H_XZ] = h_xz;
+    accumulator[CVA_H_YZ] = h_yz;
+
+    accumulator[CVA_TRUST] = trust;
+}
+
+/**
+ * Warm start every leash row for a substep: regularise the carried multiplier
+ * and put the penalty in the band. §5.2.
+ *
+ * Every leash row is hard, so — unlike the stretch table — there is no soft
+ * branch here. The row's inertial scale is the particle's own `m/h²`, because
+ * a leash has one end that can move.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha multiplier regularisation, `[0, 1]`
+ * @param {number} gamma dual decay, `[0, 1)`
+ * @param {number} k_min_ratio penalty floor, as a multiple of `m/h²`
+ * @param {number} k_max_ratio penalty ceiling, as a multiple of `m/h²`
+ * @param {number} inverse_h_squared
+ */
+export function cloth_leash_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+    const count = state.leash_count;
+
+    const row_particle = state.leash_particle;
+    const mass_inverse = state.mass_inverse;
+    const lambda = state.leash_lambda;
+    const penalty = state.leash_penalty;
+
+    const decay = alpha * gamma;
+
+    for (let row = 0; row < count; row++) {
+        const compliance = mass_inverse[row_particle[row]];
+
+        if (compliance === 0) {
+            // A pinned particle cannot move, so the row has nothing to enforce
+            // and the band it would be clamped into is unbounded. Zeroed rather
+            // than left holding `Infinity` in live state.
+            penalty[row] = 0;
+            lambda[row] = 0;
+
+            continue;
+        }
+
+        const scale = inverse_h_squared / compliance;
+
+        const lo = k_min_ratio * scale;
+        const hi = k_max_ratio * scale;
+
+        lambda[row] *= decay;
+
+        let k = penalty[row] * gamma;
+
+        if (k < lo) {
+            k = lo;
+        } else if (k > hi) {
+            k = hi;
+        }
+
+        penalty[row] = k;
+    }
+}
+
+/**
+ * Dual update for every leash row: absorb this iteration's violation into the
+ * multiplier and ramp the penalty. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} beta penalty ramp
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_leash_dual_update(state, beta, k_max_ratio, inverse_h_squared) {
+    const count = state.leash_count;
+
+    const row_particle = state.leash_particle;
+    const mass_inverse = state.mass_inverse;
+    const position = state.position;
+    const leash_target = state.leash_target;
+    const radius = state.leash_radius;
+    const lambda = state.leash_lambda;
+    const penalty = state.leash_penalty;
+
+    for (let row = 0; row < count; row++) {
+        const particle = row_particle[row];
+
+        const compliance = mass_inverse[particle];
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const k_max = k_max_ratio * inverse_h_squared / compliance;
+
+        const self = particle * 3;
+        const target = row * 3;
+
+        const dx = position[self] - leash_target[target];
+        const dy = position[self + 1] - leash_target[target + 1];
+        const dz = position[self + 2] - leash_target[target + 2];
+
+        const c = Math.sqrt(dx * dx + dy * dy + dz * dz) - radius[row];
+
+        const k = penalty[row];
+
+        const next = k * c + lambda[row];
+
+        lambda[row] = next > 0 ? next : 0;
+
+        const ramped = k + beta * Math.abs(c);
+
+        penalty[row] = ramped < k_max ? ramped : k_max;
+    }
+}

package/src/engine/physics/cloth/solver/constraint/cloth_stretch_row.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Evaluate one stretch row's constraint value and its gradient with respect to
+ * one of its two particles.
+ *
+ * This is the definition the accumulation loop below inlines, and the one the
+ * finite-difference spec checks — there is no second copy of the arithmetic.
+ *
+ * @param {Float64Array|number[]} gradient out, `∂C/∂x_slot`
+ * @param {number} gradient_offset
+ * @param {ClothState} state
+ * @param {number} row
+ * @param {number} slot 0 or 1
+ * @returns {number} `C`
+ */
+export function cloth_stretch_evaluate(gradient: Float64Array | number[], gradient_offset: number, state: ClothState, row: number, slot: number): number;
+/**
+ * Add every stretch row touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_stretch_accumulate(accumulator: Float64Array, state: ClothState, particle: number): void;
+/**
+ * Warm start every stretch row for a substep: regularise the carried
+ * multiplier and decay the penalty back towards its floor. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha multiplier regularisation, `[0, 1]`
+ * @param {number} gamma dual decay, `[0, 1)`
+ * @param {number} k_min
+ * @param {number} k_max
+ */
+export function cloth_stretch_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: any, k_max_ratio: any, inverse_h_squared: any): void;
+/**
+ * Dual update for every stretch row: absorb this iteration's violation into
+ * the multiplier and ramp the penalty towards the row's material stiffness.
+ * §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} beta penalty ramp
+ * @param {number} k_max
+ */
+export function cloth_stretch_dual_update(state: ClothState, beta: number, k_max_ratio: any, inverse_h_squared: any): void;
+/**
+ * # Stretch — the distance row
+ *
+ *     C(x) = ‖x_i − x_j‖ − L₀
+ *     ∂C/∂x_i = (x_i − x_j)/‖x_i − x_j‖ = n,   ∂C/∂x_j = −n
+ *
+ * The fabric row of §6, and — with a different rest length and a one-sided
+ * force clamp — its strain limit as well. `f_min = −∞, f_max = +∞` is the
+ * bilateral spring that resists stretching *and* compression; `f_max = 0` with
+ * `L₀ = L_max` makes it pull-only, so it does nothing until the edge is longer
+ * than the cap and then holds it hard. One row model, parameterised by mode,
+ * exactly as `physics/constraint/solve_constraints.js` does for its 6-DOF
+ * joints at the velocity level.
+ *
+ * ## The gradient is the same expression at both ends
+ *
+ * `∂C/∂x_i` is the unit vector from the *other* particle to *this* one, for
+ * whichever end this is: at slot 0 that is `(x_i − x_j)/L`, at slot 1 it is
+ * `(x_j − x_i)/L`. So the slot picks which particle is "the other one" and the
+ * arithmetic that follows is identical — no sign flip, no branch.
+ *
+ * ## The clamp gates the Hessian, not just the force
+ *
+ * `fu = k·C + λ` is the row's unclamped force; `fc = clamp(fu, f_min, f_max)`
+ * is what it actually applies. When the clamp binds, the applied force is
+ * *constant* with respect to position, so its second derivative is zero and
+ * the row contributes nothing to `H` — adding `k·ggᵀ` anyway would make an
+ * inactive unilateral row resist motion it has no business touching. §5.2.
+ *
+ * ## Coincident particles
+ *
+ * `‖x_i − x_j‖` is not differentiable at zero. Below
+ * {@link CLOTH_STRETCH_EPSILON} the row writes a zero gradient, which makes
+ * both its force and its Hessian contribution vanish without a special case
+ * downstream. Two particles exactly on top of each other is a measure-zero
+ * configuration that any perturbation leaves; a build that produces one is
+ * rejected by the welding pass (§7 P8) long before the solver sees it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Separation below which the distance gradient is treated as zero, metres.
+ * A nanometre is six orders of magnitude below the thinnest fabric this
+ * simulates and comfortably above where `Float32` positions stop resolving a
+ * difference at all.
+ * @type {number}
+ */
+export const CLOTH_STRETCH_EPSILON: number;
+//# sourceMappingURL=cloth_stretch_row.d.ts.map

package/src/engine/physics/cloth/solver/constraint/cloth_stretch_row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_stretch_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_stretch_row.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;GAaG;AACH,iDAPW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,QACN,MAAM,GACJ,MAAM,CA8BlB;AAED;;;;;;GAMG;AACH,sDAJW,YAAY,+BAEZ,MAAM,QAoIhB;AAED;;;;;;;;;GASG;AACH,mEALW,MAAM,SACN,MAAM,oEA8DhB;AAED;;;;;;;;GAQG;AACH,mEAHW,MAAM,kDA2DhB;AAjXD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;GAMG;AACH,oCAFU,MAAM,CAE0B"}