@danielsimonjr/mathts-autograd 0.1.3 → 0.3.0

package/dist/index.d.ts

@@ -51,6 +51,68 @@ declare class DualTensor {
     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;
+    /** 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;
 }
 
@@ -329,14 +391,21 @@ declare class TapedTensor {
      */
     square(): TapedTensor;
     /**
-     * Elementwise fixed-exponent power: x^k.
+     * Elementwise power: x^k.
      *
-     * Only fixed (non-TapedTensor) exponents are supported. Variable-exponent
-     * pow(taped, taped) is a follow-up slice.
+     * `k` may be a fixed `number` (constant exponent) or a `TapedTensor`
+     * (variable exponent, both inputs on the tape).
      *
-     * Adjoint: dX = dY · k · x^(k−1)
+     * 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;
+    pow(k: number | TapedTensor): TapedTensor;
     /**
      * Elementwise reciprocal: 1 / x.
      *
@@ -350,6 +419,54 @@ declare class TapedTensor {
      * 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`.
      *
@@ -484,4 +601,51 @@ declare function reverseGrad(fn: (x: Tensor) => Tensor, x: Tensor, cotangent?: T
     gradient: Tensor;
 };
 
-export { DualTensor, Tape, TapedTensor, forwardGrad, reverseGrad };
+/**
+ * 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 };

package/dist/index.js

@@ -98,6 +98,172 @@ var DualTensor = class _DualTensor {
     }
     return new _DualTensor(this.shape, p, t);
   }
+  /**
+   * 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) {
+    this.checkSameShape(other, "divide");
+    const p = new Float64Array(this.primal.length);
+    const t = new Float64Array(this.tangent.length);
+    if (this === other) {
+      for (let i = 0; i < p.length; i++) {
+        p[i] = 1;
+        t[i] = 0;
+      }
+    } else {
+      for (let i = 0; i < p.length; i++) {
+        const a = this.primal[i];
+        const b = other.primal[i];
+        p[i] = a / b;
+        t[i] = (this.tangent[i] * b - a * other.tangent[i]) / (b * b);
+      }
+    }
+    return new _DualTensor(this.shape, p, t);
+  }
+  // ---------------------------------------------------------------------------
+  // Elementwise unary ops (parity with reverse-mode TapedTensor). Each follows
+  // the dual-number rule (a, a') ↦ (f(a), f'(a)·a'), built via the
+  // `_unaryElementwise` helper. `deriv(x, y)` is f'(x) given input x and the
+  // computed output y (so adjoints needing y — exp, tanh, sqrt — stay uniform).
+  // ---------------------------------------------------------------------------
+  _unaryElementwise(primalFn, deriv) {
+    const p = new Float64Array(this.primal.length);
+    const t = new Float64Array(this.tangent.length);
+    for (let i = 0; i < p.length; i++) {
+      const y = primalFn(this.primal[i]);
+      p[i] = y;
+      t[i] = deriv(this.primal[i], y) * this.tangent[i];
+    }
+    return new _DualTensor(this.shape, p, t);
+  }
+  /** Exponential. f'(x) = eˣ = y. */
+  exp() {
+    return this._unaryElementwise(Math.exp, (_x, y) => y);
+  }
+  /** Natural logarithm. f'(x) = 1/x. */
+  log() {
+    return this._unaryElementwise(Math.log, (x) => 1 / x);
+  }
+  /** Sine. f'(x) = cos(x). */
+  sin() {
+    return this._unaryElementwise(Math.sin, (x) => Math.cos(x));
+  }
+  /** Cosine. f'(x) = −sin(x). */
+  cos() {
+    return this._unaryElementwise(Math.cos, (x) => -Math.sin(x));
+  }
+  /** Tangent. f'(x) = 1/cos²(x). */
+  tan() {
+    return this._unaryElementwise(Math.tan, (x) => 1 / (Math.cos(x) * Math.cos(x)));
+  }
+  /** Square root. f'(x) = 1/(2·y) where y = √x. */
+  sqrt() {
+    return this._unaryElementwise(Math.sqrt, (_x, y) => 1 / (2 * y));
+  }
+  /** Square (x²). f'(x) = 2x. */
+  square() {
+    return this._unaryElementwise(
+      (x) => x * x,
+      (x) => 2 * x
+    );
+  }
+  /** Reciprocal (1/x). f'(x) = −1/x². */
+  reciprocal() {
+    return this._unaryElementwise(
+      (x) => 1 / x,
+      (x) => -1 / (x * x)
+    );
+  }
+  /** Absolute value. f'(x) = sign(x) (subgradient 0 at exact zero). */
+  abs() {
+    return this._unaryElementwise(Math.abs, (x) => Math.sign(x));
+  }
+  /** Fixed-exponent power x^k. f'(x) = k·x^(k−1). */
+  pow(k) {
+    return this._unaryElementwise(
+      (x) => Math.pow(x, k),
+      (x) => k * Math.pow(x, k - 1)
+    );
+  }
+  /** Hyperbolic sine. f'(x) = cosh(x). */
+  sinh() {
+    return this._unaryElementwise(Math.sinh, (x) => Math.cosh(x));
+  }
+  /** Hyperbolic cosine. f'(x) = sinh(x). */
+  cosh() {
+    return this._unaryElementwise(Math.cosh, (x) => Math.sinh(x));
+  }
+  /** Hyperbolic tangent. f'(x) = 1 − tanh²(x) = 1 − y². */
+  tanh() {
+    return this._unaryElementwise(Math.tanh, (_x, y) => 1 - y * y);
+  }
+  /** Arcsine. f'(x) = 1/√(1 − x²). */
+  asin() {
+    return this._unaryElementwise(Math.asin, (x) => 1 / Math.sqrt(1 - x * x));
+  }
+  /** Arccosine. f'(x) = −1/√(1 − x²). */
+  acos() {
+    return this._unaryElementwise(Math.acos, (x) => -1 / Math.sqrt(1 - x * x));
+  }
+  /** Arctangent. f'(x) = 1/(1 + x²). */
+  atan() {
+    return this._unaryElementwise(Math.atan, (x) => 1 / (1 + x * x));
+  }
+  /** Inverse hyperbolic sine. f'(x) = 1/√(x² + 1). */
+  asinh() {
+    return this._unaryElementwise(Math.asinh, (x) => 1 / Math.sqrt(x * x + 1));
+  }
+  /** Inverse hyperbolic cosine (x ≥ 1). f'(x) = 1/√(x² − 1). */
+  acosh() {
+    return this._unaryElementwise(Math.acosh, (x) => 1 / Math.sqrt(x * x - 1));
+  }
+  /** Inverse hyperbolic tangent (|x| < 1). f'(x) = 1/(1 − x²). */
+  atanh() {
+    return this._unaryElementwise(Math.atanh, (x) => 1 / (1 - x * x));
+  }
+  /** Base-2 logarithm. f'(x) = 1/(x·ln2). */
+  log2() {
+    return this._unaryElementwise(Math.log2, (x) => 1 / (x * Math.LN2));
+  }
+  /** Base-10 logarithm. f'(x) = 1/(x·ln10). */
+  log10() {
+    return this._unaryElementwise(Math.log10, (x) => 1 / (x * Math.LN10));
+  }
+  /** log(1 + x). f'(x) = 1/(1 + x). */
+  log1p() {
+    return this._unaryElementwise(Math.log1p, (x) => 1 / (1 + x));
+  }
+  /** exp(x) − 1. f'(x) = eˣ = y + 1. */
+  expm1() {
+    return this._unaryElementwise(Math.expm1, (_x, y) => y + 1);
+  }
+  /** Cube root. f'(x) = 1/(3·y²) where y = x^(1/3) (→∞ at x = 0). */
+  cbrt() {
+    return this._unaryElementwise(Math.cbrt, (_x, y) => 1 / (3 * y * y));
+  }
+  /** Sign (−1/0/+1). f'(x) = 0 almost everywhere. */
+  sign() {
+    return this._unaryElementwise(Math.sign, () => 0);
+  }
+  /**
+   * Two-argument arctangent: atan2(this, other), this = y, other = x.
+   * Tangent: (b·a' − a·b') / (a² + b²), with a = this, b = other.
+   */
+  atan2(other) {
+    this.checkSameShape(other, "atan2");
+    const p = new Float64Array(this.primal.length);
+    const t = new Float64Array(this.tangent.length);
+    for (let i = 0; i < p.length; i++) {
+      const a = this.primal[i];
+      const b = other.primal[i];
+      p[i] = Math.atan2(a, b);
+      const d = a * a + b * b;
+      t[i] = (b * this.tangent[i] - a * other.tangent[i]) / d;
+    }
+    return new _DualTensor(this.shape, p, t);
+  }
   checkSameShape(other, op) {
     if (this.shape.length !== other.shape.length || !this.shape.every((v, i) => v === other.shape[i])) {
       throw new Error(`DualTensor.${op}: shape mismatch [${this.shape}] vs [${other.shape}]`);
@@ -492,8 +658,8 @@ var TapedTensor = class _TapedTensor {
     const thisGradSlot = this.tape.getInputGrad(this.id);
     const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
       const outShape = [...outT.shape];
-      const outStrides = _rowMajorStrides(outShape);
-      const inStrides = _rowMajorStrides(inputShape);
+      const outStrides = Tensor3.rowMajorStrides(outShape);
+      const inStrides = Tensor3.rowMajorStrides(inputShape);
       const inCoords = new Array(inputShape.length).fill(0);
       for (let n = 0; n < inputSize; n++) {
         let outFlat = 0;
@@ -536,7 +702,7 @@ var TapedTensor = class _TapedTensor {
     const thisGradSlot = this.tape.getInputGrad(this.id);
     const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
       const outShape = [...outT.shape];
-      const outStrides = _rowMajorStrides(outShape);
+      const outStrides = Tensor3.rowMajorStrides(outShape);
       const inCoords = new Array(inputShape.length).fill(0);
       for (let n = 0; n < inputSize; n++) {
         let outFlat = 0;
@@ -584,8 +750,8 @@ var TapedTensor = class _TapedTensor {
     const thisGradSlot = this.tape.getInputGrad(this.id);
     const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
       const outShape = [...outT.shape];
-      const outStrides = _rowMajorStrides(outShape);
-      const inStrides = _rowMajorStrides(inputShape);
+      const outStrides = Tensor3.rowMajorStrides(outShape);
+      const inStrides = Tensor3.rowMajorStrides(inputShape);
       const groups = /* @__PURE__ */ new Map();
       const inCoords = new Array(inputShape.length).fill(0);
       for (let n = 0; n < primalData.length; n++) {
@@ -649,7 +815,7 @@ var TapedTensor = class _TapedTensor {
     const thisGradSlot = this.tape.getInputGrad(this.id);
     const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
       const outShape = [...outT.shape];
-      const outStrides = _rowMajorStrides(outShape);
+      const outStrides = Tensor3.rowMajorStrides(outShape);
       const argmaxSlot = new Int32Array(outT.data.length).fill(-1);
       const inCoords = new Array(inputShape.length).fill(0);
       for (let n = 0; n < primalData.length; n++) {
@@ -698,7 +864,7 @@ var TapedTensor = class _TapedTensor {
     const thisGradSlot = this.tape.getInputGrad(this.id);
     const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
       const outShape = [...outT.shape];
-      const outStrides = _rowMajorStrides(outShape);
+      const outStrides = Tensor3.rowMajorStrides(outShape);
       const argminSlot = new Int32Array(outT.data.length).fill(-1);
       const inCoords = new Array(inputShape.length).fill(0);
       for (let n = 0; n < primalData.length; n++) {
@@ -756,7 +922,7 @@ var TapedTensor = class _TapedTensor {
       const normData = new Float64Array(outT.data);
       const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
         const outShape = [...outT.shape];
-        const outStrides = _rowMajorStrides(outShape);
+        const outStrides = Tensor3.rowMajorStrides(outShape);
         const inCoords = new Array(inputShape.length).fill(0);
         for (let n = 0; n < primalData.length; n++) {
           let outFlat = 0;
@@ -784,7 +950,7 @@ var TapedTensor = class _TapedTensor {
     if (p === 1) {
       const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
         const outShape = [...outT.shape];
-        const outStrides = _rowMajorStrides(outShape);
+        const outStrides = Tensor3.rowMajorStrides(outShape);
         const inCoords = new Array(inputShape.length).fill(0);
         for (let n = 0; n < primalData.length; n++) {
           let outFlat = 0;
@@ -811,7 +977,7 @@ var TapedTensor = class _TapedTensor {
     {
       const { id } = this.tape.record([this.id], outT.data.length, (outputGrad) => {
         const outShape = [...outT.shape];
-        const outStrides = _rowMajorStrides(outShape);
+        const outStrides = Tensor3.rowMajorStrides(outShape);
         const argmaxAbsSlot = new Int32Array(outT.data.length).fill(-1);
         const inCoords = new Array(inputShape.length).fill(0);
         for (let n = 0; n < primalData.length; n++) {
@@ -979,21 +1145,55 @@ var TapedTensor = class _TapedTensor {
     return new _TapedTensor(this.shape, out, this.tape, id);
   }
   /**
-   * Elementwise fixed-exponent power: x^k.
+   * Elementwise power: x^k.
    *
-   * Only fixed (non-TapedTensor) exponents are supported. Variable-exponent
-   * pow(taped, taped) is a follow-up slice.
+   * `k` may be a fixed `number` (constant exponent) or a `TapedTensor`
+   * (variable exponent, both inputs on the tape).
    *
-   * Adjoint: dX = dY · k · x^(k−1)
+   * 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) {
+    if (typeof k === "number") {
+      const out2 = new Float64Array(this.primal.length);
+      for (let i = 0; i < out2.length; i++) out2[i] = Math.pow(this.primal[i], k);
+      const primalData = new Float64Array(this.primal);
+      const thisGradSlot2 = this.tape.getInputGrad(this.id);
+      const { id: id2 } = this.tape.record([this.id], out2.length, (outputGrad) => {
+        for (let i = 0; i < outputGrad.length; i++) {
+          thisGradSlot2[i] += outputGrad[i] * k * Math.pow(primalData[i], k - 1);
+        }
+      });
+      return new _TapedTensor(this.shape, out2, this.tape, id2);
+    }
+    const other = k;
+    this.checkSameShape(other, "pow");
     const out = new Float64Array(this.primal.length);
-    for (let i = 0; i < out.length; i++) out[i] = Math.pow(this.primal[i], k);
-    const primalData = new Float64Array(this.primal);
+    for (let i = 0; i < out.length; i++) out[i] = Math.pow(this.primal[i], other.primal[i]);
+    const aPrimal = new Float64Array(this.primal);
+    const bPrimal = new Float64Array(other.primal);
+    const yPrimal = new Float64Array(out);
     const thisGradSlot = this.tape.getInputGrad(this.id);
-    const { id } = this.tape.record([this.id], out.length, (outputGrad) => {
+    const otherGradSlot = this.tape.getInputGrad(other.id);
+    const isAliased = this === other;
+    const { id } = this.tape.record([this.id, other.id], out.length, (outputGrad) => {
       for (let i = 0; i < outputGrad.length; i++) {
-        thisGradSlot[i] += outputGrad[i] * k * Math.pow(primalData[i], k - 1);
+        const a = aPrimal[i];
+        const b = bPrimal[i];
+        const y = yPrimal[i];
+        const g = outputGrad[i];
+        if (isAliased) {
+          thisGradSlot[i] += g * y * (Math.log(a) + 1);
+        } else {
+          thisGradSlot[i] += g * b * Math.pow(a, b - 1);
+          otherGradSlot[i] += g * y * Math.log(a);
+        }
       }
     });
     return new _TapedTensor(this.shape, out, this.tape, id);
@@ -1037,6 +1237,121 @@ var TapedTensor = class _TapedTensor {
     return new _TapedTensor(this.shape, out, this.tape, id);
   }
   // ---------------------------------------------------------------------------
+  // Extended elementwise transcendentals (hyperbolic, inverse-trig, log/exp
+  // variants, sign, cbrt, atan2). Each builds a reverse-mode node via the
+  // `_unaryElementwise` helper; `localGrad(x, y)` is dy/dx given input x and
+  // output y. The helper caches both x and y so adjoints that need either
+  // (e.g. tanh needs y, log needs x) are uniform.
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   */
+  _unaryElementwise(primalFn, localGrad) {
+    const xData = new Float64Array(this.primal);
+    const out = new Float64Array(xData.length);
+    for (let i = 0; i < out.length; i++) out[i] = primalFn(xData[i]);
+    const yData = new Float64Array(out);
+    const thisGradSlot = this.tape.getInputGrad(this.id);
+    const { id } = this.tape.record([this.id], out.length, (outputGrad) => {
+      for (let i = 0; i < outputGrad.length; i++) {
+        thisGradSlot[i] += outputGrad[i] * localGrad(xData[i], yData[i]);
+      }
+    });
+    return new _TapedTensor(this.shape, out, this.tape, id);
+  }
+  /** Hyperbolic sine. Adjoint: dX = dY · cosh(x). */
+  sinh() {
+    return this._unaryElementwise(Math.sinh, (x) => Math.cosh(x));
+  }
+  /** Hyperbolic cosine. Adjoint: dX = dY · sinh(x). */
+  cosh() {
+    return this._unaryElementwise(Math.cosh, (x) => Math.sinh(x));
+  }
+  /** Hyperbolic tangent. Adjoint: dX = dY · (1 − tanh²(x)) = dY · (1 − y²). */
+  tanh() {
+    return this._unaryElementwise(Math.tanh, (_x, y) => 1 - y * y);
+  }
+  /** Arcsine. Adjoint: dX = dY / √(1 − x²). */
+  asin() {
+    return this._unaryElementwise(Math.asin, (x) => 1 / Math.sqrt(1 - x * x));
+  }
+  /** Arccosine. Adjoint: dX = −dY / √(1 − x²). */
+  acos() {
+    return this._unaryElementwise(Math.acos, (x) => -1 / Math.sqrt(1 - x * x));
+  }
+  /** Arctangent. Adjoint: dX = dY / (1 + x²). */
+  atan() {
+    return this._unaryElementwise(Math.atan, (x) => 1 / (1 + x * x));
+  }
+  /** Inverse hyperbolic sine. Adjoint: dX = dY / √(x² + 1). */
+  asinh() {
+    return this._unaryElementwise(Math.asinh, (x) => 1 / Math.sqrt(x * x + 1));
+  }
+  /** Inverse hyperbolic cosine (x ≥ 1). Adjoint: dX = dY / √(x² − 1). */
+  acosh() {
+    return this._unaryElementwise(Math.acosh, (x) => 1 / Math.sqrt(x * x - 1));
+  }
+  /** Inverse hyperbolic tangent (|x| < 1). Adjoint: dX = dY / (1 − x²). */
+  atanh() {
+    return this._unaryElementwise(Math.atanh, (x) => 1 / (1 - x * x));
+  }
+  /** Base-2 logarithm. Adjoint: dX = dY / (x · ln2). */
+  log2() {
+    return this._unaryElementwise(Math.log2, (x) => 1 / (x * Math.LN2));
+  }
+  /** Base-10 logarithm. Adjoint: dX = dY / (x · ln10). */
+  log10() {
+    return this._unaryElementwise(Math.log10, (x) => 1 / (x * Math.LN10));
+  }
+  /** log(1 + x) (accurate near 0). Adjoint: dX = dY / (1 + x). */
+  log1p() {
+    return this._unaryElementwise(Math.log1p, (x) => 1 / (1 + x));
+  }
+  /** exp(x) − 1 (accurate near 0). Adjoint: dX = dY · eˣ = dY · (y + 1). */
+  expm1() {
+    return this._unaryElementwise(Math.expm1, (_x, y) => y + 1);
+  }
+  /** Cube root. Adjoint: dX = dY / (3 · y²) where y = x^(1/3) (→∞ at x = 0). */
+  cbrt() {
+    return this._unaryElementwise(Math.cbrt, (_x, y) => 1 / (3 * y * y));
+  }
+  /** Sign of x (−1/0/+1). Adjoint: 0 almost everywhere. */
+  sign() {
+    return this._unaryElementwise(Math.sign, () => 0);
+  }
+  /**
+   * 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) {
+    this.checkSameShape(other, "atan2");
+    const a = new Float64Array(this.primal);
+    const b = new Float64Array(other.primal);
+    const out = new Float64Array(a.length);
+    for (let i = 0; i < out.length; i++) out[i] = Math.atan2(a[i], b[i]);
+    const thisGradSlot = this.tape.getInputGrad(this.id);
+    const otherGradSlot = this.tape.getInputGrad(other.id);
+    const isAliased = this === other;
+    const { id } = this.tape.record([this.id, other.id], out.length, (outputGrad) => {
+      if (isAliased) return;
+      for (let i = 0; i < outputGrad.length; i++) {
+        const d = a[i] * a[i] + b[i] * b[i];
+        thisGradSlot[i] += outputGrad[i] * b[i] / d;
+        otherGradSlot[i] += -outputGrad[i] * a[i] / d;
+      }
+    });
+    return new _TapedTensor(this.shape, out, this.tape, id);
+  }
+  // ---------------------------------------------------------------------------
   // tensordot — generalised dot product over explicit axis pairs.
   // ---------------------------------------------------------------------------
   /**
@@ -1658,15 +1973,6 @@ function _resolveAxes(axis, rank) {
   }
   return [...axis].sort((a, b) => a - b);
 }
-function _rowMajorStrides(shape) {
-  const strides = new Array(shape.length);
-  let acc = 1;
-  for (let k = shape.length - 1; k >= 0; k--) {
-    strides[k] = acc;
-    acc *= shape[k];
-  }
-  return strides;
-}
 function _scatterToOriginalAxes(tensor, targetLabels) {
   const currentLabels = tensor.axisLabels;
   const rank = targetLabels.length;
@@ -1795,10 +2101,58 @@ function reverseGrad(fn, x, cotangent) {
     gradient: new Tensor4(x.shape, new Float64Array(xGradSlot))
   };
 }
+
+// src/grad.ts
+function toFloat64(x) {
+  if (typeof x === "number") return Float64Array.of(x);
+  return x instanceof Float64Array ? new Float64Array(x) : Float64Array.from(x);
+}
+function valueAndGrad(fn, x) {
+  const xs = toFloat64(x);
+  const tape = new Tape();
+  const { id } = tape.allocate(xs.length);
+  const leaf = new TapedTensor([xs.length], xs, tape, id);
+  const out = fn(leaf);
+  if (out.primal.length !== 1) {
+    throw new Error(
+      `valueAndGrad: fn must return a scalar (length 1); got length ${out.primal.length}. Reduce with .sum()/.mean(), or use jacobian() for vector outputs.`
+    );
+  }
+  tape.backward(out.id, Float64Array.of(1));
+  return { value: out.primal[0], grad: new Float64Array(tape.getInputGrad(id)) };
+}
+function grad(fn) {
+  return (x) => valueAndGrad(fn, x).grad;
+}
+function derivative(fn, x0) {
+  return valueAndGrad(fn, x0).grad[0];
+}
+function jacobian(fn, x) {
+  const xs = toFloat64(x);
+  const probeTape = new Tape();
+  const { id: probeId } = probeTape.allocate(xs.length);
+  const probeOut = fn(new TapedTensor([xs.length], new Float64Array(xs), probeTape, probeId));
+  const m = probeOut.primal.length;
+  const rows = [];
+  for (let r = 0; r < m; r++) {
+    const tape = new Tape();
+    const { id } = tape.allocate(xs.length);
+    const out = fn(new TapedTensor([xs.length], new Float64Array(xs), tape, id));
+    const seed = new Float64Array(m);
+    seed[r] = 1;
+    tape.backward(out.id, seed);
+    rows.push(Array.from(tape.getInputGrad(id)));
+  }
+  return rows;
+}
 export {
   DualTensor,
   Tape,
   TapedTensor,
+  derivative,
   forwardGrad,
-  reverseGrad
+  grad,
+  jacobian,
+  reverseGrad,
+  valueAndGrad
 };

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@danielsimonjr/mathts-autograd",
-  "version": "0.1.3",
-  "description": "Forward + reverse-mode automatic differentiation for MathTS rank-N Tensor",
-  "author": "Daniel Simon Jr.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "clean": "rm -rf dist",
-    "build:prod": "tsup src/index.ts --format esm --dts --clean --minify --treeshake"
-  },
-  "dependencies": {
-    "@danielsimonjr/mathts-core": "^0.1.4",
-    "@danielsimonjr/mathts-tensor": "^0.1.3"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/danielsimonjr/mathts",
-    "directory": "autograd"
-  },
-  "keywords": [
-    "math",
-    "autograd",
-    "automatic-differentiation",
-    "tensor",
-    "typescript"
-  ]
-}
+{
+  "name": "@danielsimonjr/mathts-autograd",
+  "version": "0.3.0",
+  "description": "Forward + reverse-mode automatic differentiation for MathTS rank-N Tensor",
+  "author": "Daniel Simon Jr.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "build:prod": "tsup src/index.ts --format esm --dts --clean --minify --treeshake"
+  },
+  "dependencies": {
+    "@danielsimonjr/mathts-core": "^0.1.4",
+    "@danielsimonjr/mathts-tensor": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/mathts",
+    "directory": "autograd"
+  },
+  "keywords": [
+    "math",
+    "autograd",
+    "automatic-differentiation",
+    "tensor",
+    "typescript"
+  ]
+}