@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,346 +1,353 @@
-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;
-    }
-}
+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 nearest **held particle'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];
+
+        if (radius[row] === Infinity) {
+            // A row with no bound — a particle nothing holds — has nothing to
+            // say, and asked first it costs nothing and cannot meet a zero
+            // penalty times an infinite violation.
+            continue;
+        }
+
+        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 || radius[row] === Infinity) {
+            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;
+    }
+}