@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,383 @@
+import { v3_cotangent } from "../../../../../core/geom/vec3/v3_cotangent.js";
+import {
+    CVA_F_X,
+    CVA_F_Y,
+    CVA_F_Z,
+    CVA_H_XX,
+    CVA_H_YY,
+    CVA_H_ZZ
+} from "../cloth_vertex_accumulator.js";
+
+/**
+ * # Bend — the quadratic hinge row
+ *
+ *     C(x) = Σ_k w_k · x_k        (a vector: the discrete mean-curvature vector)
+ *     ∂C_d/∂x_k = w_k · e_d       (constant — the weights *are* the gradient)
+ *
+ * The quadratic bending model (Bergou et al. 2006) over a hinge's four
+ * particles: the two ends of the shared edge and the two opposite wing
+ * vertices. The weights are cotangents of the four hinge corner angles in the
+ * **rest** shape, so `C` is linear in `x`, its gradient is a constant read out
+ * of the proxy, and its Hessian contribution is `k·w_k²·I` — a diagonal, with
+ * no cross terms and nothing to recompute. §6's "bending costs almost nothing
+ * per iteration" is this.
+ *
+ * The weights sum to zero, which makes `C(Ax + t) = A·C(x)` for any affine
+ * map: the row is blind to translation, rotation, uniform scale and in-plane
+ * shear of the whole stencil. So it vanishes on the rest shape and on every
+ * affine image of it — which is every in-plane deformation a sheet undergoes
+ * to first order, and is what separates a bending row from a badly conditioned
+ * stretch row. It does **not** vanish on an arbitrary planar configuration:
+ * four coplanar points that are not an affine image of the rest four read as
+ * bent. That is the precise content of §6's "assumes a near-flat rest shape
+ * and near-isometric deformation", and §18's caveat about a garment authored
+ * with a strong permanent curve.
+ *
+ * ## Why not a dihedral angle
+ *
+ * A dihedral formulation needs a normal, an angle and a sign, and every one of
+ * those degenerates when the two triangles become coplanar or invert — at 0°
+ * and at 180°, which is to say at the flat rest state and at a full fold. That
+ * degeneracy is a classic source of exactly the twitching this design exists
+ * to eliminate (§7 P4b). Here a full 180° fold is not singular; it is merely
+ * high energy, and high energy relaxes.
+ *
+ * The cost is stated in §18: the quadratic model assumes a near-flat rest
+ * shape, so a garment authored with a strong permanent curve relaxes flatter
+ * than intended.
+ *
+ * ## `C` is a vector, and so is its multiplier
+ *
+ * Bending resists displacement of the hinge out of plane in *all three*
+ * directions, so the row's constraint value is a 3-vector and it carries three
+ * multipliers. Each component is an ordinary scalar row of §6's model sharing
+ * one penalty stiffness; summing their `k·ggᵀ` contributions collapses to
+ * `k·w_k²·I` because the three gradients are orthogonal and equal in length.
+ * The row is bilateral in every component — a bending moment has no sign to be
+ * one-sided about — so `fc == fu` always holds and the Hessian gate of §5.2 is
+ * never taken here. The stretch row is where that gate earns its keep.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Cotangent weights for one hinge, from its rest shape.
+ *
+ * The stencil is `(i0, i1)` — the shared edge — followed by `i2`, the vertex
+ * opposite that edge in the first triangle, and `i3`, the one opposite it in
+ * the second. `bt_edge_read_diamond` produces exactly this quad and declines
+ * every configuration a hinge cannot be built on (§7 P8), so a caller that
+ * sources its hinges from the engine's binary topology has already had the
+ * degenerate cases rejected for it.
+ *
+ * **Area normalisation lives in the row's stiffness, not here.** Bergou's
+ * energy is `(3/A)·‖C‖²` for a hinge of combined triangle area `A`; in this
+ * row model the energy is `(k/2)·‖C‖²`, so a caller wanting that scaling sets
+ * `stiffness = 6·modulus/A`. Keeping it out of the weights leaves `C` in
+ * metres, which is what makes a bending residual readable in a diagnostic.
+ *
+ * @param {Float32Array|Float64Array|number[]} weight out, 4 values
+ * @param {number} weight_offset
+ * @param {Float32Array|Float64Array|number[]} position rest positions, 3 per particle
+ * @param {number} i0 shared edge, first end
+ * @param {number} i1 shared edge, second end
+ * @param {number} i2 wing opposite the shared edge in the first triangle
+ * @param {number} i3 wing opposite the shared edge in the second triangle
+ */
+export function cloth_bend_stencil_weights(weight, weight_offset, position, i0, i1, i2, i3) {
+    const a = i0 * 3;
+    const b = i1 * 3;
+    const c = i2 * 3;
+    const d = i3 * 3;
+
+    const x0 = position[a], y0 = position[a + 1], z0 = position[a + 2];
+    const x1 = position[b], y1 = position[b + 1], z1 = position[b + 2];
+    const x2 = position[c], y2 = position[c + 1], z2 = position[c + 2];
+    const x3 = position[d], y3 = position[d + 1], z3 = position[d + 2];
+
+    // Corner angles of the two triangles at the two ends of the shared edge.
+    const cot_0_in_first = v3_cotangent(x1 - x0, y1 - y0, z1 - z0, x2 - x0, y2 - y0, z2 - z0);
+    const cot_1_in_first = v3_cotangent(x0 - x1, y0 - y1, z0 - z1, x2 - x1, y2 - y1, z2 - z1);
+    const cot_0_in_second = v3_cotangent(x1 - x0, y1 - y0, z1 - z0, x3 - x0, y3 - y0, z3 - z0);
+    const cot_1_in_second = v3_cotangent(x0 - x1, y0 - y1, z0 - z1, x3 - x1, y3 - y1, z3 - z1);
+
+    // Each shared-edge end is weighted by the two angles at the *other* end;
+    // each wing by the two angles of its own triangle, negated. The four sum
+    // to zero, which is what makes `C` translation-invariant, and they
+    // annihilate any planar quad, which is what makes a flat sheet free.
+    weight[weight_offset] = cot_1_in_first + cot_1_in_second;
+    weight[weight_offset + 1] = cot_0_in_first + cot_0_in_second;
+    weight[weight_offset + 2] = -(cot_0_in_first + cot_1_in_first);
+    weight[weight_offset + 3] = -(cot_0_in_second + cot_1_in_second);
+}
+
+/**
+ * Evaluate one bend row's constraint vector at the current positions.
+ *
+ * The gradient is not returned because it is not computed: `∂C_d/∂x_slot` is
+ * `state.bend_weight[row * 4 + slot]` along axis `d` and zero on the others.
+ *
+ * @param {Float64Array|number[]} c out, 3 values
+ * @param {number} c_offset
+ * @param {ClothState} state
+ * @param {number} row
+ */
+export function cloth_bend_evaluate(c, c_offset, state, row) {
+    const particle = state.bend_particle;
+    const weight = state.bend_weight;
+    const position = state.position;
+
+    const base = row * 4;
+
+    let c_x = 0;
+    let c_y = 0;
+    let c_z = 0;
+
+    for (let slot = 0; slot < 4; slot++) {
+        const w = weight[base + slot];
+        const p = particle[base + slot] * 3;
+
+        c_x += w * position[p];
+        c_y += w * position[p + 1];
+        c_z += w * position[p + 2];
+    }
+
+    c[c_offset] = c_x;
+    c[c_offset + 1] = c_y;
+    c[c_offset + 2] = c_z;
+}
+
+/**
+ * Add every bend row touching `particle` into the vertex accumulator.
+ *
+ * `C` is recomputed per visiting particle rather than cached per row, because
+ * that is what Gauss-Seidel means: a hinge whose other three particles were
+ * updated in an earlier colour of this sweep must be seen at its new shape,
+ * not the shape it had when the iteration began. Gathering those three
+ * positions is the dominant cost of the whole step and this is where it is
+ * paid.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ */
+export function cloth_bend_accumulate(accumulator, state, particle) {
+    const offset = state.bend_adjacency_offset;
+
+    const start = offset[particle];
+    const end = offset[particle + 1];
+
+    if (start === end) {
+        return;
+    }
+
+    const adjacency = state.bend_adjacency;
+    const row_particle = state.bend_particle;
+    const weight = state.bend_weight;
+    const lambda = state.bend_lambda;
+    const penalty = state.bend_penalty;
+    const position = state.position;
+
+    let f_x = accumulator[CVA_F_X];
+    let f_y = accumulator[CVA_F_Y];
+    let f_z = accumulator[CVA_F_Z];
+
+    let h_diagonal = 0;
+
+    for (let i = start; i < end; i++) {
+        const packed = adjacency[i];
+
+        const row = packed >> 2;
+        const slot = packed & 3;
+
+        const base = row << 2;
+
+        let c_x = 0;
+        let c_y = 0;
+        let c_z = 0;
+
+        for (let k = 0; k < 4; k++) {
+            const w = weight[base + k];
+            const p = row_particle[base + k] * 3;
+
+            c_x += w * position[p];
+            c_y += w * position[p + 1];
+            c_z += w * position[p + 2];
+        }
+
+        const k_c = penalty[row];
+        const dual = row * 3;
+
+        // Bilateral in every component: `fc == fu`, so the row is always
+        // active and always contributes curvature.
+        const force_x = k_c * c_x + lambda[dual];
+        const force_y = k_c * c_y + lambda[dual + 1];
+        const force_z = k_c * c_z + lambda[dual + 2];
+
+        const w_self = weight[base + slot];
+
+        f_x -= force_x * w_self;
+        f_y -= force_y * w_self;
+        f_z -= force_z * w_self;
+
+        h_diagonal += k_c * w_self * w_self;
+    }
+
+    accumulator[CVA_F_X] = f_x;
+    accumulator[CVA_F_Y] = f_y;
+    accumulator[CVA_F_Z] = f_z;
+
+    accumulator[CVA_H_XX] += h_diagonal;
+    accumulator[CVA_H_YY] += h_diagonal;
+    accumulator[CVA_H_ZZ] += h_diagonal;
+}
+
+/**
+ * Warm start every bend row for a substep. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha
+ * @param {number} gamma
+ * @param {number} k_min
+ * @param {number} k_max
+ */
+export function cloth_bend_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+    const count = state.bend_count;
+
+    const row_particle = state.bend_particle;
+    const weight = state.bend_weight;
+    const mass_inverse = state.mass_inverse;
+    const stiffness = state.bend_stiffness;
+    const lambda = state.bend_lambda;
+    const penalty = state.bend_penalty;
+
+    const decay = alpha * gamma;
+
+    for (let row = 0; row < count; row++) {
+        const dual = row * 3;
+
+        const material = stiffness[row];
+
+        if (material < Infinity) {
+            // Soft, which in practice is every bending row a fabric carries: a
+            // bending modulus is a material property with a finite value, and
+            // nothing wants a hinge enforced to convergence.
+            penalty[row] = material;
+
+            lambda[dual] = 0;
+            lambda[dual + 1] = 0;
+            lambda[dual + 2] = 0;
+
+            continue;
+        }
+
+        const base = row * 4;
+
+        // Effective compliance of the stencil: `Σ wₖ²·(1/mₖ)`, the inverse mass
+        // seen along the constraint gradient.
+        let compliance = 0;
+
+        for (let slot = 0; slot < 4; slot++) {
+            const w = weight[base + slot];
+
+            compliance += w * w * mass_inverse[row_particle[base + slot]];
+        }
+
+        if (compliance === 0) {
+            // Every particle pinned: the row cannot move anything, and the band
+            // it would otherwise be clamped into is unbounded.
+            penalty[row] = 0;
+
+            lambda[dual] = 0;
+            lambda[dual + 1] = 0;
+            lambda[dual + 2] = 0;
+
+            continue;
+        }
+
+        const scale = inverse_h_squared / compliance;
+
+        const lo = k_min_ratio * scale;
+        const hi = k_max_ratio * scale;
+
+        lambda[dual] *= decay;
+        lambda[dual + 1] *= decay;
+        lambda[dual + 2] *= decay;
+
+        let k = penalty[row] * gamma;
+
+        if (k < lo) {
+            k = lo;
+        } else if (k > hi) {
+            k = hi;
+        }
+
+        penalty[row] = k;
+    }
+}
+
+/**
+ * Dual update for every bend row. The multiplier update is componentwise and
+ * unclamped; the penalty ramp is driven by `‖C‖`, the one scalar the three
+ * components share. §5.2.
+ *
+ * @param {ClothState} state
+ * @param {number} beta
+ * @param {number} k_max
+ */
+export function cloth_bend_dual_update(state, beta, k_max_ratio, inverse_h_squared) {
+    const count = state.bend_count;
+
+    const row_particle = state.bend_particle;
+    const weight = state.bend_weight;
+    const mass_inverse = state.mass_inverse;
+    const position = state.position;
+    const stiffness = state.bend_stiffness;
+    const lambda = state.bend_lambda;
+    const penalty = state.bend_penalty;
+
+    for (let row = 0; row < count; row++) {
+        if (stiffness[row] < Infinity) {
+            // Soft row: no multiplier, no ramp.
+            continue;
+        }
+
+        const base = row * 4;
+
+        let c_x = 0;
+        let c_y = 0;
+        let c_z = 0;
+
+        let compliance = 0;
+
+        for (let k = 0; k < 4; k++) {
+            const w = weight[base + k];
+            const particle = row_particle[base + k];
+            const p = particle * 3;
+
+            c_x += w * position[p];
+            c_y += w * position[p + 1];
+            c_z += w * position[p + 2];
+
+            compliance += w * w * mass_inverse[particle];
+        }
+
+        if (compliance === 0) {
+            continue;
+        }
+
+        const k_max = k_max_ratio * inverse_h_squared / compliance;
+
+        const k_c = penalty[row];
+        const dual = row * 3;
+
+        lambda[dual] += k_c * c_x;
+        lambda[dual + 1] += k_c * c_y;
+        lambda[dual + 2] += k_c * c_z;
+
+        const ramped = k_c + beta * Math.sqrt(c_x * c_x + c_y * c_y + c_z * c_z);
+
+        penalty[row] = ramped < k_max ? ramped : k_max;
+    }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Add every contact touching `particle` into the vertex accumulator.
+ *
+ * @param {Float64Array} accumulator
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {Float32Array|Float64Array} table packed colliders, cloth-local, posed
+ *   at the substep in progress
+ */
+export function cloth_contact_accumulate(accumulator: Float64Array, state: ClothState, particle: number, table: Float32Array | Float64Array): void;
+/**
+ * Warm start every occupied contact slot for a substep.
+ *
+ * A contact is where `β` finally means something. M0 chose `k_min = k_max`,
+ * which disables the ramp, and measured that it was as good as any ramped
+ * alternative — for *persistent* rows, which is all M0 and M1 had. A contact
+ * arrives: on the first substep it exists, its penalty starts at `k_min` and
+ * climbs by `β·|C|` per iteration, so a cape meeting a shoulder is pushed out
+ * over a few iterations instead of being shot off it in one.
+ *
+ * @param {ClothState} state
+ * @param {number} alpha
+ * @param {number} gamma
+ * @param {number} k_min_ratio
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_contact_warm_start(state: ClothState, alpha: number, gamma: number, k_min_ratio: number, k_max_ratio: number, inverse_h_squared: number): void;
+/**
+ * Dual update for every occupied contact slot.
+ *
+ * The constraint is re-evaluated here rather than cached from the accumulation,
+ * for the same reason every other row kind re-evaluates: the accumulation's `C`
+ * is measured *before* the vertex update it feeds, and a multiplier absorbing a
+ * violation that has already been corrected is a multiplier that overshoots on
+ * the next iteration. It costs a second field evaluation per contact per
+ * iteration and it is what makes the multiplier converge within the step.
+ *
+ * @param {ClothState} state
+ * @param {Float32Array|Float64Array} table
+ * @param {number} beta
+ * @param {number} k_max_ratio
+ * @param {number} inverse_h_squared
+ */
+export function cloth_contact_dual_update(state: ClothState, table: Float32Array | Float64Array, beta: number, k_max_ratio: number, inverse_h_squared: number): void;
+/**
+ * # Contact — the collision row and its friction row, which are one contact
+ *
+ * §6's table has them as two rows and they are, but they are two rows of the
+ * *same thing*: friction's clamp is the collision row's own force, so a module
+ * that carried only one of them would have to reach into the other, and a
+ * contact that carried its normal multiplier in one table and its tangential
+ * one in another would have to keep two lifetimes in step. One module, one pair
+ * of slots, one lifetime.
+ *
+ *     collision   C = (r + inflation) − sdf_c(x)        [0, +∞)     hard
+ *                 g = −∇sdf_c(x)
+ *
+ *     friction    C = ‖P_t(x − a)‖                      [0, μ·f_n)  hard
+ *                 g = P_t(x − a)/‖P_t(x − a)‖
+ *
+ * where `a` is where the particle stuck to the collider, carried in the
+ * collider's own frame, and `P_t = I − n nᵀ` projects onto the contact's
+ * tangent plane.
+ *
+ * ## The collision row is hard, which §6's table does not say
+ *
+ * §6 gives it a stiffness `k_contact` and friction a `k_friction`, and M0's own
+ * rule — "a row is **hard** exactly when its stiffness is `Infinity`" — makes
+ * that a statement that both are soft penalties. They cannot be. A soft row
+ * above about `8·(m/h²)` makes the step *add* energy (`MEASUREMENTS.md` §6),
+ * and a contact soft enough to stay under that boundary is a contact cloth
+ * sinks through: measured at 2.3 cm of penetration into a 25 cm sphere for a
+ * cape that is 4 mm thick. Both rows are therefore hard, with the multiplier
+ * carrying the load and the penalty living in the measured band — and that is
+ * also what finally gives `β` something to do, because these are the first rows
+ * in the system that arrive and leave. `MEASUREMENTS.md` §17.
+ *
+ * ## The friction clamp is one-sided because `C` is a magnitude
+ *
+ * §6 writes friction's clamps as `±μ·f_n`, which is the *signed-slip*
+ * formulation — a row whose `C` is a displacement along a chosen tangent. This
+ * one measures the magnitude of the slip in the tangent plane and points its
+ * gradient along it, so `C ≥ 0` always and the negative half of that clamp
+ * names a force that pulls the particle further from where it stuck. The row is
+ * `[0, μ·f_n]`, which is the same physics: static friction while the force it
+ * needs is under the cap, sliding at exactly the cap once it is not.
+ *
+ * Writing it as a magnitude is what removes the tangent basis. A signed row
+ * needs two of them, chosen per contact, and any choice that is continuous
+ * frame to frame is a choice with state in it — which is exactly what §7 P4(a)
+ * exists to keep out of this system.
+ *
+ * ## Which force the friction cap reads
+ *
+ * The *current iteration's* normal force, not the previous iteration's
+ * multiplier. VBD uses the multiplier, which is one iteration stale and
+ * therefore exactly zero on a contact's first iteration — so at the one
+ * iteration per substep §5.1 says the solver must be usable at, friction would
+ * never act at all. The current force is already computed, already
+ * non-negative, and makes a cloth land on a slope and stay there at 1×1.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Contact rows per particle.
+ *
+ * Four, because a particle in a garment's worst corner — an armpit, between two
+ * fingers — is inside three or four collider bounds at once and inside more
+ * than that only when a rig has redundant colliders, where the fifth is a
+ * duplicate of one of the first four. Slots are filled nearest-first, so the
+ * ones dropped are the ones furthest from binding.
+ *
+ * It is a compile-time constant rather than a field because it is a stride: the
+ * accumulation is a counted loop over `CLOTH_CONTACT_SLOTS` adjacent entries,
+ * and a per-cloth capacity would put a load and a multiply in the inner loop to
+ * buy a garment nothing.
+ * @type {number}
+ */
+export const CLOTH_CONTACT_SLOTS: number;
+/**
+ * Below this a tangential slip is treated as zero and the friction row is
+ * skipped: `‖·‖` is not differentiable there, and a particle that has not moved
+ * relative to the surface has nothing for friction to resist.
+ * @type {number}
+ */
+export const CLOTH_FRICTION_EPSILON: number;
+//# sourceMappingURL=cloth_contact_row.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_contact_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_contact_row.js"],"names":[],"mappings":"AA8GA;;;;;;;;GAQG;AACH,sDANW,YAAY,+BAEZ,MAAM,SACN,YAAY,GAAC,YAAY,QAwLnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,mEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QA0ChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oEALW,YAAY,GAAC,YAAY,QACzB,MAAM,eACN,MAAM,qBACN,MAAM,QAkGhB;AAjcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH;;;;;;;;;;;;;;GAcG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,qCAFU,MAAM,CAE2B"}