scalar-autograd 0.1.7 → 0.1.9

package/dist/ValueArithmetic.js

@@ -1,66 +1,57 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValueArithmetic = void 0;
-const Value_1 = require("./Value");
-class ValueArithmetic {
+import { Value } from './Value';
+export class ValueArithmetic {
     static add(a, b) {
-        return Value_1.Value.make(a.data + b.data, a, b, (out) => () => {
+        return Value.make(a.data + b.data, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += 1 * out.grad;
             if (b.requiresGrad)
                 b.grad += 1 * out.grad;
-        }, `(${a.label}+${b.label})`);
+        }, `(${a.label}+${b.label})`, '+');
     }
     static sqrt(a) {
         if (a.data < 0) {
             throw new Error(`Cannot take sqrt of negative number: ${a.data}`);
         }
         const root = Math.sqrt(a.data);
-        return Value_1.Value.make(root, a, null, (out) => () => {
+        return Value.make(root, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad += 0.5 / root * out.grad;
-        }, `sqrt(${a.label})`);
+        }, `sqrt(${a.label})`, 'sqrt');
     }
     static mul(a, b) {
-        return Value_1.Value.make(a.data * b.data, a, b, (out) => () => {
+        return Value.make(a.data * b.data, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += b.data * out.grad;
             if (b.requiresGrad)
                 b.grad += a.data * out.grad;
-        }, `(${a.label}*${b.label})`);
+        }, `(${a.label}*${b.label})`, '*');
     }
     static sub(a, b) {
-        return Value_1.Value.make(a.data - b.data, a, b, (out) => () => {
+        return Value.make(a.data - b.data, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += 1 * out.grad;
             if (b.requiresGrad)
                 b.grad -= 1 * out.grad;
-        }, `(${a.label}-${b.label})`);
+        }, `(${a.label}-${b.label})`, '-');
     }
     static div(a, b, eps = 1e-12) {
         if (Math.abs(b.data) < eps) {
             throw new Error(`Division by zero or near-zero encountered in div: denominator=${b.data}`);
         }
         const safe = b.data;
-        return Value_1.Value.make(a.data / safe, a, b, (out) => () => {
+        return Value.make(a.data / safe, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += (1 / safe) * out.grad;
             if (b.requiresGrad)
                 b.grad -= (a.data / (safe ** 2)) * out.grad;
-        }, `(${a.label}/${b.label})`);
+        }, `(${a.label}/${b.label})`, '/');
     }
     static pow(a, exp) {
         if (typeof exp !== "number" || Number.isNaN(exp) || !Number.isFinite(exp)) {
             throw new Error(`Exponent must be a finite number, got ${exp}`);
         }
-        if (a.data < 0 && Math.abs(exp % 1) > 1e-12) {
-            throw new Error(`Cannot raise negative base (${a.data}) to non-integer exponent (${exp})`);
-        }
-        const safeBase = a.data;
-        return Value_1.Value.make(Math.pow(safeBase, exp), a, null, (out) => () => {
-            if (a.requiresGrad)
-                a.grad += exp * Math.pow(safeBase, exp - 1) * out.grad;
-        }, `(${a.label}^${exp})`);
+        const expValue = new Value(exp, String(exp), false);
+        return ValueArithmetic.powValue(a, expValue);
     }
     static powValue(a, b, eps = 1e-12) {
         if (a.data < 0 && Math.abs(b.data % 1) > eps) {
@@ -70,33 +61,33 @@ class ValueArithmetic {
             throw new Error(`0 cannot be raised to zero or negative power: ${b.data}`);
         }
         const safeBase = a.data;
-        return Value_1.Value.make(Math.pow(safeBase, b.data), a, b, (out) => () => {
+        return Value.make(Math.pow(safeBase, b.data), a, b, (out) => () => {
             a.grad += b.data * Math.pow(safeBase, b.data - 1) * out.grad;
             b.grad += Math.log(Math.max(eps, safeBase)) * Math.pow(safeBase, b.data) * out.grad;
-        }, `(${a.label}^${b.label})`);
+        }, `(${a.label}^${b.label})`, 'powValue');
     }
     static mod(a, b) {
         if (typeof b.data !== 'number' || b.data === 0) {
             throw new Error(`Modulo by zero encountered`);
         }
-        return Value_1.Value.make(a.data % b.data, a, b, (out) => () => {
+        return Value.make(a.data % b.data, a, b, (out) => () => {
             a.grad += 1 * out.grad;
             // No grad to b (modulus not used in most diff cases)
-        }, `(${a.label}%${b.label})`);
+        }, `(${a.label}%${b.label})`, 'mod');
     }
     static abs(a) {
         const d = Math.abs(a.data);
-        return Value_1.Value.make(d, a, null, (out) => () => {
+        return Value.make(d, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad += (a.data >= 0 ? 1 : -1) * out.grad;
-        }, `abs(${a.label})`);
+        }, `abs(${a.label})`, 'abs');
     }
     static exp(a) {
         const e = Math.exp(a.data);
-        return Value_1.Value.make(e, a, null, (out) => () => {
+        return Value.make(e, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad += e * out.grad;
-        }, `exp(${a.label})`);
+        }, `exp(${a.label})`, 'exp');
     }
     static log(a, eps = 1e-12) {
         if (a.data <= 0) {
@@ -104,40 +95,40 @@ class ValueArithmetic {
         }
         const safe = Math.max(a.data, eps);
         const l = Math.log(safe);
-        return Value_1.Value.make(l, a, null, (out) => () => {
+        return Value.make(l, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad += (1 / safe) * out.grad;
-        }, `log(${a.label})`);
+        }, `log(${a.label})`, 'log');
     }
     static min(a, b) {
         const d = Math.min(a.data, b.data);
-        return Value_1.Value.make(d, a, b, (out) => () => {
+        return Value.make(d, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += (a.data < b.data ? 1 : 0) * out.grad;
             if (b.requiresGrad)
                 b.grad += (b.data < a.data ? 1 : 0) * out.grad;
-        }, `min(${a.label},${b.label})`);
+        }, `min(${a.label},${b.label})`, 'min');
     }
     static max(a, b) {
         const d = Math.max(a.data, b.data);
-        return Value_1.Value.make(d, a, b, (out) => () => {
+        return Value.make(d, a, b, (out) => () => {
             if (a.requiresGrad)
                 a.grad += (a.data > b.data ? 1 : 0) * out.grad;
             if (b.requiresGrad)
                 b.grad += (b.data > a.data ? 1 : 0) * out.grad;
-        }, `max(${a.label},${b.label})`);
+        }, `max(${a.label},${b.label})`, 'max');
     }
     static floor(a) {
         const fl = Math.floor(a.data);
-        return Value_1.Value.make(fl, a, null, () => () => { }, `floor(${a.label})`);
+        return Value.make(fl, a, null, () => () => { }, `floor(${a.label})`, 'floor');
     }
     static ceil(a) {
         const cl = Math.ceil(a.data);
-        return Value_1.Value.make(cl, a, null, () => () => { }, `ceil(${a.label})`);
+        return Value.make(cl, a, null, () => () => { }, `ceil(${a.label})`, 'ceil');
     }
     static round(a) {
         const rd = Math.round(a.data);
-        return Value_1.Value.make(rd, a, null, () => () => { }, `round(${a.label})`);
+        return Value.make(rd, a, null, () => () => { }, `round(${a.label})`, 'round');
     }
     static square(a) {
         return ValueArithmetic.pow(a, 2);
@@ -149,32 +140,49 @@ class ValueArithmetic {
         if (Math.abs(a.data) < eps) {
             throw new Error(`Reciprocal of zero or near-zero detected`);
         }
-        return Value_1.Value.make(1 / a.data, a, null, (out) => () => {
+        return Value.make(1 / a.data, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad += -1 / (a.data * a.data) * out.grad;
-        }, `reciprocal(${a.label})`);
+        }, `reciprocal(${a.label})`, 'reciprocal');
     }
     static clamp(a, min, max) {
         let val = Math.max(min, Math.min(a.data, max));
-        return Value_1.Value.make(val, a, null, (out) => () => {
+        const out = Value.make(val, a, null, (out) => () => {
             a.grad += (a.data > min && a.data < max ? 1 : 0) * out.grad;
-        }, `clamp(${a.label},${min},${max})`);
+        }, `clamp(${a.label},${min},${max})`, 'clamp');
+        out._opConstants = [min, max];
+        return out;
     }
     static sum(vals) {
         if (!vals.length)
-            return new Value_1.Value(0);
-        return vals.reduce((a, b) => a.add(b));
+            return new Value(0);
+        if (vals.length === 1)
+            return vals[0];
+        // N-ary sum to avoid deep chains
+        const sum = vals.reduce((acc, v) => acc + v.data, 0);
+        return Value.makeNary(sum, vals, (out) => () => {
+            for (const v of vals) {
+                if (v.requiresGrad)
+                    v.grad += out.grad;
+            }
+        }, `sum(${vals.length})`, 'sum');
     }
     static mean(vals) {
         if (!vals.length)
-            return new Value_1.Value(0);
+            return new Value(0);
         return ValueArithmetic.sum(vals).div(vals.length);
     }
     static neg(a) {
-        return Value_1.Value.make(-a.data, a, null, (out) => () => {
+        return Value.make(-a.data, a, null, (out) => () => {
             if (a.requiresGrad)
                 a.grad -= out.grad;
-        }, `(-${a.label})`);
+        }, `(-${a.label})`, 'neg');
+    }
+    static sign(a) {
+        const s = Math.sign(a.data);
+        return Value.make(s, a, null, (out) => () => {
+            if (a.requiresGrad)
+                a.grad += 0 * out.grad;
+        }, `sign(${a.label})`, 'sign');
     }
 }
-exports.ValueArithmetic = ValueArithmetic;

package/dist/ValueComparison.js

@@ -1,15 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValueComparison = void 0;
-const Value_1 = require("./Value");
-class ValueComparison {
+import { Value } from './Value';
+export class ValueComparison {
     static eq(a, b) {
-        return Value_1.Value.make(a.data === b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data === b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}==${b.label})`);
     }
     static ifThenElse(cond, thenVal, elseVal) {
-        return Value_1.Value.make(cond.data ? thenVal.data : elseVal.data, cond, cond.data ? thenVal : elseVal, (out) => () => {
+        return Value.make(cond.data ? thenVal.data : elseVal.data, cond, cond.data ? thenVal : elseVal, (out) => () => {
             if (cond.data) {
                 thenVal.grad += out.grad;
             }
@@ -19,29 +16,28 @@ class ValueComparison {
         }, `if(${cond.label}){${thenVal.label}}else{${elseVal.label}}`);
     }
     static neq(a, b) {
-        return Value_1.Value.make(a.data !== b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data !== b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}!=${b.label})`);
     }
     static gt(a, b) {
-        return Value_1.Value.make(a.data > b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data > b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}>${b.label})`);
     }
     static lt(a, b) {
-        return Value_1.Value.make(a.data < b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data < b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}<${b.label})`);
     }
     static gte(a, b) {
-        return Value_1.Value.make(a.data >= b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data >= b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}>=${b.label})`);
     }
     static lte(a, b) {
-        return Value_1.Value.make(a.data <= b.data ? 1 : 0, a, b, (out) => () => {
+        return Value.make(a.data <= b.data ? 1 : 0, a, b, (out) => () => {
             // No gradient - discrete operation
         }, `(${a.label}<=${b.label})`);
     }
 }
-exports.ValueComparison = ValueComparison;

package/dist/ValueRegistry.d.ts

@@ -0,0 +1,38 @@
+import { Value } from './Value';
+/**
+ * Registry for tracking unique Value objects across residual graphs.
+ * Handles deduplication of constants and optionally variables.
+ * @internal
+ */
+export declare class ValueRegistry {
+    private values;
+    private valueToId;
+    /**
+     * Register a Value and return its unique ID.
+     * Deduplication rules:
+     * - Constants (requiresGrad=false, no prev): dedupe by data value only
+     * - Variables (requiresGrad=true, has paramName): dedupe by paramName
+     * - Weights & computed values: always unique
+     */
+    register(value: Value): number;
+    /**
+     * Get Value by ID
+     */
+    getValue(id: number): Value;
+    /**
+     * Get all registered values as data array
+     */
+    getDataArray(): number[];
+    /**
+     * Update value array from current Value.data
+     */
+    updateDataArray(dataArray: number[]): void;
+    /**
+     * Get ID for a Value (must be registered)
+     */
+    getId(value: Value): number;
+    /**
+     * Total number of unique values
+     */
+    get size(): number;
+}

package/dist/ValueRegistry.js

@@ -0,0 +1,88 @@
+/**
+ * Registry for tracking unique Value objects across residual graphs.
+ * Handles deduplication of constants and optionally variables.
+ * @internal
+ */
+export class ValueRegistry {
+    values = [];
+    valueToId = new Map();
+    /**
+     * Register a Value and return its unique ID.
+     * Deduplication rules:
+     * - Constants (requiresGrad=false, no prev): dedupe by data value only
+     * - Variables (requiresGrad=true, has paramName): dedupe by paramName
+     * - Weights & computed values: always unique
+     */
+    register(value) {
+        // Check if already registered
+        if (this.valueToId.has(value)) {
+            return this.valueToId.get(value);
+        }
+        // Constants: dedupe by value only (ignore labels/paramNames)
+        if (!value.requiresGrad && value.prev.length === 0) {
+            const existing = this.values.find(v => !v.requiresGrad &&
+                v.prev.length === 0 &&
+                v.data === value.data);
+            if (existing) {
+                const existingId = this.valueToId.get(existing);
+                this.valueToId.set(value, existingId);
+                value._registryId = existingId;
+                return existingId;
+            }
+        }
+        // Variables: dedupe by paramName if present
+        if (value.requiresGrad && value.paramName && value.prev.length === 0) {
+            const existing = this.values.find(v => v.requiresGrad &&
+                v.paramName === value.paramName &&
+                v.prev.length === 0);
+            if (existing) {
+                const existingId = this.valueToId.get(existing);
+                this.valueToId.set(value, existingId);
+                value._registryId = existingId;
+                return existingId;
+            }
+        }
+        // Weights & computed values: always unique
+        const id = this.values.length;
+        this.values.push(value);
+        this.valueToId.set(value, id);
+        value._registryId = id;
+        return id;
+    }
+    /**
+     * Get Value by ID
+     */
+    getValue(id) {
+        return this.values[id];
+    }
+    /**
+     * Get all registered values as data array
+     */
+    getDataArray() {
+        return this.values.map(v => v.data);
+    }
+    /**
+     * Update value array from current Value.data
+     */
+    updateDataArray(dataArray) {
+        for (let i = 0; i < this.values.length; i++) {
+            dataArray[i] = this.values[i].data;
+        }
+    }
+    /**
+     * Get ID for a Value (must be registered)
+     */
+    getId(value) {
+        const id = this.valueToId.get(value);
+        if (id === undefined) {
+            throw new Error('Value not registered');
+        }
+        return id;
+    }
+    /**
+     * Total number of unique values
+     */
+    get size() {
+        return this.values.length;
+    }
+}

package/dist/ValueTrig.js

@@ -1,49 +1,45 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValueTrig = void 0;
-const Value_1 = require("./Value");
-class ValueTrig {
+import { Value } from './Value';
+export class ValueTrig {
     static sin(x) {
         const s = Math.sin(x.data);
-        return Value_1.Value.make(s, x, null, (out) => () => {
+        return Value.make(s, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += Math.cos(x.data) * out.grad;
-        }, `sin(${x.label})`);
+        }, `sin(${x.label})`, 'sin');
     }
     static cos(x) {
         const c = Math.cos(x.data);
-        return Value_1.Value.make(c, x, null, (out) => () => {
+        return Value.make(c, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += -Math.sin(x.data) * out.grad;
-        }, `cos(${x.label})`);
+        }, `cos(${x.label})`, 'cos');
     }
     static tan(x) {
         const t = Math.tan(x.data);
-        return Value_1.Value.make(t, x, null, (out) => () => {
+        return Value.make(t, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += (1 / (Math.cos(x.data) ** 2)) * out.grad;
-        }, `tan(${x.label})`);
+        }, `tan(${x.label})`, 'tan');
     }
     static asin(x) {
         const s = Math.asin(x.data);
-        return Value_1.Value.make(s, x, null, (out) => () => {
+        return Value.make(s, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += (1 / Math.sqrt(1 - x.data * x.data)) * out.grad;
-        }, `asin(${x.label})`);
+        }, `asin(${x.label})`, 'asin');
     }
     static acos(x) {
         const c = Math.acos(x.data);
-        return Value_1.Value.make(c, x, null, (out) => () => {
+        return Value.make(c, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += (-1 / Math.sqrt(1 - x.data * x.data)) * out.grad;
-        }, `acos(${x.label})`);
+        }, `acos(${x.label})`, 'acos');
     }
     static atan(x) {
         const a = Math.atan(x.data);
-        return Value_1.Value.make(a, x, null, (out) => () => {
+        return Value.make(a, x, null, (out) => () => {
             if (x.requiresGrad)
                 x.grad += (1 / (1 + x.data * x.data)) * out.grad;
-        }, `atan(${x.label})`);
+        }, `atan(${x.label})`, 'atan');
     }
 }
-exports.ValueTrig = ValueTrig;

package/dist/Vec2.d.ts

@@ -0,0 +1,45 @@
+import { Value } from './Value';
+/**
+ * 2D vector class with differentiable operations.
+ * @public
+ */
+export declare class Vec2 {
+    x: Value;
+    y: Value;
+    constructor(x: Value | number, y: Value | number);
+    static W(x: number, y: number): Vec2;
+    static C(x: number, y: number): Vec2;
+    static zero(): Vec2;
+    static one(): Vec2;
+    get magnitude(): Value;
+    get sqrMagnitude(): Value;
+    get normalized(): Vec2;
+    static dot(a: Vec2, b: Vec2): Value;
+    add(other: Vec2): Vec2;
+    sub(other: Vec2): Vec2;
+    mul(scalar: Value | number): Vec2;
+    div(scalar: Value | number): Vec2;
+    /**
+     * 2D cross product (returns scalar z-component of 3D cross product).
+     * Also known as the "perpendicular dot product" or "wedge product".
+     * Returns positive if b is counter-clockwise from a, negative if clockwise.
+     */
+    static cross(a: Vec2, b: Vec2): Value;
+    /**
+     * Get perpendicular vector (rotated 90° counter-clockwise).
+     * Useful for computing distances to lines.
+     */
+    get perpendicular(): Vec2;
+    /**
+     * Distance from this point to a line defined by two points.
+     * Uses the perpendicular distance formula.
+     */
+    static distanceToLine(point: Vec2, lineStart: Vec2, lineEnd: Vec2): Value;
+    /**
+     * Angle between two vectors in radians.
+     * Returns value in range [0, π].
+     */
+    static angleBetween(a: Vec2, b: Vec2): Value;
+    get trainables(): Value[];
+    toString(): string;
+}

package/dist/Vec2.js

@@ -0,0 +1,93 @@
+import { V } from './V';
+import { Value } from './Value';
+/**
+ * 2D vector class with differentiable operations.
+ * @public
+ */
+export class Vec2 {
+    x;
+    y;
+    constructor(x, y) {
+        this.x = typeof x === 'number' ? new Value(x) : x;
+        this.y = typeof y === 'number' ? new Value(y) : y;
+    }
+    static W(x, y) {
+        return new Vec2(V.W(x), V.W(y));
+    }
+    static C(x, y) {
+        return new Vec2(V.C(x), V.C(y));
+    }
+    static zero() {
+        return new Vec2(V.C(0), V.C(0));
+    }
+    static one() {
+        return new Vec2(V.C(1), V.C(1));
+    }
+    get magnitude() {
+        return V.sqrt(V.add(V.square(this.x), V.square(this.y)));
+    }
+    get sqrMagnitude() {
+        return V.add(V.square(this.x), V.square(this.y));
+    }
+    get normalized() {
+        const mag = this.magnitude;
+        return new Vec2(V.div(this.x, mag), V.div(this.y, mag));
+    }
+    static dot(a, b) {
+        return V.add(V.mul(a.x, b.x), V.mul(a.y, b.y));
+    }
+    add(other) {
+        return new Vec2(V.add(this.x, other.x), V.add(this.y, other.y));
+    }
+    sub(other) {
+        return new Vec2(V.sub(this.x, other.x), V.sub(this.y, other.y));
+    }
+    mul(scalar) {
+        return new Vec2(V.mul(this.x, scalar), V.mul(this.y, scalar));
+    }
+    div(scalar) {
+        return new Vec2(V.div(this.x, scalar), V.div(this.y, scalar));
+    }
+    /**
+     * 2D cross product (returns scalar z-component of 3D cross product).
+     * Also known as the "perpendicular dot product" or "wedge product".
+     * Returns positive if b is counter-clockwise from a, negative if clockwise.
+     */
+    static cross(a, b) {
+        return V.sub(V.mul(a.x, b.y), V.mul(a.y, b.x));
+    }
+    /**
+     * Get perpendicular vector (rotated 90° counter-clockwise).
+     * Useful for computing distances to lines.
+     */
+    get perpendicular() {
+        return new Vec2(V.neg(this.y), this.x);
+    }
+    /**
+     * Distance from this point to a line defined by two points.
+     * Uses the perpendicular distance formula.
+     */
+    static distanceToLine(point, lineStart, lineEnd) {
+        const lineDir = lineEnd.sub(lineStart);
+        const pointDir = point.sub(lineStart);
+        const lineLength = lineDir.magnitude;
+        const cross = Vec2.cross(lineDir, pointDir);
+        return V.div(V.abs(cross), lineLength);
+    }
+    /**
+     * Angle between two vectors in radians.
+     * Returns value in range [0, π].
+     */
+    static angleBetween(a, b) {
+        const dotProd = Vec2.dot(a, b);
+        const magProduct = V.mul(a.magnitude, b.magnitude);
+        const cosAngle = V.div(dotProd, magProduct);
+        return V.acos(cosAngle);
+    }
+    get trainables() {
+        return [this.x, this.y];
+    }
+    toString() {
+        return `Vec2(${this.x.data}, ${this.y.data})`;
+    }
+}