scalar-autograd 0.1.4 → 0.1.6

package/dist/Value.d.ts

@@ -0,0 +1,260 @@
+export type BackwardFn = () => void;
+export { V } from './V';
+export { Optimizer, SGD, Adam, AdamW } from './Optimizers';
+export type { OptimizerOptions, AdamOptions } from './Optimizers';
+export { Losses } from './Losses';
+export declare class Value {
+    static no_grad_mode: boolean;
+    data: number;
+    grad: number;
+    requiresGrad: boolean;
+    private backwardFn;
+    private prev;
+    label: string;
+    constructor(data: number, label?: string, requiresGrad?: boolean);
+    private static ensureValue;
+    /**
+     * Returns sin(this).
+     * @returns New Value with sin.
+     */
+    sin(): Value;
+    /**
+     * Returns cos(this).
+     * @returns New Value with cos.
+     */
+    cos(): Value;
+    /**
+     * Returns tan(this).
+     * @returns New Value with tan.
+     */
+    tan(): Value;
+    /**
+     * Returns asin(this).
+     * @returns New Value with asin.
+     */
+    asin(): Value;
+    /**
+     * Returns acos(this).
+     * @returns New Value with acos.
+     */
+    acos(): Value;
+    /**
+     * Returns atan(this).
+     * @returns New Value with atan.
+     */
+    atan(): Value;
+    /**
+     * Returns relu(this).
+     * @returns New Value with relu.
+     */
+    relu(): Value;
+    /**
+     * Returns abs(this).
+     * @returns New Value with abs.
+     */
+    abs(): Value;
+    /**
+     * Returns exp(this).
+     * @returns New Value with exp.
+     */
+    exp(): Value;
+    /**
+     * Returns log(this).
+     * @returns New Value with log.
+     */
+    log(): Value;
+    /**
+     * Returns min(this, other).
+     * @param other Value to compare
+     * @returns New Value with min.
+     */
+    min(other: Value): Value;
+    /**
+     * Returns max(this, other).
+     * @param other Value to compare
+     * @returns New Value with max.
+     */
+    max(other: Value): Value;
+    /**
+     * Adds this and other.
+     * @param other Value or number to add
+     * @returns New Value with sum.
+     */
+    add(other: Value | number): Value;
+    /**
+     * Multiplies this and other.
+     * @param other Value or number to multiply
+     * @returns New Value with product.
+     */
+    mul(other: Value | number): Value;
+    /**
+     * Subtracts other from this.
+     * @param other Value or number to subtract
+     * @returns New Value with difference.
+     */
+    sub(other: Value | number): Value;
+    /**
+     * Divides this by other.
+     * @param other Value or number divisor
+     * @returns New Value with quotient.
+     */
+    div(other: Value | number): Value;
+    /**
+     * Raises this to the power exp.
+     * @param exp Exponent
+     * @returns New Value with pow(this, exp)
+     */
+    pow(exp: number): Value;
+    /**
+     * Raises this to a dynamic Value (other).
+     * @param other Exponent Value or number
+     * @returns New Value with pow(this, other)
+     */
+    powValue(other: Value | number): Value;
+    /**
+     * Returns this modulo other.
+     * @param other Divisor Value
+     * @returns New Value with modulo.
+     */
+    mod(other: Value): Value;
+    /**
+     * Returns Value indicating if this equals other.
+     * @param other Value to compare
+     * @returns New Value (1 if equal, else 0)
+     */
+    eq(other: Value): Value;
+    /**
+     * Returns Value indicating if this not equals other.
+     * @param other Value to compare
+     * @returns New Value (1 if not equal, else 0)
+     */
+    neq(other: Value): Value;
+    /**
+     * Returns Value indicating if this greater than other.
+     * @param other Value to compare
+     * @returns New Value (1 if true, else 0)
+     */
+    gt(other: Value): Value;
+    /**
+     * Returns Value indicating if this less than other.
+     * @param other Value to compare
+     * @returns New Value (1 if true, else 0)
+     */
+    lt(other: Value): Value;
+    /**
+     * Returns Value indicating if this greater than or equal to other.
+     * @param other Value to compare
+     * @returns New Value (1 if true, else 0)
+     */
+    gte(other: Value): Value;
+    /**
+     * Returns Value indicating if this less than or equal to other.
+     * @param other Value to compare
+     * @returns New Value (1 if true, else 0)
+     */
+    lte(other: Value): Value;
+    /**
+     * Returns softplus(this).
+     * @returns New Value with softplus.
+     */
+    softplus(): Value;
+    /**
+     * Returns the floor of this Value.
+     * @returns New Value with floor(data).
+     */
+    floor(): Value;
+    /**
+     * Returns the ceiling of this Value.
+     * @returns New Value with ceil(data).
+     */
+    ceil(): Value;
+    /**
+     * Returns the rounded value of this Value.
+     * @returns New Value with rounded data.
+     */
+    round(): Value;
+    /**
+     * Returns the square of this Value.
+     * @returns New Value with squared data.
+     */
+    square(): Value;
+    /**
+     * Returns the cube of this Value.
+     * @returns New Value with cubed data.
+     */
+    cube(): Value;
+    /**
+     * Returns the reciprocal (1/x) of this Value.
+     * @returns New Value with reciprocal.
+     */
+    reciprocal(): Value;
+    /**
+     * Clamps this between min and max.
+     * @param min Minimum value
+     * @param max Maximum value
+     * @returns New clamped Value
+     */
+    clamp(min: number, max: number): Value;
+    /**
+     * Returns the negation (-this) Value.
+     * @returns New Value which is the negation.
+     */
+    neg(): Value;
+    /**
+     * Returns the sum of the given Values.
+     * @param vals Array of Value objects
+     * @returns New Value holding their sum.
+     */
+    static sum(vals: Value[]): Value;
+    /**
+     * Returns the mean of the given Values.
+     * @param vals Array of Value objects
+     * @returns New Value holding their mean.
+     */
+    static mean(vals: Value[]): Value;
+    /**
+     * Returns tanh(this).
+     * @returns New Value with tanh.
+     */
+    tanh(): Value;
+    /**
+     * Returns sigmoid(this).
+     * @returns New Value with sigmoid.
+     */
+    sigmoid(): Value;
+    /**
+     * Performs a reverse-mode autodiff backward pass from this Value.
+     * @param zeroGrad If true, zeroes all grads in the graph before backward
+     */
+    backward(zeroGrad?: boolean): void;
+    /**
+     * Sets all grad fields in the computation tree (from root) to 0.
+     * @param root Value to zero tree from
+     */
+    static zeroGradTree(root: Value): void;
+    /**
+     * Sets all grad fields in all supplied trees to 0.
+     * @param vals Values whose trees to zero
+     */
+    static zeroGradAll(vals: Value[]): void;
+    /**
+     * Internal helper to construct a Value with correct backward fn and grads.
+     * @param data Output value data
+     * @param left Left operand Value
+     * @param right Right operand Value or null
+     * @param backwardFnBuilder Function to create backward closure
+     * @param label Node label for debugging
+     * @returns New Value node
+     */
+    static make(data: number, left: Value, right: Value | null, backwardFnBuilder: (out: Value) => BackwardFn, label: string): Value;
+    /**
+     * Returns string representation for debugging.
+     * @returns String summary of Value
+     */
+    toString(): string;
+    /**
+     * Temporarily disables gradient tracking within the callback scope, like torch.no_grad().
+     * Restores the previous state after running fn.
+     */
+    static withNoGrad<T>(fn: () => T): T;
+}

package/dist/Value.edge-cases.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Value.edge-cases.spec.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Value_1 = require("./Value");
+// Edge cases and error handling
+describe('Value edge cases and error handling', () => {
+    it('throws on invalid numeric inputs', () => {
+        expect(() => new Value_1.Value(NaN)).toThrow();
+        expect(() => new Value_1.Value(Infinity)).toThrow();
+        expect(() => new Value_1.Value(-Infinity)).toThrow();
+    });
+    it('handles gradient accumulation correctly', () => {
+        const x = new Value_1.Value(2, 'x', true);
+        const y = x.mul(3);
+        const z = x.mul(4);
+        const out = y.add(z);
+        out.backward();
+        expect(x.grad).toBe(7); // 3 + 4
+    });
+    it('handles repeated use of same value in expression', () => {
+        const x = new Value_1.Value(3, 'x', true);
+        const y = x.mul(x).mul(x); // x^3
+        y.backward();
+        expect(x.grad).toBeCloseTo(27); // 3*x^2 = 27
+    });
+    it('throws on division by zero', () => {
+        const a = new Value_1.Value(1);
+        const b = new Value_1.Value(0);
+        expect(() => a.div(b)).toThrow();
+    });
+    it('throws on log of negative number', () => {
+        const x = new Value_1.Value(-1);
+        expect(() => x.log()).toThrow();
+    });
+    it('throws on negative base with fractional exponent', () => {
+        const x = new Value_1.Value(-2);
+        expect(() => x.pow(0.5)).toThrow();
+    });
+});
+// Complex expressions
+describe('Complex mathematical expressions', () => {
+    it('computes gradient of complex expression', () => {
+        const x = new Value_1.Value(0.5, 'x', true);
+        const y = x.sin().mul(x.cos()).add(x.exp());
+        y.backward();
+        const expected = Math.cos(0.5) ** 2 - Math.sin(0.5) ** 2 + Math.exp(0.5);
+        expect(x.grad).toBeCloseTo(expected, 4);
+    });
+    it('handles nested activation functions', () => {
+        const x = new Value_1.Value(0.5, 'x', true);
+        const y = x.tanh().sigmoid().relu();
+        y.backward();
+        expect(x.grad).toBeGreaterThan(0);
+    });
+});

package/dist/Value.grad-flow.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Value.grad-flow.spec.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Value_1 = require("./Value");
+describe('Gradient flow control', () => {
+    it('stops gradient at non-requiresGrad nodes', () => {
+        const x = new Value_1.Value(2, 'x', true);
+        const y = new Value_1.Value(3, 'y', false);
+        const z = new Value_1.Value(4, 'z', true);
+        const out = x.mul(y).add(z);
+        out.backward();
+        expect(x.grad).toBe(3);
+        expect(y.grad).toBe(0);
+        expect(z.grad).toBe(1);
+    });
+    it('handles detached computation graphs', () => {
+        const x = new Value_1.Value(2, 'x', true);
+        const y = x.mul(3);
+        const z = new Value_1.Value(y.data, 'z', true); // detached
+        const out = z.mul(4);
+        out.backward();
+        expect(z.grad).toBe(4);
+        expect(x.grad).toBe(0); // no gradient flows to x
+    });
+});