scalar-autograd 0.1.7 → 0.1.9

package/dist/Optimizers.d.ts

@@ -2,20 +2,35 @@ import { Value } from "./Value";
 /**
  * Abstract base class for all optimizers.
  * Ensures only requiresGrad parameters are optimized.
+ * @public
  */
 export declare abstract class Optimizer {
+    /**
+     * Array of trainable Value parameters filtered to only those requiring gradients.
+     * @public
+     */
     protected trainables: Value[];
+    /**
+     * Learning rate for parameter updates.
+     * @public
+     */
     learningRate: number;
     /**
      * Constructs an Optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param learningRate Learning rate for updates.
+     * @param trainables - Array of Value parameters to optimize.
+     * @param learningRate - Learning rate for updates.
      */
     constructor(trainables: Value[], learningRate: number);
     /**
      * Performs a parameter update step.
+     * @public
      */
     abstract step(): void;
+    /**
+     * Resets optimizer state for a specific trainable parameter.
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     abstract resetStateFor(trainable: Value): void;
     /**
      * Sets grads of all trainables to zero.
@@ -29,47 +44,75 @@ export declare abstract class Optimizer {
 }
 /**
  * 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).
+ * @public
  */
 export interface OptimizerOptions {
+    /**
+     * Overrides the step size for parameter updates (default varies by optimizer).
+     * @public
+     */
     learningRate?: number;
+    /**
+     * L2 regularization multiplier (default 0). Ignored for plain SGD.
+     * @public
+     */
     weightDecay?: number;
+    /**
+     * Maximum absolute value for gradient updates (default 0: no clipping).
+     * @public
+     */
     gradientClip?: number;
 }
 /**
  * Stochastic Gradient Descent (SGD) optimizer. Accepts weightDecay and gradientClip for API consistency (ignored).
+ * @public
  */
 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).
+     * @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.
+     * @public
      */
     step(): void;
+    /**
+     * Resets optimizer state for a trainable (no-op for SGD).
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable: Value): 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).
+ * @public
  */
 export interface AdamOptions extends OptimizerOptions {
+    /**
+     * Exponential decay rate for 1st moment (default 0.9).
+     * @public
+     */
     beta1?: number;
+    /**
+     * Exponential decay rate for 2nd moment (default 0.999).
+     * @public
+     */
     beta2?: number;
+    /**
+     * Numerical stability fudge factor (default 1e-8).
+     * @public
+     */
     epsilon?: number;
 }
 /**
  * Adam optimizer, supports decoupled weight decay and gradient clipping.
+ * @public
  */
 export declare class Adam extends Optimizer {
     private beta1;
@@ -82,18 +125,25 @@ export declare class Adam extends Optimizer {
     private stepCount;
     /**
      * Constructs an Adam optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     * @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.
+     * @public
      */
     step(): void;
+    /**
+     * Resets optimizer state (momentum and velocity) for a specific trainable.
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable: Value): void;
 }
 /**
  * AdamW optimizer, supports decoupled weight decay and gradient clipping (same options as Adam).
+ * @public
  */
 export declare class AdamW extends Optimizer {
     private beta1;
@@ -106,13 +156,19 @@ export declare class AdamW extends Optimizer {
     private stepCount;
     /**
      * Constructs an AdamW optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     * @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).
+     * @public
      */
     step(): void;
+    /**
+     * Resets optimizer state (momentum and velocity) for a specific trainable.
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable: Value): void;
 }

package/dist/Optimizers.js

@@ -1,18 +1,24 @@
-"use strict";
 // Optimizers.ts
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdamW = exports.Adam = exports.SGD = exports.Optimizer = void 0;
 /**
  * Abstract base class for all optimizers.
  * Ensures only requiresGrad parameters are optimized.
+ * @public
  */
-class Optimizer {
+export class Optimizer {
+    /**
+     * Array of trainable Value parameters filtered to only those requiring gradients.
+     * @public
+     */
     trainables;
+    /**
+     * Learning rate for parameter updates.
+     * @public
+     */
     learningRate;
     /**
      * Constructs an Optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param learningRate Learning rate for updates.
+     * @param trainables - Array of Value parameters to optimize.
+     * @param learningRate - Learning rate for updates.
      */
     constructor(trainables, learningRate) {
         this.trainables = trainables.filter(v => v.requiresGrad);
@@ -38,17 +44,17 @@ class Optimizer {
         }
     }
 }
-exports.Optimizer = Optimizer;
 /**
  * Stochastic Gradient Descent (SGD) optimizer. Accepts weightDecay and gradientClip for API consistency (ignored).
+ * @public
  */
-class SGD extends Optimizer {
+export class SGD extends Optimizer {
     weightDecay;
     gradientClip;
     /**
      * Constructs an SGD optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param opts Optional parameters (learningRate, weightDecay, gradientClip).
+     * @param trainables - Array of Value parameters to optimize.
+     * @param opts - Optional parameters (learningRate, weightDecay, gradientClip).
      */
     constructor(trainables, opts = {}) {
         super(trainables, opts.learningRate ?? 1e-2);
@@ -57,6 +63,7 @@ class SGD extends Optimizer {
     }
     /**
      * Performs a parameter update using standard SGD.
+     * @public
      */
     step() {
         // Intentionally ignoring weightDecay/gradientClip for SGD
@@ -64,14 +71,19 @@ class SGD extends Optimizer {
             v.data -= this.learningRate * v.grad;
         }
     }
+    /**
+     * Resets optimizer state for a trainable (no-op for SGD).
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable) {
     }
 }
-exports.SGD = SGD;
 /**
  * Adam optimizer, supports decoupled weight decay and gradient clipping.
+ * @public
  */
-class Adam extends Optimizer {
+export class Adam extends Optimizer {
     beta1;
     beta2;
     epsilon;
@@ -82,8 +94,8 @@ class Adam extends Optimizer {
     stepCount = 0;
     /**
      * Constructs an Adam optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     * @param trainables - Array of Value parameters to optimize.
+     * @param opts - Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
      */
     constructor(trainables, opts = {}) {
         super(trainables, opts.learningRate ?? 0.001);
@@ -99,6 +111,7 @@ class Adam extends Optimizer {
     }
     /**
      * Performs a parameter update using Adam optimization.
+     * @public
      */
     step() {
         this.stepCount++;
@@ -121,16 +134,21 @@ class Adam extends Optimizer {
             this.v.set(v, vVal);
         }
     }
+    /**
+     * Resets optimizer state (momentum and velocity) for a specific trainable.
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable) {
         this.m.set(trainable, 0);
         this.v.set(trainable, 0);
     }
 }
-exports.Adam = Adam;
 /**
  * AdamW optimizer, supports decoupled weight decay and gradient clipping (same options as Adam).
+ * @public
  */
-class AdamW extends Optimizer {
+export class AdamW extends Optimizer {
     beta1;
     beta2;
     epsilon;
@@ -141,8 +159,8 @@ class AdamW extends Optimizer {
     stepCount = 0;
     /**
      * Constructs an AdamW optimizer.
-     * @param trainables Array of Value parameters to optimize.
-     * @param opts Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
+     * @param trainables - Array of Value parameters to optimize.
+     * @param opts - Optional parameters (learningRate, weightDecay, gradientClip, beta1, beta2, epsilon).
      */
     constructor(trainables, opts = {}) {
         super(trainables, opts.learningRate ?? 0.001);
@@ -158,6 +176,7 @@ class AdamW extends Optimizer {
     }
     /**
      * Performs a parameter update using AdamW optimization (decoupled weight decay).
+     * @public
      */
     step() {
         this.stepCount++;
@@ -179,9 +198,13 @@ class AdamW extends Optimizer {
             this.v.set(v, vVal);
         }
     }
+    /**
+     * Resets optimizer state (momentum and velocity) for a specific trainable.
+     * @param trainable - The Value parameter to reset state for.
+     * @public
+     */
     resetStateFor(trainable) {
         this.m.set(trainable, 0);
         this.v.set(trainable, 0);
     }
 }
-exports.AdamW = AdamW;

package/dist/Value.d.ts

@@ -1,16 +1,83 @@
+/**
+ * Function type for backward pass computations in automatic differentiation.
+ * @public
+ */
 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 type { NonlinearLeastSquaresOptions, NonlinearLeastSquaresResult } from './NonlinearLeastSquares';
+export { Vec2 } from './Vec2';
+export { Vec3 } from './Vec3';
+/**
+ * Represents a scalar value in the computational graph for automatic differentiation.
+ * Supports forward computation and reverse-mode autodiff (backpropagation).
+ * @public
+ */
 export declare class Value {
+    /**
+     * Global flag to disable gradient tracking. Use Value.withNoGrad() instead of setting directly.
+     * @public
+     */
     static no_grad_mode: boolean;
+    /**
+     * Current graph builder for incremental hash tracking (null when not building).
+     * @internal
+     */
+    static currentBuilder: any;
+    /**
+     * Global counter for unique Value IDs.
+     * @internal
+     */
+    private static nextId;
+    /**
+     * Unique ID for this Value instance (for hashing intermediate nodes).
+     * @internal
+     */
+    _id: number;
+    /**
+     * The numeric value stored in this node.
+     * @public
+     */
     data: number;
+    /**
+     * The gradient of the output with respect to this value.
+     * @public
+     */
     grad: number;
+    /**
+     * Whether this value participates in gradient computation.
+     * @public
+     */
     requiresGrad: boolean;
     private backwardFn;
-    private prev;
+    /** @internal */ prev: Value[];
+    /**
+     * Optional label for debugging and visualization.
+     * @public
+     */
     label: string;
+    /**
+     * Operation type for JIT compilation (e.g., '+', 'exp', 'sin').
+     * @internal
+     */
+    _op?: string;
+    /**
+     * Parameter name for JIT compilation inputs.
+     * @internal
+     */
+    paramName?: string;
+    /**
+     * Registry ID for kernel reuse system.
+     * @internal
+     */
+    _registryId?: number;
+    /**
+     * Operation constants (e.g., min/max for clamp, exponent for pow).
+     * @internal
+     */
+    _opConstants?: number[];
     constructor(data: number, label?: string, requiresGrad?: boolean);
     private static ensureValue;
     /**
@@ -200,6 +267,11 @@ export declare class Value {
      * @returns New Value which is the negation.
      */
     neg(): Value;
+    /**
+     * Returns sign(this).
+     * @returns New Value with sign.
+     */
+    sign(): Value;
     /**
      * Returns the sum of the given Values.
      * @param vals Array of Value objects
@@ -244,9 +316,17 @@ export declare class Value {
      * @param right Right operand Value or null
      * @param backwardFnBuilder Function to create backward closure
      * @param label Node label for debugging
+     * @param op Operation name for JIT compilation
      * @returns New Value node
      */
-    static make(data: number, left: Value, right: Value | null, backwardFnBuilder: (out: Value) => BackwardFn, label: string): Value;
+    static make(data: number, left: Value, right: Value | null, backwardFnBuilder: (out: Value) => BackwardFn, label: string, op?: string): Value;
+    /**
+     * N-ary operation helper for operations with multiple inputs
+     *
+     * TODO: Move code generation logic into makeNary instead of centralized switches.
+     * This would co-locate runtime and codegen logic at operation definition sites.
+     */
+    static makeNary(data: number, inputs: Value[], backwardFnBuilder: (out: Value) => BackwardFn, label: string, op?: string): Value;
     /**
      * Returns string representation for debugging.
      * @returns String summary of Value
@@ -257,4 +337,6 @@ export declare class Value {
      * Restores the previous state after running fn.
      */
     static withNoGrad<T>(fn: () => T): T;
+    getForwardCode(childCodes: string[]): string;
+    getBackwardCode(gradVar: string, childGrads: string[], childVars: string[]): string;
 }