@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -0,0 +1,133 @@
+import { assert } from "../../../../core/assert.js";
+import { csr_build_incidence } from "../../../../core/graph/csr/csr_build_incidence.js";
+
+/**
+ * The particle graph a cloth's rows imply: an edge between every two particles
+ * that share a row, as a sorted CSR adjacency.
+ *
+ * A stretch row couples its two endpoints; a bend stencil couples all six pairs
+ * of its four particles, since every one of them appears in the same row. Two
+ * build-time consumers want exactly this set — the colouring, where an edge is
+ * a pair that must not be updated at once (`cloth_color_particles.js`), and the
+ * self-collision exclusions, where it is a pair a row already governs
+ * (`cloth_self_find.js`) — and this is the one place it is built.
+ *
+ * The set is deduplicated, because a garment adds every hinge's shared edge
+ * once as a stretch row and again as a bend pair, so duplicates are the common
+ * case; and a row that names one particle twice couples nothing. Each particle's
+ * partners come out ascending, which is the contract the exclusion scans read.
+ *
+ * Build-time only: it allocates its result and a scratch the size of the
+ * half-edge list.
+ *
+ * @param {number} particle_count
+ * @param {Int32Array|number[]} stretch_particle particle index pairs, 2 per row
+ * @param {number} stretch_count
+ * @param {Int32Array|number[]} bend_particle particle index quads, 4 per row
+ * @param {number} bend_count
+ * @returns {{offset: Int32Array, partner: Int32Array}} `partner[offset[i] .. offset[i + 1])` are the
+ *   particles sharing a row with `i`, ascending, without `i` itself
+ */
+export function cloth_particle_coupling(
+    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');
+
+    // Both directions of every coupled pair, duplicates and all.
+    const capacity = stretch_count * 2 + bend_count * 12;
+
+    const from = new Int32Array(capacity);
+    const to = new Int32Array(capacity);
+
+    let half_edge_count = 0;
+
+    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`);
+
+        if (a !== b) {
+            from[half_edge_count] = a;
+            to[half_edge_count++] = b;
+            from[half_edge_count] = b;
+            to[half_edge_count++] = a;
+        }
+    }
+
+    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++) {
+                const b = bend_particle[base + j];
+
+                if (a !== b) {
+                    from[half_edge_count] = a;
+                    to[half_edge_count++] = b;
+                    from[half_edge_count] = b;
+                    to[half_edge_count++] = a;
+                }
+            }
+        }
+    }
+
+    const offset = new Int32Array(particle_count + 1);
+    const partner = new Int32Array(half_edge_count);
+
+    csr_build_incidence(offset, partner, from, half_edge_count, particle_count);
+
+    // half-edge index to the particle at its far end
+    for (let k = 0; k < half_edge_count; k++) {
+        partner[k] = to[partner[k]];
+    }
+
+    // Sort each particle's partners and drop the repeats, compacting in place.
+    // The write cursor never passes the read cursor, so an entry is always read
+    // before anything is written over it.
+    let written = 0;
+
+    for (let particle = 0; particle < particle_count; particle++) {
+        const start = offset[particle];
+        const end = offset[particle + 1];
+
+        offset[particle] = written;
+
+        const row_start = written;
+
+        for (let k = start; k < end; k++) {
+            const value = partner[k];
+
+            // insertion into the sorted run `[row_start, written)`, skipping a value already there
+            let j = written - 1;
+
+            while (j >= row_start && partner[j] > value) {
+                j--;
+            }
+
+            if (j >= row_start && partner[j] === value) {
+                continue;
+            }
+
+            for (let m = written; m > j + 1; m--) {
+                partner[m] = partner[m - 1];
+            }
+
+            partner[j + 1] = value;
+            written++;
+        }
+    }
+
+    offset[particle_count] = written;
+
+    return { offset, partner: partner.slice(0, written) };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Invert {@link ClothState#source_of_particle}: for every source vertex, the
+ * particle it became.
+ *
+ * `ClothState.from` permutes particles into colour order, so anything built
+ * against the source mesh — a triangle list, a joint layout, a node table —
+ * names the wrong particles until it is read through this map.
+ *
+ * @param {Int32Array} out particle of every source vertex, `particle_count` entries
+ * @param {Int32Array} source_of_particle source vertex of every particle, a permutation
+ *   of `[0, particle_count)`
+ * @param {number} particle_count
+ * @returns {void}
+ */
+export function cloth_particle_of_source(out: Int32Array, source_of_particle: Int32Array, particle_count: number): void;
+//# sourceMappingURL=cloth_particle_of_source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_particle_of_source.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_particle_of_source.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,8CANW,UAAU,sBACV,UAAU,kBAEV,MAAM,GACJ,IAAI,CAMhB"}

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

@@ -0,0 +1,19 @@
+/**
+ * Invert {@link ClothState#source_of_particle}: for every source vertex, the
+ * particle it became.
+ *
+ * `ClothState.from` permutes particles into colour order, so anything built
+ * against the source mesh — a triangle list, a joint layout, a node table —
+ * names the wrong particles until it is read through this map.
+ *
+ * @param {Int32Array} out particle of every source vertex, `particle_count` entries
+ * @param {Int32Array} source_of_particle source vertex of every particle, a permutation
+ *   of `[0, particle_count)`
+ * @param {number} particle_count
+ * @returns {void}
+ */
+export function cloth_particle_of_source(out, source_of_particle, particle_count) {
+    for (let particle = 0; particle < particle_count; particle++) {
+        out[source_of_particle[particle]] = particle;
+    }
+}

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

@@ -28,8 +28,12 @@ export function cloth_self_exclusions(state: ClothState): {
  * measured left the settled cape with three permanently active pairs.
  * `MEASUREMENTS.md` §37.
  *
- * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
- * so this measures the pairs the row can actually act on and nothing else.
+ * **Every particle is measured, held or not.** Which particles are held changes
+ * while a cloth runs — a hand lets go, a hook catches — and this is measured
+ * once, when the rows are built; a ceiling that left out the particles held at
+ * that moment would be too generous for the cloth once they were let go, which
+ * is §36's permanently active pair. {@link cloth_self_find} pairs a held
+ * particle with a free one for the same reason.
  *
  * @param {ClothState} state
  * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CA0DrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAoHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AA1aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}
+{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA6DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAQrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAgHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AAxXD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}

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

@@ -1,4 +1,5 @@
 import { PointHashGrid3 } from "../../../../core/geom/3d/hash-grid/PointHashGrid3.js";
+import { cloth_particle_coupling } from "./cloth_particle_coupling.js";
 
 /**
  * # Finding the self-collision pairs, once per step
@@ -65,61 +66,11 @@ export const CLOTH_SELF_PAIRS_PER_PARTICLE = 8;
  * @returns {{offset: Int32Array, partner: Int32Array}} CSR, sorted within each particle
  */
 export function cloth_self_exclusions(state) {
-    const particle_count = state.particle_count;
-
-    /** @type {Set<number>[]} */
-    const sets = new Array(particle_count);
-
-    for (let i = 0; i < particle_count; i++) {
-        sets[i] = new Set();
-    }
-
-    /**
-     * @param {number} a
-     * @param {number} b
-     */
-    const link = (a, b) => {
-        if (a === b) {
-            return;
-        }
-
-        sets[a].add(b);
-        sets[b].add(a);
-    };
-
-    for (let row = 0; row < state.stretch_count; row++) {
-        link(state.stretch_particle[row * 2], state.stretch_particle[row * 2 + 1]);
-    }
-
-    for (let row = 0; row < state.bend_count; row++) {
-        const base = row * 4;
-
-        for (let a = 0; a < 4; a++) {
-            for (let b = a + 1; b < 4; b++) {
-                link(state.bend_particle[base + a], state.bend_particle[base + b]);
-            }
-        }
-    }
-
-    const offset = new Int32Array(particle_count + 1);
-
-    let total = 0;
-
-    for (let i = 0; i < particle_count; i++) {
-        total += sets[i].size;
-
-        offset[i + 1] = total;
-    }
-
-    const partner = new Int32Array(total);
-
-    for (let i = 0; i < particle_count; i++) {
-        const sorted = Array.from(sets[i]).sort((a, b) => a - b);
-
-        partner.set(sorted, offset[i]);
-    }
-
-    return { offset, partner };
+    return cloth_particle_coupling(
+        state.particle_count,
+        state.stretch_particle, state.stretch_count,
+        state.bend_particle, state.bend_count
+    );
 }
 
 /**
@@ -142,8 +93,12 @@ export function cloth_self_exclusions(state) {
  * measured left the settled cape with three permanently active pairs.
  * `MEASUREMENTS.md` §37.
  *
- * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
- * so this measures the pairs the row can actually act on and nothing else.
+ * **Every particle is measured, held or not.** Which particles are held changes
+ * while a cloth runs — a hand lets go, a hook catches — and this is measured
+ * once, when the rows are built; a ceiling that left out the particles held at
+ * that moment would be too generous for the cloth once they were let go, which
+ * is §36's permanently active pair. {@link cloth_self_find} pairs a held
+ * particle with a free one for the same reason.
  *
  * @param {ClothState} state
  * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
@@ -179,10 +134,6 @@ export function cloth_self_closest_free_pair(state, exclusions, search) {
     let closest_squared = search * search;
 
     for (let i = 0; i < particle_count; i++) {
-        if (mass_inverse[i] === 0) {
-            continue;
-        }
-
         const a = i * 3;
 
         const x = position[a];
@@ -224,7 +175,7 @@ export function cloth_self_closest_free_pair(state, exclusions, search) {
                     for (let at = grid_offset[bucket]; at < end; at++) {
                         const j = grid_point[at];
 
-                        if (j <= i || mass_inverse[j] === 0) {
+                        if (j <= i) {
                             continue;
                         }
 
@@ -308,11 +259,11 @@ export function cloth_self_find(state, exclusions) {
     const radius_squared = radius * radius;
 
     for (let i = 0; i < particle_count; i++) {
-        if (mass_inverse[i] === 0) {
-            // A pinned particle cannot be pushed, so a pair on it is a force
-            // assembled and thrown away for one end and doubled for the other.
-            continue;
-        }
+        // A held particle is paired with free ones and not with another held
+        // one: it cannot be pushed, but it can be carried through the fabric —
+        // a grabbed corner swept across the sheet — and the free end of the
+        // pair is what has to get out of its way.
+        const i_held = mass_inverse[i] === 0;
 
         const a = i * 3;
 
@@ -365,7 +316,7 @@ export function cloth_self_find(state, exclusions) {
                             continue;
                         }
 
-                        if (mass_inverse[j] === 0) {
+                        if (i_held && mass_inverse[j] === 0) {
                             continue;
                         }
 

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_solve_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solve_vertex.js"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;GAaG;AACH,gEANW,MAAM,qBACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,QAgIxC"}
+{"version":3,"file":"cloth_solve_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solve_vertex.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;GAaG;AACH,gEANW,MAAM,qBACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,QA0FxC"}

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { matrix_symmetric_3x3_solve_ldlt } from "../../../../core/math/linalg/matrix_symmetric_3x3_solve_ldlt.js";
 import { cloth_backstop_accumulate } from "./constraint/cloth_backstop_row.js";
 import { cloth_bend_accumulate } from "./constraint/cloth_bend_row.js";
 import { cloth_contact_accumulate } from "./constraint/cloth_contact_row.js";
@@ -7,16 +8,11 @@ import { cloth_self_accumulate } from "./constraint/cloth_self_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
+    CVA_STRIDE,
+    cloth_vertex_accumulator_seed
 } from "./cloth_vertex_accumulator.js";
 
 /**
@@ -78,6 +74,13 @@ import {
  */
 const ACCUMULATOR = new Float64Array(CVA_STRIDE);
 
+/**
+ * The Newton step `H⁻¹f`, scratch for the same call.
+ * @type {Float64Array}
+ * @private
+ */
+const DELTA = new Float64Array(3);
+
 /**
  * Update one particle in place.
  *
@@ -104,24 +107,9 @@ export function cloth_solve_vertex(state, particle, inverse_h_squared, collider_
 
     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_vertex_accumulator_seed(accumulator, position, inertial, p, inverse_h_squared / inverse_mass);
 
     cloth_stretch_accumulate(accumulator, state, particle);
     cloth_bend_accumulate(accumulator, state, particle);
@@ -136,53 +124,30 @@ export function cloth_solve_vertex(state, particle, inverse_h_squared, collider_
         cloth_self_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. The message is built only when the check fails: as
-    // an argument it was a string of four numbers per vertex per iteration.
-    if (!(pivot_x > 0 && pivot_y > 0 && pivot_z > 0)) {
+    // LDLᵀ, not a cofactor inverse: a vertex with one very stiff row and a
+    // small mass term assembles an `H` with a condition number in the billions,
+    // whose cofactor determinant comes out negative though every eigenvalue is
+    // positive (the core function carries the argument). The `H` slots are laid
+    // out `[xx, yy, zz, xy, xz, yz]`, which is the packing it reads.
+    //
+    // Its pivot check — all three positive *is* positive definiteness — is the
+    // same claim §5.3 makes, checked where it is actually used. A shipped build
+    // strips the assert and leaves the particle where it is rather than moving
+    // it by a solve of an indefinite system.
+    if (!matrix_symmetric_3x3_solve_ldlt(DELTA, 0, accumulator, CVA_H_XX, accumulator, CVA_F_X)) {
+        // The message is built only when the check fails: as an argument it
+        // was a string of numbers per vertex per iteration.
         assert.ok(
             false,
-            `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`
+            `cloth vertex ${particle}: H is not positive definite (H ${accumulator.subarray(CVA_H_XX, CVA_H_YZ + 1).join(', ')}) — 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;
+        return;
+    }
 
-    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;
+    const delta_x = DELTA[0];
+    const delta_y = DELTA[1];
+    const delta_z = DELTA[2];
 
     // Trust region. `H⁻¹f` is a descent direction — that is what positive
     // definiteness buys — but a *full* Newton step is only a descent *step*

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

@@ -145,18 +145,30 @@ export const CLOTH_CONTACT_K_MIN_RATIO: number;
  * sees anything of the kind: what it holds apart weighs grams and is moving at
  * the speed cloth moves relative to itself.
  *
- * **Eight, and the dissipative band is not the reason.** Eight is where M0's
- * band tops out and it would be natural to read this as the same ceiling, but
- * `MEASUREMENTS.md` §32 swept the ratio from 1 to 64 and found no energy growth
- * anywhere: the band was measured on rows that are *on every step*, and a
- * one-sided row that vanishes the instant it is satisfied has no standing spring
- * to pump. What picks eight is the crossing count — it is the joint minimum of
- * the mean, and a stiffer row makes the *worst* case steadily worse by throwing
- * a particle hard enough to put the sheet through itself elsewhere.
- *
- * The consequence is a row with no multiplier, no warm start and no identity
- * across steps, which is what makes rebuilding the pair list from scratch every
- * step affordable. `MEASUREMENTS.md` §33.
+ * **Two: the stiffest ratio at which cloth resting on itself comes to rest.**
+ * The ratio trades two measured things against each other.
+ *
+ * - **A stiffer row passes through itself less while the cloth moves.** On
+ *   §32's folding sheet, over 48 gusts, silk, cotton, hair and a sheet with no
+ *   bending average 2.09 crossings a sample at 8, 2.98 at 2 and 3.74 at 1,
+ *   against 9.17 with no row. That is why §32 shipped 8.
+ * - **A pair that carries weight is a spring that is on every step**, which is
+ *   the case M0's dissipative band was measured on. §32's sheet never had one,
+ *   because its contacts come and go, so its "no energy growth anywhere" held
+ *   only for that sheet. A fold resting on a fold has one. At 8, piles of
+ *   ribbons, a sheet draped on a sphere and a skirt after a twirl never sleep,
+ *   and piles reach 3.8 times the speed their drop could give them (§64).
+ *
+ * At 2 all three sleep. Of 225 ribbon piles in three fabrics, 135 land without
+ * passing through themselves and 134 of those come to rest. At 4, five of 38
+ * clean silk piles never do. The draped sheet sleeps by step 386 at every
+ * ratio up to 2.25 and is erratic above it, never sleeping at 5 or 8. Below 2
+ * the folding sheet only gets worse, and more piles land through themselves.
+ * The library bench cannot tell 2 from 8. `MEASUREMENTS.md` §65.
+ *
+ * It stays a plain penalty: no multiplier, no warm start and no identity across
+ * steps, which is what makes rebuilding the pair list from scratch every step
+ * affordable. `MEASUREMENTS.md` §33.
  * @type {number}
  */
 export const CLOTH_SELF_RATIO: number;

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;GAIG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;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"}
+{"version":3,"file":"cloth_solver_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solver_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;GAIG;AACH,yBAFU,MAAM,CAEc;AAE9B;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;;GASG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;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"}

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

@@ -152,21 +152,33 @@ export const CLOTH_CONTACT_K_MIN_RATIO = 0.25;
  * sees anything of the kind: what it holds apart weighs grams and is moving at
  * the speed cloth moves relative to itself.
  *
- * **Eight, and the dissipative band is not the reason.** Eight is where M0's
- * band tops out and it would be natural to read this as the same ceiling, but
- * `MEASUREMENTS.md` §32 swept the ratio from 1 to 64 and found no energy growth
- * anywhere: the band was measured on rows that are *on every step*, and a
- * one-sided row that vanishes the instant it is satisfied has no standing spring
- * to pump. What picks eight is the crossing count — it is the joint minimum of
- * the mean, and a stiffer row makes the *worst* case steadily worse by throwing
- * a particle hard enough to put the sheet through itself elsewhere.
+ * **Two: the stiffest ratio at which cloth resting on itself comes to rest.**
+ * The ratio trades two measured things against each other.
  *
- * The consequence is a row with no multiplier, no warm start and no identity
- * across steps, which is what makes rebuilding the pair list from scratch every
- * step affordable. `MEASUREMENTS.md` §33.
+ * - **A stiffer row passes through itself less while the cloth moves.** On
+ *   §32's folding sheet, over 48 gusts, silk, cotton, hair and a sheet with no
+ *   bending average 2.09 crossings a sample at 8, 2.98 at 2 and 3.74 at 1,
+ *   against 9.17 with no row. That is why §32 shipped 8.
+ * - **A pair that carries weight is a spring that is on every step**, which is
+ *   the case M0's dissipative band was measured on. §32's sheet never had one,
+ *   because its contacts come and go, so its "no energy growth anywhere" held
+ *   only for that sheet. A fold resting on a fold has one. At 8, piles of
+ *   ribbons, a sheet draped on a sphere and a skirt after a twirl never sleep,
+ *   and piles reach 3.8 times the speed their drop could give them (§64).
+ *
+ * At 2 all three sleep. Of 225 ribbon piles in three fabrics, 135 land without
+ * passing through themselves and 134 of those come to rest. At 4, five of 38
+ * clean silk piles never do. The draped sheet sleeps by step 386 at every
+ * ratio up to 2.25 and is erratic above it, never sleeping at 5 or 8. Below 2
+ * the folding sheet only gets worse, and more piles land through themselves.
+ * The library bench cannot tell 2 from 8. `MEASUREMENTS.md` §65.
+ *
+ * It stays a plain penalty: no multiplier, no warm start and no identity across
+ * steps, which is what makes rebuilding the pair list from scratch every step
+ * affordable. `MEASUREMENTS.md` §33.
  * @type {number}
  */
-export const CLOTH_SELF_RATIO = 8;
+export const CLOTH_SELF_RATIO = 2;
 
 /**
  * Smallest radius a self-collision row is written at, as a multiple of the

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

@@ -11,6 +11,7 @@
  *     warm start   λ ← λ·α·γ ;  k ← clamp(k·γ, k_min, k_max)      (hard rows only)
  *     iterate      × iterations:
  *                    for each colour: for each particle: vertex update
+ *                    last iteration, held particles on one line: turn about it
  *                    dual update:  λ ← clamp(k·C + λ, f_min, f_max)
  *                                  k ← min(k + β·|C|, min(k_max, stiffness))
  *     integrate    v  = (x − x_prev)/h
@@ -54,6 +55,21 @@
  * which is what makes "no wind produces the bytes M5 measured" a fact about the
  * code rather than a claim about floating point.
  *
+ * ## One more block when the holds are a line
+ *
+ * Every vertex update is a 3×3 block of the descent, and a cloth held along one
+ * line has a motion no such block can make: turning about the line as a rigid
+ * body. About a vertical line nothing restores that turn, and the step stopped
+ * at a fabric's iteration count left a moment about it every substep — a flag
+ * turned on its pole for as long as it was run. So the turn is a block of its
+ * own, `cloth_hold_line.js`: one Newton step along it, in the last iteration,
+ * after the sweep and before the dual update.
+ *
+ * Whether the held particles are on a line is decided at every substep, from
+ * where the predict has just carried them. The predict lists them as it goes,
+ * so the question costs a pass over the held particles rather than over the
+ * cloth.
+ *
  * ## What each piece is for
  *
  * **Warm start** carries the multipliers into the next substep so a hard row

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,aAC3G,YAAY,GAAC,IAAI,QAsG3B"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,aAC3G,YAAY,GAAC,IAAI,QAkI3B"}