@danielsimonjr/mathts-autograd 0.3.13 → 0.3.15

package/dist/index.d.ts

@@ -1,659 +1,20 @@
-import { Tensor, Index } from '@danielsimonjr/mathts-tensor';
-
 /**
- * DualTensor — a Tensor + per-element tangent component for forward-mode AD.
- * Storage: two Float64Arrays of equal length (primal + tangent), shape from
- * the wrapped Tensor. Arithmetic follows the dual-number rules:
- *   (a, a') + (b, b') = (a+b, a'+b')
- *   (a, a') * (b, b') = (a·b, a·b' + a'·b)
- *   (a, a') / (b, b') = (a/b, (a'·b − a·b')/b²)
- *   scale((a, a'), k)  = (k·a, k·a')
- * Elementwise unless noted. Reductions and contractions add their own rules.
+ * @danielsimonjr/mathts-autograd — forward + reverse-mode automatic
+ * differentiation for the MathTS rank-N Tensor type.
  *
- * The dual-number framework: tracking ε such that ε²=0; (a + a'·ε)(b + b'·ε)
- * = ab + (ab'+a'b)ε, so the tangent is the linearized first-order response.
+ * v0.1.0 ships:
+ *   - forwardGrad(fn, x): dual-number AD; returns { value, jacobian }.
+ *   - reverseGrad(fn, x, cotangent?): tape-based reverse-mode AD;
+ *     returns { value, gradient }.
  *
- * @packageDocumentation
- */
-
-declare class DualTensor {
-    readonly shape: ReadonlyArray<number>;
-    readonly primal: Float64Array;
-    readonly tangent: Float64Array;
-    constructor(shape: ReadonlyArray<number>, primal: Float64Array, tangent: Float64Array);
-    /**
-     * S5 fix: existing engine ops (e.g. lower, pderiv, contract) reach into
-     * `.data`. The getter returns the primal so those ops still work when a
-     * DualTensor flows through them as a structurally-compatible Tensor.
-     * (AD-aware ops branch on `'tangent' in arg` before reaching here.)
-     */
-    get data(): Float64Array;
-    /** Lift a Tensor to a DualTensor with zero tangent. */
-    static fromTensor(t: Tensor): DualTensor;
-    /** Lift a Tensor to a DualTensor with a unit tangent at flat-index `i`. */
-    static unitAt(t: Tensor, i: number): DualTensor;
-    /** Extract the primal as a plain Tensor. */
-    toPrimalTensor(): Tensor;
-    /** Extract the tangent as a plain Tensor. */
-    toTangentTensor(): Tensor;
-    /** Elementwise addition following dual-number rule: (a+b, a'+b'). */
-    add(other: DualTensor): DualTensor;
-    /** Elementwise subtraction following dual-number rule: (a-b, a'-b'). */
-    sub(other: DualTensor): DualTensor;
-    /**
-     * Elementwise multiplication following dual-number rule: (a·b, a·b' + a'·b).
-     *
-     * I3 fix: explicit alias check. When `this === other` (self-multiplication),
-     * use the specialised rule (a·a)' = 2·a·a' directly. The general rule also
-     * degenerates correctly, but the explicit branch is more readable and aligns
-     * the forward-mode implementation with the reverse-mode alias fix.
-     */
-    mul(other: DualTensor): DualTensor;
-    /** Scalar multiplication following dual-number rule: (k·a, k·a'). */
-    scale(k: number): DualTensor;
-    /**
-     * Elementwise division following the dual-number quotient rule:
-     *   (a, a') / (b, b') = (a/b, (a'·b − a·b') / b²).
-     * The aliased case a.divide(a) is (1, 0).
-     */
-    divide(other: DualTensor): DualTensor;
-    private _unaryElementwise;
-    /**
-     * Apply a shared elementary rule from core's `DUAL_UNARY_RULES` element-wise.
-     * Sourcing `primal`/`deriv` from the canonical table (rather than inline
-     * `Math.*`) keeps this AD path and the scalar `Dual` in lock-step and lets a
-     * future accelerated `primal` in the standard layer propagate here for free —
-     * the loop still calls plain scalar functions, so it stays allocation-free.
-     */
-    private _rule;
-    /** Exponential. f'(x) = eˣ = y. */
-    exp(): DualTensor;
-    /** Natural logarithm. f'(x) = 1/x. */
-    log(): DualTensor;
-    /** Sine. f'(x) = cos(x). */
-    sin(): DualTensor;
-    /** Cosine. f'(x) = −sin(x). */
-    cos(): DualTensor;
-    /** Tangent. f'(x) = 1/cos²(x). */
-    tan(): DualTensor;
-    /** Square root. f'(x) = 1/(2·y) where y = √x. */
-    sqrt(): DualTensor;
-    /** Square (x²). f'(x) = 2x. */
-    square(): DualTensor;
-    /** Reciprocal (1/x). f'(x) = −1/x². */
-    reciprocal(): DualTensor;
-    /** Absolute value. f'(x) = sign(x) (subgradient 0 at exact zero). */
-    abs(): DualTensor;
-    /** Fixed-exponent power x^k. f'(x) = k·x^(k−1). */
-    pow(k: number): DualTensor;
-    /** Hyperbolic sine. f'(x) = cosh(x). */
-    sinh(): DualTensor;
-    /** Hyperbolic cosine. f'(x) = sinh(x). */
-    cosh(): DualTensor;
-    /** Hyperbolic tangent. f'(x) = 1 − tanh²(x) = 1 − y². */
-    tanh(): DualTensor;
-    /** Arcsine. f'(x) = 1/√(1 − x²). */
-    asin(): DualTensor;
-    /** Arccosine. f'(x) = −1/√(1 − x²). */
-    acos(): DualTensor;
-    /** Arctangent. f'(x) = 1/(1 + x²). */
-    atan(): DualTensor;
-    /** Inverse hyperbolic sine. f'(x) = 1/√(x² + 1). */
-    asinh(): DualTensor;
-    /** Inverse hyperbolic cosine (x ≥ 1). f'(x) = 1/√(x² − 1). */
-    acosh(): DualTensor;
-    /** Inverse hyperbolic tangent (|x| < 1). f'(x) = 1/(1 − x²). */
-    atanh(): DualTensor;
-    /** Base-2 logarithm. f'(x) = 1/(x·ln2). */
-    log2(): DualTensor;
-    /** Base-10 logarithm. f'(x) = 1/(x·ln10). */
-    log10(): DualTensor;
-    /** log(1 + x). f'(x) = 1/(1 + x). */
-    log1p(): DualTensor;
-    /** exp(x) − 1. f'(x) = eˣ = y + 1. */
-    expm1(): DualTensor;
-    /** Cube root. f'(x) = 1/(3·y²) where y = x^(1/3) (→∞ at x = 0). */
-    cbrt(): DualTensor;
-    /** Sign (−1/0/+1). f'(x) = 0 almost everywhere. */
-    sign(): DualTensor;
-    /**
-     * Two-argument arctangent: atan2(this, other), this = y, other = x.
-     * Tangent: (b·a' − a·b') / (a² + b²), with a = this, b = other.
-     */
-    atan2(other: DualTensor): DualTensor;
-    private checkSameShape;
-}
-
-/**
- * Forward-mode AD via dual numbers. Returns the value and the full Jacobian
- * of fn at x, shape [...value.shape, ...x.shape] (row-major flatten).
- *
- * Implementation: for each flat-index k in x, build a DualTensor with a unit
- * tangent at position k, run fn (which operates on Tensors — see "interop"
- * below), extract the tangent of the result. The tangent is the k-th column
- * of the Jacobian (in row-major-of-output-flattened form).
- *
- * Interop with the Tensor type: fn is typed `(x: Tensor) => Tensor`, so the
- * tracing requires fn's body to be implementable on either Tensor OR
- * DualTensor. v0.1.0 ships a documented "trace mode" — if fn uses only the
- * core ops that DualTensor implements (add/sub/mul/scale), the
- * implementation auto-traces by detecting DualTensor inputs via a thin
- * wrapper. The actual mechanism in v0.1.0: caller writes fn as if Tensor's
- * methods accept either Tensor or DualTensor (TypeScript's structural typing
- * makes this work for the implemented ops). v0.2.0 may broaden via decorator
- * instrumentation.
- *
- * For UPT v0.4.0's call-sites (metric functions in christoffel lowering),
- * fn uses only add/sub/mul/scale → safe.
+ * Tasks 6/7 populate this barrel. Task 5 scaffolds the package.
  *
  * @packageDocumentation
  */
-
-/**
- * Compute the value and full Jacobian of `fn` at point `x` using forward-mode
- * automatic differentiation (dual numbers).
- *
- * @param fn - Pure function operating on Tensors via add/sub/mul/scale.
- *   Must be traceable: at runtime it receives a DualTensor (structurally
- *   compatible with Tensor) and must return a DualTensor.
- * @param x - Input tensor at which to differentiate.
- * @returns `{ value, jacobian }` where:
- *   - `value` has the output shape of fn applied to x
- *   - `jacobian` has shape `[...value.shape, ...x.shape]` row-major.
- *     `jacobian.data[kY * xSize + kX]` = ∂y[kY] / ∂x[kX].
- *     Verified by Adam+Eve review 2026-05-15 (E13): kY outer, kX inner,
- *     stride xSize between successive y-rows IS row-major [...y.shape, ...x.shape].
- */
-declare function forwardGrad(fn: (x: Tensor) => Tensor, x: Tensor): {
-    value: Tensor;
-    jacobian: Tensor;
-};
-
-/**
- * Tape — records the sequence of ops during a forward pass so we can
- * replay them in reverse to compute the vector-Jacobian product.
- *
- * Each TapedTensor wraps a primal Tensor + a tape-node id. Ops on
- * TapedTensors record their backward closures into a shared Tape.
- * After the forward pass, calling Tape.backward(outputGrad) walks the
- * tape in reverse, accumulating gradients into each input slot.
- *
- * v0.1.0 supports the same ops as DualTensor: add, sub, mul, scale.
- * v0.2.0 adds: contract (named-index), matmul (batched rank-N).
- */
-
-type BackwardFn = (outputGrad: Float64Array) => void;
-declare class Tape {
-    private nodes;
-    private inputGradSlots;
-    private nextOpId;
-    private nextInputId;
-    /** Allocate a fresh id for an input or intermediate. */
-    allocate(size: number): {
-        id: number;
-        gradSlot: Float64Array;
-    };
-    record(inputIds: ReadonlyArray<number>, outputSize: number, backward: BackwardFn): {
-        id: number;
-        gradSlot: Float64Array;
-    };
-    /** Seed the final output's gradient slot, then replay in reverse. */
-    backward(outputId: number, outputGrad: Float64Array): void;
-    getInputGrad(id: number): Float64Array | undefined;
-}
-declare class TapedTensor {
-    readonly shape: ReadonlyArray<number>;
-    readonly primal: Float64Array;
-    readonly tape: Tape;
-    readonly id: number;
-    /**
-     * Optional per-axis Index labels. When set, enables `contract`.
-     * Must have the same length as `shape` when present.
-     */
-    readonly axisLabels?: ReadonlyArray<Index>;
-    constructor(shape: ReadonlyArray<number>, primal: Float64Array, tape: Tape, id: number, axisLabels?: ReadonlyArray<Index>);
-    /**
-     * S5 fix: existing engine ops (e.g. lower, pderiv, contract) reach into
-     * `.data`. The getter returns the primal so those ops still work when a
-     * TapedTensor flows through them as a structurally-compatible Tensor.
-     * (AD-aware ops branch on `'tape' in arg` before reaching here.)
-     */
-    get data(): Float64Array;
-    static fromTensorAsInput(t: Tensor, tape: Tape): TapedTensor;
-    toPrimalTensor(): Tensor;
-    /**
-     * Reconstruct the Tensor primal with the given axisLabels (used internally
-     * when the primal was computed from an op that produces labelled output).
-     */
-    private toPrimalTensorWith;
-    add(other: TapedTensor): TapedTensor;
-    sub(other: TapedTensor): TapedTensor;
-    /**
-     * Elementwise division: this / other.
-     *
-     * Adjoints (quotient rule):
-     *   dA = dY / b
-     *   dB = −dY · a / b²
-     *
-     * The alias case (a.divide(a)) is handled explicitly: the combined gradient
-     * is dA + dB = dY/a − dY·a/a² = dY/a − dY/a = 0. This is correct since
-     * a/a = 1 everywhere and d(1)/da = 0.
-     */
-    divide(other: TapedTensor): TapedTensor;
-    mul(other: TapedTensor): TapedTensor;
-    scale(k: number): TapedTensor;
-    /**
-     * Reverse-mode AD over `Tensor.contract`.
-     *
-     * Both operands must carry `axisLabels`; the resulting TapedTensor inherits
-     * the contracted-output axisLabels (non-shared axis concatenation).
-     *
-     * Adjoint derivation (T-notation):
-     *   Let Y = A.contract(B)  (contraction over shared indices S).
-     *   dA = dY.contract(B')  where B' = B with its free axes re-labelled to
-     *        match the shared positions in A. Equivalently: for each element of A,
-     *        dA[...a_free, ...s] = Σ_{...b_free} dY[...a_free, ...b_free] · B[...s, ...b_free]
-     *   dB = A'.contract(dY)  symmetrically.
-     *
-     * Implementation: because `Tensor.contract` matches by Index identity, we
-     * build the backward contraction by re-labelling the free axes of dY with
-     * the Index objects from the other operand — so `Tensor.contract` automatically
-     * finds the right shared axes.
-     */
-    contract(other: TapedTensor): TapedTensor;
-    /**
-     * Reverse-mode AD over batched matmul.
-     *
-     * Accepts operands of rank ≥ 2. Convention: trailing 2 axes are the matrix
-     * dims (rows × cols); all leading axes are batch dims (must be broadcast-
-     * compatible). For rank-2 inputs this is classical matrix multiplication.
-     *
-     * Adjoint derivation (classical matrix calc, extended to batched):
-     *   Y = A @ B  (A: ...×m×k, B: ...×k×n  →  Y: ...×m×n)
-     *   dA = dY @ Bᵀ       (dA: ...×m×k)
-     *   dB = Aᵀ @ dY       (dB: ...×k×n)
-     *
-     * Implemented via `Tensor.einsum` with a dynamically-built spec:
-     *   forward:  '...ik,...kj->...ij'
-     *   dA:       '...ij,...kj->...ik'   (contract dY with B on j)
-     *   dB:       '...ki,...kj->...ij'   (contract A on k with dY on k)
-     */
-    matmul(other: TapedTensor): TapedTensor;
-    private checkSameShape;
-    /**
-     * Sum elements along the given axis/axes (or all axes if omitted).
-     *
-     * Adjoint: dX[...] = dY[reduced(idx)] broadcast back to input shape.
-     * Each input element receives the output-gradient entry from its reduced
-     * counterpart (the non-reduced coordinates select the dY element; the
-     * reduced coordinates are collapsed to 0 in the keepDims=false case).
-     */
-    sum(axis?: number | ReadonlyArray<number>, opts?: {
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * Arithmetic mean along the given axis/axes (or all axes if omitted).
-     *
-     * Adjoint: dX[...] = dY[reduced(idx)] / N, broadcast back to input shape.
-     * N = product of reduced-axis dimensions.
-     */
-    mean(axis?: number | ReadonlyArray<number>, opts?: {
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * Product of elements along the given axis/axes (or all axes if omitted).
-     *
-     * Adjoint: dX_i = dY * (prod_over_axes(x) / x_i) per element.
-     *
-     * Zero-element corners:
-     * - Exactly one x_i = 0 in the reduced group: d/dx_i = product of all others
-     *   (which is the full product / x_i evaluated via alternate product),
-     *   and d/dx_j = 0 for all j ≠ i where x_j ≠ 0.
-     * - Two or more zeros in the reduced group: gradient is 0 everywhere for that
-     *   group (because changing any single zero cannot change a product that is
-     *   zero due to another zero).
-     *
-     * Implementation: uses prefix/suffix products to handle zeros robustly.
-     */
-    prod(axis?: number | ReadonlyArray<number>, opts?: {
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * Maximum value along the given axis/axes (or all axes if omitted).
-     *
-     * Adjoint: dY is scattered to the argmax position(s).
-     * Tie-breaking: "first-wins" — the gradient flows to the first (smallest
-     * flat-index) element among those that attain the maximum.
-     */
-    max(axis?: number | ReadonlyArray<number>, opts?: {
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * Minimum value along the given axis/axes (or all axes if omitted).
-     *
-     * Adjoint: dY is scattered to the argmin position(s).
-     * Tie-breaking: "first-wins" — gradient flows to the first (smallest
-     * flat-index) element that attains the minimum.
-     */
-    min(axis?: number | ReadonlyArray<number>, opts?: {
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * p-norm of the tensor.
-     *
-     * Supported p values: 1, 2, 'fro', 'inf'. Default p = 2.
-     * When `opts.axis` is given, reduces along that axis; otherwise reduces all axes.
-     *
-     * Adjoints:
-     * - p=2 / p='fro': dX = dY · x / ‖x‖₂  (Frobenius is the 2-norm of the flattened tensor)
-     * - p=1:           dX = dY · sign(x)  (subgradient = 0 at exact zero)
-     * - p='inf':       dX scattered to the element(s) of max absolute value;
-     *                  tie-breaking: first-wins. Sign of the scattered gradient
-     *                  matches sign(x_max).
-     */
-    norm(opts?: {
-        p?: 1 | 2 | 'fro' | 'inf';
-        axis?: number;
-        keepDims?: boolean;
-    }): TapedTensor;
-    /**
-     * Elementwise natural logarithm.
-     *
-     * Adjoint: dX = dY / x
-     */
-    log(): TapedTensor;
-    /**
-     * Elementwise exponential.
-     *
-     * Adjoint: dX = dY · y  where y = exp(x). Primal output is cached.
-     */
-    exp(): TapedTensor;
-    /**
-     * Elementwise sine.
-     *
-     * Adjoint: dX = dY · cos(x)
-     */
-    sin(): TapedTensor;
-    /**
-     * Elementwise cosine.
-     *
-     * Adjoint: dX = −dY · sin(x)
-     */
-    cos(): TapedTensor;
-    /**
-     * Elementwise tangent.
-     *
-     * Adjoint: dX = dY / cos²(x)  (= dY · sec²(x))
-     */
-    tan(): TapedTensor;
-    /**
-     * Elementwise square root.
-     *
-     * Adjoint: dX = dY / (2·y)  where y = sqrt(x). Primal output is cached.
-     */
-    sqrt(): TapedTensor;
-    /**
-     * Elementwise square (x²).
-     *
-     * Adjoint: dX = dY · 2x
-     */
-    square(): TapedTensor;
-    /**
-     * Elementwise power: x^k.
-     *
-     * `k` may be a fixed `number` (constant exponent) or a `TapedTensor`
-     * (variable exponent, both inputs on the tape).
-     *
-     * Adjoints, for y = a^b:
-     *   - fixed exponent k:   dA = dY · k · a^(k−1)
-     *   - variable exponent:  dA = dY · b · a^(b−1),   dB = dY · a^b · ln(a)
-     *   - aliased a^a:         dA = dY · a^a · (ln a + 1)
-     *
-     * The dB term needs ln(a); for a ≤ 0 it is mathematically undefined and
-     * yields NaN/−Inf, honestly signalling non-differentiability w.r.t. the
-     * exponent rather than masking it.
-     */
-    pow(k: number | TapedTensor): TapedTensor;
-    /**
-     * Elementwise reciprocal: 1 / x.
-     *
-     * Adjoint: dX = −dY / x²
-     */
-    reciprocal(): TapedTensor;
-    /**
-     * Elementwise absolute value: |x|.
-     *
-     * Adjoint: dX = dY · sign(x)
-     * Subgradient at exact zero is defined as 0 (rather than undefined).
-     */
-    abs(): TapedTensor;
-    /**
-     * Build a reverse-mode node for an elementwise unary op.
-     * @param primalFn forward value y = f(x)
-     * @param localGrad local derivative dy/dx, given x and the computed y
-     */
-    private _unaryElementwise;
-    /** Hyperbolic sine. Adjoint: dX = dY · cosh(x). */
-    sinh(): TapedTensor;
-    /** Hyperbolic cosine. Adjoint: dX = dY · sinh(x). */
-    cosh(): TapedTensor;
-    /** Hyperbolic tangent. Adjoint: dX = dY · (1 − tanh²(x)) = dY · (1 − y²). */
-    tanh(): TapedTensor;
-    /** Arcsine. Adjoint: dX = dY / √(1 − x²). */
-    asin(): TapedTensor;
-    /** Arccosine. Adjoint: dX = −dY / √(1 − x²). */
-    acos(): TapedTensor;
-    /** Arctangent. Adjoint: dX = dY / (1 + x²). */
-    atan(): TapedTensor;
-    /** Inverse hyperbolic sine. Adjoint: dX = dY / √(x² + 1). */
-    asinh(): TapedTensor;
-    /** Inverse hyperbolic cosine (x ≥ 1). Adjoint: dX = dY / √(x² − 1). */
-    acosh(): TapedTensor;
-    /** Inverse hyperbolic tangent (|x| < 1). Adjoint: dX = dY / (1 − x²). */
-    atanh(): TapedTensor;
-    /** Base-2 logarithm. Adjoint: dX = dY / (x · ln2). */
-    log2(): TapedTensor;
-    /** Base-10 logarithm. Adjoint: dX = dY / (x · ln10). */
-    log10(): TapedTensor;
-    /** log(1 + x) (accurate near 0). Adjoint: dX = dY / (1 + x). */
-    log1p(): TapedTensor;
-    /** exp(x) − 1 (accurate near 0). Adjoint: dX = dY · eˣ = dY · (y + 1). */
-    expm1(): TapedTensor;
-    /** Cube root. Adjoint: dX = dY / (3 · y²) where y = x^(1/3) (→∞ at x = 0). */
-    cbrt(): TapedTensor;
-    /** Sign of x (−1/0/+1). Adjoint: 0 almost everywhere. */
-    sign(): TapedTensor;
-    /**
-     * Two-argument arctangent: atan2(this, other), with this = y, other = x.
-     *
-     * Adjoints (a = this, b = other, d = a² + b²):
-     *   dA = dY · b / d
-     *   dB = −dY · a / d
-     *
-     * The aliased case atan2(a, a) is locally constant (±π/4 or ±3π/4), so its
-     * gradient is 0 — produced naturally by contributing nothing when aliased
-     * (dA + dB = dY · (b − a)/d = 0 at a = b).
-     */
-    atan2(other: TapedTensor): TapedTensor;
-    /**
-     * Reverse-mode AD over `Tensor.tensordot`.
-     *
-     * `axes[i] = [a, b]` contracts axis `a` of `this` with axis `b` of `other`.
-     * The result shape is `this`'s non-contracted axes (in original order)
-     * followed by `other`'s non-contracted axes (in original order).
-     *
-     * Adjoint derivation (NumPy/PyTorch tensordot backward, see Townsend 2016 §6,
-     * and the canonical PyTorch implementation `TensorDotBackward0` in
-     * `torch/csrc/autograd/generated/Functions.cpp`):
-     *
-     *   Z = tensordot(A, B, axes)
-     *   dA = tensordot(dZ, B, [axes_of_dZ_corresponding_to_B's_free, B's_free])
-     *        then permute back into A's original axis order.
-     *   dB = tensordot(A, dZ, [A's_free, axes_of_dZ_corresponding_to_A's_free])
-     *        then permute back into B's original axis order.
-     *
-     * The axis-permutation bookkeeping is the trickiest part: Tensor.tensordot
-     * produces output axes in the order [A's free axes (original A order),
-     * B's free axes (original B order)] — and after the backward contractions
-     * the survivors come out in B's original (resp. A's original) axis order
-     * for the contracted side, which then needs to be permuted into pair order
-     * (so axis k of the contracted block matches the kth pair) and finally
-     * scattered back into A's (resp. B's) full original axis order.
-     *
-     * For the rank-2 × rank-2 single-axis case (i.e. ordinary matmul A·B with
-     * axes = [[1, 0]]), this reduces to dA = dZ · Bᵀ, dB = Aᵀ · dZ — the same
-     * adjoint as `TapedTensor.matmul`.
-     */
-    tensordot(other: TapedTensor, axes: ReadonlyArray<readonly [number, number]>): TapedTensor;
-    /**
-     * Reverse-mode AD over the full SVD of a rank-2 matrix.
-     *
-     * Forward: `A = U · diag(S) · Vt`, where for input shape [m, n], k = min(m, n):
-     *   - U  has shape [m, k]
-     *   - S  has shape [k]
-     *   - Vt has shape [k, n]    (Vt is V^T in the standard A = U Σ V^T convention,
-     *                              i.e. its rows are right-singular-vector components)
-     *
-     * Returned TapedTensors share a single backward closure. When backward()
-     * runs, it pulls dU, dS, dV from each output's gradient slot, assembles
-     * dA, and writes to the input's gradient slot.
-     *
-     * Adjoint (real, distinct nonzero singular values, m = n square case;
-     * extended to rectangular below). Derived directly from the forward
-     * Jacobian; equivalent to PyTorch's `svd_backward`
-     * (`aten/src/ATen/native/BatchLinearAlgebra.cpp`) and Townsend (2016)
-     * "Differentiating the Singular Value Decomposition" §3:
-     *
-     *   Let α = skew(U^T · dU),  β = skew(V^T · dV)        (k×k, antisymmetric)
-     *   Build C (k×k):
-     *     C[i,i] = dS[i]
-     *     C[i,j] = (α[i,j] + β[i,j]) / (s_j − s_i)
-     *            + (α[i,j] − β[i,j]) / (s_j + s_i)         for i ≠ j
-     *   dA_in = U · C · V^T                                 (m×n in-subspace part)
-     *
-     * Rectangular correction (when m > k, i.e. m > n):
-     *   dA += (I − U U^T) · dU · diag(1/s) · V^T
-     * Rectangular correction (when n > k, i.e. n > m):
-     *   dA += U · diag(1/s) · dV^T · (I − V V^T)
-     *
-     * Regularisation at repeated/near-zero singular values (PyTorch-equivalent
-     * subgradient choice): the (i,j) entry of C is masked to 0 whenever
-     * `|s_j − s_i| < REL_TOL · max(|s|)` (the "difference" denominator) or
-     * `|s_j + s_i| < REL_TOL · max(|s|)` (the "sum" denominator, only relevant
-     * when both are ~0). REL_TOL = 1e-10. This makes the gradient a subgradient
-     * at exact degeneracy — finite, but not the unique true derivative (which
-     * does not exist at degeneracies). The rectangular correction also masks
-     * 1/s_i when |s_i| < REL_TOL · max(|s|).
-     *
-     * Throws if input is not rank-2. For rank > 2 inputs the user should
-     * reshape first.
-     */
-    svd(): {
-        U: TapedTensor;
-        S: TapedTensor;
-        V: TapedTensor;
-    };
-    /**
-     * Reverse-mode AD over the eigendecomposition of a rank-2 matrix.
-     *
-     * Symmetric path (`symmetric: true`):
-     *   Forward: `A = U · diag(Λ) · U^T` for symmetric A (n×n).
-     *   Adjoint (Magnus & Neudecker 1999 §10.6.6; PyTorch `linalg_eigh_backward`):
-     *     F[i,j] = 1 / (λ_j − λ_i)   for i ≠ j, 0 otherwise (with degeneracy mask)
-     *     dA_raw = U · (diag(dΛ) + F ∘ (U^T · dU)) · U^T
-     *     dA     = (dA_raw + dA_raw^T) / 2          (symmetrise)
-     *
-     * Non-symmetric path (`symmetric: false`):
-     *   Forward: `A = V · diag(λ) · V^{-1}` (V columns are right eigenvectors).
-     *   Adjoint (Magnus & Neudecker 1999 §10.6 / Giles 2008 §3.2 / Townsend 2016 §4;
-     *   cross-check: PyTorch `linalg_eig_backward`):
-     *     E[i,j] = 1 / (λ_j − λ_i)  for i ≠ j, 0 otherwise (with degeneracy mask)
-     *     dA = V^{-T} · ( E ∘ (V^T · dV) + diag(dλ) ) · V^T
-     *
-     *   Restrictions (all enforced — throw a clear error otherwise):
-     *   1. Eigenvalues must be real. The underlying matrix-eig primitive returns
-     *      placeholder eigenvectors (not actual complex vectors) when complex
-     *      eigenvalues arise, so the adjoint formula cannot be evaluated. Real-
-     *      Schur differentiation would require complex arithmetic infrastructure
-     *      throughout the Tape/TapedTensor stack, which is out of scope.
-     *   2. A must be diagonalisable (non-defective). The adjoint assumes V is
-     *      invertible; defective inputs have algebraic > geometric multiplicity
-     *      so V is rank-deficient. Detected by cond_∞(V) > 1e14.
-     *
-     * Regularisation at repeated eigenvalues (subgradient choice): mask
-     * F/E[i,j] = 0 when `|λ_i − λ_j| < REL_TOL · max(|λ|)`. REL_TOL = 1e-10.
-     *
-     * Throws if input is not rank-2 or square, if `symmetric` is missing, or
-     * (non-symmetric path) on complex eigenvalues / defective input.
-     */
-    eig(opts: {
-        symmetric: boolean;
-    }): {
-        eigvals: TapedTensor;
-        eigvecs: TapedTensor;
-    };
-    private _eigSymmetric;
-    private _eigGeneral;
-}
-
-/**
- * Reverse-mode AD via tape. Returns the value and the vector-Jacobian product
- * (gradient = ∂(cotangent · value) / ∂x). gradient.shape = x.shape.
- *
- * Default cotangent: ones-like(value) — required for scalar outputs, useful
- * for VJP defaults. For non-scalar value, cotangent's shape must match value.shape.
- */
-
-declare function reverseGrad(fn: (x: Tensor) => Tensor, x: Tensor, cotangent?: Tensor): {
-    value: Tensor;
-    gradient: Tensor;
-};
-
-/**
- * GC15 — ergonomic, number-friendly autodiff bridge.
- *
- * The low-level building blocks (`Tape`, `TapedTensor`, `reverseGrad`) require
- * manual tape management and `Tensor` marshalling. This is the JAX-style
- * convenience layer: write a function of a single `TapedTensor` (the AD-aware
- * surface — `.sin()`, `.mul()`, `.sum()`, `.matmul()`, … all record adjoints)
- * and differentiate it against plain JS numbers / arrays.
- *
- *   grad((x) => x.sin())(1)              // [cos(1)]
- *   valueAndGrad((x) => x.pow(2).sum())([1, 2, 3])  // { value: 14, grad: [2,4,6] }
- *   derivative((x) => x.sin().mul(x), 2) // sin(2) + 2cos(2)
- *
- * `f` must use TapedTensor operations (not the plain `functions/` ops, which are
- * not AD-aware). Differentiating arbitrary `functions/` ops would require
- * overloading them onto dual numbers / the tape — a separate, larger effort.
- */
-
-type ScalarFn = (x: TapedTensor) => TapedTensor;
-type NumericInput = number | readonly number[] | Float64Array;
-/**
- * Forward value and reverse-mode gradient of a scalar-valued function.
- *
- * @param fn  maps a TapedTensor (shape `[n]`) to a scalar TapedTensor (length 1).
- * @param x   the point — a number, number[], or Float64Array.
- * @returns   `{ value, grad }` where `grad` has the same length as `x`.
- * @throws    if `fn` does not return a length-1 (scalar) result.
- */
-declare function valueAndGrad(fn: ScalarFn, x: NumericInput): {
-    value: number;
-    grad: Float64Array;
-};
-/**
- * Gradient function of a scalar-valued function: `grad(f)(x)` returns ∇f(x).
- */
-declare function grad(fn: ScalarFn): (x: NumericInput) => Float64Array;
-/**
- * Scalar convenience: derivative of `f: ℝ → ℝ` at `x0`.
- */
-declare function derivative(fn: ScalarFn, x0: number): number;
-/**
- * Jacobian of a vector-valued function `f: ℝⁿ → ℝᵐ`, one reverse pass per output
- * row. Returns an `m × n` array. (For tall outputs forward-mode is cheaper; this
- * favours wide-input / few-output cases, the common ML gradient shape.)
- */
-declare function jacobian(fn: ScalarFn, x: NumericInput): number[][];
-
-export { DualTensor, type NumericInput, type ScalarFn, Tape, TapedTensor, derivative, forwardGrad, grad, jacobian, reverseGrad, valueAndGrad };
+export { DualTensor } from './dual-tensor.js';
+export { forwardGrad } from './forward-grad.js';
+export { Tape, TapedTensor } from './tape.js';
+export { reverseGrad } from './reverse-grad.js';
+export { grad, valueAndGrad, derivative, jacobian } from './grad.js';
+export type { ScalarFn, NumericInput } from './grad.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}