scalar-autograd 0.1.5 → 0.1.6

package/dist/Losses.d.ts

@@ -0,0 +1,51 @@
+import { Value } from "./Value";
+export declare class Losses {
+    /**
+     * Computes mean squared error (MSE) loss between outputs and targets.
+     * @param outputs Array of Value predictions.
+     * @param targets Array of Value targets.
+     * @returns Mean squared error as a Value.
+     */
+    static mse(outputs: Value[], targets: Value[]): Value;
+    /**
+     * Computes mean absolute error (MAE) loss between outputs and targets.
+     * @param outputs Array of Value predictions.
+     * @param targets Array of Value targets.
+     * @returns Mean absolute error as a Value.
+     */
+    static mae(outputs: Value[], targets: Value[]): Value;
+    static EPS: number;
+    /**
+     * Computes binary cross-entropy loss between predicted outputs and targets (after sigmoid).
+     * @param outputs Array of Value predictions (expected in (0,1)).
+     * @param targets Array of Value targets (typically 0 or 1).
+     * @returns Binary cross-entropy loss as a Value.
+     */
+    static binaryCrossEntropy(outputs: Value[], targets: Value[]): Value;
+    /**
+     * Computes categorical cross-entropy loss between outputs (logits) and integer target classes.
+     * @param outputs Array of Value logits for each class.
+     * @param targets Array of integer class indices (0-based, one per sample).
+     * @returns Categorical cross-entropy loss as a Value.
+     */
+    static categoricalCrossEntropy(outputs: Value[], targets: number[]): Value;
+    /**
+     * Computes Huber loss between outputs and targets.
+     * Combines quadratic loss for small residuals and linear loss for large residuals.
+     * @param outputs Array of Value predictions.
+     * @param targets Array of Value targets.
+     * @param delta Threshold at which to switch from quadratic to linear (default: 1.0).
+     * @returns Huber loss as a Value.
+     */
+    static huber(outputs: Value[], targets: Value[], delta?: number): Value;
+    /**
+     * Computes Tukey loss between outputs and targets.
+     * This robust loss function saturates for large residuals.
+     *
+     * @param outputs Array of Value predictions.
+     * @param targets Array of Value targets.
+     * @param c Threshold constant (typically 4.685).
+     * @returns Tukey loss as a Value.
+     */
+    static tukey(outputs: Value[], targets: Value[], c?: number): Value;
+}

package/dist/Losses.spec.d.ts

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

package/dist/Optimizers.d.ts

@@ -0,0 +1,114 @@
+import { Value } from "./Value";
+/**
+ * Abstract base class for all optimizers.
+ * Ensures only requiresGrad parameters are optimized.
+ */
+export declare abstract class Optimizer {
+    protected trainables: Value[];
+    learningRate: number;
+    /**
+     * Constructs an Optimizer.
+     * @param trainables Array of Value parameters to optimize.
+     * @param learningRate Learning rate for updates.
+     */
+    constructor(trainables: Value[], learningRate: number);
+    /**
+     * Performs a parameter update step.
+     */
+    abstract step(): void;
+    /**
+     * Sets grads of all trainables to zero.
+     */
+    zeroGrad(): void;
+    /**
+     * Clips global norm of gradients as regularization.
+     * @param maxNorm Maximum allowed norm for gradients.
+     */
+    clipGradients(maxNorm: number): void;
+}
+/**
+ * Optional arguments for basic optimizers.
+ * @property learningRate: Overrides the step size for parameter updates (default varies by optimizer).
+ * @property weightDecay: L2 regularization multiplier (default 0). Ignored for plain SGD.
+ * @property gradientClip: Maximum absolute value for gradient updates (default 0: no clipping).
+ */
+export interface OptimizerOptions {
+    learningRate?: number;
+    weightDecay?: number;
+    gradientClip?: number;
+}
+/**
+ * Stochastic Gradient Descent (SGD) optimizer. Accepts weightDecay and gradientClip for API consistency (ignored).
+ */
+export declare class SGD extends Optimizer {
+    private weightDecay;
+    private gradientClip;
+    /**
+     * Constructs an SGD optimizer.
+     * @param trainables Array of Value parameters to optimize.
+     * @param opts Optional parameters (learningRate, weightDecay, gradientClip).
+     */
+    constructor(trainables: Value[], opts?: OptimizerOptions);
+    /**
+     * Performs a parameter update using standard SGD.
+     */
+    step(): void;
+}
+/**
+ * Adam and AdamW optimizer parameters.
+ * Extends OptimizerOptions.
+ * @property beta1: Exponential decay rate for 1st moment (default 0.9).
+ * @property beta2: Exponential decay rate for 2nd moment (default 0.999).
+ * @property epsilon: Numerical stability fudge factor (default 1e-8).
+ */
+export interface AdamOptions extends OptimizerOptions {
+    beta1?: number;
+    beta2?: number;
+    epsilon?: number;
+}
+/**
+ * Adam optimizer, supports decoupled weight decay and gradient clipping.
+ */
+export declare class Adam extends Optimizer {
+    private beta1;
+    private beta2;
+    private epsilon;
+    private weightDecay;
+    private gradientClip;
+    private m;
+    private v;
+    private stepCount;
+    /**
+     * Constructs an Adam optimizer.
+     * @param trainables Array of Value parameters to optimize.
+     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     */
+    constructor(trainables: Value[], opts?: AdamOptions);
+    /**
+     * Performs a parameter update using Adam optimization.
+     */
+    step(): void;
+}
+/**
+ * AdamW optimizer, supports decoupled weight decay and gradient clipping (same options as Adam).
+ */
+export declare class AdamW extends Optimizer {
+    private beta1;
+    private beta2;
+    private epsilon;
+    private weightDecay;
+    private gradientClip;
+    private m;
+    private v;
+    private stepCount;
+    /**
+     * Constructs an AdamW optimizer.
+     * @param trainables Array of Value parameters to optimize.
+     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     */
+    constructor(trainables: Value[], opts?: AdamOptions);
+    /**
+     * Performs a parameter update using AdamW optimization (decoupled weight decay).
+     */
+    step(): void;
+}

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

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

package/dist/Optimizers.spec.d.ts

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

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.grad-flow.spec.d.ts

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

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

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

package/dist/Value.memory.spec.d.ts

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

package/dist/Value.nn.spec.d.ts

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

package/dist/Value.spec.d.ts

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

package/dist/ValueActivation.d.ts

@@ -0,0 +1,7 @@
+import { Value } from './Value';
+export declare class ValueActivation {
+    static relu(x: Value): Value;
+    static softplus(x: Value): Value;
+    static tanh(x: Value): Value;
+    static sigmoid(x: Value): Value;
+}

package/dist/ValueArithmetic.d.ts

@@ -0,0 +1,26 @@
+import { Value } from './Value';
+export declare class ValueArithmetic {
+    static add(a: Value, b: Value): Value;
+    static sqrt(a: Value): Value;
+    static mul(a: Value, b: Value): Value;
+    static sub(a: Value, b: Value): Value;
+    static div(a: Value, b: Value, eps?: number): Value;
+    static pow(a: Value, exp: number): Value;
+    static powValue(a: Value, b: Value, eps?: number): Value;
+    static mod(a: Value, b: Value): Value;
+    static abs(a: Value): Value;
+    static exp(a: Value): Value;
+    static log(a: Value, eps?: number): Value;
+    static min(a: Value, b: Value): Value;
+    static max(a: Value, b: Value): Value;
+    static floor(a: Value): Value;
+    static ceil(a: Value): Value;
+    static round(a: Value): Value;
+    static square(a: Value): Value;
+    static cube(a: Value): Value;
+    static reciprocal(a: Value, eps?: number): Value;
+    static clamp(a: Value, min: number, max: number): Value;
+    static sum(vals: Value[]): Value;
+    static mean(vals: Value[]): Value;
+    static neg(a: Value): Value;
+}

package/dist/ValueComparison.d.ts

@@ -0,0 +1,10 @@
+import { Value } from './Value';
+export declare class ValueComparison {
+    static eq(a: Value, b: Value): Value;
+    static ifThenElse(cond: Value, thenVal: Value, elseVal: Value): Value;
+    static neq(a: Value, b: Value): Value;
+    static gt(a: Value, b: Value): Value;
+    static lt(a: Value, b: Value): Value;
+    static gte(a: Value, b: Value): Value;
+    static lte(a: Value, b: Value): Value;
+}

package/dist/ValueTrig.d.ts

@@ -0,0 +1,9 @@
+import { Value } from './Value';
+export declare class ValueTrig {
+    static sin(x: Value): Value;
+    static cos(x: Value): Value;
+    static tan(x: Value): Value;
+    static asin(x: Value): Value;
+    static acos(x: Value): Value;
+    static atan(x: Value): Value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalar-autograd",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Scalar-based reverse-mode automatic differentiation in TypeScript.",
   "main": "dist/Value.js",
   "types": "dist/Value.d.ts",