@woosh/meep-engine 3.21.0 → 3.22.0

package/src/engine/physics/cloth/solver/cloth_color_particles.d.ts

@@ -0,0 +1,67 @@
+/**
+ * # Particle-graph colouring for the cloth solver
+ *
+ * The solver's iteration is Gauss-Seidel over *particles* (§5.2): a particle
+ * reads its neighbours' positions and writes its own. Two particles may be
+ * updated concurrently — and, more importantly for a scalar run, may be
+ * updated in either order without changing the answer — exactly when no
+ * constraint row touches both. Colouring the particle graph so that no row
+ * spans two particles of one colour turns "for each particle" into "for each
+ * colour, for every particle in it", which is the form a worker or a compute
+ * dispatch can parallelise and the form that makes a step's result independent
+ * of particle numbering.
+ *
+ * The graph is the *particle* graph, not the constraint graph: a node per
+ * particle, an edge for every pair of particles that share a row. A stretch
+ * row contributes its one edge; a bend stencil spans four particles and so
+ * contributes all six pairs, which is why the bend diagonals dominate the
+ * chromatic number. VBD reports 8 colours for a 3,891-vertex tetrahedral mesh
+ * against 76 for its 14,802 tetrahedra — the same asymmetry, and the reason
+ * this design colours vertices rather than constraints.
+ *
+ * This runs **once**, at build time, on a `Graph` object. The runtime never
+ * sees a graph: {@link ClothState} bakes the result into a permuted particle
+ * order plus a range per colour, so the sweep is a pair of nested counted
+ * loops over contiguous indices.
+ *
+ * The greedy colouriser is fed a largest-degree-first order (Welsh–Powell),
+ * which is the cheap heuristic that gets a regular triangulated sheet down to
+ * the 8–10 colours §5.4 predicts. The result is checked with the engine's own
+ * {@link validateGraphColoring} behind `assert.*`, so a colouring that would
+ * let two coupled particles race is caught in a dev build and compiles out of
+ * a shipped one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Colour the particle graph implied by a cloth's constraint rows.
+ *
+ * @param {number} particle_count
+ * @param {Int32Array|number[]} stretch_particle particle index pairs, 2 per row
+ * @param {number} stretch_count number of stretch rows
+ * @param {Int32Array|number[]} bend_particle particle index quads, 4 per row
+ * @param {number} bend_count number of bend rows
+ * @returns {Uint32Array} colour of every particle, indexed by particle
+ */
+export function cloth_color_particles(particle_count: number, stretch_particle: Int32Array | number[], stretch_count: number, bend_particle: Int32Array | number[], bend_count: number): Uint32Array;
+/**
+ * Turn a per-particle colouring into the permuted order the solver sweeps:
+ * particles grouped by colour, contiguous, with a start offset per colour.
+ *
+ * Within a colour the original particle order is preserved, so a mesh built
+ * with any locality at all keeps it — the sweep over one colour walks memory
+ * forwards even though it visits every k-th particle of the source mesh.
+ *
+ * @param {Uint32Array} colors colour of every particle
+ * @param {number} particle_count
+ * @returns {{colour_count: number, colour_offset: Int32Array, order: Int32Array}}
+ *   `order[k]` is the source particle that lands at permuted index `k`;
+ *   colour `c` occupies permuted indices `[colour_offset[c], colour_offset[c + 1])`
+ */
+export function cloth_color_order(colors: Uint32Array, particle_count: number): {
+    colour_count: number;
+    colour_offset: Int32Array;
+    order: Int32Array;
+};
+//# sourceMappingURL=cloth_color_particles.d.ts.map

package/src/engine/physics/cloth/solver/cloth_color_particles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_color_particles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_color_particles.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;;GASG;AACH,sDAPW,MAAM,oBACN,UAAU,GAAC,MAAM,EAAE,iBACnB,MAAM,iBACN,UAAU,GAAC,MAAM,EAAE,cACnB,MAAM,GACJ,WAAW,CAyFvB;AAmCD;;;;;;;;;;;;;GAaG;AACH,0CANW,WAAW,kBACX,MAAM,GACJ;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,CAmChF"}

package/src/engine/physics/cloth/solver/cloth_color_particles.js

@@ -0,0 +1,220 @@
+import { assert } from "../../../../core/assert.js";
+import { colorizeGraphGreedy } from "../../../../core/graph/coloring/colorizeGraphGreedy.js";
+import { validateGraphColoring } from "../../../../core/graph/coloring/validateGraphColoring.js";
+import { Graph } from "../../../../core/graph/v2/Graph.js";
+
+/**
+ * # Particle-graph colouring for the cloth solver
+ *
+ * The solver's iteration is Gauss-Seidel over *particles* (§5.2): a particle
+ * reads its neighbours' positions and writes its own. Two particles may be
+ * updated concurrently — and, more importantly for a scalar run, may be
+ * updated in either order without changing the answer — exactly when no
+ * constraint row touches both. Colouring the particle graph so that no row
+ * spans two particles of one colour turns "for each particle" into "for each
+ * colour, for every particle in it", which is the form a worker or a compute
+ * dispatch can parallelise and the form that makes a step's result independent
+ * of particle numbering.
+ *
+ * The graph is the *particle* graph, not the constraint graph: a node per
+ * particle, an edge for every pair of particles that share a row. A stretch
+ * row contributes its one edge; a bend stencil spans four particles and so
+ * contributes all six pairs, which is why the bend diagonals dominate the
+ * chromatic number. VBD reports 8 colours for a 3,891-vertex tetrahedral mesh
+ * against 76 for its 14,802 tetrahedra — the same asymmetry, and the reason
+ * this design colours vertices rather than constraints.
+ *
+ * This runs **once**, at build time, on a `Graph` object. The runtime never
+ * sees a graph: {@link ClothState} bakes the result into a permuted particle
+ * order plus a range per colour, so the sweep is a pair of nested counted
+ * loops over contiguous indices.
+ *
+ * The greedy colouriser is fed a largest-degree-first order (Welsh–Powell),
+ * which is the cheap heuristic that gets a regular triangulated sheet down to
+ * the 8–10 colours §5.4 predicts. The result is checked with the engine's own
+ * {@link validateGraphColoring} behind `assert.*`, so a colouring that would
+ * let two coupled particles race is caught in a dev build and compiles out of
+ * a shipped one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Colour the particle graph implied by a cloth's constraint rows.
+ *
+ * @param {number} particle_count
+ * @param {Int32Array|number[]} stretch_particle particle index pairs, 2 per row
+ * @param {number} stretch_count number of stretch rows
+ * @param {Int32Array|number[]} bend_particle particle index quads, 4 per row
+ * @param {number} bend_count number of bend rows
+ * @returns {Uint32Array} colour of every particle, indexed by particle
+ */
+export function cloth_color_particles(
+    particle_count,
+    stretch_particle, stretch_count,
+    bend_particle, bend_count
+) {
+    assert.isNonNegativeInteger(particle_count, 'particle_count');
+    assert.isNonNegativeInteger(stretch_count, 'stretch_count');
+    assert.isNonNegativeInteger(bend_count, 'bend_count');
+
+    if (particle_count === 0) {
+        return new Uint32Array(0);
+    }
+
+    const graph = new Graph();
+
+    // Nodes are the particle indices themselves, inserted in order, so the
+    // colouriser's node array is the identity permutation and `colors[i]` is
+    // the colour of particle `i` without a second lookup.
+    for (let i = 0; i < particle_count; i++) {
+        graph.addNode(i);
+    }
+
+    // `Graph#hasEdge` is identity-based, so the same pair added twice becomes
+    // two edges and shows up twice in a neighbour list. A garment adds every
+    // hinge's shared edge once as a stretch row and again as a bend pair, so
+    // the duplicates are the common case rather than the exception; they cost
+    // the colouriser a linear `indexOf` each. Fold them here instead.
+    const seen = new Set();
+
+    /**
+     * @param {number} a
+     * @param {number} b
+     */
+    const couple = (a, b) => {
+        if (a === b) {
+            return;
+        }
+
+        const key = a < b ? a * particle_count + b : b * particle_count + a;
+
+        if (seen.has(key)) {
+            return;
+        }
+
+        seen.add(key);
+
+        graph.createEdge(a, b);
+    };
+
+    // A stretch row couples its two endpoints.
+    for (let row = 0; row < stretch_count; row++) {
+        const a = stretch_particle[row * 2];
+        const b = stretch_particle[row * 2 + 1];
+
+        assert.ok(a >= 0 && a < particle_count, `stretch row ${row} particle 0 (=${a}) out of range`);
+        assert.ok(b >= 0 && b < particle_count, `stretch row ${row} particle 1 (=${b}) out of range`);
+
+        couple(a, b);
+    }
+
+    // A bend stencil couples all six pairs of its four particles — every one
+    // of them appears in the same row, so any two of them writing at once is
+    // the race the colouring exists to prevent.
+    for (let row = 0; row < bend_count; row++) {
+        const base = row * 4;
+
+        for (let i = 0; i < 4; i++) {
+            const a = bend_particle[base + i];
+
+            assert.ok(a >= 0 && a < particle_count, `bend row ${row} particle ${i} (=${a}) out of range`);
+
+            for (let j = i + 1; j < 4; j++) {
+                couple(a, bend_particle[base + j]);
+            }
+        }
+    }
+
+    const order = order_by_descending_degree(graph, particle_count);
+
+    const colors = colorizeGraphGreedy(graph, order);
+
+    assert.ok(
+        validateGraphColoring(colors, graph),
+        'cloth particle colouring is invalid — two coupled particles share a colour'
+    );
+
+    return colors;
+}
+
+/**
+ * Welsh–Powell: colour the most constrained particle first. Greedy colouring
+ * is order-sensitive and this is the order that keeps a regular sheet inside
+ * the colour count §5.4 budgets for.
+ *
+ * Ties are broken by particle index so the ordering — and therefore the whole
+ * baked layout — is a deterministic function of the topology alone.
+ *
+ * @param {Graph<number>} graph
+ * @param {number} particle_count
+ * @returns {Uint32Array}
+ * @private
+ */
+function order_by_descending_degree(graph, particle_count) {
+    const degree = new Int32Array(particle_count);
+
+    for (let i = 0; i < particle_count; i++) {
+        degree[i] = graph.getNeighbours(i).length;
+    }
+
+    const order = new Uint32Array(particle_count);
+
+    for (let i = 0; i < particle_count; i++) {
+        order[i] = i;
+    }
+
+    // `Array#sort` over a typed array is a numeric sort already; the comparator
+    // is here for the tie-break, not for the ordering of the degrees.
+    order.sort((a, b) => (degree[b] - degree[a]) || (a - b));
+
+    return order;
+}
+
+/**
+ * Turn a per-particle colouring into the permuted order the solver sweeps:
+ * particles grouped by colour, contiguous, with a start offset per colour.
+ *
+ * Within a colour the original particle order is preserved, so a mesh built
+ * with any locality at all keeps it — the sweep over one colour walks memory
+ * forwards even though it visits every k-th particle of the source mesh.
+ *
+ * @param {Uint32Array} colors colour of every particle
+ * @param {number} particle_count
+ * @returns {{colour_count: number, colour_offset: Int32Array, order: Int32Array}}
+ *   `order[k]` is the source particle that lands at permuted index `k`;
+ *   colour `c` occupies permuted indices `[colour_offset[c], colour_offset[c + 1])`
+ */
+export function cloth_color_order(colors, particle_count) {
+    assert.isNonNegativeInteger(particle_count, 'particle_count');
+
+    let colour_count = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const c = colors[i];
+
+        if (c >= colour_count) {
+            colour_count = c + 1;
+        }
+    }
+
+    const colour_offset = new Int32Array(colour_count + 1);
+
+    for (let i = 0; i < particle_count; i++) {
+        colour_offset[colors[i] + 1]++;
+    }
+
+    for (let c = 0; c < colour_count; c++) {
+        colour_offset[c + 1] += colour_offset[c];
+    }
+
+    const cursor = colour_offset.slice(0, colour_count);
+    const order = new Int32Array(particle_count);
+
+    for (let i = 0; i < particle_count; i++) {
+        order[cursor[colors[i]]++] = i;
+    }
+
+    return { colour_count, colour_offset, order };
+}

package/src/engine/physics/cloth/solver/cloth_solve_vertex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Update one particle in place.
+ *
+ * A particle with zero inverse mass is pinned: it is an immovable anchor whose
+ * rows still act on its neighbours, and it is skipped here rather than divided
+ * by.
+ *
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ */
+export function cloth_solve_vertex(state: ClothState, particle: number, inverse_h_squared: number): void;
+//# sourceMappingURL=cloth_solve_vertex.d.ts.map

package/src/engine/physics/cloth/solver/cloth_solve_vertex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_solve_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solve_vertex.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;GAUG;AACH,gEAHW,MAAM,qBACN,MAAM,QAkHhB"}

package/src/engine/physics/cloth/solver/cloth_solve_vertex.js

@@ -0,0 +1,201 @@
+import { assert } from "../../../../core/assert.js";
+import { cloth_bend_accumulate } from "./constraint/cloth_bend_row.js";
+import { cloth_leash_accumulate } from "./constraint/cloth_leash_row.js";
+import { cloth_stretch_accumulate } from "./constraint/cloth_stretch_row.js";
+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,
+    CVA_STRIDE
+} from "./cloth_vertex_accumulator.js";
+
+/**
+ * # The vertex update — one 3×3 block of the descent
+ *
+ * The whole solver is this function run over every particle, colour by colour,
+ * `iterations` times a substep. It minimises the implicit-Euler variational
+ * energy with respect to one particle's position while every other particle is
+ * held fixed:
+ *
+ *     E_i(x) = (m/2h²)‖x − y‖² + Σ_c Ψ_c(C_c(x))
+ *
+ * — an inertial term pulling towards the predicted position `y`, plus one
+ * augmented-Lagrangian term per row. The step is Newton's:
+ *
+ *     f = −∇E_i = −(m/h²)(x − y) − Σ_c fc_c·g_c
+ *     H =  (m/h²)·I + Σ_tension (fc_c/L_c)(I − g_c g_cᵀ) + Σ_{active c} k_c·(g_c g_cᵀ)
+ *     x ← x + H⁻¹f
+ *
+ * ## Why the update never explodes
+ *
+ * The mass term `(m/h²)·I` is positive definite, every `k_c·g gᵀ` is a positive
+ * semidefinite rank-one term, and every `(fc/L)·(I − g gᵀ)` kept above is
+ * positive semidefinite too — that is precisely the test each row applies
+ * before adding one. So **`H` is symmetric positive definite by construction**
+ * — for any topology, any parameter values, any degenerate configuration, and
+ * regardless of how many rows are clamped out. The 3×3 solve therefore never
+ * divides by zero and `H⁻¹f` is always a descent direction. That is a
+ * structural property of the assembled matrix, not an empirical observation,
+ * and it is the whole of §5.3's stability argument.
+ *
+ * **Half of the geometric-stiffness term `fc·∂²C/∂x²` is kept, not all of it
+ * and not none of it.** For a distance row `∂²C/∂x² = (I − ggᵀ)/L`, which is
+ * positive semidefinite exactly when the row is in tension, so the tension
+ * half goes in without touching the argument above and the compression half —
+ * the indefinite one — stays out. An earlier draft of this file dropped the
+ * whole term, and `MEASUREMENTS.md` §5.1 is what that cost: the update
+ * overshoots sideways once `fc/L` passes `m/h²`, raising the vertex energy by
+ * 22% at a ratio of 4 and by a factor of 40 at 7e4. Do not drop it again to
+ * "restore" the SPD claim; the claim never needed it dropped.
+ *
+ * ## Order within a colour does not matter
+ *
+ * Colouring guarantees no row touches two particles of one colour, so every
+ * particle in a colour reads only positions no other particle in that colour
+ * writes. The sweep is Gauss-Seidel across colours and order-independent
+ * within one, which is what lets a worker split a colour across threads and
+ * still produce the main thread's bits (§12).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The `(f, H)` scratch. Module-level and reused: a vertex update allocates
+ * nothing, and the accumulator's life is strictly inside one call.
+ * @type {Float64Array}
+ * @private
+ */
+const ACCUMULATOR = new Float64Array(CVA_STRIDE);
+
+/**
+ * Update one particle in place.
+ *
+ * A particle with zero inverse mass is pinned: it is an immovable anchor whose
+ * rows still act on its neighbours, and it is skipped here rather than divided
+ * by.
+ *
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ */
+export function cloth_solve_vertex(state, particle, inverse_h_squared) {
+    const inverse_mass = state.mass_inverse[particle];
+
+    if (inverse_mass === 0) {
+        return;
+    }
+
+    const position = state.position;
+    const inertial = state.inertial;
+
+    const p = particle * 3;
+
+    // m/h², the inertial term's weight. Positive and finite whenever the
+    // particle has a mass at all, which is what makes `H` positive definite
+    // rather than merely semidefinite.
+    const mass_over_h_squared = inverse_h_squared / inverse_mass;
+
+    const accumulator = ACCUMULATOR;
+
+    accumulator[CVA_F_X] = -mass_over_h_squared * (position[p] - inertial[p]);
+    accumulator[CVA_F_Y] = -mass_over_h_squared * (position[p + 1] - inertial[p + 1]);
+    accumulator[CVA_F_Z] = -mass_over_h_squared * (position[p + 2] - inertial[p + 2]);
+
+    accumulator[CVA_H_XX] = mass_over_h_squared;
+    accumulator[CVA_H_YY] = mass_over_h_squared;
+    accumulator[CVA_H_ZZ] = mass_over_h_squared;
+    accumulator[CVA_H_XY] = 0;
+    accumulator[CVA_H_XZ] = 0;
+    accumulator[CVA_H_YZ] = 0;
+    accumulator[CVA_TRUST] = Infinity;
+
+    cloth_stretch_accumulate(accumulator, state, particle);
+    cloth_bend_accumulate(accumulator, state, particle);
+    cloth_leash_accumulate(accumulator, state, particle);
+
+    const a = accumulator[CVA_H_XX];
+    const b = accumulator[CVA_H_XY];
+    const c = accumulator[CVA_H_XZ];
+    const d = accumulator[CVA_H_YY];
+    const e = accumulator[CVA_H_YZ];
+    const f = accumulator[CVA_H_ZZ];
+
+    // LDLᵀ of the symmetric matrix [[a,b,c],[b,d,e],[c,e,f]], not a cofactor
+    // inverse. The two agree in exact arithmetic and do not agree in Float64:
+    // a vertex with one very stiff row and a small mass term assembles an `H`
+    // with a condition number in the billions, and the cofactor determinant —
+    // a sum of triple products that has to cancel down by that ratio squared —
+    // comes out *negative* on a matrix whose eigenvalues are all positive. The
+    // factorisation never forms those products, so its pivots stay positive
+    // where the determinant does not, and their product is the determinant to
+    // full precision.
+    const pivot_x = a;
+    const lower_yx = b / pivot_x;
+    const lower_zx = c / pivot_x;
+
+    const pivot_y = d - lower_yx * b;
+    const lower_zy = (e - lower_zx * b) / pivot_y;
+
+    const pivot_z = f - lower_zx * c - lower_zy * lower_zy * pivot_y;
+
+    // The pivots of an SPD matrix are its `H` restricted to nested subspaces,
+    // so all three positive *is* positive definiteness — the same claim §5.3
+    // makes, checked where it is actually used.
+    assert.ok(
+        pivot_x > 0 && pivot_y > 0 && pivot_z > 0,
+        `cloth vertex ${particle}: H is not positive definite (pivots ${pivot_x}, ${pivot_y}, ${pivot_z}) — the SPD-by-construction argument of §5.3 has been broken`
+    );
+
+    const force_x = accumulator[CVA_F_X];
+    const force_y = accumulator[CVA_F_Y];
+    const force_z = accumulator[CVA_F_Z];
+
+    // Forward substitution through L, scale by D, back substitution through Lᵀ.
+    const forward_y = force_y - lower_yx * force_x;
+    const forward_z = force_z - lower_zx * force_x - lower_zy * forward_y;
+
+    const delta_z = forward_z / pivot_z;
+    const delta_y = forward_y / pivot_y - lower_zy * delta_z;
+    const delta_x = force_x / pivot_x - lower_yx * delta_y - lower_zx * delta_z;
+
+    // Trust region. `H⁻¹f` is a descent direction — that is what positive
+    // definiteness buys — but a *full* Newton step is only a descent *step*
+    // while the model it was built from still resembles the energy. For a
+    // distance row the model's gradient is the direction to a neighbour, and
+    // that direction is meaningless once the step is comparable to how far
+    // away the neighbour is: a particle sitting a hair from its neighbour with
+    // a large multiplier assembles a perfectly good SPD system and solves it
+    // for a step a thousand times the separation, which climbs.
+    //
+    // So the step is bounded by the shortest row the particle sits on. The
+    // radius is the mesh's own geometry rather than a tuned constant, it is
+    // already in hand from the accumulation, and for cloth in any ordinary
+    // motion it never binds — a step that moves a particle further than its
+    // own edge length in one iteration is already outside what one
+    // linearisation can be asked to describe.
+    const trust = accumulator[CVA_TRUST];
+
+    const length_squared = delta_x * delta_x + delta_y * delta_y + delta_z * delta_z;
+
+    if (length_squared > trust * trust) {
+        const scale = trust / Math.sqrt(length_squared);
+
+        position[p] += delta_x * scale;
+        position[p + 1] += delta_y * scale;
+        position[p + 2] += delta_z * scale;
+
+        return;
+    }
+
+    position[p] += delta_x;
+    position[p + 1] += delta_y;
+    position[p + 2] += delta_z;
+}

package/src/engine/physics/cloth/solver/cloth_solver_constants.d.ts

@@ -0,0 +1,97 @@
+/**
+ * # Solver constants, measured
+ *
+ * `α`, `β`, `γ`, `k_min` and `k_max` are the augmented Lagrangian's tuning.
+ * They are solver internals, they are global, and they are deliberately **not**
+ * on `ClothDynamics` — they are not a property of a fabric, and an author who
+ * has to reach for one of them has been handed the wrong knob.
+ *
+ * Nothing here was copied. The reference AVBD implementation is 2D and
+ * rigid-body-focused: mass terms `m/h²` in the hundreds against handfuls of
+ * hard rows, where cloth has single digits — a 0.3 kg cape across 600
+ * particles is half a gram each — against thousands of soft rows and a few
+ * hard ones. The values below come from
+ * `__fixtures__/cloth_constants_sweep.mjs`; run it to reproduce the tables, and
+ * see `MEASUREMENTS.md` beside `PLAN.md` for the full grids and the four things
+ * the sweep established that §5.2 did not anticipate.
+ *
+ * ## The band is a ratio, not a stiffness
+ *
+ * `k_min` and `k_max` are **multiples of the row's own inertial scale**
+ * `m_eff/h²`, not stiffnesses in N/m. The sweep held a 20-link hard chain at a
+ * fixed ratio while moving the particle mass across five decades and got the
+ * same residual column every time; held at a fixed *stiffness* it got a
+ * different answer for every mass. A stiffness in N/m is therefore not a
+ * constant at all, and the ratio is. §5.2's own reasoning agrees —
+ * `k_max/(m/h²)` is named there as the condition number the 3×3 solve has to
+ * survive — it just stops one step short of making the ratio the parameter.
+ *
+ * ## What each one does, and what the sweep found
+ *
+ * **`α` and `γ` act only through their product.** `α·γ` is how much of a hard
+ * row's multiplier survives a substep, and it is the one number that decides
+ * whether the solver converges or detonates: at `α·γ ≤ 0.3` a 20-link hard
+ * chain settles to rest with kinetic energy at 1e-9 J, at 0.5 it jitters, and
+ * at 0.6 it diverges. Residual improves monotonically towards that cliff, so
+ * the value is a margin decision rather than an optimum: **0.25, a factor of
+ * two clear of divergence.** γ is left at 1 because its second job — decaying
+ * the penalty — has nothing to do while the band is a single point, so putting
+ * the whole decay in α, whose only job is the multiplier, is the truthful
+ * placement. When M2's contacts make the band real again, γ becomes live and
+ * has to be re-measured.
+ *
+ * **`k_min` and `k_max` are equal, which disables the ramp.** Pinning the
+ * penalty at the top of the band measured as good as or better than every
+ * ramped alternative for M0's persistent rows, and it removes a
+ * scale-dependence that a ramp reintroduces: the ramp's speed is set by `β`,
+ * whose useful magnitude tracks `m/h²` the way `k` does, so a live ramp would
+ * make a heavy garment behave differently from a light one. The ramp exists
+ * for **transient** rows — a contact that should arrive soft and stiffen rather
+ * than shock the mesh on its first frame — and M0 has none.
+ *
+ * **`β` could not be chosen from M0 data.** Above about 1e4 every M0 scenario
+ * gives an identical answer, and with the band collapsed it has no effect at
+ * all. The value below is a placeholder that M2 must replace with a
+ * measurement against real contacts.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Multiplier regularisation, `[0, 1]`.
+ * @type {number}
+ */
+export const CLOTH_ALPHA: number;
+/**
+ * Penalty ramp.
+ * @type {number}
+ */
+export const CLOTH_BETA: number;
+/**
+ * Dual decay, `[0, 1)`.
+ * @type {number}
+ */
+export const CLOTH_GAMMA: number;
+/**
+ * Penalty floor, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+export const CLOTH_K_MIN_RATIO: number;
+/**
+ * Penalty ceiling, as a multiple of the row's `m/h²`.
+ * @type {number}
+ */
+export const CLOTH_K_MAX_RATIO: number;
+/**
+ * The five constants as one frozen object, which is what {@link cloth_step}
+ * takes. A sweep passes its own; nothing else should.
+ * @type {Readonly<{alpha: number, beta: number, gamma: number, k_min_ratio: number, k_max_ratio: number}>}
+ */
+export const CLOTH_SOLVER_TUNING: Readonly<{
+    alpha: number;
+    beta: number;
+    gamma: number;
+    k_min_ratio: number;
+    k_max_ratio: number;
+}>;
+//# sourceMappingURL=cloth_solver_constants.d.ts.map

package/src/engine/physics/cloth/solver/cloth_solver_constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;GAGG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;GAIG;AACH,kCAFU,SAAS;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC,CAQvG"}