numopt-js 0.1.0

package/dist/core/gradientDescent.js

@@ -0,0 +1,204 @@
+/**
+ * This file implements the gradient descent optimization algorithm.
+ *
+ * References:
+ * - Nocedal & Wright, "Numerical Optimization" (2nd ed.), Chapter 2 (steepest descent and line search basics)
+ * - Boyd & Vandenberghe, "Convex Optimization", Section 9.3 (backtracking line search with Armijo rule)
+ *
+ * Role in system:
+ * - Phase 1 foundation algorithm (simple, testable)
+ * - Establishes basic optimization framework
+ * - Used as building block for more advanced methods
+ *
+ * For first-time readers:
+ * - Start with gradientDescent function
+ * - Understand how it uses line search or fixed step size
+ * - Check convergence criteria implementation
+ */
+import { backtrackingLineSearch } from './lineSearch.js';
+import { vectorNorm, scaleVector, addVectors } from '../utils/matrix.js';
+import { checkGradientConvergence, checkStepSizeConvergence, createConvergenceResult } from './convergence.js';
+import { Logger } from './logger.js';
+const DEFAULT_MAX_ITERATIONS = 1000;
+const DEFAULT_TOLERANCE = 1e-6;
+const DEFAULT_STEP_SIZE = 0.01;
+const DEFAULT_USE_LINE_SEARCH = true;
+const ZERO_STEP_SIZE = 0.0; // Indicates line search found no valid step (not a descent direction)
+const NEGATIVE_GRADIENT_DIRECTION = -1.0; // Multiplier for negative gradient direction (steepest descent)
+/**
+ * Determines the step size for gradient descent iteration.
+ * Uses line search if enabled, otherwise uses fixed step size.
+ * Returns the step size and whether line search was used.
+ */
+function determineStepSize(currentGradient, currentParameters, costFunction, gradientFunction, useLineSearch, fixedStepSize) {
+    // Early return for fixed step size case
+    if (!useLineSearch || fixedStepSize !== undefined) {
+        return { stepSize: fixedStepSize ?? DEFAULT_STEP_SIZE, usedLineSearch: false };
+    }
+    // Use line search when enabled and no fixed step size provided
+    const searchDirection = scaleVector(currentGradient, NEGATIVE_GRADIENT_DIRECTION);
+    // Backtracking line search with Armijo condition (Boyd & Vandenberghe, Sec. 9.3)
+    // to choose a step satisfying sufficient decrease (Nocedal & Wright, Ch. 2)
+    const stepSize = backtrackingLineSearch(costFunction, gradientFunction, currentParameters, searchDirection);
+    return { stepSize, usedLineSearch: true };
+}
+/**
+ * Updates parameters by taking a step in the negative gradient direction.
+ * Returns the new parameters and the step vector.
+ */
+function updateParametersWithGradientStep(currentParameters, currentGradient, stepSize) {
+    const negativeStepSize = NEGATIVE_GRADIENT_DIRECTION * stepSize;
+    const step = scaleVector(currentGradient, negativeStepSize);
+    const newParameters = addVectors(currentParameters, step);
+    return { newParameters, step };
+}
+/**
+ * Checks gradient convergence and returns result if converged.
+ * Early return pattern to reduce nesting.
+ */
+function checkGradientConvergenceAndReturn(currentParameters, iteration, currentCost, gradientNorm, tolerance, usedLineSearchFlag, logger) {
+    if (checkGradientConvergence(gradientNorm, tolerance, iteration)) {
+        logger.info('gradientDescent', iteration, 'Converged', [
+            { key: 'Cost:', value: currentCost },
+            { key: 'Gradient norm:', value: gradientNorm }
+        ]);
+        const result = createConvergenceResult(currentParameters, iteration, true, currentCost, gradientNorm);
+        return { converged: true, result: { ...result, usedLineSearch: usedLineSearchFlag } };
+    }
+    return { converged: false };
+}
+/**
+ * Handles line search failure case.
+ * Returns convergence result indicating failure.
+ */
+function handleLineSearchFailure(currentParameters, iteration, currentCost, gradientNorm, logger) {
+    logger.warn('gradientDescent', iteration, 'Line search failed', [
+        { key: 'Cost:', value: currentCost },
+        { key: 'Gradient norm:', value: gradientNorm }
+    ]);
+    return {
+        converged: true,
+        result: {
+            parameters: currentParameters,
+            iterations: iteration,
+            converged: false,
+            finalCost: currentCost,
+            finalGradientNorm: gradientNorm,
+            usedLineSearch: true
+        }
+    };
+}
+/**
+ * Checks step size convergence and returns result if converged.
+ * Early return pattern to reduce nesting.
+ */
+function checkStepSizeConvergenceAndReturn(currentParameters, iteration, currentCost, gradientNorm, stepNorm, tolerance, newUsedLineSearch, logger) {
+    if (checkStepSizeConvergence(stepNorm, tolerance, iteration)) {
+        logger.info('gradientDescent', iteration, 'Converged', [
+            { key: 'Cost:', value: currentCost },
+            { key: 'Gradient norm:', value: gradientNorm },
+            { key: 'Step size:', value: stepNorm }
+        ]);
+        const result = createConvergenceResult(currentParameters, iteration, true, currentCost, gradientNorm);
+        return { converged: true, result: { ...result, usedLineSearch: newUsedLineSearch } };
+    }
+    return { converged: false };
+}
+/**
+ * Performs a single gradient descent iteration.
+ * Returns the updated state or a convergence result if converged.
+ */
+function performGradientDescentIteration(iteration, currentParameters, currentCost, costFunction, gradientFunction, tolerance, useLineSearch, fixedStepSize, onIteration, logger, usedLineSearchFlag) {
+    const currentGradient = gradientFunction(currentParameters);
+    const gradientNorm = vectorNorm(currentGradient); // Uses Euclidean norm for steepest descent direction (Nocedal & Wright, Ch. 2)
+    // Handle callback (different behavior for first iteration)
+    if (onIteration) {
+        const callbackIteration = iteration === 0 ? 0 : iteration;
+        onIteration(callbackIteration, currentCost, currentParameters);
+    }
+    // Check gradient convergence - early return
+    const gradientConvergenceResult = checkGradientConvergenceAndReturn(currentParameters, iteration, currentCost, gradientNorm, tolerance, usedLineSearchFlag, logger);
+    if (gradientConvergenceResult.converged && gradientConvergenceResult.result) {
+        return { converged: true, result: gradientConvergenceResult.result };
+    }
+    // Determine step size
+    const stepSizeResult = determineStepSize(currentGradient, currentParameters, costFunction, gradientFunction, useLineSearch, fixedStepSize);
+    // Early return: line search failed
+    if (stepSizeResult.stepSize === ZERO_STEP_SIZE) {
+        const failureResult = handleLineSearchFailure(currentParameters, iteration, currentCost, gradientNorm, logger);
+        return failureResult;
+    }
+    const newUsedLineSearch = usedLineSearchFlag || stepSizeResult.usedLineSearch;
+    // Update parameters
+    const { newParameters, step } = updateParametersWithGradientStep(currentParameters, currentGradient, stepSizeResult.stepSize);
+    const newCost = costFunction(newParameters);
+    // Check step size convergence - early return
+    const stepNorm = vectorNorm(step); // Step length via 2-norm for step-size convergence (Boyd & Vandenberghe, Sec. 9.3)
+    const stepSizeConvergenceResult = checkStepSizeConvergenceAndReturn(currentParameters, iteration, currentCost, gradientNorm, stepNorm, tolerance, newUsedLineSearch, logger);
+    if (stepSizeConvergenceResult.converged && stepSizeConvergenceResult.result) {
+        return { converged: true, result: stepSizeConvergenceResult.result };
+    }
+    // Log progress
+    logger.debug('gradientDescent', iteration, 'Progress', [
+        { key: 'Cost:', value: currentCost },
+        { key: 'Gradient norm:', value: gradientNorm },
+        { key: 'Step size:', value: stepSizeResult.stepSize }
+    ]);
+    return { converged: false, newParameters, newCost, newUsedLineSearch };
+}
+/**
+ * Performs gradient descent optimization to minimize a cost function.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters
+ * 2. Compute gradient at current point
+ * 3. Move in negative gradient direction (steepest descent)
+ * 4. Use line search or fixed step size to determine step
+ * 5. Repeat until convergence or max iterations
+ *
+ * Convergence criteria:
+ * - Gradient norm < tolerance
+ * - Step size < tolerance
+ * - Maximum iterations reached
+ */
+export function gradientDescent(initialParameters, costFunction, gradientFunction, options = {}) {
+    const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const tolerance = options.tolerance ?? DEFAULT_TOLERANCE;
+    const stepSize = options.stepSize;
+    const useLineSearch = options.useLineSearch ?? DEFAULT_USE_LINE_SEARCH;
+    const onIteration = options.onIteration;
+    const logger = new Logger(options.logLevel, options.verbose);
+    let currentParameters = new Float64Array(initialParameters);
+    let currentCost = costFunction(currentParameters);
+    let usedLineSearchFlag = false;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        const iterationResult = performGradientDescentIteration(iteration, currentParameters, currentCost, costFunction, gradientFunction, tolerance, useLineSearch, stepSize, onIteration, logger, usedLineSearchFlag);
+        if (iterationResult.converged && iterationResult.result) {
+            return iterationResult.result;
+        }
+        if (iterationResult.newParameters && iterationResult.newCost !== undefined) {
+            currentParameters = new Float64Array(iterationResult.newParameters);
+            currentCost = iterationResult.newCost;
+            if (iterationResult.newUsedLineSearch !== undefined) {
+                usedLineSearchFlag = iterationResult.newUsedLineSearch;
+            }
+        }
+    }
+    // Maximum iterations reached
+    const finalGradient = gradientFunction(currentParameters);
+    const finalGradientNorm = vectorNorm(finalGradient);
+    logger.warn('gradientDescent', undefined, 'Maximum iterations reached', [
+        { key: 'Iterations:', value: maxIterations },
+        { key: 'Final cost:', value: currentCost },
+        { key: 'Final gradient norm:', value: finalGradientNorm }
+    ]);
+    return {
+        parameters: currentParameters,
+        iterations: maxIterations,
+        converged: false,
+        finalCost: currentCost,
+        finalGradientNorm: finalGradientNorm,
+        usedLineSearch: usedLineSearchFlag
+    };
+}
+//# sourceMappingURL=gradientDescent.js.map

package/dist/core/gradientDescent.js.map

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

package/dist/core/jacobianComputation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file provides a shared function for computing Jacobian matrices
+ * using analytical functions or numerical differentiation.
+ *
+ * Role in system:
+ * - Eliminates code duplication between Gauss-Newton and Levenberg-Marquardt
+ * - Centralizes Jacobian computation logic (DRY principle)
+ * - Used by both least squares optimization algorithms
+ *
+ * For first-time readers:
+ * - This is a utility function used internally by optimization algorithms
+ * - Prefers analytical Jacobian if provided, falls back to numerical differentiation
+ */
+import { Matrix } from 'ml-matrix';
+import type { ResidualFn, JacobianFn } from './types.js';
+/**
+ * Computes the Jacobian matrix using analytical function or numerical differentiation.
+ * Early return pattern: prefers analytical Jacobian if available.
+ *
+ * This function is shared between Gauss-Newton and Levenberg-Marquardt algorithms
+ * to avoid code duplication.
+ */
+export declare function computeJacobianMatrix(jacobianFunction: JacobianFn | undefined, residualFunction: ResidualFn, parameters: Float64Array, useNumericJacobian: boolean, jacobianStep: number, algorithmName: string): Matrix;
+//# sourceMappingURL=jacobianComputation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jacobianComputation.d.ts","sourceRoot":"","sources":["../../src/core/jacobianComputation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGzD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,UAAU,GAAG,SAAS,EACxC,gBAAgB,EAAE,UAAU,EAC5B,UAAU,EAAE,YAAY,EACxB,kBAAkB,EAAE,OAAO,EAC3B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,MAAM,CAmBR"}

package/dist/core/jacobianComputation.js

@@ -0,0 +1,38 @@
+/**
+ * This file provides a shared function for computing Jacobian matrices
+ * using analytical functions or numerical differentiation.
+ *
+ * Role in system:
+ * - Eliminates code duplication between Gauss-Newton and Levenberg-Marquardt
+ * - Centralizes Jacobian computation logic (DRY principle)
+ * - Used by both least squares optimization algorithms
+ *
+ * For first-time readers:
+ * - This is a utility function used internally by optimization algorithms
+ * - Prefers analytical Jacobian if provided, falls back to numerical differentiation
+ */
+import { finiteDiffJacobian } from './finiteDiff.js';
+/**
+ * Computes the Jacobian matrix using analytical function or numerical differentiation.
+ * Early return pattern: prefers analytical Jacobian if available.
+ *
+ * This function is shared between Gauss-Newton and Levenberg-Marquardt algorithms
+ * to avoid code duplication.
+ */
+export function computeJacobianMatrix(jacobianFunction, residualFunction, parameters, useNumericJacobian, jacobianStep, algorithmName) {
+    // Early return: use analytical Jacobian if provided
+    if (jacobianFunction) {
+        return jacobianFunction(parameters);
+    }
+    // Early return: use numerical Jacobian if enabled
+    if (useNumericJacobian) {
+        return finiteDiffJacobian(residualFunction, parameters, { stepSize: jacobianStep });
+    }
+    // Neither provided: throw error with helpful message
+    throw new Error('Jacobian computation is required but not provided. ' +
+        `Please either:\n` +
+        `  1. Provide a jacobian in options: ${algorithmName}(params, residualFn, { jacobian: jacobianFn })\n` +
+        `  2. Enable numerical Jacobian: ${algorithmName}(params, residualFn, { useNumericJacobian: true })\n` +
+        'Note: Numerical Jacobian is enabled by default. If you see this error, it may have been explicitly disabled.');
+}
+//# sourceMappingURL=jacobianComputation.js.map

package/dist/core/jacobianComputation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jacobianComputation.js","sourceRoot":"","sources":["../../src/core/jacobianComputation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,gBAAwC,EACxC,gBAA4B,EAC5B,UAAwB,EACxB,kBAA2B,EAC3B,YAAoB,EACpB,aAAqB;IAErB,oDAAoD;IACpD,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,gBAAgB,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAED,kDAAkD;IAClD,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,kBAAkB,CAAC,gBAAgB,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,qDAAqD;IACrD,MAAM,IAAI,KAAK,CACb,qDAAqD;QACrD,kBAAkB;QAClB,uCAAuC,aAAa,kDAAkD;QACtG,mCAAmC,aAAa,sDAAsD;QACtG,8GAA8G,CAC/G,CAAC;AACJ,CAAC"}

package/dist/core/levenbergMarquardt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * This file implements the Levenberg-Marquardt algorithm for solving
+ * nonlinear least squares problems, following the derivations in:
+ * - Moré, "The Levenberg-Marquardt Algorithm: Implementation and Theory", 1978 (Lecture Notes in Mathematics 630)
+ * - Lourakis, "A Brief Description of the Levenberg-Marquardt Algorithm", 2005 tutorial
+ *
+ * Role in system:
+ * - Phase 3 advanced algorithm (main MVP target)
+ * - Combines Gauss-Newton method with damping for robustness
+ * - Handles cases where Gauss-Newton might fail (singular matrices, poor conditioning)
+ *
+ * For first-time readers:
+ * - Start with levenbergMarquardt function
+ * - Understand lambda (damping parameter) update strategy
+ * - Check convergence criteria implementation
+ * - Debug features (callbacks, verbose logging) are top priority
+ */
+import type { ResidualFn, LevenbergMarquardtOptions, LevenbergMarquardtResult } from './types.js';
+/**
+ * Performs Levenberg-Marquardt optimization for nonlinear least squares problems.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters and lambda (damping parameter)
+ * 2. Compute residual vector r and Jacobian matrix J
+ * 3. Solve damped normal equations: (J^T J + λI) δ = -J^T r
+ * 4. Try step: x_new = x_old + δ
+ * 5. If cost decreases: accept step, decrease lambda
+ * 6. If cost increases: reject step, increase lambda
+ * 7. Repeat until convergence
+ *
+ * The damping parameter lambda interpolates between:
+ * - Gauss-Newton (λ → 0): fast convergence near solution
+ * - Gradient descent (λ → ∞): robust but slow
+ */
+export declare function levenbergMarquardt(initialParameters: Float64Array, residualFunction: ResidualFn, options?: LevenbergMarquardtOptions): LevenbergMarquardtResult;
+//# sourceMappingURL=levenbergMarquardt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"levenbergMarquardt.d.ts","sourceRoot":"","sources":["../../src/core/levenbergMarquardt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACV,UAAU,EAEV,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAgKpB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,YAAY,EAC/B,gBAAgB,EAAE,UAAU,EAC5B,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CAiN1B"}

package/dist/core/levenbergMarquardt.js

@@ -0,0 +1,286 @@
+/**
+ * This file implements the Levenberg-Marquardt algorithm for solving
+ * nonlinear least squares problems, following the derivations in:
+ * - Moré, "The Levenberg-Marquardt Algorithm: Implementation and Theory", 1978 (Lecture Notes in Mathematics 630)
+ * - Lourakis, "A Brief Description of the Levenberg-Marquardt Algorithm", 2005 tutorial
+ *
+ * Role in system:
+ * - Phase 3 advanced algorithm (main MVP target)
+ * - Combines Gauss-Newton method with damping for robustness
+ * - Handles cases where Gauss-Newton might fail (singular matrices, poor conditioning)
+ *
+ * For first-time readers:
+ * - Start with levenbergMarquardt function
+ * - Understand lambda (damping parameter) update strategy
+ * - Check convergence criteria implementation
+ * - Debug features (callbacks, verbose logging) are top priority
+ */
+import { Matrix, solve, CholeskyDecomposition } from 'ml-matrix';
+import { float64ArrayToMatrix, matrixToFloat64Array, vectorNorm, computeSumOfSquaredResiduals } from '../utils/matrix.js';
+import { checkGradientConvergence, checkStepSizeConvergence, checkResidualConvergence } from './convergence.js';
+import { computeJacobianMatrix } from './jacobianComputation.js';
+import { Logger } from './logger.js';
+const DEFAULT_MAX_ITERATIONS = 1000;
+const DEFAULT_LAMBDA_INITIAL = 1e-3;
+const DEFAULT_LAMBDA_FACTOR = 10.0;
+const DEFAULT_TOL_GRADIENT = 1e-6;
+const DEFAULT_TOL_STEP = 1e-6;
+const DEFAULT_TOL_RESIDUAL = 1e-6;
+const DEFAULT_USE_NUMERIC_JACOBIAN = true;
+const DEFAULT_JACOBIAN_STEP = 1e-6;
+const MAXIMUM_LAMBDA_THRESHOLD = 1e10; // Maximum lambda before giving up (prevents infinite loop)
+const NEGATIVE_COEFFICIENT = -1.0; // Coefficient for negative right-hand side in damped normal equations: (J^T J + λI) δ = -J^T r
+/**
+ * Computes J^T J and J^T r matrices needed for normal equations.
+ * Returns both matrices for use in solving damped normal equations.
+ */
+function computeNormalEquationsMatrices(jacobianMatrix, residual) {
+    const jacobianTranspose = jacobianMatrix.transpose();
+    const jtj = jacobianTranspose.mmul(jacobianMatrix);
+    const residualMatrix = float64ArrayToMatrix(residual);
+    const jtr = jacobianTranspose.mmul(residualMatrix);
+    return { jtj, jtr };
+}
+/**
+ * Creates a convergence result object for Levenberg-Marquardt algorithm.
+ * Centralizes result creation to avoid code duplication.
+ */
+function createConvergenceResultForLM(parameters, iteration, converged, finalCost, finalGradientNorm, finalResidualNorm, finalLambda) {
+    return {
+        parameters,
+        iterations: iteration + 1,
+        converged,
+        finalCost,
+        finalGradientNorm,
+        finalResidualNorm,
+        finalLambda
+    };
+}
+/**
+ * Tries a Levenberg-Marquardt step by solving damped normal equations.
+ * Returns whether step was accepted and updated parameters/lambda.
+ */
+function tryLevenbergMarquardtStep(jtj, jtr, currentParameters, currentLambda, lambdaFactor, residualFunction, currentCost, tolStep, iteration, logger) {
+    // Early return: lambda too large
+    if (currentLambda >= MAXIMUM_LAMBDA_THRESHOLD) {
+        logger.warn('levenbergMarquardt', iteration, 'Lambda too large, stopping optimization', [
+            { key: 'Lambda:', value: currentLambda },
+            { key: 'Cost:', value: currentCost }
+        ]);
+        return { stepAccepted: false, newLambda: currentLambda, shouldStop: true };
+    }
+    try {
+        // Add damping: J^T J + λI
+        const parameterCount = jtj.rows;
+        const identity = Matrix.eye(parameterCount, parameterCount);
+        const dampedHessian = jtj.add(identity.mul(currentLambda));
+        // Solve: (J^T J + λI) δ = -J^T r
+        // Use Cholesky decomposition for efficiency (dampedHessian is always positive definite when λ > 0)
+        const negativeJtr = jtr.mul(NEGATIVE_COEFFICIENT);
+        let stepMatrix;
+        try {
+            const cholesky = new CholeskyDecomposition(dampedHessian);
+            if (cholesky.isPositiveDefinite()) {
+                stepMatrix = cholesky.solve(negativeJtr);
+            }
+            else {
+                // Fallback to LU decomposition if Cholesky fails (should not happen when λ > 0)
+                stepMatrix = solve(dampedHessian, negativeJtr);
+            }
+        }
+        catch (choleskyError) {
+            // Fallback to LU decomposition if Cholesky decomposition fails
+            stepMatrix = solve(dampedHessian, negativeJtr);
+        }
+        const step = matrixToFloat64Array(stepMatrix);
+        const stepNorm = vectorNorm(step);
+        // Check step size convergence (termination test suggested in Lourakis 2005, Section 5)
+        if (checkStepSizeConvergence(stepNorm, tolStep, iteration)) {
+            return { stepAccepted: false, newLambda: currentLambda, stepNorm };
+        }
+        // Try the step: x_new = x_old + δ
+        const newParameters = new Float64Array(currentParameters.length);
+        for (let i = 0; i < currentParameters.length; i++) {
+            newParameters[i] = currentParameters[i] + step[i];
+        }
+        const newResidual = residualFunction(newParameters);
+        const newResidualNorm = vectorNorm(newResidual);
+        const newCost = computeSumOfSquaredResiduals(newResidualNorm);
+        // Check if step improved the cost
+        if (newCost < currentCost) {
+            // Step successful: accept it and decrease lambda
+            // (trust-region style update per Moré 1978, Section 4 and Lourakis 2005, Section 4.1)
+            const newLambda = currentLambda / lambdaFactor;
+            logger.debug('levenbergMarquardt', iteration, 'Step accepted', [
+                { key: 'Cost:', value: currentCost },
+                { key: 'New cost:', value: newCost },
+                { key: 'Lambda:', value: newLambda }
+            ]);
+            return { stepAccepted: true, newParameters, newLambda };
+        }
+        // Step failed: reject it and increase lambda
+        // (damping increase strategy from Moré 1978, Section 4 and Lourakis 2005, Section 4.1)
+        const newLambda = currentLambda * lambdaFactor;
+        logger.debug('levenbergMarquardt', iteration, 'Step rejected', [
+            { key: 'Cost:', value: currentCost },
+            { key: 'New cost:', value: newCost },
+            { key: 'Lambda:', value: newLambda }
+        ]);
+        return { stepAccepted: false, newLambda };
+    }
+    catch (error) {
+        // Singular matrix or numerical issues: increase lambda and retry
+        const newLambda = currentLambda * lambdaFactor;
+        logger.warn('levenbergMarquardt', iteration, 'Singular matrix encountered, increasing lambda', [
+            { key: 'Lambda:', value: newLambda },
+            { key: 'Cost:', value: currentCost }
+        ]);
+        return { stepAccepted: false, newLambda };
+    }
+}
+/**
+ * Performs Levenberg-Marquardt optimization for nonlinear least squares problems.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters and lambda (damping parameter)
+ * 2. Compute residual vector r and Jacobian matrix J
+ * 3. Solve damped normal equations: (J^T J + λI) δ = -J^T r
+ * 4. Try step: x_new = x_old + δ
+ * 5. If cost decreases: accept step, decrease lambda
+ * 6. If cost increases: reject step, increase lambda
+ * 7. Repeat until convergence
+ *
+ * The damping parameter lambda interpolates between:
+ * - Gauss-Newton (λ → 0): fast convergence near solution
+ * - Gradient descent (λ → ∞): robust but slow
+ */
+export function levenbergMarquardt(initialParameters, residualFunction, options = {}) {
+    const actualOptions = options;
+    const jacobianFunction = actualOptions.jacobian;
+    const maxIterations = actualOptions.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const lambdaInitial = actualOptions.lambdaInitial ?? DEFAULT_LAMBDA_INITIAL;
+    const lambdaFactor = actualOptions.lambdaFactor ?? DEFAULT_LAMBDA_FACTOR;
+    const tolGradient = actualOptions.tolGradient ?? DEFAULT_TOL_GRADIENT;
+    const tolStep = actualOptions.tolStep ?? DEFAULT_TOL_STEP;
+    const tolResidual = actualOptions.tolResidual ?? DEFAULT_TOL_RESIDUAL;
+    const useNumericJacobian = actualOptions.useNumericJacobian ?? DEFAULT_USE_NUMERIC_JACOBIAN;
+    const jacobianStep = actualOptions.jacobianStep ?? DEFAULT_JACOBIAN_STEP;
+    const onIteration = actualOptions.onIteration;
+    const logger = new Logger(actualOptions.logLevel, actualOptions.verbose);
+    let currentParameters = new Float64Array(initialParameters);
+    let currentLambda = lambdaInitial;
+    let bestParameters = new Float64Array(initialParameters);
+    let bestCost = Infinity;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        // Compute residual vector
+        const residual = residualFunction(currentParameters);
+        const residualNorm = vectorNorm(residual);
+        const cost = computeSumOfSquaredResiduals(residualNorm);
+        // Track best solution so far
+        if (cost < bestCost) {
+            bestCost = cost;
+            bestParameters = new Float64Array(currentParameters);
+        }
+        // Call progress callback if provided
+        if (onIteration) {
+            onIteration(iteration, cost, currentParameters);
+        }
+        // Compute Jacobian matrix
+        // Early return: use analytical Jacobian if provided
+        const jacobianMatrix = computeJacobianMatrix(jacobianFunction, residualFunction, currentParameters, useNumericJacobian, jacobianStep, 'levenbergMarquardt');
+        // Compute J^T J and J^T r
+        const { jtj, jtr } = computeNormalEquationsMatrices(jacobianMatrix, residual);
+        // Compute gradient norm: ||J^T r||
+        const gradientVector = matrixToFloat64Array(jtr);
+        const gradientNorm = vectorNorm(gradientVector);
+        // Check convergence: gradient norm is small enough (Moré 1978, Section 4 termination test; Lourakis 2005, Section 5)
+        if (checkGradientConvergence(gradientNorm, tolGradient, iteration)) {
+            logger.info('levenbergMarquardt', iteration, 'Converged', [
+                { key: 'Cost:', value: cost },
+                { key: 'Gradient norm:', value: gradientNorm },
+                { key: 'Residual norm:', value: residualNorm },
+                { key: 'Lambda:', value: currentLambda }
+            ]);
+            return createConvergenceResultForLM(currentParameters, iteration, true, cost, gradientNorm, residualNorm, currentLambda);
+        }
+        // Try to solve damped normal equations: (J^T J + λI) δ = -J^T r
+        let stepAccepted = false;
+        while (!stepAccepted && currentLambda < MAXIMUM_LAMBDA_THRESHOLD) {
+            const stepResult = tryLevenbergMarquardtStep(jtj, jtr, currentParameters, currentLambda, lambdaFactor, residualFunction, cost, tolStep, iteration, logger);
+            // Early return: lambda too large
+            if (stepResult.shouldStop) {
+                return createConvergenceResultForLM(bestParameters, iteration, false, bestCost, gradientNorm, residualNorm, stepResult.newLambda);
+            }
+            // Early return: step size convergence (Lourakis 2005, Section 5)
+            if (stepResult.stepNorm !== undefined && checkStepSizeConvergence(stepResult.stepNorm, tolStep, iteration)) {
+                logger.info('levenbergMarquardt', iteration, 'Converged', [
+                    { key: 'Cost:', value: cost },
+                    { key: 'Gradient norm:', value: gradientNorm },
+                    { key: 'Residual norm:', value: residualNorm },
+                    { key: 'Step size:', value: stepResult.stepNorm },
+                    { key: 'Lambda:', value: currentLambda }
+                ]);
+                return createConvergenceResultForLM(currentParameters, iteration, true, cost, gradientNorm, residualNorm, currentLambda);
+            }
+            // Update lambda
+            currentLambda = stepResult.newLambda;
+            // Accept step if successful
+            if (stepResult.stepAccepted && stepResult.newParameters) {
+                currentParameters = new Float64Array(stepResult.newParameters);
+                stepAccepted = true;
+            }
+        }
+        // Check if step was never accepted (lambda became too large)
+        if (!stepAccepted && currentLambda >= MAXIMUM_LAMBDA_THRESHOLD) {
+            logger.warn('levenbergMarquardt', iteration, 'Could not find acceptable step even with maximum lambda. Stopping optimization.', [
+                { key: 'Lambda:', value: currentLambda },
+                { key: 'Cost:', value: cost },
+                { key: 'Best cost:', value: bestCost }
+            ]);
+            const finalResidual = residualFunction(bestParameters);
+            const finalResidualNorm = vectorNorm(finalResidual);
+            const finalGradient = jacobianFunction
+                ? matrixToFloat64Array(jacobianFunction(bestParameters).transpose().mmul(float64ArrayToMatrix(finalResidual)))
+                : undefined;
+            const finalGradientNorm = finalGradient ? vectorNorm(finalGradient) : undefined;
+            return createConvergenceResultForLM(bestParameters, iteration, false, bestCost, finalGradientNorm ?? gradientNorm, finalResidualNorm, currentLambda);
+        }
+        // Check residual norm convergence (Moré 1978, Section 4 stopping rule; Lourakis 2005, Section 5)
+        const currentResidual = residualFunction(currentParameters);
+        const currentResidualNorm = vectorNorm(currentResidual);
+        const currentCost = computeSumOfSquaredResiduals(currentResidualNorm);
+        if (checkResidualConvergence(currentResidualNorm, tolResidual, iteration)) {
+            logger.info('levenbergMarquardt', iteration, 'Converged', [
+                { key: 'Cost:', value: currentCost },
+                { key: 'Gradient norm:', value: gradientNorm },
+                { key: 'Residual norm:', value: currentResidualNorm },
+                { key: 'Lambda:', value: currentLambda }
+            ]);
+            return createConvergenceResultForLM(currentParameters, iteration, true, currentCost, gradientNorm, currentResidualNorm, currentLambda);
+        }
+    }
+    // Maximum iterations reached - return best solution found
+    const finalResidual = residualFunction(bestParameters);
+    const finalResidualNorm = vectorNorm(finalResidual);
+    const finalGradient = jacobianFunction
+        ? matrixToFloat64Array(jacobianFunction(bestParameters).transpose().mmul(float64ArrayToMatrix(finalResidual)))
+        : undefined;
+    const finalGradientNorm = finalGradient ? vectorNorm(finalGradient) : undefined;
+    logger.warn('levenbergMarquardt', undefined, 'Maximum iterations reached', [
+        { key: 'Iterations:', value: maxIterations },
+        { key: 'Final cost:', value: bestCost },
+        { key: 'Final gradient norm:', value: finalGradientNorm ?? 0 },
+        { key: 'Final residual norm:', value: finalResidualNorm },
+        { key: 'Final lambda:', value: currentLambda }
+    ]);
+    return {
+        parameters: bestParameters,
+        iterations: maxIterations,
+        converged: false,
+        finalCost: bestCost,
+        finalGradientNorm: finalGradientNorm,
+        finalResidualNorm: finalResidualNorm,
+        finalLambda: currentLambda
+    };
+}
+//# sourceMappingURL=levenbergMarquardt.js.map

package/dist/core/levenbergMarquardt.js.map

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