@danielsimonjr/mathts-autograd 0.3.13 → 0.3.14

package/dist/dual-tensor.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @packageDocumentation
+ */
+import { Tensor } from '@danielsimonjr/mathts-tensor';
+/**
+ * Holds a tensor value and its tangent for forward-mode automatic differentiation.
+ *
+ * The primal and the tangent are flat arrays of equal length, laid out by `shape`.
+ * The `data` getter returns the primal, so tensor ops that read `.data` accept a DualTensor.
+ *
+ * @throws Error from the constructor if the primal length and the tangent length differ.
+ */
+export 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;
+}
+//# sourceMappingURL=dual-tensor.d.ts.map

package/dist/dual-tensor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-tensor.d.ts","sourceRoot":"","sources":["../src/dual-tensor.ts"],"names":[],"mappings":"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"}

package/dist/forward-grad.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ */
+import { Tensor } from '@danielsimonjr/mathts-tensor';
+/**
+ * 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].
+ */
+export declare function forwardGrad(fn: (x: Tensor) => Tensor, x: Tensor): {
+    value: Tensor;
+    jacobian: Tensor;
+};
+//# sourceMappingURL=forward-grad.d.ts.map

package/dist/forward-grad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-grad.d.ts","sourceRoot":"","sources":["../src/forward-grad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAGtD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EACzB,CAAC,EAAE,MAAM,GACR;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgDrC"}

package/dist/grad.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+import { TapedTensor } from './tape.js';
+/**
+ * Function that `valueAndGrad`, `grad`, `derivative` and `jacobian` differentiate.
+ *
+ * The function must build its result from TapedTensor operations only, because only these operations record adjoints.
+ * `valueAndGrad`, `grad` and `derivative` require a result of length 1. `jacobian` accepts a vector result.
+ */
+export type ScalarFn = (x: TapedTensor) => TapedTensor;
+/**
+ * Point at which a function is differentiated: a number, a number array, or a Float64Array.
+ *
+ * The helpers copy the input into a new Float64Array, so they do not change the caller's array.
+ */
+export 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.
+ */
+export declare function valueAndGrad(fn: ScalarFn, x: NumericInput): {
+    value: number;
+    grad: Float64Array;
+};
+/**
+ * Gradient function of a scalar-valued function: `grad(f)(x)` returns ∇f(x).
+ */
+export declare function grad(fn: ScalarFn): (x: NumericInput) => Float64Array;
+/**
+ * Scalar convenience: derivative of `f: ℝ → ℝ` at `x0`.
+ */
+export 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.)
+ */
+export declare function jacobian(fn: ScalarFn, x: NumericInput): number[][];
+//# sourceMappingURL=grad.d.ts.map

package/dist/grad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grad.d.ts","sourceRoot":"","sources":["../src/grad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAQ,WAAW,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC;AACvD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAOrE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAcjG;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,QAAQ,GAAG,CAAC,CAAC,EAAE,YAAY,KAAK,YAAY,CAEpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAmBlE"}