scalar-autograd 0.1.7 → 0.1.9

package/dist/Vec3.d.ts

@@ -0,0 +1,78 @@
+import { Value } from './Value';
+/**
+ * 3D vector class with differentiable operations.
+ * @public
+ */
+export declare class Vec3 {
+    x: Value;
+    y: Value;
+    z: Value;
+    constructor(x: Value | number, y: Value | number, z: Value | number);
+    static W(x: number, y: number, z: number): Vec3;
+    static C(x: number, y: number, z: number): Vec3;
+    static zero(): Vec3;
+    static one(): Vec3;
+    get magnitude(): Value;
+    get sqrMagnitude(): Value;
+    get normalized(): Vec3;
+    /**
+     * Normalized vector with custom analytical gradients.
+     * More efficient than autodiff through magnitude and division.
+     *
+     * Gradient formula: ∂(v/|v|)/∂v = (I - nn^T)/|v| where n = v/|v|
+     */
+    normalizedCustomGrad(): Vec3;
+    static dot(a: Vec3, b: Vec3): Value;
+    static cross(a: Vec3, b: Vec3): Vec3;
+    add(other: Vec3): Vec3;
+    sub(other: Vec3): Vec3;
+    mul(scalar: Value | number): Vec3;
+    div(scalar: Value | number): Vec3;
+    get trainables(): Value[];
+    toString(): string;
+    /**
+     * Compute angle between two vectors in radians.
+     * Returns value in range [0, π].
+     */
+    static angleBetween(a: Vec3, b: Vec3): Value;
+    /**
+     * Project vector a onto vector b.
+     */
+    static project(a: Vec3, b: Vec3): Vec3;
+    /**
+     * Reject vector a from vector b (component of a perpendicular to b).
+     */
+    static reject(a: Vec3, b: Vec3): Vec3;
+    /**
+     * Linear interpolation between two vectors.
+     */
+    static lerp(a: Vec3, b: Vec3, t: Value | number): Vec3;
+    /**
+     * Component-wise minimum.
+     */
+    static min(a: Vec3, b: Vec3): Vec3;
+    /**
+     * Component-wise maximum.
+     */
+    static max(a: Vec3, b: Vec3): Vec3;
+    /**
+     * Clone this vector (create new Vec3 with same values but independent graph).
+     */
+    clone(): Vec3;
+    /**
+     * Create Vec3 from raw data (no gradients).
+     */
+    static fromData(x: number, y: number, z: number): Vec3;
+    /**
+     * Extract raw data as array [x, y, z].
+     */
+    toArray(): number[];
+    /**
+     * Distance between two points.
+     */
+    static distance(a: Vec3, b: Vec3): Value;
+    /**
+     * Squared distance (faster, no sqrt).
+     */
+    static sqrDistance(a: Vec3, b: Vec3): Value;
+}

package/dist/Vec3.js

@@ -0,0 +1,169 @@
+import { V } from './V';
+import { Value } from './Value';
+/**
+ * 3D vector class with differentiable operations.
+ * @public
+ */
+export class Vec3 {
+    x;
+    y;
+    z;
+    constructor(x, y, z) {
+        this.x = typeof x === 'number' ? new Value(x) : x;
+        this.y = typeof y === 'number' ? new Value(y) : y;
+        this.z = typeof z === 'number' ? new Value(z) : z;
+    }
+    static W(x, y, z) {
+        return new Vec3(V.W(x), V.W(y), V.W(z));
+    }
+    static C(x, y, z) {
+        return new Vec3(V.C(x), V.C(y), V.C(z));
+    }
+    static zero() {
+        return new Vec3(V.C(0), V.C(0), V.C(0));
+    }
+    static one() {
+        return new Vec3(V.C(1), V.C(1), V.C(1));
+    }
+    get magnitude() {
+        return V.sqrt(V.add(V.add(V.square(this.x), V.square(this.y)), V.square(this.z)));
+    }
+    get sqrMagnitude() {
+        return V.add(V.add(V.square(this.x), V.square(this.y)), V.square(this.z));
+    }
+    get normalized() {
+        const mag = this.magnitude;
+        return new Vec3(V.div(this.x, mag), V.div(this.y, mag), V.div(this.z, mag));
+    }
+    /**
+     * Normalized vector with custom analytical gradients.
+     * More efficient than autodiff through magnitude and division.
+     *
+     * Gradient formula: ∂(v/|v|)/∂v = (I - nn^T)/|v| where n = v/|v|
+     */
+    normalizedCustomGrad() {
+        // Forward pass: compute normalized vector using .data (no autodiff graph)
+        const mag = Math.sqrt(this.x.data * this.x.data + this.y.data * this.y.data + this.z.data * this.z.data);
+        const nx = this.x.data / mag;
+        const ny = this.y.data / mag;
+        const nz = this.z.data / mag;
+        const invMag = 1.0 / mag;
+        // Create output Values with custom backward pass
+        const outX = Value.makeNary(nx, [this.x, this.y, this.z], (out) => () => {
+            // ∂nx/∂vx = (1 - nx*nx)/|v|, ∂nx/∂vy = -nx*ny/|v|, ∂nx/∂vz = -nx*nz/|v|
+            this.x.grad += out.grad * (1 - nx * nx) * invMag;
+            this.y.grad += out.grad * (-nx * ny) * invMag;
+            this.z.grad += out.grad * (-nx * nz) * invMag;
+        }, 'normalize_x', 'normalize_x');
+        const outY = Value.makeNary(ny, [this.x, this.y, this.z], (out) => () => {
+            // ∂ny/∂vx = -ny*nx/|v|, ∂ny/∂vy = (1 - ny*ny)/|v|, ∂ny/∂vz = -ny*nz/|v|
+            this.x.grad += out.grad * (-ny * nx) * invMag;
+            this.y.grad += out.grad * (1 - ny * ny) * invMag;
+            this.z.grad += out.grad * (-ny * nz) * invMag;
+        }, 'normalize_y', 'normalize_y');
+        const outZ = Value.makeNary(nz, [this.x, this.y, this.z], (out) => () => {
+            // ∂nz/∂vx = -nz*nx/|v|, ∂nz/∂vy = -nz*ny/|v|, ∂nz/∂vz = (1 - nz*nz)/|v|
+            this.x.grad += out.grad * (-nz * nx) * invMag;
+            this.y.grad += out.grad * (-nz * ny) * invMag;
+            this.z.grad += out.grad * (1 - nz * nz) * invMag;
+        }, 'normalize_z', 'normalize_z');
+        return new Vec3(outX, outY, outZ);
+    }
+    static dot(a, b) {
+        return V.add(V.add(V.mul(a.x, b.x), V.mul(a.y, b.y)), V.mul(a.z, b.z));
+    }
+    static cross(a, b) {
+        return new Vec3(V.sub(V.mul(a.y, b.z), V.mul(a.z, b.y)), V.sub(V.mul(a.z, b.x), V.mul(a.x, b.z)), V.sub(V.mul(a.x, b.y), V.mul(a.y, b.x)));
+    }
+    add(other) {
+        return new Vec3(V.add(this.x, other.x), V.add(this.y, other.y), V.add(this.z, other.z));
+    }
+    sub(other) {
+        return new Vec3(V.sub(this.x, other.x), V.sub(this.y, other.y), V.sub(this.z, other.z));
+    }
+    mul(scalar) {
+        return new Vec3(V.mul(this.x, scalar), V.mul(this.y, scalar), V.mul(this.z, scalar));
+    }
+    div(scalar) {
+        return new Vec3(V.div(this.x, scalar), V.div(this.y, scalar), V.div(this.z, scalar));
+    }
+    get trainables() {
+        return [this.x, this.y, this.z];
+    }
+    toString() {
+        return `Vec3(${this.x.data}, ${this.y.data}, ${this.z.data})`;
+    }
+    /**
+     * Compute angle between two vectors in radians.
+     * Returns value in range [0, π].
+     */
+    static angleBetween(a, b) {
+        const dotProd = Vec3.dot(a, b);
+        const magProduct = V.mul(a.magnitude, b.magnitude);
+        const cosAngle = V.div(dotProd, magProduct);
+        return V.acos(V.clamp(cosAngle, -1, 1)); // Clamp for numerical stability
+    }
+    /**
+     * Project vector a onto vector b.
+     */
+    static project(a, b) {
+        const bMagSq = b.sqrMagnitude;
+        const scale = V.div(Vec3.dot(a, b), bMagSq);
+        return b.mul(scale);
+    }
+    /**
+     * Reject vector a from vector b (component of a perpendicular to b).
+     */
+    static reject(a, b) {
+        return a.sub(Vec3.project(a, b));
+    }
+    /**
+     * Linear interpolation between two vectors.
+     */
+    static lerp(a, b, t) {
+        const oneMinusT = V.sub(1, t);
+        return new Vec3(V.add(V.mul(a.x, oneMinusT), V.mul(b.x, t)), V.add(V.mul(a.y, oneMinusT), V.mul(b.y, t)), V.add(V.mul(a.z, oneMinusT), V.mul(b.z, t)));
+    }
+    /**
+     * Component-wise minimum.
+     */
+    static min(a, b) {
+        return new Vec3(V.min(a.x, b.x), V.min(a.y, b.y), V.min(a.z, b.z));
+    }
+    /**
+     * Component-wise maximum.
+     */
+    static max(a, b) {
+        return new Vec3(V.max(a.x, b.x), V.max(a.y, b.y), V.max(a.z, b.z));
+    }
+    /**
+     * Clone this vector (create new Vec3 with same values but independent graph).
+     */
+    clone() {
+        return new Vec3(new Value(this.x.data), new Value(this.y.data), new Value(this.z.data));
+    }
+    /**
+     * Create Vec3 from raw data (no gradients).
+     */
+    static fromData(x, y, z) {
+        return Vec3.C(x, y, z);
+    }
+    /**
+     * Extract raw data as array [x, y, z].
+     */
+    toArray() {
+        return [this.x.data, this.y.data, this.z.data];
+    }
+    /**
+     * Distance between two points.
+     */
+    static distance(a, b) {
+        return a.sub(b).magnitude;
+    }
+    /**
+     * Squared distance (faster, no sqrt).
+     */
+    static sqrDistance(a, b) {
+        return a.sub(b).sqrMagnitude;
+    }
+}

package/dist/Vec4.d.ts

@@ -0,0 +1,45 @@
+import { Value } from 'scalar-autograd';
+/**
+ * 4D vector class with differentiable operations.
+ * Primarily used for quaternions (w, x, y, z) where w is the scalar part.
+ */
+export declare class Vec4 {
+    w: Value;
+    x: Value;
+    y: Value;
+    z: Value;
+    constructor(w: Value | number, x: Value | number, y: Value | number, z: Value | number);
+    static W(w: number, x: number, y: number, z: number): Vec4;
+    static C(w: number, x: number, y: number, z: number): Vec4;
+    static zero(): Vec4;
+    static identity(): Vec4;
+    get magnitude(): Value;
+    get sqrMagnitude(): Value;
+    get normalized(): Vec4;
+    /**
+     * Normalized quaternion with custom analytical gradients.
+     * More efficient than autodiff through magnitude and division.
+     *
+     * Gradient formula: ∂(q/|q|)/∂q = (I - nn^T)/|q| where n = q/|q|
+     */
+    normalizedCustomGrad(): Vec4;
+    static dot(a: Vec4, b: Vec4): Value;
+    add(other: Vec4): Vec4;
+    sub(other: Vec4): Vec4;
+    mul(scalar: Value | number): Vec4;
+    div(scalar: Value | number): Vec4;
+    get trainables(): Value[];
+    toString(): string;
+    /**
+     * Clone this vector (create new Vec4 with same values but independent graph).
+     */
+    clone(): Vec4;
+    /**
+     * Create Vec4 from raw data (no gradients).
+     */
+    static fromData(w: number, x: number, y: number, z: number): Vec4;
+    /**
+     * Extract raw data as array [w, x, y, z].
+     */
+    toArray(): [number, number, number, number];
+}

package/dist/Vec4.js

@@ -0,0 +1,126 @@
+import { V } from 'scalar-autograd';
+import { Value } from 'scalar-autograd';
+/**
+ * 4D vector class with differentiable operations.
+ * Primarily used for quaternions (w, x, y, z) where w is the scalar part.
+ */
+export class Vec4 {
+    w;
+    x;
+    y;
+    z;
+    constructor(w, x, y, z) {
+        this.w = typeof w === 'number' ? new Value(w) : w;
+        this.x = typeof x === 'number' ? new Value(x) : x;
+        this.y = typeof y === 'number' ? new Value(y) : y;
+        this.z = typeof z === 'number' ? new Value(z) : z;
+    }
+    static W(w, x, y, z) {
+        return new Vec4(V.W(w), V.W(x), V.W(y), V.W(z));
+    }
+    static C(w, x, y, z) {
+        return new Vec4(V.C(w), V.C(x), V.C(y), V.C(z));
+    }
+    static zero() {
+        return new Vec4(V.C(0), V.C(0), V.C(0), V.C(0));
+    }
+    static identity() {
+        // Identity quaternion: (1, 0, 0, 0)
+        return new Vec4(V.C(1), V.C(0), V.C(0), V.C(0));
+    }
+    get magnitude() {
+        return V.sqrt(V.add(V.add(V.square(this.w), V.square(this.x)), V.add(V.square(this.y), V.square(this.z))));
+    }
+    get sqrMagnitude() {
+        return V.add(V.add(V.square(this.w), V.square(this.x)), V.add(V.square(this.y), V.square(this.z)));
+    }
+    get normalized() {
+        const mag = this.magnitude;
+        return new Vec4(V.div(this.w, mag), V.div(this.x, mag), V.div(this.y, mag), V.div(this.z, mag));
+    }
+    /**
+     * Normalized quaternion with custom analytical gradients.
+     * More efficient than autodiff through magnitude and division.
+     *
+     * Gradient formula: ∂(q/|q|)/∂q = (I - nn^T)/|q| where n = q/|q|
+     */
+    normalizedCustomGrad() {
+        // Forward pass: compute normalized quaternion using .data (no autodiff graph)
+        const magSq = this.w.data * this.w.data +
+            this.x.data * this.x.data +
+            this.y.data * this.y.data +
+            this.z.data * this.z.data;
+        const mag = Math.sqrt(magSq);
+        const nw = this.w.data / mag;
+        const nx = this.x.data / mag;
+        const ny = this.y.data / mag;
+        const nz = this.z.data / mag;
+        const invMag = 1.0 / mag;
+        // Create output Values with custom backward pass
+        // Gradient: ∂(qi/|q|)/∂qj = δij/|q| - qi*qj/|q|³
+        const outW = Value.makeNary(nw, [this.w, this.x, this.y, this.z], (out) => () => {
+            this.w.grad += out.grad * (1 - nw * nw) * invMag;
+            this.x.grad += out.grad * (-nw * nx) * invMag;
+            this.y.grad += out.grad * (-nw * ny) * invMag;
+            this.z.grad += out.grad * (-nw * nz) * invMag;
+        }, 'normalize_w', 'normalize_w');
+        const outX = Value.makeNary(nx, [this.w, this.x, this.y, this.z], (out) => () => {
+            this.w.grad += out.grad * (-nx * nw) * invMag;
+            this.x.grad += out.grad * (1 - nx * nx) * invMag;
+            this.y.grad += out.grad * (-nx * ny) * invMag;
+            this.z.grad += out.grad * (-nx * nz) * invMag;
+        }, 'normalize_x', 'normalize_x');
+        const outY = Value.makeNary(ny, [this.w, this.x, this.y, this.z], (out) => () => {
+            this.w.grad += out.grad * (-ny * nw) * invMag;
+            this.x.grad += out.grad * (-ny * nx) * invMag;
+            this.y.grad += out.grad * (1 - ny * ny) * invMag;
+            this.z.grad += out.grad * (-ny * nz) * invMag;
+        }, 'normalize_y', 'normalize_y');
+        const outZ = Value.makeNary(nz, [this.w, this.x, this.y, this.z], (out) => () => {
+            this.w.grad += out.grad * (-nz * nw) * invMag;
+            this.x.grad += out.grad * (-nz * nx) * invMag;
+            this.y.grad += out.grad * (-nz * ny) * invMag;
+            this.z.grad += out.grad * (1 - nz * nz) * invMag;
+        }, 'normalize_z', 'normalize_z');
+        return new Vec4(outW, outX, outY, outZ);
+    }
+    static dot(a, b) {
+        return V.add(V.add(V.mul(a.w, b.w), V.mul(a.x, b.x)), V.add(V.mul(a.y, b.y), V.mul(a.z, b.z)));
+    }
+    add(other) {
+        return new Vec4(V.add(this.w, other.w), V.add(this.x, other.x), V.add(this.y, other.y), V.add(this.z, other.z));
+    }
+    sub(other) {
+        return new Vec4(V.sub(this.w, other.w), V.sub(this.x, other.x), V.sub(this.y, other.y), V.sub(this.z, other.z));
+    }
+    mul(scalar) {
+        return new Vec4(V.mul(this.w, scalar), V.mul(this.x, scalar), V.mul(this.y, scalar), V.mul(this.z, scalar));
+    }
+    div(scalar) {
+        return new Vec4(V.div(this.w, scalar), V.div(this.x, scalar), V.div(this.y, scalar), V.div(this.z, scalar));
+    }
+    get trainables() {
+        return [this.w, this.x, this.y, this.z];
+    }
+    toString() {
+        return `Vec4(${this.w.data}, ${this.x.data}, ${this.y.data}, ${this.z.data})`;
+    }
+    /**
+     * Clone this vector (create new Vec4 with same values but independent graph).
+     */
+    clone() {
+        return new Vec4(new Value(this.w.data), new Value(this.x.data), new Value(this.y.data), new Value(this.z.data));
+    }
+    /**
+     * Create Vec4 from raw data (no gradients).
+     */
+    static fromData(w, x, y, z) {
+        return Vec4.C(w, x, y, z);
+    }
+    /**
+     * Extract raw data as array [w, x, y, z].
+     */
+    toArray() {
+        return [this.w.data, this.x.data, this.y.data, this.z.data];
+    }
+}

package/dist/__tests__/duplicate-inputs.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { Value } from '../Value';
+describe('Duplicate Input Gradient Accumulation', () => {
+    it('should correctly compute gradients for different inputs (x * y)', () => {
+        const x = new Value(2, 'x', true);
+        const y = new Value(3, 'y', true);
+        const result = x.mul(y);
+        result.backward();
+        expect(result.data).toBe(6);
+        expect(x.grad).toBe(3);
+        expect(y.grad).toBe(2);
+    });
+    it('should correctly compute gradients when same input is used twice (t * t)', () => {
+        const t = new Value(2, 't', true);
+        const result = t.mul(t);
+        result.backward();
+        expect(result.data).toBe(4);
+        expect(t.grad).toBe(4); // Should be 2*t = 4, not half!
+        const expected = 4.0;
+        const ratio = t.grad / expected;
+        expect(Math.abs(ratio - 1.0)).toBeLessThan(0.01);
+    });
+    it('should correctly compute gradients for log(1 - t^2) - SAC entropy pattern', () => {
+        const t = new Value(0.5, 't', true);
+        const tSquared = t.mul(t);
+        const oneMinusTSquared = new Value(1, '1').sub(tSquared);
+        const result = oneMinusTSquared.log();
+        result.backward();
+        // Analytical derivative of log(1-t^2) is -2t/(1-t^2)
+        const expected = -2 * 0.5 / (1 - 0.25);
+        expect(Math.abs(t.grad - expected)).toBeLessThan(0.0001);
+    });
+});

package/dist/cli/gradient-gen.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for symbolic gradient generation.
+ * Accepts mathematical expressions and outputs gradient computation code.
+ */
+interface CliOptions {
+    input?: string;
+    output?: string;
+    wrt?: string[];
+    format: 'js' | 'ts' | 'function' | 'inline';
+    simplify: boolean;
+    functionName?: string;
+    help: boolean;
+    version: boolean;
+}
+declare function parseArgs(args: string[]): CliOptions;
+declare function extractParameters(input: string): string[];
+declare function main(): void;
+export { main, parseArgs, extractParameters };