numopt-js 0.1.0

package/dist/core/constrainedUtils.js

@@ -0,0 +1,364 @@
+/**
+ * This file provides shared utility functions for constrained optimization algorithms
+ * using the adjoint method.
+ *
+ * Role in system:
+ * - Eliminates code duplication between adjointGradientDescent, constrainedGaussNewton, and constrainedLevenbergMarquardt
+ * - Centralizes adjoint method computation logic (DRY principle)
+ * - Provides reusable functions for state updates and constraint handling
+ *
+ * For first-time readers:
+ * - These are utility functions used internally by constrained optimization algorithms
+ * - solveAdjointEquation: Solves the adjoint equation for computing gradients
+ * - updateStates: Updates states using linear approximation to maintain constraint satisfaction
+ * - validateInitialConditions: Validates initial states and constraints
+ *
+ * Extracted from adjointGradientDescent.ts to enable code reuse.
+ */
+import { Matrix, solve, CholeskyDecomposition } from 'ml-matrix';
+import { vectorNorm, scaleVector, addVectors } from '../utils/matrix.js';
+import { float64ArrayToMatrix, matrixToFloat64Array } from '../utils/matrix.js';
+import { finiteDiffConstraintPartialX } from './finiteDiff.js';
+const NEGATIVE_COEFFICIENT = -1.0; // Coefficient for negating vectors
+const MAX_DIAG_LOG_DIM = 40; // upper bound to log row/col diagnostics
+const MAX_REGULARIZATION_ATTEMPTS = 8; // Maximum number of regularization attempts when solving linear systems
+const REGULARIZATION_BASE = 10; // Base for exponential regularization scaling
+const REGULARIZATION_INITIAL_EXPONENT = -8; // Initial exponent for regularization: 10^(-8)
+const REGULARIZATION_MAX_EXPONENT = 7; // Maximum exponent for regularization: 10^7
+const REGULARIZATION_FALLBACK_EXPONENT = -1; // Fallback exponent when baseReg is 0: 10^(-1)
+const MAX_DIAGNOSTIC_ENTRIES = 5; // Maximum number of smallest rows/columns to include in diagnostics
+function checkFiniteMatrix(mat) {
+    for (let r = 0; r < mat.rows; r++) {
+        for (let c = 0; c < mat.columns; c++) {
+            const v = mat.get(r, c);
+            if (!Number.isFinite(v)) {
+                return { ok: false, firstBad: { row: r, col: c, value: v } };
+            }
+        }
+    }
+    return { ok: true };
+}
+function computeVectorDiagnostics(b) {
+    let sum = 0;
+    let minAbs = Number.POSITIVE_INFINITY;
+    let maxAbs = 0;
+    for (let r = 0; r < b.rows; r++) {
+        for (let c = 0; c < b.columns; c++) {
+            const v = b.get(r, c);
+            const abs = Math.abs(v);
+            sum += v * v;
+            minAbs = Math.min(minAbs, abs);
+            maxAbs = Math.max(maxAbs, abs);
+        }
+    }
+    return { norm: Math.sqrt(sum), minAbs: minAbs === Number.POSITIVE_INFINITY ? 0 : minAbs, maxAbs };
+}
+function computeRowColDiagnostics(A) {
+    const rowNorms = [];
+    const colNorms = [];
+    for (let r = 0; r < A.rows; r++) {
+        let sum = 0;
+        for (let c = 0; c < A.columns; c++) {
+            const v = A.get(r, c);
+            sum += v * v;
+        }
+        rowNorms.push(Math.sqrt(sum));
+    }
+    for (let c = 0; c < A.columns; c++) {
+        let sum = 0;
+        for (let r = 0; r < A.rows; r++) {
+            const v = A.get(r, c);
+            sum += v * v;
+        }
+        colNorms.push(Math.sqrt(sum));
+    }
+    const rowPairs = rowNorms.map((norm, index) => ({ index, norm })).sort((a, b) => a.norm - b.norm).slice(0, MAX_DIAGNOSTIC_ENTRIES);
+    const colPairs = colNorms.map((norm, index) => ({ index, norm })).sort((a, b) => a.norm - b.norm).slice(0, MAX_DIAGNOSTIC_ENTRIES);
+    return {
+        minRowNorm: Math.min(...rowNorms),
+        maxRowNorm: Math.max(...rowNorms),
+        minColNorm: Math.min(...colNorms),
+        maxColNorm: Math.max(...colNorms),
+        smallestRows: rowPairs,
+        smallestCols: colPairs
+    };
+}
+/**
+ * Computes regularization lambda for a given attempt.
+ * Uses exponential scaling to gradually increase regularization strength.
+ */
+function computeRegularizationLambda(baseReg, attempt) {
+    return baseReg > 0
+        ? baseReg * Math.pow(REGULARIZATION_BASE, attempt)
+        : Math.pow(REGULARIZATION_BASE, REGULARIZATION_INITIAL_EXPONENT + attempt);
+}
+/**
+ * Attempts to solve linear system with regularization retries.
+ * Cholesky decomposition is preferred for efficiency, falls back to general solver.
+ */
+function trySolveWithRegularization(A, b, baseReg, logger, algorithmName) {
+    let lastError;
+    for (let attempt = 0; attempt < MAX_REGULARIZATION_ATTEMPTS; attempt++) {
+        const lambda = computeRegularizationLambda(baseReg, attempt);
+        const AwithReg = A.add(Matrix.eye(A.rows, A.columns).mul(lambda));
+        try {
+            const chol = new CholeskyDecomposition(AwithReg);
+            if (chol.isPositiveDefinite()) {
+                return matrixToFloat64Array(chol.solve(b));
+            }
+        }
+        catch (err) {
+            lastError = err;
+        }
+        try {
+            return matrixToFloat64Array(solve(AwithReg, b));
+        }
+        catch (err) {
+            lastError = err;
+            continue;
+        }
+    }
+    logger.warn(algorithmName, undefined, `Failed to solve system with regularization: ${lastError}`);
+    throw new Error(`Failed to solve linear system even with Tikhonov regularization. ` +
+        `Matrix may be singular or ill-conditioned. Last error: ${lastError}`);
+}
+/**
+ * Solves square system Ax = b with validation and regularization.
+ * Fast path for square matrices using direct Cholesky/LU decomposition.
+ */
+function solveSquareSystem(Areg, b, regularization, logger, algorithmName) {
+    const baseReg = regularization > 0 ? regularization : 0;
+    const diagnostics = Areg.rows <= MAX_DIAG_LOG_DIM && Areg.columns <= MAX_DIAG_LOG_DIM
+        ? computeRowColDiagnostics(Areg)
+        : undefined;
+    const rhsDiagnostics = computeVectorDiagnostics(b);
+    const dimsOk = Areg.rows === b.rows;
+    const Afinite = checkFiniteMatrix(Areg);
+    const bFinite = checkFiniteMatrix(b);
+    if (!dimsOk || !Afinite.ok || !bFinite.ok) {
+        const detailRows = [
+            { key: 'A_rows', value: Areg.rows },
+            { key: 'A_cols', value: Areg.columns },
+            { key: 'b_rows', value: b.rows },
+            { key: 'b_cols', value: b.columns }
+        ];
+        if (!Afinite.ok && Afinite.firstBad) {
+            detailRows.push({ key: 'A_bad_row', value: Afinite.firstBad.row });
+            detailRows.push({ key: 'A_bad_col', value: Afinite.firstBad.col });
+            detailRows.push({ key: 'A_bad_val', value: Afinite.firstBad.value });
+        }
+        if (!bFinite.ok && bFinite.firstBad) {
+            detailRows.push({ key: 'b_bad_row', value: bFinite.firstBad.row });
+            detailRows.push({ key: 'b_bad_col', value: bFinite.firstBad.col });
+            detailRows.push({ key: 'b_bad_val', value: bFinite.firstBad.value });
+        }
+        const numericDetails = detailRows.filter(d => typeof d.value === 'number');
+        logger.warn(algorithmName, undefined, 'Invalid dimensions or NaN/Inf detected before solve', numericDetails);
+        throw new Error('Invalid dimensions or NaN/Inf in inputs for square solve');
+    }
+    try {
+        return trySolveWithRegularization(Areg, b, baseReg, logger, algorithmName);
+    }
+    catch (error) {
+        const detailRows = [
+            { key: 'rows', value: Areg.rows },
+            { key: 'cols', value: Areg.columns },
+            { key: 'reg_final', value: baseReg > 0 ? baseReg * Math.pow(REGULARIZATION_BASE, REGULARIZATION_MAX_EXPONENT) : Math.pow(REGULARIZATION_BASE, REGULARIZATION_FALLBACK_EXPONENT) }
+        ];
+        detailRows.push({ key: 'rhs_norm', value: rhsDiagnostics.norm }, { key: 'rhs_min_abs', value: rhsDiagnostics.minAbs }, { key: 'rhs_max_abs', value: rhsDiagnostics.maxAbs });
+        if (diagnostics) {
+            detailRows.push({ key: 'minRowNorm', value: diagnostics.minRowNorm }, { key: 'minColNorm', value: diagnostics.minColNorm }, { key: 'maxRowNorm', value: diagnostics.maxRowNorm }, { key: 'maxColNorm', value: diagnostics.maxColNorm });
+            diagnostics.smallestRows.forEach((row, idx) => {
+                detailRows.push({ key: `row_${idx}`, value: row.index });
+                detailRows.push({ key: `row_${idx}_norm`, value: row.norm });
+            });
+            diagnostics.smallestCols.forEach((col, idx) => {
+                detailRows.push({ key: `col_${idx}`, value: col.index });
+                detailRows.push({ key: `col_${idx}_norm`, value: col.norm });
+            });
+        }
+        const numericDetails = detailRows.filter(d => typeof d.value === 'number');
+        logger.warn(algorithmName, undefined, `Failed to solve square system with regularization up to ~1e0: ${error}`, numericDetails);
+        throw error;
+    }
+}
+/**
+ * Solves overdetermined system (rows > columns) using normal equations.
+ * Converts to square system A^T A x = A^T b for efficient Cholesky solution.
+ */
+function solveOverdeterminedSystem(A, b, regularization, logger, algorithmName) {
+    const AT = A.transpose();
+    const ATA = AT.mmul(A);
+    const ATb = AT.mmul(b);
+    const baseReg = regularization > 0 ? regularization : 0;
+    try {
+        return trySolveWithRegularization(ATA, ATb, baseReg, logger, algorithmName);
+    }
+    catch (error) {
+        logger.warn(algorithmName, undefined, `Failed to solve overdetermined system with normal equations: ${error}`);
+        throw new Error(`Failed to solve overdetermined system Ax = b using normal equations A^T A x = A^T b. ` +
+            `Matrix A^T A may be singular or ill-conditioned. Last error: ${error}`);
+    }
+}
+/**
+ * Solves underdetermined system (rows < columns) using normal equations.
+ * Strategy: solve A A^T y = b, then x = A^T y for minimum-norm solution.
+ */
+function solveUnderdeterminedSystem(A, b, regularization, logger, algorithmName) {
+    const AT = A.transpose();
+    const AAT = A.mmul(AT);
+    const baseReg = regularization > 0 ? regularization : 0;
+    try {
+        const y = trySolveWithRegularization(AAT, b, baseReg, logger, algorithmName);
+        const x = AT.mmul(float64ArrayToMatrix(y));
+        return matrixToFloat64Array(x);
+    }
+    catch (error) {
+        logger.warn(algorithmName, undefined, `Failed to solve underdetermined system with normal equations: ${error}`);
+        throw new Error(`Failed to solve underdetermined system Ax = b using normal equations A A^T y = b, x = A^T y. ` +
+            `Matrix A A^T may be singular or ill-conditioned. Last error: ${error}`);
+    }
+}
+/**
+ * Solves a least squares problem Ax = b using Cholesky decomposition.
+ * For square matrices, uses Cholesky/LU decomposition directly.
+ * For non-square matrices, uses normal equations to convert to square system:
+ * - Overdetermined (rows > columns): A^T A x = A^T b (Cholesky on A^T A)
+ * - Underdetermined (rows < columns): A A^T y = b, x = A^T y (Cholesky on A A^T)
+ * This approach avoids SVD/pseudoInverse entirely for better performance.
+ *
+ * @param A - Coefficient matrix
+ * @param b - Right-hand side vector (as Matrix column vector)
+ * @param logger - Logger for error messages
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @returns Solution vector x as Float64Array
+ */
+export function solveLeastSquares(A, b, logger, algorithmName = 'constrainedOptimization', regularization = 0) {
+    const Areg = regularization > 0 && A.rows === A.columns
+        ? A.add(Matrix.eye(A.rows, A.columns).mul(regularization))
+        : A;
+    if (Areg.rows === Areg.columns) {
+        return solveSquareSystem(Areg, b, regularization, logger, algorithmName);
+    }
+    const isOverdetermined = A.rows > A.columns;
+    if (isOverdetermined) {
+        return solveOverdeterminedSystem(A, b, regularization, logger, algorithmName);
+    }
+    return solveUnderdeterminedSystem(A, b, regularization, logger, algorithmName);
+}
+/**
+ * Solves the adjoint equation: (∂c/∂x)^T λ = rhs
+ * Returns the adjoint variable λ.
+ * Supports both square and non-square constraint Jacobians.
+ *
+ * This is the core of the adjoint method, used for efficient gradient computation
+ * without explicitly inverting matrices.
+ *
+ * @param dcdx - Constraint Jacobian ∂c/∂x
+ * @param rhs - Right-hand side vector (e.g., (∂f/∂x)^T or (r_x^T r))
+ * @param logger - Logger instance for error reporting
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @returns Adjoint variable λ
+ */
+export function solveAdjointEquation(dcdx, rhs, logger, algorithmName = 'constrainedOptimization', regularization = 0) {
+    // Transpose needed to form adjoint equation: (∂c/∂x)^T λ = rhs (standard form for linear solve)
+    const dcdxTranspose = dcdx.transpose();
+    const rhsMatrix = float64ArrayToMatrix(rhs);
+    // Hierarchical solver handles both square and non-square constraint Jacobians efficiently
+    try {
+        return solveLeastSquares(dcdxTranspose, rhsMatrix, logger, algorithmName, regularization);
+    }
+    catch (error) {
+        logger.warn(algorithmName, undefined, `Failed to solve adjoint equation: ${error}`);
+        throw new Error(`Failed to solve adjoint equation (∂c/∂x)^T λ = rhs. ` +
+            `The constraint Jacobian ∂c/∂x may be singular or ill-conditioned. ` +
+            `Matrix size: ${dcdx.rows} × ${dcdx.columns}. ` +
+            `Original error: ${error}`);
+    }
+}
+/**
+ * Updates states using linear approximation: x_new = x_old + dx
+ * where dx solves (∂c/∂x) dx = -∂c/∂p · Δp
+ * Supports both square and non-square constraint Jacobians.
+ *
+ * This maintains constraint satisfaction approximately using first-order Taylor expansion.
+ * For large steps, constraints may be violated slightly, but the algorithm will correct
+ * this in subsequent iterations.
+ *
+ * @param currentStates - Current state vector x
+ * @param dcdx - Constraint Jacobian ∂c/∂x
+ * @param dcdp - Constraint Jacobian ∂c/∂p
+ * @param deltaP - Parameter change Δp
+ * @param logger - Logger instance for error reporting
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @returns Updated state vector x_new
+ */
+export function updateStates(currentStates, dcdx, dcdp, deltaP, logger, algorithmName = 'constrainedOptimization') {
+    // Compute how parameter changes affect constraints: needed to determine state updates
+    const deltaPMatrix = float64ArrayToMatrix(deltaP);
+    const dcdpDeltaP = dcdp.mmul(deltaPMatrix);
+    const dcdpDeltaPVector = matrixToFloat64Array(dcdpDeltaP);
+    // Linear approximation maintains constraint satisfaction: (∂c/∂x) dx = -∂c/∂p · Δp
+    const negativeDcdpDeltaP = scaleVector(dcdpDeltaPVector, NEGATIVE_COEFFICIENT);
+    const negativeDcdpDeltaPMatrix = float64ArrayToMatrix(negativeDcdpDeltaP);
+    // Hierarchical solver efficiently handles both square and non-square constraint Jacobians
+    const dx = solveLeastSquares(dcdx, negativeDcdpDeltaPMatrix, logger, algorithmName);
+    return addVectors(currentStates, dx);
+}
+/**
+ * Projects states onto the constraint manifold for fixed parameters using
+ * a few Newton correction steps: (∂c/∂x) Δx = -c(p, x).
+ * This is a standard feasibility-restoration step consistent with the
+ * implicit function theorem (solving c(p, x) = 0 locally).
+ */
+export function projectStatesToConstraints(parameters, states, constraintFunction, stepSizeX, constraintTolerance, logger, algorithmName = 'constrainedOptimization', maxIterations = 3) {
+    let projectedStates = new Float64Array(states);
+    for (let i = 0; i < maxIterations; i++) {
+        const constraint = constraintFunction(parameters, projectedStates);
+        const constraintNorm = vectorNorm(constraint);
+        if (constraintNorm <= constraintTolerance) {
+            break;
+        }
+        const dcdx = finiteDiffConstraintPartialX(parameters, projectedStates, constraintFunction, { stepSize: stepSizeX });
+        const negativeConstraint = scaleVector(constraint, NEGATIVE_COEFFICIENT);
+        const negativeConstraintMatrix = float64ArrayToMatrix(negativeConstraint);
+        try {
+            const deltaX = solveLeastSquares(dcdx, negativeConstraintMatrix, logger, algorithmName);
+            const updatedStates = addVectors(projectedStates, deltaX);
+            projectedStates = new Float64Array(updatedStates);
+        }
+        catch (error) {
+            logger.warn(algorithmName, undefined, `Failed to project onto constraints: ${error}`);
+            break;
+        }
+    }
+    return projectedStates;
+}
+/**
+ * Validates initial conditions including constraint satisfaction and dimensions.
+ *
+ * Checks that:
+ * 1. Constraint count equals state count (required for adjoint method)
+ * 2. Initial constraint violation is within tolerance (warns if not)
+ *
+ * @param initialParameters - Initial parameter vector p0
+ * @param initialStates - Initial state vector x0
+ * @param constraintFunction - Constraint function c(p, x) = 0
+ * @param constraintTolerance - Tolerance for constraint violation
+ * @param logger - Logger instance for warnings
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @throws Error if constraint count != state count
+ */
+export function validateInitialConditions(initialParameters, initialStates, constraintFunction, constraintTolerance, logger, algorithmName = 'constrainedOptimization') {
+    const initialConstraint = constraintFunction(initialParameters, initialStates);
+    const initialConstraintNorm = vectorNorm(initialConstraint);
+    if (initialConstraintNorm > constraintTolerance) {
+        logger.warn(algorithmName, undefined, 'Initial constraint violation', [
+            { key: '||c(p0,x0)||:', value: initialConstraintNorm },
+            { key: 'Tolerance:', value: constraintTolerance }
+        ]);
+    }
+    // Note: Constraint count and state count no longer need to match.
+    // The adjoint method now supports non-square constraint Jacobians.
+}
+//# sourceMappingURL=constrainedUtils.js.map

package/dist/core/constrainedUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constrainedUtils.js","sourceRoot":"","sources":["../../src/core/constrainedUtils.ts"],"names":[],"mappings":"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"}

package/dist/core/convergence.d.ts

@@ -0,0 +1,35 @@
+/**
+ * This file provides helper functions for convergence checking across
+ * different optimization algorithms.
+ *
+ * Role in system:
+ * - Centralizes convergence checking logic (DRY principle)
+ * - Used by gradient descent, Gauss-Newton, and Levenberg-Marquardt
+ * - Provides consistent convergence criteria
+ *
+ * For first-time readers:
+ * - These are utility functions used by optimization algorithms
+ * - Each function checks a specific convergence criterion
+ */
+import type { OptimizationResult } from './types.js';
+/**
+ * Creates a convergence result object with consistent structure.
+ * Used to avoid code duplication across optimization algorithms.
+ */
+export declare function createConvergenceResult(parameters: Float64Array, iteration: number, converged: boolean, finalCost: number, finalGradientNorm?: number): OptimizationResult;
+/**
+ * Checks if gradient norm indicates convergence.
+ * Returns true if gradient is small enough (algorithm has found a stationary point).
+ */
+export declare function checkGradientConvergence(gradientNorm: number, tolerance: number, iteration: number): boolean;
+/**
+ * Checks if step size indicates convergence.
+ * Returns true if step is small enough (algorithm is making minimal progress).
+ */
+export declare function checkStepSizeConvergence(stepNorm: number, tolerance: number, iteration: number): boolean;
+/**
+ * Checks if residual norm indicates convergence.
+ * Returns true if residual is small enough (problem is solved to desired accuracy).
+ */
+export declare function checkResidualConvergence(residualNorm: number, tolerance: number, iteration: number): boolean;
+//# sourceMappingURL=convergence.d.ts.map

package/dist/core/convergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convergence.d.ts","sourceRoot":"","sources":["../../src/core/convergence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,YAAY,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,EACjB,iBAAiB,CAAC,EAAE,MAAM,GACzB,kBAAkB,CAQpB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAGT"}

package/dist/core/convergence.js

@@ -0,0 +1,51 @@
+/**
+ * This file provides helper functions for convergence checking across
+ * different optimization algorithms.
+ *
+ * Role in system:
+ * - Centralizes convergence checking logic (DRY principle)
+ * - Used by gradient descent, Gauss-Newton, and Levenberg-Marquardt
+ * - Provides consistent convergence criteria
+ *
+ * For first-time readers:
+ * - These are utility functions used by optimization algorithms
+ * - Each function checks a specific convergence criterion
+ */
+/**
+ * Creates a convergence result object with consistent structure.
+ * Used to avoid code duplication across optimization algorithms.
+ */
+export function createConvergenceResult(parameters, iteration, converged, finalCost, finalGradientNorm) {
+    return {
+        parameters,
+        iterations: iteration + 1,
+        converged,
+        finalCost,
+        finalGradientNorm
+    };
+}
+/**
+ * Checks if gradient norm indicates convergence.
+ * Returns true if gradient is small enough (algorithm has found a stationary point).
+ */
+export function checkGradientConvergence(gradientNorm, tolerance, iteration) {
+    // Skip convergence check on first iteration (no step taken yet)
+    return iteration > 0 && gradientNorm < tolerance;
+}
+/**
+ * Checks if step size indicates convergence.
+ * Returns true if step is small enough (algorithm is making minimal progress).
+ */
+export function checkStepSizeConvergence(stepNorm, tolerance, iteration) {
+    // Skip convergence check on first iteration (no step taken yet)
+    return iteration > 0 && stepNorm < tolerance;
+}
+/**
+ * Checks if residual norm indicates convergence.
+ * Returns true if residual is small enough (problem is solved to desired accuracy).
+ */
+export function checkResidualConvergence(residualNorm, tolerance, iteration) {
+    // Skip convergence check on first iteration (no step taken yet)
+    return iteration > 0 && residualNorm < tolerance;
+}
+//# sourceMappingURL=convergence.js.map

package/dist/core/convergence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convergence.js","sourceRoot":"","sources":["../../src/core/convergence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAwB,EACxB,SAAiB,EACjB,SAAkB,EAClB,SAAiB,EACjB,iBAA0B;IAE1B,OAAO;QACL,UAAU;QACV,UAAU,EAAE,SAAS,GAAG,CAAC;QACzB,SAAS;QACT,SAAS;QACT,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,YAAoB,EACpB,SAAiB,EACjB,SAAiB;IAEjB,gEAAgE;IAChE,OAAO,SAAS,GAAG,CAAC,IAAI,YAAY,GAAG,SAAS,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,SAAiB,EACjB,SAAiB;IAEjB,gEAAgE;IAChE,OAAO,SAAS,GAAG,CAAC,IAAI,QAAQ,GAAG,SAAS,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,YAAoB,EACpB,SAAiB,EACjB,SAAiB;IAEjB,gEAAgE;IAChE,OAAO,SAAS,GAAG,CAAC,IAAI,YAAY,GAAG,SAAS,CAAC;AACnD,CAAC"}

package/dist/core/createGradientFunction.d.ts

@@ -0,0 +1,85 @@
+/**
+ * This file provides helper functions for creating gradient and Jacobian functions
+ * from cost and residual functions using finite differences.
+ *
+ * Role in system:
+ * - Simplifies the API for users who want to use numerical differentiation
+ * - Prevents common mistakes with parameter ordering
+ * - Provides a more intuitive interface for optimization algorithms
+ *
+ * For first-time readers:
+ * - Use createFiniteDiffGradient when you have a cost function and need a gradient
+ * - Use createFiniteDiffJacobian when you have a residual function and need a Jacobian
+ * - These are convenience wrappers around finiteDiffGradient and finiteDiffJacobian
+ */
+import type { CostFn, GradientFn, ResidualFn, JacobianFn, NumericalDifferentiationOptions } from './types.js';
+/**
+ * Creates a gradient function from a cost function using finite differences.
+ *
+ * This is a convenience wrapper around finiteDiffGradient that returns a gradient
+ * function suitable for use with optimization algorithms like gradientDescent.
+ *
+ * @param costFunction - The cost function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns A gradient function that can be passed to optimization algorithms
+ *
+ * @example
+ * ```typescript
+ * import { gradientDescent, createFiniteDiffGradient } from 'numopt-js';
+ *
+ * // Define your cost function
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ *
+ * // Create a gradient function (no need to worry about parameter order!)
+ * const gradientFn = createFiniteDiffGradient(costFn);
+ *
+ * // Use it with an optimizer
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   gradientFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom step size
+ * const gradientFn = createFiniteDiffGradient(costFn, { stepSize: 1e-8 });
+ * ```
+ */
+export declare function createFiniteDiffGradient(costFunction: CostFn, options?: NumericalDifferentiationOptions): GradientFn;
+/**
+ * Creates a Jacobian function from a residual function using finite differences.
+ *
+ * This is a convenience wrapper around finiteDiffJacobian that returns a Jacobian
+ * function suitable for use with optimization algorithms like gaussNewton.
+ *
+ * @param residualFunction - The residual function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns A Jacobian function that can be passed to optimization algorithms
+ *
+ * @example
+ * ```typescript
+ * import { gaussNewton, createFiniteDiffJacobian } from 'numopt-js';
+ *
+ * // Define your residual function
+ * const residualFn = (params) => {
+ *   // Return residuals for curve fitting, etc.
+ *   return new Float64Array([...]);
+ * };
+ *
+ * // Create a Jacobian function
+ * const jacobianFn = createFiniteDiffJacobian(residualFn);
+ *
+ * // Use it with an optimizer
+ * const result = gaussNewton(
+ *   new Float64Array([1, 1]),
+ *   residualFn,
+ *   jacobianFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ */
+export declare function createFiniteDiffJacobian(residualFunction: ResidualFn, options?: NumericalDifferentiationOptions): JacobianFn;
+//# sourceMappingURL=createGradientFunction.d.ts.map

package/dist/core/createGradientFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createGradientFunction.d.ts","sourceRoot":"","sources":["../../src/core/createGradientFunction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACR,MAAM,EACN,UAAU,EACV,UAAU,EACV,UAAU,EACV,+BAA+B,EAClC,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,wBAAwB,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,+BAA+B,GAC1C,UAAU,CAIZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,wBAAwB,CACpC,gBAAgB,EAAE,UAAU,EAC5B,OAAO,CAAC,EAAE,+BAA+B,GAC1C,UAAU,CAIZ"}

package/dist/core/createGradientFunction.js

@@ -0,0 +1,93 @@
+/**
+ * This file provides helper functions for creating gradient and Jacobian functions
+ * from cost and residual functions using finite differences.
+ *
+ * Role in system:
+ * - Simplifies the API for users who want to use numerical differentiation
+ * - Prevents common mistakes with parameter ordering
+ * - Provides a more intuitive interface for optimization algorithms
+ *
+ * For first-time readers:
+ * - Use createFiniteDiffGradient when you have a cost function and need a gradient
+ * - Use createFiniteDiffJacobian when you have a residual function and need a Jacobian
+ * - These are convenience wrappers around finiteDiffGradient and finiteDiffJacobian
+ */
+import { finiteDiffGradient, finiteDiffJacobian } from './finiteDiff.js';
+/**
+ * Creates a gradient function from a cost function using finite differences.
+ *
+ * This is a convenience wrapper around finiteDiffGradient that returns a gradient
+ * function suitable for use with optimization algorithms like gradientDescent.
+ *
+ * @param costFunction - The cost function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns A gradient function that can be passed to optimization algorithms
+ *
+ * @example
+ * ```typescript
+ * import { gradientDescent, createFiniteDiffGradient } from 'numopt-js';
+ *
+ * // Define your cost function
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ *
+ * // Create a gradient function (no need to worry about parameter order!)
+ * const gradientFn = createFiniteDiffGradient(costFn);
+ *
+ * // Use it with an optimizer
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   gradientFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom step size
+ * const gradientFn = createFiniteDiffGradient(costFn, { stepSize: 1e-8 });
+ * ```
+ */
+export function createFiniteDiffGradient(costFunction, options) {
+    return (params) => {
+        return finiteDiffGradient(params, costFunction, options);
+    };
+}
+/**
+ * Creates a Jacobian function from a residual function using finite differences.
+ *
+ * This is a convenience wrapper around finiteDiffJacobian that returns a Jacobian
+ * function suitable for use with optimization algorithms like gaussNewton.
+ *
+ * @param residualFunction - The residual function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns A Jacobian function that can be passed to optimization algorithms
+ *
+ * @example
+ * ```typescript
+ * import { gaussNewton, createFiniteDiffJacobian } from 'numopt-js';
+ *
+ * // Define your residual function
+ * const residualFn = (params) => {
+ *   // Return residuals for curve fitting, etc.
+ *   return new Float64Array([...]);
+ * };
+ *
+ * // Create a Jacobian function
+ * const jacobianFn = createFiniteDiffJacobian(residualFn);
+ *
+ * // Use it with an optimizer
+ * const result = gaussNewton(
+ *   new Float64Array([1, 1]),
+ *   residualFn,
+ *   jacobianFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ */
+export function createFiniteDiffJacobian(residualFunction, options) {
+    return (params) => {
+        return finiteDiffJacobian(residualFunction, params, options);
+    };
+}
+//# sourceMappingURL=createGradientFunction.js.map