bireactive 0.2.0

package/dist/constraints/term.js

@@ -0,0 +1,80 @@
+// term.ts — abstract Term: one augmented-Lagrangian constraint over
+// cells, with residual `C(x)`, Jacobian `J = ∂C/∂x`, dual `λ`, penalty.
+// Cells are integer ids into the solver's SOA buffers.
+//
+// AVBD inner loop, per term:
+//   - initialize() once per prepare(); `false` drops the term.
+//   - computeConstraint(alpha) writes `C`; hard constraints stabilise
+//     as `C(x) = C*(x) − α·C*(x⁻)`.
+//   - computeDerivatives(cellIdx) writes the Jacobian column and
+//     geometric-stiffness Hessian column-norms. `cellIdx` indexes
+//     `term.cells`, not the integer cell id.
+export const PENALTY_MIN = 1.0;
+export const PENALTY_MAX = 1e9;
+/** Hard symmetric cap on the per-row multiplier `λ`. Without it the
+ *  dual update grows unboundedly while a constraint stays infeasible
+ *  (e.g. a joint dragged outside its workspace), blowing positions to
+ *  infinity. Capping at `1e9` saturates instead of exploding;
+ *  symmetric so equalities stay reachable from either side. */
+export const LAMBDA_MAX = 1e9;
+export class Term {
+    solver;
+    /** Bound cell ids in subclass order; `cells[ci]` is cell-index ci. */
+    cells;
+    /** Per-cell-index offset into `solver.positions`; cached (offsets are
+     *  append-only). */
+    cellOffsets;
+    cellDims;
+    rows;
+    /** Current constraint values; filled by `computeConstraint`. */
+    C;
+    /** Constraint values at start of step (hard-constraint stabilisation). */
+    C0;
+    /** Per-row stiffness; `Infinity` = hard (augmented-Lagrangian path). */
+    stiffness;
+    /** Per-row lower bound on λ (default `-Infinity`); one-sided
+     *  constraints and friction-cone clamps. */
+    lambdaMin;
+    lambdaMax;
+    /** Fracture threshold: `|λ| > fracture` disables the term. */
+    fracture;
+    /** Current penalty (warm-started, ramped via β). */
+    penalty;
+    /** Lagrange multiplier for hard constraints (soft uses 0). */
+    lambda;
+    /** Removal flag, honoured at the next `prepare()`. Set by
+     *  `dispose()` or by fracture in `_dualPass`. */
+    disabled = false;
+    /** Per-cell-index Jacobian; `J[ci]` is `rows × dim` row-major. */
+    J;
+    /** Per-cell-index Hessian column norms; same shape as `J[ci]`. */
+    HCols;
+    constructor(solver, cells, rows) {
+        this.solver = solver;
+        this.cells = cells;
+        this.cellOffsets = cells.map(id => solver.offsets[id]);
+        this.cellDims = cells.map(id => solver.dims[id]);
+        this.rows = rows;
+        this.C = new Float64Array(rows);
+        this.C0 = new Float64Array(rows);
+        this.stiffness = new Float64Array(rows).fill(Number.POSITIVE_INFINITY);
+        this.lambdaMin = new Float64Array(rows).fill(Number.NEGATIVE_INFINITY);
+        this.lambdaMax = new Float64Array(rows).fill(Number.POSITIVE_INFINITY);
+        this.fracture = new Float64Array(rows).fill(Number.POSITIVE_INFINITY);
+        this.penalty = new Float64Array(rows).fill(PENALTY_MIN);
+        this.lambda = new Float64Array(rows);
+        this.J = this.cellDims.map(d => new Float64Array(rows * d));
+        this.HCols = this.cellDims.map(d => new Float64Array(rows * d));
+        for (let ci = 0; ci < cells.length; ci++) {
+            solver._connectTerm(this, cells[ci], ci);
+        }
+    }
+    /** Mark for removal; takes effect on the next solver pass. */
+    dispose() {
+        this.disabled = true;
+    }
+    /** True iff row is hard (`stiffness === Infinity`). */
+    isHard(row) {
+        return this.stiffness[row] === Number.POSITIVE_INFINITY;
+    }
+}

package/dist/constraints/terms.d.ts

@@ -0,0 +1,80 @@
+import { type Cell, type Writable } from "../core/index.js";
+import type { Solver } from "./solver.js";
+import { Term } from "./term.js";
+export declare const Strength: {
+    readonly WEAK: 1;
+    readonly MEDIUM: 1000;
+    readonly STRONG: 1000000;
+    readonly REQUIRED: 1000000000;
+    /** True hard constraint (augmented-Lagrangian path); `*Term` default. */
+    readonly HARD: number;
+};
+export declare class EqTerm extends Term {
+    constructor(solver: Solver, a: number, b: number, hard?: boolean);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}
+export declare class LensNumTerm extends Term {
+    fwd: (a: number) => number;
+    private readonly fdStep;
+    private _cachedFwdA;
+    private _cachedA;
+    constructor(solver: Solver, a: number, b: number, fwd: (x: number) => number, fdStep?: number);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}
+export declare class DistanceTerm extends Term {
+    /** Rest-length signal; cached in `initialize()`. */
+    readonly rest: Cell<number>;
+    /** Optional mutable stiffness signal (only set when `hard=false`). */
+    readonly stiffnessSig?: Cell<number>;
+    private _restCached;
+    private _cachedNx;
+    private _cachedNy;
+    private _cachedInvD;
+    private _cachedDegenerate;
+    constructor(solver: Solver, a: number, b: number, rest: number | Writable<Cell<number>>, hard?: boolean, stiffness?: number | Writable<Cell<number>>);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}
+export declare class BoundsTerm extends Term {
+    readonly lo: Cell<number>;
+    readonly hi: Cell<number>;
+    private _loCached;
+    private _hiCached;
+    constructor(solver: Solver, cellIdx: number, lo: number | Writable<Cell<number>>, hi: number | Writable<Cell<number>>);
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(_cellIdx: number): void;
+}
+export declare class SoftTargetTerm extends Term {
+    target: Float64Array;
+    constructor(solver: Solver, cell: number, target: ArrayLike<number>, stiffness: number);
+    initialize(): boolean;
+    computeConstraint(_alpha: number): void;
+    computeDerivatives(_cellIdx: number): void;
+}
+export type ResidualFn = (
+/** Per-cell position snapshots, in order (read-only). */
+positions: readonly Float64Array[], 
+/** Output buffer of length `rows`; write residuals (0 = satisfied). */
+out: Float64Array) => void;
+export declare class GenericTerm extends Term {
+    private fn;
+    private fdStep;
+    private _fdPositions;
+    private _fdRawBase;
+    private _fdScratchPlus;
+    private _fdScratchMinus;
+    constructor(solver: Solver, cells: readonly number[], rows: number, fn: ResidualFn, opts?: {
+        fdStep?: number;
+        hard?: boolean;
+        stiffness?: number;
+    });
+    initialize(): boolean;
+    computeConstraint(alpha: number): void;
+    computeDerivatives(cellIdx: number): void;
+}

package/dist/constraints/terms.js

@@ -0,0 +1,302 @@
+// terms.ts — concrete `Term` subclasses (numerical kernel).
+//
+// Each subclass reads positions via `solver.positions`/`offsets` and
+// writes Jacobian / Hessian column norms into `J[ci]` / `HCols[ci]`.
+//
+// Mutable numeric parameters (rest lengths, bounds, …) are held as
+// `Cell<number>` and cached in `initialize()` (called once per
+// `solve()`), so the inner per-iteration methods stay signal-free.
+// Subscription happens at the cluster layer: the network body reads
+// each param signal, so mutating it triggers a re-solve.
+import { cell } from "../core/index.js";
+import { Term } from "./term.js";
+export const Strength = {
+    WEAK: 1,
+    MEDIUM: 1e3,
+    STRONG: 1e6,
+    REQUIRED: 1e9,
+    /** True hard constraint (augmented-Lagrangian path); `*Term` default. */
+    HARD: Number.POSITIVE_INFINITY,
+};
+export class EqTerm extends Term {
+    constructor(solver, a, b, hard = true) {
+        if (solver.dims[a] !== solver.dims[b]) {
+            throw new Error("eq: cell dims must match");
+        }
+        super(solver, [a, b], solver.dims[a]);
+        if (!hard)
+            this.stiffness.fill(1e6);
+    }
+    initialize() {
+        return true;
+    }
+    computeConstraint(alpha) {
+        const positions = this.solver.positions;
+        const aOff = this.cellOffsets[0];
+        const bOff = this.cellOffsets[1];
+        for (let k = 0; k < this.rows; k++) {
+            const Cn = positions[aOff + k] - positions[bOff + k];
+            this.C[k] = this.stiffness[k] === Number.POSITIVE_INFINITY ? Cn - alpha * this.C0[k] : Cn;
+        }
+    }
+    computeDerivatives(cellIdx) {
+        const dim = this.rows;
+        const J = this.J[cellIdx];
+        const sign = cellIdx === 0 ? 1.0 : -1.0;
+        for (let r = 0; r < dim; r++) {
+            for (let k = 0; k < dim; k++)
+                J[r * dim + k] = r === k ? sign : 0.0;
+        }
+    }
+}
+export class LensNumTerm extends Term {
+    fwd;
+    fdStep;
+    _cachedFwdA = 0;
+    _cachedA = Number.NaN;
+    constructor(solver, a, b, fwd, fdStep = 1e-6) {
+        if (solver.dims[a] !== 1 || solver.dims[b] !== 1) {
+            throw new Error("lensNum: both cells must be Num (dim=1)");
+        }
+        super(solver, [a, b], 1);
+        this.fwd = fwd;
+        this.fdStep = fdStep;
+    }
+    initialize() {
+        return true;
+    }
+    computeConstraint(alpha) {
+        const positions = this.solver.positions;
+        const aOff = this.cellOffsets[0];
+        const bOff = this.cellOffsets[1];
+        const a = positions[aOff];
+        const b = positions[bOff];
+        const fa = this.fwd(a);
+        this._cachedFwdA = fa;
+        this._cachedA = a;
+        const Cn = b - fa;
+        this.C[0] = this.stiffness[0] === Number.POSITIVE_INFINITY ? Cn - alpha * this.C0[0] : Cn;
+    }
+    computeDerivatives(cellIdx) {
+        const J = this.J[cellIdx];
+        if (cellIdx === 1) {
+            J[0] = 1.0;
+            return;
+        }
+        const a = this._cachedA;
+        const f0 = this._cachedFwdA;
+        const f1 = this.fwd(a + this.fdStep);
+        J[0] = -(f1 - f0) / this.fdStep;
+    }
+}
+export class DistanceTerm extends Term {
+    /** Rest-length signal; cached in `initialize()`. */
+    rest;
+    /** Optional mutable stiffness signal (only set when `hard=false`). */
+    stiffnessSig;
+    _restCached = 0;
+    _cachedNx = 0;
+    _cachedNy = 0;
+    _cachedInvD = 0;
+    _cachedDegenerate = false;
+    constructor(solver, a, b, rest, hard = true, stiffness) {
+        if (solver.dims[a] !== 2 || solver.dims[b] !== 2) {
+            throw new Error("distance: both cells must be Vec (dim=2)");
+        }
+        super(solver, [a, b], 1);
+        this.rest = cell(rest);
+        this._restCached = this.rest.peek();
+        if (!hard) {
+            this.stiffnessSig = cell(stiffness ?? 1e6);
+            this.stiffness.fill(this.stiffnessSig.peek());
+        }
+    }
+    initialize() {
+        // `.value` (not `.peek()`): runs in the network body, so the read
+        // both refreshes the cache and subscribes the param signal.
+        this._restCached = this.rest.value;
+        if (this.stiffnessSig !== undefined) {
+            const k = this.stiffnessSig.value;
+            this.stiffness[0] = k;
+        }
+        return true;
+    }
+    computeConstraint(alpha) {
+        const positions = this.solver.positions;
+        const aOff = this.cellOffsets[0];
+        const bOff = this.cellOffsets[1];
+        const dx = positions[aOff] - positions[bOff];
+        const dy = positions[aOff + 1] - positions[bOff + 1];
+        const d2 = dx * dx + dy * dy;
+        const restCached = this._restCached;
+        if (d2 < 1e-24) {
+            this._cachedDegenerate = true;
+            this._cachedNx = 0;
+            this._cachedNy = 0;
+            this._cachedInvD = 0;
+            const Cn = -restCached;
+            this.C[0] = this.stiffness[0] === Number.POSITIVE_INFINITY ? Cn - alpha * this.C0[0] : Cn;
+            return;
+        }
+        const d = Math.sqrt(d2);
+        const inv = 1 / d;
+        this._cachedDegenerate = false;
+        this._cachedNx = dx * inv;
+        this._cachedNy = dy * inv;
+        this._cachedInvD = inv;
+        const Cn = d - restCached;
+        this.C[0] = this.stiffness[0] === Number.POSITIVE_INFINITY ? Cn - alpha * this.C0[0] : Cn;
+    }
+    computeDerivatives(cellIdx) {
+        const J = this.J[cellIdx];
+        const Hcols = this.HCols[cellIdx];
+        if (this._cachedDegenerate) {
+            J[0] = cellIdx === 0 ? 1 : -1;
+            J[1] = 0;
+            Hcols[0] = 0;
+            Hcols[1] = 0;
+            return;
+        }
+        const nx = this._cachedNx;
+        const ny = this._cachedNy;
+        const inv = this._cachedInvD;
+        const sign = cellIdx === 0 ? 1.0 : -1.0;
+        J[0] = sign * nx;
+        J[1] = sign * ny;
+        Hcols[0] = Math.sqrt(1 - nx * nx) * inv;
+        Hcols[1] = Math.sqrt(1 - ny * ny) * inv;
+    }
+}
+export class BoundsTerm extends Term {
+    lo;
+    hi;
+    _loCached = 0;
+    _hiCached = 0;
+    constructor(solver, cellIdx, lo, hi) {
+        if (solver.dims[cellIdx] !== 1)
+            throw new Error("clamp: cell must be Num (dim=1)");
+        super(solver, [cellIdx], 2);
+        this.lo = cell(lo);
+        this.hi = cell(hi);
+        this._loCached = this.lo.peek();
+        this._hiCached = this.hi.peek();
+        this.lambdaMax[0] = 0;
+        this.lambdaMax[1] = 0;
+    }
+    initialize() {
+        // `.value` to subscribe + refresh; see DistanceTerm note.
+        this._loCached = this.lo.value;
+        this._hiCached = this.hi.value;
+        return true;
+    }
+    computeConstraint(alpha) {
+        const positions = this.solver.positions;
+        const off = this.cellOffsets[0];
+        const x = positions[off];
+        const c0 = x - this._loCached;
+        const c1 = this._hiCached - x;
+        const stiff = this.stiffness;
+        this.C[0] = stiff[0] === Number.POSITIVE_INFINITY ? c0 - alpha * this.C0[0] : c0;
+        this.C[1] = stiff[1] === Number.POSITIVE_INFINITY ? c1 - alpha * this.C0[1] : c1;
+    }
+    computeDerivatives(_cellIdx) {
+        const J = this.J[0];
+        J[0] = 1;
+        J[1] = -1;
+    }
+}
+export class SoftTargetTerm extends Term {
+    target;
+    constructor(solver, cell, target, stiffness) {
+        const dim = solver.dims[cell];
+        super(solver, [cell], dim);
+        this.target = new Float64Array(dim);
+        for (let k = 0; k < dim; k++)
+            this.target[k] = target[k] ?? 0;
+        this.stiffness.fill(stiffness);
+    }
+    initialize() {
+        return true;
+    }
+    computeConstraint(_alpha) {
+        const positions = this.solver.positions;
+        const off = this.cellOffsets[0];
+        const dim = this.rows;
+        for (let k = 0; k < dim; k++) {
+            this.C[k] = positions[off + k] - this.target[k];
+        }
+    }
+    computeDerivatives(_cellIdx) {
+        const dim = this.rows;
+        const J = this.J[0];
+        for (let r = 0; r < dim; r++) {
+            for (let k = 0; k < dim; k++)
+                J[r * dim + k] = r === k ? 1 : 0;
+        }
+    }
+}
+export class GenericTerm extends Term {
+    fn;
+    fdStep;
+    _fdPositions;
+    _fdRawBase;
+    _fdScratchPlus;
+    _fdScratchMinus;
+    constructor(solver, cells, rows, fn, opts = {}) {
+        super(solver, cells, rows);
+        this.fn = fn;
+        this.fdStep = opts.fdStep ?? 1e-6;
+        this._fdScratchPlus = new Float64Array(rows);
+        this._fdScratchMinus = new Float64Array(rows);
+        this._fdRawBase = new Float64Array(rows);
+        this._fdPositions = this.cellDims.map(d => new Float64Array(d));
+        if (opts.hard === false)
+            this.stiffness.fill(opts.stiffness ?? 1e6);
+    }
+    initialize() {
+        return true;
+    }
+    computeConstraint(alpha) {
+        const positions = this.solver.positions;
+        const offsets = this.cellOffsets;
+        const dims = this.cellDims;
+        for (let i = 0; i < this.cells.length; i++) {
+            const off = offsets[i];
+            const dim = dims[i];
+            const into = this._fdPositions[i];
+            for (let k = 0; k < dim; k++)
+                into[k] = positions[off + k];
+        }
+        this.fn(this._fdPositions, this._fdRawBase);
+        const stiff = this.stiffness;
+        for (let r = 0; r < this.rows; r++) {
+            const raw = this._fdRawBase[r];
+            this.C[r] = stiff[r] === Number.POSITIVE_INFINITY ? raw - alpha * this.C0[r] : raw;
+        }
+    }
+    computeDerivatives(cellIdx) {
+        const dim = this.cellDims[cellIdx];
+        const J = this.J[cellIdx];
+        const Hcols = this.HCols[cellIdx];
+        const baseRaw = this._fdRawBase;
+        const Cplus = this._fdScratchPlus;
+        const Cminus = this._fdScratchMinus;
+        const fdPos = this._fdPositions[cellIdx];
+        const h = this.fdStep;
+        const invH = 1 / h;
+        const invH2 = 1 / (h * h);
+        for (let k = 0; k < dim; k++) {
+            const saved = fdPos[k];
+            fdPos[k] = saved + h;
+            this.fn(this._fdPositions, Cplus);
+            fdPos[k] = saved - h;
+            this.fn(this._fdPositions, Cminus);
+            fdPos[k] = saved;
+            for (let r = 0; r < this.rows; r++) {
+                J[r * dim + k] = (Cplus[r] - baseRaw[r]) * invH;
+                const d2 = (Cplus[r] - 2 * baseRaw[r] + Cminus[r]) * invH2;
+                Hcols[r * dim + k] = d2 < 0 ? -d2 : d2;
+            }
+        }
+    }
+}

package/dist/constraints/world.d.ts

@@ -0,0 +1,31 @@
+import { Constraints } from "./cluster.js";
+import type { PhysicsOpts } from "./physics.js";
+import { Body } from "./rigid.js";
+export interface WorldOpts extends PhysicsOpts {
+    /** Cap on angular speed (rad/s), applied each sub-step before the
+     *  inertial extrapolation. Stops a body that picked up spurious
+     *  spin from running away. Default `50`. */
+    maxAngularSpeed?: number;
+}
+export interface World extends Constraints {
+    /** External acceleration vector. */
+    readonly aExt: Float64Array;
+    /** Read velocity for cell `id`. */
+    velocity(id: number, out?: number[]): number[];
+    /** Write velocity for cell `id`. */
+    setVelocity(id: number, value: ArrayLike<number>): void;
+    /** Per-tick velocity damping. */
+    damping: number;
+    /** All `Body` instances currently registered. */
+    readonly bodies: readonly Body[];
+}
+/** Build a `Constraints` configured for 2D rigid-body physics:
+ *  velocity + gravity + broadphase + contact manifolds.
+ *
+ *    const w = world({ gravity: [0, 1500], iterations: 24 });
+ *    const a = w.add(body({ size: { w: 40, h: 40 } }, { x: 0, y: 0 }));
+ *    const b = w.add(body({ size: { w: 40, h: 40 } }, { x: 100, y: 0 }));
+ *    w.add(joint(a, b, { x: 0, y: 0 }, { x: 0, y: 0 }));
+ *    this.anim.start(fixedStep(w, 1/60));
+ */
+export declare function world(opts?: WorldOpts): World;