numopt-js 0.1.0

package/dist/core/finiteDiff.js

@@ -0,0 +1,363 @@
+/**
+ * This file implements numerical differentiation methods for computing
+ * gradients and Jacobian matrices when analytical derivatives are not available.
+ *
+ * Role in system:
+ * - Provides automatic gradient/Jacobian computation via finite differences
+ * - Used when users don't provide analytical derivatives
+ * - Critical for algorithms that require gradient information
+ *
+ * For first-time readers:
+ * - Start with finiteDiffGradient for general optimization
+ * - finiteDiffJacobian is for nonlinear least squares problems
+ * - Central difference is used for better accuracy than forward difference
+ */
+import { Matrix } from 'ml-matrix';
+const DEFAULT_STEP_SIZE = 1e-6;
+const CENTRAL_DIFFERENCE_DENOMINATOR = 2.0; // Denominator for central difference formula: (f(x+h) - f(x-h)) / (2h)
+/**
+ * Computes the gradient vector using central difference method.
+ *
+ * Central difference formula: f'(x) ≈ (f(x+h) - f(x-h)) / (2h)
+ *
+ * This is more accurate than forward difference but requires two function
+ * evaluations per parameter. The trade-off is worth it for better convergence.
+ *
+ * @param parameters - The point at which to evaluate the gradient
+ * @param costFunction - The cost function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns The gradient vector at the given parameters
+ *
+ * @example
+ * ```typescript
+ * // Standalone usage - compute gradient at a specific point
+ * const costFn = (params) => params[0] ** 2 + params[1] ** 2;
+ * const params = new Float64Array([1.0, 2.0]);
+ * const gradient = finiteDiffGradient(params, costFn);
+ * // gradient ≈ [2.0, 4.0]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage with gradientDescent - note the parameter order!
+ * import { gradientDescent, finiteDiffGradient } from 'numopt-js';
+ *
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ *
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   (params) => finiteDiffGradient(params, costFn),  // ✅ Correct: params first!
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // For easier usage with optimizers, consider using createFiniteDiffGradient:
+ * import { gradientDescent, createFiniteDiffGradient } from 'numopt-js';
+ *
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ * const gradientFn = createFiniteDiffGradient(costFn);  // No parameter order confusion!
+ *
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   gradientFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @remarks
+ * **Important:** When using with optimization algorithms, note the parameter order:
+ * - ✅ Correct: `(params) => finiteDiffGradient(params, costFn)`
+ * - ❌ Wrong: `(params) => finiteDiffGradient(costFn, params)`
+ *
+ * Consider using {@link createFiniteDiffGradient} for a more intuitive API.
+ */
+export function finiteDiffGradient(parameters, costFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const parameterCount = parameters.length;
+    const gradient = new Float64Array(parameterCount);
+    for (let i = 0; i < parameterCount; i++) {
+        // Forward point: x + h
+        const forwardParams = new Float64Array(parameters);
+        forwardParams[i] += stepSize;
+        const forwardCost = costFunction(forwardParams);
+        // Backward point: x - h
+        const backwardParams = new Float64Array(parameters);
+        backwardParams[i] -= stepSize;
+        const backwardCost = costFunction(backwardParams);
+        // Central difference: (f(x+h) - f(x-h)) / (2h)
+        gradient[i] = (forwardCost - backwardCost) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+    }
+    return gradient;
+}
+/**
+ * Computes the Jacobian matrix using central difference method.
+ *
+ * The Jacobian J has dimensions (residualCount × parameterCount) where:
+ * - Each row corresponds to a residual component
+ * - Each column corresponds to a parameter
+ * - J[i][j] = ∂r_i / ∂p_j
+ *
+ * Central difference is used for each partial derivative.
+ */
+export function finiteDiffJacobian(residualFunction, parameters, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const parameterCount = parameters.length;
+    // Compute residual at current point to determine dimension
+    const currentResidual = residualFunction(parameters);
+    const residualCount = currentResidual.length;
+    // Initialize Jacobian matrix (residualCount × parameterCount)
+    const jacobianData = [];
+    for (let i = 0; i < residualCount; i++) {
+        jacobianData.push(new Array(parameterCount).fill(0));
+    }
+    // Compute each column of the Jacobian (derivative w.r.t. each parameter)
+    for (let paramIndex = 0; paramIndex < parameterCount; paramIndex++) {
+        // Forward point: p + h * e_j (where e_j is unit vector)
+        const forwardParams = new Float64Array(parameters);
+        forwardParams[paramIndex] += stepSize;
+        const forwardResidual = residualFunction(forwardParams);
+        // Backward point: p - h * e_j
+        const backwardParams = new Float64Array(parameters);
+        backwardParams[paramIndex] -= stepSize;
+        const backwardResidual = residualFunction(backwardParams);
+        // Central difference for each residual component
+        for (let residualIndex = 0; residualIndex < residualCount; residualIndex++) {
+            const derivative = (forwardResidual[residualIndex] - backwardResidual[residualIndex]) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+            jacobianData[residualIndex][paramIndex] = derivative;
+        }
+    }
+    return new Matrix(jacobianData);
+}
+/**
+ * Computes the partial derivative of a constrained cost function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ *
+ * Formula: ∂f/∂p_i ≈ (f(p+h·e_i, x) - f(p-h·e_i, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param costFunction - Constrained cost function f(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Gradient vector ∂f/∂p
+ */
+export function finiteDiffPartialP(parameters, states, costFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const parameterCount = parameters.length;
+    const gradient = new Float64Array(parameterCount);
+    for (let i = 0; i < parameterCount; i++) {
+        // Forward point: p + h·e_i
+        const forwardParams = new Float64Array(parameters);
+        forwardParams[i] += stepSize;
+        const forwardCost = costFunction(forwardParams, states);
+        // Backward point: p - h·e_i
+        const backwardParams = new Float64Array(parameters);
+        backwardParams[i] -= stepSize;
+        const backwardCost = costFunction(backwardParams, states);
+        // Central difference: (f(p+h·e_i, x) - f(p-h·e_i, x)) / (2h)
+        gradient[i] = (forwardCost - backwardCost) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+    }
+    return gradient;
+}
+/**
+ * Computes the partial derivative of a constrained cost function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ *
+ * Formula: ∂f/∂x_i ≈ (f(p, x+h·e_i) - f(p, x-h·e_i)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param costFunction - Constrained cost function f(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Gradient vector ∂f/∂x
+ */
+export function finiteDiffPartialX(parameters, states, costFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const stateCount = states.length;
+    const gradient = new Float64Array(stateCount);
+    for (let i = 0; i < stateCount; i++) {
+        // Forward point: x + h·e_i
+        const forwardStates = new Float64Array(states);
+        forwardStates[i] += stepSize;
+        const forwardCost = costFunction(parameters, forwardStates);
+        // Backward point: x - h·e_i
+        const backwardStates = new Float64Array(states);
+        backwardStates[i] -= stepSize;
+        const backwardCost = costFunction(parameters, backwardStates);
+        // Central difference: (f(p, x+h·e_i) - f(p, x-h·e_i)) / (2h)
+        gradient[i] = (forwardCost - backwardCost) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+    }
+    return gradient;
+}
+/**
+ * Computes the partial derivative of a constraint function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ * Returns a Jacobian matrix of size (constraintCount × parameterCount).
+ *
+ * Formula: ∂c/∂p_ij ≈ (c_i(p+h·e_j, x) - c_i(p-h·e_j, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param constraintFunction - Constraint function c(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂c/∂p
+ */
+export function finiteDiffConstraintPartialP(parameters, states, constraintFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const parameterCount = parameters.length;
+    // Compute constraint at current point to determine dimension
+    const currentConstraint = constraintFunction(parameters, states);
+    const constraintCount = currentConstraint.length;
+    // Initialize Jacobian matrix (constraintCount × parameterCount)
+    const jacobianData = [];
+    for (let i = 0; i < constraintCount; i++) {
+        jacobianData.push(new Array(parameterCount).fill(0));
+    }
+    // Compute each column of the Jacobian (derivative w.r.t. each parameter)
+    for (let paramIndex = 0; paramIndex < parameterCount; paramIndex++) {
+        // Forward point: p + h·e_j
+        const forwardParams = new Float64Array(parameters);
+        forwardParams[paramIndex] += stepSize;
+        const forwardConstraint = constraintFunction(forwardParams, states);
+        // Backward point: p - h·e_j
+        const backwardParams = new Float64Array(parameters);
+        backwardParams[paramIndex] -= stepSize;
+        const backwardConstraint = constraintFunction(backwardParams, states);
+        // Central difference for each constraint component
+        for (let constraintIndex = 0; constraintIndex < constraintCount; constraintIndex++) {
+            const derivative = (forwardConstraint[constraintIndex] - backwardConstraint[constraintIndex]) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+            jacobianData[constraintIndex][paramIndex] = derivative;
+        }
+    }
+    return new Matrix(jacobianData);
+}
+/**
+ * Computes the partial derivative of a constraint function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ * Returns a Jacobian matrix of size (constraintCount × stateCount).
+ *
+ * Formula: ∂c/∂x_ij ≈ (c_i(p, x+h·e_j) - c_i(p, x-h·e_j)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param constraintFunction - Constraint function c(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂c/∂x
+ */
+export function finiteDiffConstraintPartialX(parameters, states, constraintFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const stateCount = states.length;
+    // Compute constraint at current point to determine dimension
+    const currentConstraint = constraintFunction(parameters, states);
+    const constraintCount = currentConstraint.length;
+    // Initialize Jacobian matrix (constraintCount × stateCount)
+    const jacobianData = [];
+    for (let i = 0; i < constraintCount; i++) {
+        jacobianData.push(new Array(stateCount).fill(0));
+    }
+    // Compute each column of the Jacobian (derivative w.r.t. each state)
+    for (let stateIndex = 0; stateIndex < stateCount; stateIndex++) {
+        // Forward point: x + h·e_j
+        const forwardStates = new Float64Array(states);
+        forwardStates[stateIndex] += stepSize;
+        const forwardConstraint = constraintFunction(parameters, forwardStates);
+        // Backward point: x - h·e_j
+        const backwardStates = new Float64Array(states);
+        backwardStates[stateIndex] -= stepSize;
+        const backwardConstraint = constraintFunction(parameters, backwardStates);
+        // Central difference for each constraint component
+        for (let constraintIndex = 0; constraintIndex < constraintCount; constraintIndex++) {
+            const derivative = (forwardConstraint[constraintIndex] - backwardConstraint[constraintIndex]) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+            jacobianData[constraintIndex][stateIndex] = derivative;
+        }
+    }
+    return new Matrix(jacobianData);
+}
+/**
+ * Computes the partial derivative of a constrained residual function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ * Returns a Jacobian matrix of size (residualCount × parameterCount).
+ *
+ * Formula: ∂r/∂p_ij ≈ (r_i(p+h·e_j, x) - r_i(p-h·e_j, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param residualFunction - Constrained residual function r(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂r/∂p
+ */
+export function finiteDiffResidualPartialP(parameters, states, residualFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const parameterCount = parameters.length;
+    // Compute residual at current point to determine dimension
+    const currentResidual = residualFunction(parameters, states);
+    const residualCount = currentResidual.length;
+    // Initialize Jacobian matrix (residualCount × parameterCount)
+    const jacobianData = [];
+    for (let i = 0; i < residualCount; i++) {
+        jacobianData.push(new Array(parameterCount).fill(0));
+    }
+    // Compute each column of the Jacobian (derivative w.r.t. each parameter)
+    for (let paramIndex = 0; paramIndex < parameterCount; paramIndex++) {
+        // Forward point: p + h·e_j
+        const forwardParams = new Float64Array(parameters);
+        forwardParams[paramIndex] += stepSize;
+        const forwardResidual = residualFunction(forwardParams, states);
+        // Backward point: p - h·e_j
+        const backwardParams = new Float64Array(parameters);
+        backwardParams[paramIndex] -= stepSize;
+        const backwardResidual = residualFunction(backwardParams, states);
+        // Central difference for each residual component
+        for (let residualIndex = 0; residualIndex < residualCount; residualIndex++) {
+            const derivative = (forwardResidual[residualIndex] - backwardResidual[residualIndex]) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+            jacobianData[residualIndex][paramIndex] = derivative;
+        }
+    }
+    return new Matrix(jacobianData);
+}
+/**
+ * Computes the partial derivative of a constrained residual function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ * Returns a Jacobian matrix of size (residualCount × stateCount).
+ *
+ * Formula: ∂r/∂x_ij ≈ (r_i(p, x+h·e_j) - r_i(p, x-h·e_j)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param residualFunction - Constrained residual function r(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂r/∂x
+ */
+export function finiteDiffResidualPartialX(parameters, states, residualFunction, options = {}) {
+    const stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+    const stateCount = states.length;
+    // Compute residual at current point to determine dimension
+    const currentResidual = residualFunction(parameters, states);
+    const residualCount = currentResidual.length;
+    // Initialize Jacobian matrix (residualCount × stateCount)
+    const jacobianData = [];
+    for (let i = 0; i < residualCount; i++) {
+        jacobianData.push(new Array(stateCount).fill(0));
+    }
+    // Compute each column of the Jacobian (derivative w.r.t. each state)
+    for (let stateIndex = 0; stateIndex < stateCount; stateIndex++) {
+        // Forward point: x + h·e_j
+        const forwardStates = new Float64Array(states);
+        forwardStates[stateIndex] += stepSize;
+        const forwardResidual = residualFunction(parameters, forwardStates);
+        // Backward point: x - h·e_j
+        const backwardStates = new Float64Array(states);
+        backwardStates[stateIndex] -= stepSize;
+        const backwardResidual = residualFunction(parameters, backwardStates);
+        // Central difference for each residual component
+        for (let residualIndex = 0; residualIndex < residualCount; residualIndex++) {
+            const derivative = (forwardResidual[residualIndex] - backwardResidual[residualIndex]) / (CENTRAL_DIFFERENCE_DENOMINATOR * stepSize);
+            jacobianData[residualIndex][stateIndex] = derivative;
+        }
+    }
+    return new Matrix(jacobianData);
+}
+//# sourceMappingURL=finiteDiff.js.map

package/dist/core/finiteDiff.js.map

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

package/dist/core/gaussNewton.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This file implements the Gauss-Newton method for solving nonlinear least squares problems.
+ *
+ * Role in system:
+ * - Phase 2 intermediate algorithm (builds on gradient descent concepts)
+ * - Foundation for Levenberg-Marquardt method
+ * - Specifically designed for nonlinear least squares problems
+ *
+ * For first-time readers:
+ * - Start with gaussNewton function
+ * - Understand how it solves normal equations: (J^T J) δ = -J^T r
+ * - This is a special case of Newton's method for least squares
+ */
+import type { ResidualFn, GaussNewtonOptions, OptimizationResult } from './types.js';
+/**
+ * Performs Gauss-Newton optimization for nonlinear least squares problems.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters
+ * 2. Compute residual vector r and Jacobian matrix J
+ * 3. Solve normal equations: (J^T J) δ = -J^T r
+ * 4. Update parameters: x_new = x_old + δ
+ * 5. Repeat until convergence
+ *
+ * The Gauss-Newton method approximates the Hessian as J^T J, which is
+ * exact for linear least squares and a good approximation for nonlinear cases.
+ */
+export declare function gaussNewton(initialParameters: Float64Array, residualFunction: ResidualFn, options?: GaussNewtonOptions): OptimizationResult;
+//# sourceMappingURL=gaussNewton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gaussNewton.d.ts","sourceRoot":"","sources":["../../src/core/gaussNewton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,UAAU,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,iBAAiB,EAAE,YAAY,EAC/B,gBAAgB,EAAE,UAAU,EAC5B,OAAO,GAAE,kBAAuB,GAC/B,kBAAkB,CAqIpB"}

package/dist/core/gaussNewton.js

@@ -0,0 +1,151 @@
+/**
+ * This file implements the Gauss-Newton method for solving nonlinear least squares problems.
+ *
+ * Role in system:
+ * - Phase 2 intermediate algorithm (builds on gradient descent concepts)
+ * - Foundation for Levenberg-Marquardt method
+ * - Specifically designed for nonlinear least squares problems
+ *
+ * For first-time readers:
+ * - Start with gaussNewton function
+ * - Understand how it solves normal equations: (J^T J) δ = -J^T r
+ * - This is a special case of Newton's method for least squares
+ */
+import { solve, CholeskyDecomposition } from 'ml-matrix';
+import { float64ArrayToMatrix, matrixToFloat64Array, vectorNorm, computeSumOfSquaredResiduals } from '../utils/matrix.js';
+import { checkStepSizeConvergence, checkResidualConvergence, createConvergenceResult } from './convergence.js';
+import { computeJacobianMatrix } from './jacobianComputation.js';
+import { Logger } from './logger.js';
+const DEFAULT_MAX_ITERATIONS = 1000;
+const DEFAULT_TOLERANCE = 1e-6;
+const DEFAULT_USE_NUMERIC_JACOBIAN = true;
+const DEFAULT_JACOBIAN_STEP = 1e-6;
+const NEGATIVE_COEFFICIENT = -1.0; // Coefficient for negative right-hand side in normal equations: (J^T J) δ = -J^T r
+/**
+ * Performs Gauss-Newton optimization for nonlinear least squares problems.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters
+ * 2. Compute residual vector r and Jacobian matrix J
+ * 3. Solve normal equations: (J^T J) δ = -J^T r
+ * 4. Update parameters: x_new = x_old + δ
+ * 5. Repeat until convergence
+ *
+ * The Gauss-Newton method approximates the Hessian as J^T J, which is
+ * exact for linear least squares and a good approximation for nonlinear cases.
+ */
+export function gaussNewton(initialParameters, residualFunction, options = {}) {
+    const actualOptions = options;
+    const jacobianFunction = actualOptions.jacobian;
+    const maxIterations = actualOptions.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const tolerance = actualOptions.tolerance ?? DEFAULT_TOLERANCE;
+    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);
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        // Compute residual vector
+        const residual = residualFunction(currentParameters);
+        const residualNorm = vectorNorm(residual);
+        const cost = computeSumOfSquaredResiduals(residualNorm);
+        // 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, 'gaussNewton');
+        // Compute J^T J and J^T r
+        const jacobianTranspose = jacobianMatrix.transpose();
+        const jtj = jacobianTranspose.mmul(jacobianMatrix);
+        const residualMatrix = float64ArrayToMatrix(residual);
+        const jtr = jacobianTranspose.mmul(residualMatrix);
+        // Solve normal equations: (J^T J) δ = -J^T r
+        // This gives us: δ = -(J^T J)^(-1) J^T r
+        // Try Cholesky decomposition first for efficiency (if J^T J is positive definite)
+        let step;
+        try {
+            const negativeJtr = jtr.mul(NEGATIVE_COEFFICIENT);
+            let stepMatrix;
+            try {
+                const cholesky = new CholeskyDecomposition(jtj);
+                if (cholesky.isPositiveDefinite()) {
+                    // Use Cholesky decomposition for efficiency (about 2x faster than LU)
+                    stepMatrix = cholesky.solve(negativeJtr);
+                }
+                else {
+                    // J^T J is not positive definite, fallback to LU decomposition
+                    stepMatrix = solve(jtj, negativeJtr);
+                }
+            }
+            catch (choleskyError) {
+                // Cholesky decomposition failed (non-symmetric or other issues), fallback to LU
+                stepMatrix = solve(jtj, negativeJtr);
+            }
+            step = matrixToFloat64Array(stepMatrix);
+        }
+        catch (error) {
+            // Handle singular matrix (J^T J is not invertible)
+            logger.warn('gaussNewton', iteration, 'Singular matrix encountered. Consider using Levenberg-Marquardt method for better robustness.', [
+                { key: 'Cost:', value: cost },
+                { key: 'Residual norm:', value: residualNorm }
+            ]);
+            const result = createConvergenceResult(currentParameters, iteration, false, cost, undefined);
+            return { ...result, finalResidualNorm: residualNorm };
+        }
+        // Check convergence: step size is small enough
+        const stepNorm = vectorNorm(step);
+        if (checkStepSizeConvergence(stepNorm, tolerance, iteration)) {
+            logger.info('gaussNewton', iteration, 'Converged', [
+                { key: 'Cost:', value: cost },
+                { key: 'Residual norm:', value: residualNorm },
+                { key: 'Step size:', value: stepNorm }
+            ]);
+            const result = createConvergenceResult(currentParameters, iteration, true, cost, undefined);
+            return { ...result, finalResidualNorm: residualNorm };
+        }
+        // Update parameters: x_new = x_old + δ
+        const newParameters = new Float64Array(currentParameters.length);
+        for (let i = 0; i < currentParameters.length; i++) {
+            newParameters[i] = currentParameters[i] + step[i];
+        }
+        // Compute residual for new parameters
+        const newResidual = residualFunction(newParameters);
+        const newResidualNorm = vectorNorm(newResidual);
+        const newCost = computeSumOfSquaredResiduals(newResidualNorm);
+        // Check convergence: residual norm is small enough
+        if (checkResidualConvergence(newResidualNorm, tolerance, iteration)) {
+            logger.info('gaussNewton', iteration, 'Converged', [
+                { key: 'Cost:', value: newCost },
+                { key: 'Residual norm:', value: newResidualNorm }
+            ]);
+            const result = createConvergenceResult(newParameters, iteration, true, newCost, undefined);
+            return { ...result, finalResidualNorm: newResidualNorm };
+        }
+        logger.debug('gaussNewton', iteration, 'Progress', [
+            { key: 'Cost:', value: cost },
+            { key: 'Residual norm:', value: residualNorm },
+            { key: 'Step norm:', value: stepNorm }
+        ]);
+        currentParameters = newParameters;
+    }
+    // Maximum iterations reached
+    const finalResidual = residualFunction(currentParameters);
+    const finalResidualNorm = vectorNorm(finalResidual);
+    const finalCost = computeSumOfSquaredResiduals(finalResidualNorm);
+    logger.warn('gaussNewton', undefined, 'Maximum iterations reached', [
+        { key: 'Iterations:', value: maxIterations },
+        { key: 'Final cost:', value: finalCost },
+        { key: 'Final residual norm:', value: finalResidualNorm }
+    ]);
+    return {
+        parameters: currentParameters,
+        iterations: maxIterations,
+        converged: false,
+        finalCost: finalCost,
+        finalGradientNorm: undefined,
+        finalResidualNorm: finalResidualNorm
+    };
+}
+//# sourceMappingURL=gaussNewton.js.map

package/dist/core/gaussNewton.js.map

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

package/dist/core/gradientDescent.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 type { CostFn, GradientFn, GradientDescentOptions, GradientDescentResult } from './types.js';
+/**
+ * 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 declare function gradientDescent(initialParameters: Float64Array, costFunction: CostFn, gradientFunction: GradientFn, options?: GradientDescentOptions): GradientDescentResult;
+//# sourceMappingURL=gradientDescent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gradientDescent.d.ts","sourceRoot":"","sources":["../../src/core/gradientDescent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA2OpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,iBAAiB,EAAE,YAAY,EAC/B,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,UAAU,EAC5B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA0DvB"}