numopt-js 0.1.0

package/dist/utils/matrix.d.ts

@@ -0,0 +1,63 @@
+/**
+ * This file provides utility functions for converting between Float64Array
+ * and ml-matrix Matrix types, and for vector operations.
+ *
+ * Role in system:
+ * - Bridges the gap between native JavaScript arrays and ml-matrix library
+ * - Provides efficient conversion utilities used throughout the codebase
+ * - Implements common vector operations needed by optimization algorithms
+ *
+ * For first-time readers:
+ * - These are helper functions used by core algorithms
+ * - Focus on understanding the conversion functions first
+ * - Vector norm computation is used for convergence checks
+ */
+import { Matrix } from 'ml-matrix';
+/**
+ * Converts a Float64Array to an ml-matrix Matrix (column vector).
+ * This is efficient for single-column matrices used in optimization.
+ */
+export declare function float64ArrayToMatrix(vector: Float64Array): Matrix;
+/**
+ * Converts an ml-matrix Matrix to a Float64Array.
+ * Assumes the matrix is a column vector (single column).
+ */
+export declare function matrixToFloat64Array(matrix: Matrix): Float64Array;
+/**
+ * Converts a 2D ml-matrix Matrix to a Float64Array (row-major order).
+ * Used for converting Jacobian matrices to flat arrays when needed.
+ */
+export declare function matrixToFloat64Array2D(matrix: Matrix): Float64Array;
+/**
+ * Computes the L2 (Euclidean) norm of a Float64Array vector.
+ * Used for convergence checks and gradient norm calculations.
+ */
+export declare function vectorNorm(vector: Float64Array): number;
+/**
+ * Computes the dot product of two Float64Array vectors.
+ * Both vectors must have the same length.
+ */
+export declare function dotProduct(vectorA: Float64Array, vectorB: Float64Array): number;
+/**
+ * Adds two Float64Array vectors element-wise.
+ * Returns a new Float64Array with the result.
+ */
+export declare function addVectors(vectorA: Float64Array, vectorB: Float64Array): Float64Array;
+/**
+ * Subtracts vectorB from vectorA element-wise.
+ * Returns a new Float64Array with the result.
+ */
+export declare function subtractVectors(vectorA: Float64Array, vectorB: Float64Array): Float64Array;
+/**
+ * Multiplies a Float64Array vector by a scalar.
+ * Returns a new Float64Array with the result.
+ */
+export declare function scaleVector(vector: Float64Array, scalar: number): Float64Array;
+/**
+ * Computes the sum of squared residuals (cost function for least squares problems).
+ * This is the squared L2 norm: ||r||^2 = r^T r = sum(r_i^2)
+ *
+ * Used to avoid code duplication when computing cost from residual norm.
+ */
+export declare function computeSumOfSquaredResiduals(residualNorm: number): number;
+//# sourceMappingURL=matrix.d.ts.map

package/dist/utils/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/utils/matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CASjE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CASjE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAYnE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CASvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAY/E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAYrF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAY1F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAQ9E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/dist/utils/matrix.js

@@ -0,0 +1,129 @@
+/**
+ * This file provides utility functions for converting between Float64Array
+ * and ml-matrix Matrix types, and for vector operations.
+ *
+ * Role in system:
+ * - Bridges the gap between native JavaScript arrays and ml-matrix library
+ * - Provides efficient conversion utilities used throughout the codebase
+ * - Implements common vector operations needed by optimization algorithms
+ *
+ * For first-time readers:
+ * - These are helper functions used by core algorithms
+ * - Focus on understanding the conversion functions first
+ * - Vector norm computation is used for convergence checks
+ */
+import { Matrix } from 'ml-matrix';
+/**
+ * Converts a Float64Array to an ml-matrix Matrix (column vector).
+ * This is efficient for single-column matrices used in optimization.
+ */
+export function float64ArrayToMatrix(vector) {
+    const rows = vector.length;
+    const matrixData = [];
+    for (let i = 0; i < rows; i++) {
+        matrixData.push([vector[i]]);
+    }
+    return new Matrix(matrixData);
+}
+/**
+ * Converts an ml-matrix Matrix to a Float64Array.
+ * Assumes the matrix is a column vector (single column).
+ */
+export function matrixToFloat64Array(matrix) {
+    const rows = matrix.rows;
+    const result = new Float64Array(rows);
+    for (let i = 0; i < rows; i++) {
+        result[i] = matrix.get(i, 0);
+    }
+    return result;
+}
+/**
+ * Converts a 2D ml-matrix Matrix to a Float64Array (row-major order).
+ * Used for converting Jacobian matrices to flat arrays when needed.
+ */
+export function matrixToFloat64Array2D(matrix) {
+    const rows = matrix.rows;
+    const cols = matrix.columns;
+    const result = new Float64Array(rows * cols);
+    for (let i = 0; i < rows; i++) {
+        for (let j = 0; j < cols; j++) {
+            result[i * cols + j] = matrix.get(i, j);
+        }
+    }
+    return result;
+}
+/**
+ * Computes the L2 (Euclidean) norm of a Float64Array vector.
+ * Used for convergence checks and gradient norm calculations.
+ */
+export function vectorNorm(vector) {
+    let sumOfSquares = 0.0;
+    for (let i = 0; i < vector.length; i++) {
+        const value = vector[i];
+        sumOfSquares += value * value;
+    }
+    return Math.sqrt(sumOfSquares);
+}
+/**
+ * Computes the dot product of two Float64Array vectors.
+ * Both vectors must have the same length.
+ */
+export function dotProduct(vectorA, vectorB) {
+    if (vectorA.length !== vectorB.length) {
+        throw new Error('Vectors must have the same length for dot product');
+    }
+    let sum = 0.0;
+    for (let i = 0; i < vectorA.length; i++) {
+        sum += vectorA[i] * vectorB[i];
+    }
+    return sum;
+}
+/**
+ * Adds two Float64Array vectors element-wise.
+ * Returns a new Float64Array with the result.
+ */
+export function addVectors(vectorA, vectorB) {
+    if (vectorA.length !== vectorB.length) {
+        throw new Error('Vectors must have the same length for addition');
+    }
+    const result = new Float64Array(vectorA.length);
+    for (let i = 0; i < vectorA.length; i++) {
+        result[i] = vectorA[i] + vectorB[i];
+    }
+    return result;
+}
+/**
+ * Subtracts vectorB from vectorA element-wise.
+ * Returns a new Float64Array with the result.
+ */
+export function subtractVectors(vectorA, vectorB) {
+    if (vectorA.length !== vectorB.length) {
+        throw new Error('Vectors must have the same length for subtraction');
+    }
+    const result = new Float64Array(vectorA.length);
+    for (let i = 0; i < vectorA.length; i++) {
+        result[i] = vectorA[i] - vectorB[i];
+    }
+    return result;
+}
+/**
+ * Multiplies a Float64Array vector by a scalar.
+ * Returns a new Float64Array with the result.
+ */
+export function scaleVector(vector, scalar) {
+    const result = new Float64Array(vector.length);
+    for (let i = 0; i < vector.length; i++) {
+        result[i] = vector[i] * scalar;
+    }
+    return result;
+}
+/**
+ * Computes the sum of squared residuals (cost function for least squares problems).
+ * This is the squared L2 norm: ||r||^2 = r^T r = sum(r_i^2)
+ *
+ * Used to avoid code duplication when computing cost from residual norm.
+ */
+export function computeSumOfSquaredResiduals(residualNorm) {
+    return residualNorm * residualNorm;
+}
+//# sourceMappingURL=matrix.js.map

package/dist/utils/matrix.js.map

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

package/dist/utils/resultFormatter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * This file provides helper functions for formatting and displaying
+ * optimization results in a consistent, user-friendly manner.
+ *
+ * Role in system:
+ * - Replaces repetitive console.log statements in examples
+ * - Provides consistent formatting across all result types
+ * - Improves UI/UX with better readability and structure
+ *
+ * For first-time readers:
+ * - Use printOptimizationResult() for direct console output
+ * - Use formatOptimizationResult() to get formatted string
+ * - Functions automatically handle different result types via overloading
+ */
+import type { OptimizationResult, GradientDescentResult, LevenbergMarquardtResult, AdjointGradientDescentResult, ConstrainedGaussNewtonResult, ConstrainedLevenbergMarquardtResult } from '../core/types.js';
+/**
+ * Options for customizing result formatting.
+ */
+export interface ResultFormatterOptions {
+    /**
+     * Whether to show section headers (e.g., "=== Optimization Results ===").
+     * Default: true
+     */
+    showSectionHeaders?: boolean;
+    /**
+     * Whether to show execution time information.
+     * Default: false (requires elapsedTimeMs to be provided)
+     */
+    showExecutionTime?: boolean;
+    /**
+     * Execution time in milliseconds (for display).
+     * Only used if showExecutionTime is true.
+     */
+    elapsedTimeMs?: number;
+    /**
+     * Maximum number of parameters to display before truncating.
+     * Default: 10
+     */
+    maxParametersToShow?: number;
+    /**
+     * Precision for parameter values.
+     * Default: 6
+     */
+    parameterPrecision?: number;
+    /**
+     * Precision for cost and norm values.
+     * Default: 8
+     */
+    costPrecision?: number;
+    /**
+     * Precision for constraint violation values.
+     * Default: 10
+     */
+    constraintPrecision?: number;
+}
+/**
+ * Formats a basic OptimizationResult.
+ */
+export declare function formatOptimizationResult(result: OptimizationResult, options?: ResultFormatterOptions): string;
+/**
+ * Formats a GradientDescentResult.
+ */
+export declare function formatGradientDescentResult(result: GradientDescentResult, options?: ResultFormatterOptions): string;
+/**
+ * Formats a LevenbergMarquardtResult.
+ */
+export declare function formatLevenbergMarquardtResult(result: LevenbergMarquardtResult, options?: ResultFormatterOptions): string;
+/**
+ * Formats a ConstrainedGaussNewtonResult.
+ */
+export declare function formatConstrainedGaussNewtonResult(result: ConstrainedGaussNewtonResult, options?: ResultFormatterOptions): string;
+/**
+ * Formats a ConstrainedLevenbergMarquardtResult.
+ */
+export declare function formatConstrainedLevenbergMarquardtResult(result: ConstrainedLevenbergMarquardtResult, options?: ResultFormatterOptions): string;
+/**
+ * Formats an AdjointGradientDescentResult.
+ */
+export declare function formatAdjointGradientDescentResult(result: AdjointGradientDescentResult, options?: ResultFormatterOptions): string;
+/**
+ * Type-safe overloaded function for formatting any optimization result.
+ */
+export declare function formatResult(result: OptimizationResult, options?: ResultFormatterOptions): string;
+export declare function formatResult(result: GradientDescentResult, options?: ResultFormatterOptions): string;
+export declare function formatResult(result: LevenbergMarquardtResult, options?: ResultFormatterOptions): string;
+export declare function formatResult(result: ConstrainedGaussNewtonResult, options?: ResultFormatterOptions): string;
+export declare function formatResult(result: ConstrainedLevenbergMarquardtResult, options?: ResultFormatterOptions): string;
+export declare function formatResult(result: AdjointGradientDescentResult, options?: ResultFormatterOptions): string;
+/**
+ * Prints an optimization result directly to console.
+ */
+export declare function printOptimizationResult(result: OptimizationResult, options?: ResultFormatterOptions): void;
+/**
+ * Prints a gradient descent result directly to console.
+ */
+export declare function printGradientDescentResult(result: GradientDescentResult, options?: ResultFormatterOptions): void;
+/**
+ * Prints a Levenberg-Marquardt result directly to console.
+ */
+export declare function printLevenbergMarquardtResult(result: LevenbergMarquardtResult, options?: ResultFormatterOptions): void;
+/**
+ * Prints a constrained Gauss-Newton result directly to console.
+ */
+export declare function printConstrainedGaussNewtonResult(result: ConstrainedGaussNewtonResult, options?: ResultFormatterOptions): void;
+/**
+ * Prints a constrained Levenberg-Marquardt result directly to console.
+ */
+export declare function printConstrainedLevenbergMarquardtResult(result: ConstrainedLevenbergMarquardtResult, options?: ResultFormatterOptions): void;
+/**
+ * Prints an adjoint gradient descent result directly to console.
+ */
+export declare function printAdjointGradientDescentResult(result: AdjointGradientDescentResult, options?: ResultFormatterOptions): void;
+/**
+ * Type-safe overloaded function for printing any optimization result.
+ */
+export declare function printResult(result: OptimizationResult, options?: ResultFormatterOptions): void;
+export declare function printResult(result: GradientDescentResult, options?: ResultFormatterOptions): void;
+export declare function printResult(result: LevenbergMarquardtResult, options?: ResultFormatterOptions): void;
+export declare function printResult(result: ConstrainedGaussNewtonResult, options?: ResultFormatterOptions): void;
+export declare function printResult(result: ConstrainedLevenbergMarquardtResult, options?: ResultFormatterOptions): void;
+export declare function printResult(result: AdjointGradientDescentResult, options?: ResultFormatterOptions): void;
+//# sourceMappingURL=resultFormatter.d.ts.map

package/dist/utils/resultFormatter.d.ts.map

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

package/dist/utils/resultFormatter.js

@@ -0,0 +1,342 @@
+/**
+ * This file provides helper functions for formatting and displaying
+ * optimization results in a consistent, user-friendly manner.
+ *
+ * Role in system:
+ * - Replaces repetitive console.log statements in examples
+ * - Provides consistent formatting across all result types
+ * - Improves UI/UX with better readability and structure
+ *
+ * For first-time readers:
+ * - Use printOptimizationResult() for direct console output
+ * - Use formatOptimizationResult() to get formatted string
+ * - Functions automatically handle different result types via overloading
+ */
+import { formatNumberWithPrecision } from './formatting.js';
+const DEFAULT_OPTIONS = {
+    showSectionHeaders: true,
+    showExecutionTime: false,
+    elapsedTimeMs: 0,
+    maxParametersToShow: 10,
+    parameterPrecision: 6,
+    costPrecision: 8,
+    constraintPrecision: 10
+};
+/**
+ * Formats a parameter array for display.
+ * Automatically switches between individual and array format based on size.
+ */
+function formatParameters(parameters, options) {
+    const length = parameters.length;
+    const maxShow = options.maxParametersToShow;
+    const precision = options.parameterPrecision;
+    if (length === 0) {
+        return '[]';
+    }
+    // For small arrays (≤3 elements), show individually with labels
+    if (length <= 3) {
+        const labels = ['p', 'x', 'y'];
+        return Array.from(parameters)
+            .map((value, index) => {
+            const label = labels[index] || `param${index}`;
+            return `${label} = ${formatNumberWithPrecision(value, precision)}`;
+        })
+            .join(', ');
+    }
+    // For medium arrays (4-10 elements), show as array
+    if (length <= maxShow) {
+        const formatted = Array.from(parameters)
+            .map(value => formatNumberWithPrecision(value, precision))
+            .join(', ');
+        return `[${formatted}]`;
+    }
+    // For large arrays, show first 5 elements + "... and N more"
+    const firstFew = Array.from(parameters.slice(0, 5))
+        .map(value => formatNumberWithPrecision(value, precision))
+        .join(', ');
+    const remaining = length - 5;
+    return `[${firstFew}, ... and ${remaining} more]`;
+}
+/**
+ * Formats a state array for display (used in constrained optimization).
+ */
+function formatStates(states, options) {
+    return formatParameters(states, options);
+}
+/**
+ * Formats basic optimization result information.
+ */
+function formatBasicResult(result, options) {
+    const lines = [];
+    if (options.showSectionHeaders) {
+        lines.push('\n=== Optimization Results ===');
+    }
+    // Parameters
+    lines.push('Optimized parameters:');
+    const paramStr = formatParameters(result.parameters, options);
+    lines.push(`  ${paramStr}`);
+    // Cost
+    lines.push('\nCost:');
+    lines.push(`  f(p) = ${formatNumberWithPrecision(result.finalCost, options.costPrecision)}`);
+    // Convergence information
+    lines.push('\nConvergence:');
+    lines.push(`  Converged: ${result.converged}`);
+    lines.push(`  Iterations: ${result.iterations}`);
+    if (result.finalGradientNorm !== undefined) {
+        lines.push(`  Final gradient norm: ${formatNumberWithPrecision(result.finalGradientNorm, options.costPrecision)}`);
+    }
+    if (result.finalResidualNorm !== undefined) {
+        lines.push(`  Final residual norm: ${formatNumberWithPrecision(result.finalResidualNorm, options.costPrecision)}`);
+    }
+    // Execution time
+    if (options.showExecutionTime && options.elapsedTimeMs > 0) {
+        lines.push(`\nExecution time: ${formatNumberWithPrecision(options.elapsedTimeMs, 2)} ms`);
+        if (result.iterations > 0) {
+            const timePerIteration = options.elapsedTimeMs / result.iterations;
+            lines.push(`Time per iteration: ${formatNumberWithPrecision(timePerIteration, 3)} ms`);
+        }
+    }
+    return lines;
+}
+/**
+ * Formats a basic OptimizationResult.
+ */
+export function formatOptimizationResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = formatBasicResult(result, opts);
+    return lines.join('\n');
+}
+/**
+ * Formats a GradientDescentResult.
+ */
+export function formatGradientDescentResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = formatBasicResult(result, opts);
+    // Add line search information
+    const lineSearchIndex = lines.findIndex(line => line.includes('Final gradient norm') || line.includes('Final residual norm'));
+    if (lineSearchIndex >= 0) {
+        lines.splice(lineSearchIndex + 1, 0, `  Used line search: ${result.usedLineSearch}`);
+    }
+    else {
+        lines.push(`  Used line search: ${result.usedLineSearch}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats a LevenbergMarquardtResult.
+ */
+export function formatLevenbergMarquardtResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = formatBasicResult(result, opts);
+    // Add lambda information
+    const lambdaIndex = lines.findIndex(line => line.includes('Final residual norm'));
+    if (lambdaIndex >= 0) {
+        lines.splice(lambdaIndex + 1, 0, `  Final lambda: ${formatNumberWithPrecision(result.finalLambda, 6)}`);
+    }
+    else {
+        lines.push(`  Final lambda: ${formatNumberWithPrecision(result.finalLambda, 6)}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats a ConstrainedGaussNewtonResult.
+ */
+export function formatConstrainedGaussNewtonResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = [];
+    if (opts.showSectionHeaders) {
+        lines.push('\n=== Optimization Results ===');
+    }
+    // Parameters
+    lines.push('Optimized parameters:');
+    const paramStr = formatParameters(result.parameters, opts);
+    lines.push(`  ${paramStr}`);
+    // States
+    lines.push('Optimized states:');
+    const stateStr = formatStates(result.finalStates, opts);
+    lines.push(`  ${stateStr}`);
+    // Cost
+    lines.push('\nCost:');
+    lines.push(`  f(p, x) = ${formatNumberWithPrecision(result.finalCost, opts.costPrecision)}`);
+    // Constraint satisfaction
+    lines.push('\nConstraint satisfaction:');
+    if (result.finalConstraintNorm !== undefined) {
+        lines.push(`  ||c(p, x)|| = ${formatNumberWithPrecision(result.finalConstraintNorm, opts.constraintPrecision)}`);
+    }
+    else {
+        lines.push(`  ||c(p, x)|| = N/A`);
+    }
+    // Convergence information
+    lines.push('\nConvergence:');
+    lines.push(`  Converged: ${result.converged}`);
+    lines.push(`  Iterations: ${result.iterations}`);
+    if (result.finalGradientNorm !== undefined) {
+        lines.push(`  Final gradient norm: ${formatNumberWithPrecision(result.finalGradientNorm, opts.costPrecision)}`);
+    }
+    if (result.finalResidualNorm !== undefined) {
+        lines.push(`  Final residual norm: ${formatNumberWithPrecision(result.finalResidualNorm, opts.costPrecision)}`);
+    }
+    // Execution time
+    if (opts.showExecutionTime && opts.elapsedTimeMs > 0) {
+        lines.push(`\nExecution time: ${formatNumberWithPrecision(opts.elapsedTimeMs, 2)} ms`);
+        if (result.iterations > 0) {
+            const timePerIteration = opts.elapsedTimeMs / result.iterations;
+            lines.push(`Time per iteration: ${formatNumberWithPrecision(timePerIteration, 3)} ms`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats a ConstrainedLevenbergMarquardtResult.
+ */
+export function formatConstrainedLevenbergMarquardtResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = [];
+    if (opts.showSectionHeaders) {
+        lines.push('\n=== Optimization Results ===');
+    }
+    // Parameters
+    lines.push('Optimized parameters:');
+    const paramStr = formatParameters(result.parameters, opts);
+    lines.push(`  ${paramStr}`);
+    // States
+    lines.push('Optimized states:');
+    const stateStr = formatStates(result.finalStates, opts);
+    lines.push(`  ${stateStr}`);
+    // Cost
+    lines.push('\nCost:');
+    lines.push(`  f(p, x) = ${formatNumberWithPrecision(result.finalCost, opts.costPrecision)}`);
+    // Constraint satisfaction
+    lines.push('\nConstraint satisfaction:');
+    if (result.finalConstraintNorm !== undefined) {
+        lines.push(`  ||c(p, x)|| = ${formatNumberWithPrecision(result.finalConstraintNorm, opts.constraintPrecision)}`);
+    }
+    else {
+        lines.push(`  ||c(p, x)|| = N/A`);
+    }
+    // Convergence information
+    lines.push('\nConvergence:');
+    lines.push(`  Converged: ${result.converged}`);
+    lines.push(`  Iterations: ${result.iterations}`);
+    if (result.finalGradientNorm !== undefined) {
+        lines.push(`  Final gradient norm: ${formatNumberWithPrecision(result.finalGradientNorm, opts.costPrecision)}`);
+    }
+    if (result.finalResidualNorm !== undefined) {
+        lines.push(`  Final residual norm: ${formatNumberWithPrecision(result.finalResidualNorm, opts.costPrecision)}`);
+    }
+    lines.push(`  Final lambda: ${formatNumberWithPrecision(result.finalLambda, 6)}`);
+    // Execution time
+    if (opts.showExecutionTime && opts.elapsedTimeMs > 0) {
+        lines.push(`\nExecution time: ${formatNumberWithPrecision(opts.elapsedTimeMs, 2)} ms`);
+        if (result.iterations > 0) {
+            const timePerIteration = opts.elapsedTimeMs / result.iterations;
+            lines.push(`Time per iteration: ${formatNumberWithPrecision(timePerIteration, 3)} ms`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats an AdjointGradientDescentResult.
+ */
+export function formatAdjointGradientDescentResult(result, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const lines = [];
+    if (opts.showSectionHeaders) {
+        lines.push('\n=== Optimization Results ===');
+    }
+    // Parameters
+    lines.push('Optimized parameters:');
+    const paramStr = formatParameters(result.parameters, opts);
+    lines.push(`  ${paramStr}`);
+    // States
+    lines.push('Optimized states:');
+    const stateStr = formatStates(result.finalStates, opts);
+    lines.push(`  ${stateStr}`);
+    // Cost
+    lines.push('\nCost:');
+    lines.push(`  f(p, x) = ${formatNumberWithPrecision(result.finalCost, opts.costPrecision)}`);
+    // Constraint satisfaction
+    lines.push('\nConstraint satisfaction:');
+    if (result.finalConstraintNorm !== undefined) {
+        lines.push(`  ||c(p, x)|| = ${formatNumberWithPrecision(result.finalConstraintNorm, opts.constraintPrecision)}`);
+    }
+    else {
+        lines.push(`  ||c(p, x)|| = N/A`);
+    }
+    // Convergence information
+    lines.push('\nConvergence:');
+    lines.push(`  Converged: ${result.converged}`);
+    lines.push(`  Iterations: ${result.iterations}`);
+    if (result.finalGradientNorm !== undefined) {
+        lines.push(`  Final gradient norm: ${formatNumberWithPrecision(result.finalGradientNorm, opts.costPrecision)}`);
+    }
+    lines.push(`  Used line search: ${result.usedLineSearch}`);
+    // Execution time
+    if (opts.showExecutionTime && opts.elapsedTimeMs > 0) {
+        lines.push(`\nExecution time: ${formatNumberWithPrecision(opts.elapsedTimeMs, 2)} ms`);
+        if (result.iterations > 0) {
+            const timePerIteration = opts.elapsedTimeMs / result.iterations;
+            lines.push(`Time per iteration: ${formatNumberWithPrecision(timePerIteration, 3)} ms`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatResult(result, options) {
+    // Type guards to determine which formatter to use
+    if ('finalStates' in result && 'finalLambda' in result) {
+        return formatConstrainedLevenbergMarquardtResult(result, options);
+    }
+    if ('finalStates' in result && 'finalConstraintNorm' in result) {
+        if ('usedLineSearch' in result) {
+            return formatAdjointGradientDescentResult(result, options);
+        }
+        return formatConstrainedGaussNewtonResult(result, options);
+    }
+    if ('finalLambda' in result) {
+        return formatLevenbergMarquardtResult(result, options);
+    }
+    if ('usedLineSearch' in result) {
+        return formatGradientDescentResult(result, options);
+    }
+    return formatOptimizationResult(result, options);
+}
+/**
+ * Prints an optimization result directly to console.
+ */
+export function printOptimizationResult(result, options) {
+    console.log(formatOptimizationResult(result, options));
+}
+/**
+ * Prints a gradient descent result directly to console.
+ */
+export function printGradientDescentResult(result, options) {
+    console.log(formatGradientDescentResult(result, options));
+}
+/**
+ * Prints a Levenberg-Marquardt result directly to console.
+ */
+export function printLevenbergMarquardtResult(result, options) {
+    console.log(formatLevenbergMarquardtResult(result, options));
+}
+/**
+ * Prints a constrained Gauss-Newton result directly to console.
+ */
+export function printConstrainedGaussNewtonResult(result, options) {
+    console.log(formatConstrainedGaussNewtonResult(result, options));
+}
+/**
+ * Prints a constrained Levenberg-Marquardt result directly to console.
+ */
+export function printConstrainedLevenbergMarquardtResult(result, options) {
+    console.log(formatConstrainedLevenbergMarquardtResult(result, options));
+}
+/**
+ * Prints an adjoint gradient descent result directly to console.
+ */
+export function printAdjointGradientDescentResult(result, options) {
+    console.log(formatAdjointGradientDescentResult(result, options));
+}
+export function printResult(result, options) {
+    console.log(formatResult(result, options));
+}
+//# sourceMappingURL=resultFormatter.js.map