scalar-autograd 0.1.7 → 0.1.9

package/README.md

@@ -81,6 +81,126 @@ console.log('Fitted b:', b.data); // ~3
 
 This pattern—forward pass, backward for gradients, and calling `optimizer.step()`—applies to more complex optimization tasks and neural networks as well!
 
+## Example: Nonlinear Least Squares Solver
+
+For problems where you need to minimize the sum of squared residuals, the built-in Levenberg-Marquardt solver is much faster than gradient descent:
+
+```typescript
+import { V } from './V';
+
+// Fit a circle to noisy points
+const params = [V.W(0), V.W(0), V.W(5)]; // cx, cy, radius
+
+// Generate noisy circle data
+const points = Array.from({ length: 50 }, (_, i) => {
+  const angle = (i / 50) * 2 * Math.PI;
+  return {
+    x: 10 * Math.cos(angle) + (Math.random() - 0.5) * 0.5,
+    y: 10 * Math.sin(angle) + (Math.random() - 0.5) * 0.5,
+  };
+});
+
+const result = V.nonlinearLeastSquares(
+  params,
+  ([cx, cy, r]) => {
+    // Compute residual for each point (distance from circle)
+    return points.map(p => {
+      const dx = V.sub(p.x, cx);
+      const dy = V.sub(p.y, cy);
+      const dist = V.sqrt(V.add(V.square(dx), V.square(dy)));
+      return V.sub(dist, r);
+    });
+  },
+  {
+    maxIterations: 100,
+    costTolerance: 1e-6,
+    verbose: true,
+  }
+);
+
+console.log('Circle fitted in', result.iterations, 'iterations');
+console.log('Center:', params[0].data, params[1].data);
+console.log('Radius:', params[2].data);
+```
+
+The Levenberg-Marquardt algorithm typically converges 100-1000x faster than gradient descent for least squares problems.
+
+## Choosing the Right Optimizer
+
+ScalarAutograd provides three categories of optimizers, each suited for different problem types:
+
+### 1. Gradient Descent Optimizers (SGD, Adam, AdamW)
+**Best for:** Training neural networks, iterative refinement, online learning
+
+```typescript
+const opt = new Adam([w, b], { learningRate: 0.01 });
+for (let epoch = 0; epoch < 1000; epoch++) {
+  const loss = computeLoss();
+  opt.zeroGrad();
+  loss.backward();
+  opt.step();
+}
+```
+
+**Pros:** Simple, works on any differentiable objective, good for streaming data
+**Cons:** Slow convergence, requires tuning learning rate and iterations
+
+### 2. Levenberg-Marquardt (`V.nonlinearLeastSquares`)
+**Best for:** Nonlinear least squares: minimizing Σ rᵢ(x)²
+
+```typescript
+const result = V.nonlinearLeastSquares(
+  params,
+  (p) => points.map(pt => residualFunction(p, pt)), // Returns array of residuals
+  { maxIterations: 100 }
+);
+```
+
+**Use when:**
+- Problem is naturally formulated as sum of squared residuals
+- You have overdetermined systems (more equations than unknowns)
+- Examples: curve fitting, calibration, parameter estimation, circle/sphere fitting
+
+**Pros:** 10-100x faster than gradient descent, exploits Jacobian structure
+**Cons:** Only works for least squares problems, requires residual formulation
+
+### 3. L-BFGS (`lbfgs`)
+**Best for:** General unconstrained optimization
+
+```typescript
+import { lbfgs } from 'scalar-autograd';
+
+const result = lbfgs(
+  params,
+  (p) => computeObjective(p), // Returns single Value (the cost)
+  { maxIterations: 100 }
+);
+```
+
+**Use when:**
+- Objective has no special structure (not sum-of-squares)
+- High-dimensional problems (100s-1000s of parameters)
+- Memory constrained (stores only ~10 recent gradient pairs)
+- Examples: energy minimization, ML losses, geometric optimization, developable surfaces
+
+**Pros:** Memory efficient, handles non-quadratic objectives well, faster than gradient descent
+**Cons:** Not as fast as LM for least squares, requires smooth objectives
+
+### Quick Decision Guide
+
+```
+Can you write your objective as f(x) = Σ rᵢ(x)² ?
+├─ YES → Use V.nonlinearLeastSquares() (Levenberg-Marquardt)
+│         Fastest for curve fitting, calibration, parameter estimation
+│
+└─ NO → Is it a general smooth objective?
+    ├─ YES → Use lbfgs() for large-scale or L-BFGS for efficiency
+    │         Good for energy minimization, geometric optimization
+    │
+    └─ NO → Use Adam/AdamW for training neural networks
+              Good for online learning, streaming data
+```
+
 ## API Overview
 - **Core Value construction:**
     - `V.C(data, label?)` — constant (non-differentiable), e.g. for data/inputs.
@@ -95,9 +215,14 @@ This pattern—forward pass, backward for gradients, and calling `optimizer.step
     - `.backward()` — trigger automatic differentiation from this node.
     - `.grad` — access the computed gradient after backward pass.
 - **Optimizers:**
-    - E.g. `const opt = new SGD([w, b], {learningRate: 0.01})`
+    - `SGD`, `Adam`, `AdamW` - E.g. `const opt = new SGD([w, b], {learningRate: 0.01})`
 - **Losses:**
-    - Import from `Losses.ts` (e.g. `import { mse } from './Losses'`)
+    - `Losses.mse()`, `Losses.mae()`, `Losses.binaryCrossEntropy()`, `Losses.categoricalCrossEntropy()`, `Losses.huber()`, `Losses.tukey()`
+- **Advanced Optimization:**
+    - `V.nonlinearLeastSquares(params, residualFn, options)` — Levenberg-Marquardt solver for nonlinear least squares problems (minimizing Σ rᵢ²)
+    - `lbfgs(params, objectiveFn, options)` — L-BFGS optimizer for general unconstrained optimization
+- **Vector utilities:**
+    - `Vec2`, `Vec3` — Differentiable 2D/3D vectors with dot, cross, normalize operations
 
 All API operations work with both `Value` and raw number inputs (numbers are automatically wrapped as non-grad constants).
 

package/dist/CompiledFunctions.d.ts

@@ -0,0 +1,111 @@
+import { Value } from "./Value";
+/**
+ * Pre-compiled scalar functions with automatic differentiation and kernel reuse.
+ *
+ * Uses kernel reuse: topologically identical functions share the same compiled kernel.
+ *
+ * Compile once, reuse many times - ideal for optimization, IK, animation, or any scenario
+ * where you repeatedly evaluate the same structure with different parameter values.
+ *
+ * @example
+ * ```typescript
+ * // Single objective (L-BFGS, Adam, SGD)
+ * const compiled = CompiledFunctions.compile(params, (p) => [loss(p)]);
+ * const { value, gradient } = compiled.evaluateGradient(params);
+ *
+ * // Multiple residuals (Levenberg-Marquardt)
+ * const compiled = CompiledFunctions.compile(params, (p) => residuals(p));
+ * const { values, jacobian } = compiled.evaluateJacobian(params);
+ * ```
+ */
+export declare class CompiledFunctions {
+    private registry;
+    private kernelPool;
+    private functionDescriptors;
+    private numParams;
+    private constructor();
+    /**
+     * Compile scalar functions for reuse with kernel sharing.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param functionsFn - Function that builds scalar outputs from params
+     * @returns Compiled functions ready for optimization
+     */
+    static compile(params: Value[], functionsFn: (params: Value[]) => Value[]): CompiledFunctions;
+    /**
+     * Count nodes in a computation graph.
+     * @internal
+     */
+    private static countGraphNodes;
+    /**
+     * Compile scalar functions for reuse with kernel sharing (async version).
+     * Yields to browser between chunks to prevent UI freezing on large problems.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param functionsFn - Function that builds scalar outputs from params
+     * @param chunkSize - Number of functions to process per chunk (default: 50)
+     * @param onProgress - Optional callback for progress updates (current, total, percent)
+     * @returns Compiled functions ready for optimization
+     */
+    static compileAsync(params: Value[], functionsFn: (params: Value[]) => Value[], chunkSize?: number, onProgress?: (current: number, total: number, percent: number) => void): Promise<CompiledFunctions>;
+    /**
+     * Evaluate gradient of first function (for single objective optimization).
+     *
+     * @param params - Current parameter values
+     * @returns Function value and gradient vector
+     */
+    evaluateGradient(params: Value[]): {
+        value: number;
+        gradient: number[];
+    };
+    /**
+     * Evaluate sum of all functions with accumulated gradient (for L-BFGS, Adam, etc).
+     *
+     * This is the key method for kernel reuse with gradient-based optimizers.
+     * When you have N structurally identical residuals, this will:
+     * - Compile ~1 kernel instead of N
+     * - Evaluate all N residuals, accumulating their gradients
+     * - Return total loss and accumulated gradient
+     *
+     * @param params - Current parameter values
+     * @returns Sum of all function values and accumulated gradient
+     */
+    evaluateSumWithGradient(params: Value[]): {
+        value: number;
+        gradient: number[];
+    };
+    /**
+     * Evaluate all functions and their Jacobian matrix.
+     *
+     * @param params - Current parameter values
+     * @returns Function values and Jacobian matrix
+     */
+    evaluateJacobian(params: Value[]): {
+        values: number[];
+        jacobian: number[][];
+    };
+    /**
+     * Backward compatibility: evaluate as least-squares residuals.
+     *
+     * @deprecated Use evaluateJacobian() instead and compute cost yourself
+     * @param params - Current parameter values
+     * @returns Residuals, Jacobian, and sum of squared residuals
+     */
+    evaluate(params: Value[]): {
+        residuals: number[];
+        J: number[][];
+        cost: number;
+    };
+    /** Get number of compiled functions */
+    get numFunctions(): number;
+    /** @deprecated Use numFunctions instead */
+    get numResiduals(): number;
+    /** Get number of unique kernels (for metrics) */
+    get kernelCount(): number;
+    /** Get kernel reuse factor */
+    get kernelReuseFactor(): number;
+}
+/**
+ * @deprecated Use CompiledFunctions instead
+ */
+export declare const CompiledResiduals: typeof CompiledFunctions;

package/dist/CompiledFunctions.js

@@ -0,0 +1,268 @@
+import { ValueRegistry } from "./ValueRegistry";
+import { KernelPool } from "./KernelPool";
+import { extractInputIndices } from "./compileIndirectKernel";
+/**
+ * Pre-compiled scalar functions with automatic differentiation and kernel reuse.
+ *
+ * Uses kernel reuse: topologically identical functions share the same compiled kernel.
+ *
+ * Compile once, reuse many times - ideal for optimization, IK, animation, or any scenario
+ * where you repeatedly evaluate the same structure with different parameter values.
+ *
+ * @example
+ * ```typescript
+ * // Single objective (L-BFGS, Adam, SGD)
+ * const compiled = CompiledFunctions.compile(params, (p) => [loss(p)]);
+ * const { value, gradient } = compiled.evaluateGradient(params);
+ *
+ * // Multiple residuals (Levenberg-Marquardt)
+ * const compiled = CompiledFunctions.compile(params, (p) => residuals(p));
+ * const { values, jacobian } = compiled.evaluateJacobian(params);
+ * ```
+ */
+export class CompiledFunctions {
+    registry;
+    kernelPool;
+    functionDescriptors;
+    numParams;
+    constructor(registry, kernelPool, functionDescriptors, numParams) {
+        this.registry = registry;
+        this.kernelPool = kernelPool;
+        this.functionDescriptors = functionDescriptors;
+        this.numParams = numParams;
+    }
+    /**
+     * Compile scalar functions for reuse with kernel sharing.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param functionsFn - Function that builds scalar outputs from params
+     * @returns Compiled functions ready for optimization
+     */
+    static compile(params, functionsFn) {
+        // Ensure params have names for compilation
+        params.forEach((p, i) => {
+            if (!p.paramName) {
+                p.paramName = `p${i}`;
+            }
+        });
+        const registry = new ValueRegistry();
+        const kernelPool = new KernelPool();
+        // Register all params first
+        params.forEach(p => registry.register(p));
+        // Build function graphs
+        const functionValues = functionsFn(params);
+        // Build param index map for gradient mapping
+        const paramIndexMap = new Map(params.map((p, i) => [registry.getId(p), i]));
+        // Compile kernels with reuse
+        console.log(`[CompiledFunctions] Compiling ${functionValues.length} functions...`);
+        const functionDescriptors = functionValues.map((f, idx) => {
+            if (idx % 100 === 0) {
+                console.log(`[CompiledFunctions] Processing function ${idx}/${functionValues.length}`);
+            }
+            // Get or compile kernel for this graph structure
+            const descriptor = kernelPool.getOrCompile(f, params, registry);
+            // Extract input indices for this specific function
+            const inputIndices = extractInputIndices(f, registry);
+            // Build gradient indices: maps kernel local inputs → global gradient positions
+            const gradientIndices = inputIndices.map(regId => {
+                // Check if this input is a param (needs gradient)
+                if (paramIndexMap.has(regId)) {
+                    return paramIndexMap.get(regId);
+                }
+                // Not a param (constant) - no gradient
+                return -1;
+            });
+            return {
+                kernelHash: descriptor.canonicalString,
+                inputIndices,
+                gradientIndices
+            };
+        });
+        return new CompiledFunctions(registry, kernelPool, functionDescriptors, params.length);
+    }
+    /**
+     * Count nodes in a computation graph.
+     * @internal
+     */
+    static countGraphNodes(output) {
+        const visited = new Set();
+        function traverse(node) {
+            if (visited.has(node))
+                return;
+            visited.add(node);
+            const prev = node.prev;
+            for (const child of prev) {
+                traverse(child);
+            }
+        }
+        traverse(output);
+        return visited.size;
+    }
+    /**
+     * Compile scalar functions for reuse with kernel sharing (async version).
+     * Yields to browser between chunks to prevent UI freezing on large problems.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param functionsFn - Function that builds scalar outputs from params
+     * @param chunkSize - Number of functions to process per chunk (default: 50)
+     * @param onProgress - Optional callback for progress updates (current, total, percent)
+     * @returns Compiled functions ready for optimization
+     */
+    static async compileAsync(params, functionsFn, chunkSize = 50, onProgress) {
+        // Ensure params have names for compilation
+        params.forEach((p, i) => {
+            if (!p.paramName) {
+                p.paramName = `p${i}`;
+            }
+        });
+        const registry = new ValueRegistry();
+        const kernelPool = new KernelPool();
+        // Register all params first
+        params.forEach(p => registry.register(p));
+        // Build function graphs
+        const functionValues = functionsFn(params);
+        // Build param index map for gradient mapping
+        const paramIndexMap = new Map(params.map((p, i) => [registry.getId(p), i]));
+        console.log(`[CompiledFunctions] Compiling ${functionValues.length} functions...`);
+        const functionDescriptors = [];
+        const totalChunks = Math.ceil(functionValues.length / chunkSize);
+        let lastLoggedPercent = 0;
+        let totalGraphSize = 0;
+        for (let i = 0; i < functionValues.length; i += chunkSize) {
+            const chunkEnd = Math.min(i + chunkSize, functionValues.length);
+            // Only log every 25% progress to reduce clutter
+            const percentComplete = Math.floor((chunkEnd / functionValues.length) * 100);
+            if (percentComplete >= lastLoggedPercent + 25) {
+                console.log(`[CompiledFunctions] Processing ${chunkEnd}/${functionValues.length} (${percentComplete}%)`);
+                lastLoggedPercent = percentComplete;
+            }
+            // Call progress callback
+            if (onProgress) {
+                onProgress(chunkEnd, functionValues.length, percentComplete);
+            }
+            for (let j = i; j < chunkEnd; j++) {
+                const f = functionValues[j];
+                // Count graph size (number of nodes)
+                const graphSize = this.countGraphNodes(f);
+                totalGraphSize += graphSize;
+                const descriptor = kernelPool.getOrCompile(f, params, registry);
+                const inputIndices = extractInputIndices(f, registry);
+                const gradientIndices = inputIndices.map(regId => paramIndexMap.has(regId) ? paramIndexMap.get(regId) : -1);
+                functionDescriptors.push({
+                    kernelHash: descriptor.canonicalString,
+                    inputIndices,
+                    gradientIndices
+                });
+            }
+            // Yield to browser
+            await new Promise(resolve => setTimeout(resolve, 0));
+        }
+        const avgGraphSize = Math.round(totalGraphSize / functionValues.length);
+        console.log(`[CompiledFunctions] Complete: ${kernelPool.kernels.size} unique kernels, ${(functionValues.length / kernelPool.kernels.size).toFixed(1)}x reuse (${kernelPool.canonMode}, avg ${avgGraphSize} nodes)`);
+        return new CompiledFunctions(registry, kernelPool, functionDescriptors, params.length);
+    }
+    /**
+     * Evaluate gradient of first function (for single objective optimization).
+     *
+     * @param params - Current parameter values
+     * @returns Function value and gradient vector
+     */
+    evaluateGradient(params) {
+        if (this.functionDescriptors.length === 0) {
+            throw new Error('No functions compiled');
+        }
+        // Update registry with current param values
+        const allValues = this.registry.getDataArray();
+        params.forEach(p => {
+            const id = this.registry.getId(p);
+            allValues[id] = p.data;
+        });
+        const gradient = new Array(this.numParams).fill(0);
+        const desc = this.functionDescriptors[0];
+        const kernelDesc = this.kernelPool.kernels.get(desc.kernelHash);
+        const value = kernelDesc.kernel(allValues, desc.inputIndices, desc.gradientIndices, gradient);
+        return { value, gradient };
+    }
+    /**
+     * Evaluate sum of all functions with accumulated gradient (for L-BFGS, Adam, etc).
+     *
+     * This is the key method for kernel reuse with gradient-based optimizers.
+     * When you have N structurally identical residuals, this will:
+     * - Compile ~1 kernel instead of N
+     * - Evaluate all N residuals, accumulating their gradients
+     * - Return total loss and accumulated gradient
+     *
+     * @param params - Current parameter values
+     * @returns Sum of all function values and accumulated gradient
+     */
+    evaluateSumWithGradient(params) {
+        // Update registry with current param values
+        const allValues = this.registry.getDataArray();
+        params.forEach(p => {
+            const id = this.registry.getId(p);
+            allValues[id] = p.data;
+        });
+        const gradient = new Array(this.numParams).fill(0);
+        let totalValue = 0;
+        for (const desc of this.functionDescriptors) {
+            const kernelDesc = this.kernelPool.kernels.get(desc.kernelHash);
+            totalValue += kernelDesc.kernel(allValues, desc.inputIndices, desc.gradientIndices, gradient);
+        }
+        return { value: totalValue, gradient };
+    }
+    /**
+     * Evaluate all functions and their Jacobian matrix.
+     *
+     * @param params - Current parameter values
+     * @returns Function values and Jacobian matrix
+     */
+    evaluateJacobian(params) {
+        // Update registry with current param values
+        const allValues = this.registry.getDataArray();
+        params.forEach(p => {
+            const id = this.registry.getId(p);
+            allValues[id] = p.data;
+        });
+        const numFunctions = this.functionDescriptors.length;
+        const values = new Array(numFunctions);
+        const jacobian = Array(numFunctions).fill(0).map(() => new Array(this.numParams).fill(0));
+        for (let i = 0; i < numFunctions; i++) {
+            const desc = this.functionDescriptors[i];
+            const kernelDesc = this.kernelPool.kernels.get(desc.kernelHash);
+            values[i] = kernelDesc.kernel(allValues, desc.inputIndices, desc.gradientIndices, jacobian[i]);
+        }
+        return { values, jacobian };
+    }
+    /**
+     * Backward compatibility: evaluate as least-squares residuals.
+     *
+     * @deprecated Use evaluateJacobian() instead and compute cost yourself
+     * @param params - Current parameter values
+     * @returns Residuals, Jacobian, and sum of squared residuals
+     */
+    evaluate(params) {
+        const { values, jacobian } = this.evaluateJacobian(params);
+        const cost = values.reduce((sum, v) => sum + v * v, 0);
+        return { residuals: values, J: jacobian, cost };
+    }
+    /** Get number of compiled functions */
+    get numFunctions() {
+        return this.functionDescriptors.length;
+    }
+    /** @deprecated Use numFunctions instead */
+    get numResiduals() {
+        return this.numFunctions;
+    }
+    /** Get number of unique kernels (for metrics) */
+    get kernelCount() {
+        return this.kernelPool.size;
+    }
+    /** Get kernel reuse factor */
+    get kernelReuseFactor() {
+        return this.numFunctions / this.kernelPool.size;
+    }
+}
+/**
+ * @deprecated Use CompiledFunctions instead
+ */
+export const CompiledResiduals = CompiledFunctions;

package/dist/CompiledResiduals.d.ts

@@ -0,0 +1,74 @@
+import { Value } from "./Value";
+/**
+ * Pre-compiled residual functions for efficient repeated optimization.
+ *
+ * Wrapper around CompiledFunctions that provides a simpler API for
+ * Levenberg-Marquardt optimization use cases.
+ *
+ * Compile once, reuse many times - ideal for IK, animation, or any scenario
+ * where you solve the same structure with different parameter values.
+ *
+ * @example
+ * ```typescript
+ * // Compile once
+ * const compiled = CompiledResiduals.compile(params, residualFn);
+ *
+ * // Solve many times with different initial values
+ * for (let i = 0; i < 100; i++) {
+ *   params.forEach(p => p.data = randomInitialValue());
+ *   V.nonlinearLeastSquares(params, compiled);
+ * }
+ * ```
+ */
+export declare class CompiledResiduals {
+    private compiledFunctions;
+    private constructor();
+    /**
+     * Compile residual functions for reuse.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param residualFn - Function that builds residuals from params
+     * @returns Compiled residual functions ready for optimization
+     */
+    static compile(params: Value[], residualFn: (params: Value[]) => Value[]): CompiledResiduals;
+    /**
+     * Compile residual functions asynchronously with progress reporting.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param residualFn - Function that builds residuals from params
+     * @param chunkSize - Number of residuals to compile per chunk
+     * @param onProgress - Callback for progress updates
+     * @returns Compiled residual functions ready for optimization
+     */
+    static compileAsync(params: Value[], residualFn: (params: Value[]) => Value[], chunkSize?: number, onProgress?: (current: number, total: number, percent: number) => void): Promise<CompiledResiduals>;
+    /**
+     * Evaluate compiled residuals and Jacobian.
+     *
+     * @param params - Current parameter values
+     * @returns Residuals, Jacobian, and cost
+     */
+    evaluate(params: Value[]): {
+        residuals: number[];
+        J: number[][];
+        cost: number;
+    };
+    /** Get number of residuals */
+    get numResiduals(): number;
+    /** Get number of functions (alias for numResiduals) */
+    get numFunctions(): number;
+    /** Get number of unique kernels */
+    get kernelCount(): number;
+    /** Get kernel reuse factor */
+    get kernelReuseFactor(): number;
+    /**
+     * Evaluate sum of all residuals with accumulated gradient.
+     * Used by LBFGS for scalar optimization.
+     *
+     * @param params - Current parameter values
+     * @returns Sum of all residuals and accumulated gradient
+     */
+    evaluateSumWithGradient(params: Value[]): {
+        value: number;
+        gradient: number[];
+    };
+}

package/dist/CompiledResiduals.js

@@ -0,0 +1,94 @@
+import { CompiledFunctions } from "./CompiledFunctions";
+/**
+ * Pre-compiled residual functions for efficient repeated optimization.
+ *
+ * Wrapper around CompiledFunctions that provides a simpler API for
+ * Levenberg-Marquardt optimization use cases.
+ *
+ * Compile once, reuse many times - ideal for IK, animation, or any scenario
+ * where you solve the same structure with different parameter values.
+ *
+ * @example
+ * ```typescript
+ * // Compile once
+ * const compiled = CompiledResiduals.compile(params, residualFn);
+ *
+ * // Solve many times with different initial values
+ * for (let i = 0; i < 100; i++) {
+ *   params.forEach(p => p.data = randomInitialValue());
+ *   V.nonlinearLeastSquares(params, compiled);
+ * }
+ * ```
+ */
+export class CompiledResiduals {
+    compiledFunctions;
+    constructor(compiledFunctions) {
+        this.compiledFunctions = compiledFunctions;
+    }
+    /**
+     * Compile residual functions for reuse.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param residualFn - Function that builds residuals from params
+     * @returns Compiled residual functions ready for optimization
+     */
+    static compile(params, residualFn) {
+        const compiledFunctions = CompiledFunctions.compile(params, residualFn);
+        return new CompiledResiduals(compiledFunctions);
+    }
+    /**
+     * Compile residual functions asynchronously with progress reporting.
+     *
+     * @param params - Parameter Values (must have .paramName set)
+     * @param residualFn - Function that builds residuals from params
+     * @param chunkSize - Number of residuals to compile per chunk
+     * @param onProgress - Callback for progress updates
+     * @returns Compiled residual functions ready for optimization
+     */
+    static async compileAsync(params, residualFn, chunkSize = 50, onProgress) {
+        const compiledFunctions = await CompiledFunctions.compileAsync(params, residualFn, chunkSize, onProgress);
+        return new CompiledResiduals(compiledFunctions);
+    }
+    /**
+     * Evaluate compiled residuals and Jacobian.
+     *
+     * @param params - Current parameter values
+     * @returns Residuals, Jacobian, and cost
+     */
+    evaluate(params) {
+        const { values, jacobian } = this.compiledFunctions.evaluateJacobian(params);
+        const residuals = values;
+        const J = jacobian;
+        let cost = 0;
+        for (const r of residuals) {
+            cost += r * r;
+        }
+        return { residuals, J, cost };
+    }
+    /** Get number of residuals */
+    get numResiduals() {
+        return this.compiledFunctions.numFunctions;
+    }
+    /** Get number of functions (alias for numResiduals) */
+    get numFunctions() {
+        return this.compiledFunctions.numFunctions;
+    }
+    /** Get number of unique kernels */
+    get kernelCount() {
+        return this.compiledFunctions.kernelCount;
+    }
+    /** Get kernel reuse factor */
+    get kernelReuseFactor() {
+        return this.compiledFunctions.kernelReuseFactor;
+    }
+    /**
+     * Evaluate sum of all residuals with accumulated gradient.
+     * Used by LBFGS for scalar optimization.
+     *
+     * @param params - Current parameter values
+     * @returns Sum of all residuals and accumulated gradient
+     */
+    evaluateSumWithGradient(params) {
+        return this.compiledFunctions.evaluateSumWithGradient(params);
+    }
+}