@danielsimonjr/mathts-autograd 0.1.3 → 0.2.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;
 }
 
@@ -350,6 +412,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`.
      *

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}]`);
@@ -1037,6 +1203,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.
   // ---------------------------------------------------------------------------
   /**

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.2.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.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"
+  ]
+}