numopt-js 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,427 @@
+/**
+ * This file defines the core type definitions for the numopt-js library.
+ *
+ * Role in system:
+ * - Provides type contracts for all optimization algorithms
+ * - Defines function signatures for cost functions, gradients, and Jacobians
+ * - Establishes option and result interfaces for consistent API design
+ *
+ * For first-time readers:
+ * - Start with ResidualFn and CostFn to understand function signatures
+ * - Check option interfaces to see what can be configured
+ * - Review result interfaces to understand what each algorithm returns
+ */
+import { Matrix } from 'ml-matrix';
+/**
+ * Function that computes the residual vector for nonlinear least squares problems.
+ * Takes parameter vector and returns residual vector.
+ *
+ * Note: Uses Float64Array for performance and type safety in numerical computations.
+ */
+export type ResidualFn = (parameters: Float64Array) => Float64Array;
+/**
+ * Function that computes the Jacobian matrix for nonlinear least squares problems.
+ * Takes parameter vector and returns Jacobian matrix (ml-matrix Matrix type).
+ *
+ * Note: Uses Matrix from ml-matrix package for efficient matrix operations.
+ * The Matrix type provides optimized linear algebra operations and is browser-compatible.
+ */
+export type JacobianFn = (parameters: Float64Array) => Matrix;
+/**
+ * Function that computes the cost (objective function value) for general optimization.
+ * Takes parameter vector and returns scalar cost value.
+ *
+ * Note: Uses Float64Array for parameter vector to ensure 64-bit floating-point precision
+ * and better performance in numerical computations.
+ */
+export type CostFn = (parameters: Float64Array) => number;
+/**
+ * Function that computes the gradient vector for general optimization.
+ * Takes parameter vector and returns gradient vector.
+ *
+ * Note: Uses Float64Array for performance and memory efficiency in numerical computations.
+ */
+export type GradientFn = (parameters: Float64Array) => Float64Array;
+/**
+ * Function that computes the constraint vector for constrained optimization problems.
+ * Takes parameter vector and state vector, returns constraint vector.
+ * The constraint c(p, x) = 0 must be satisfied.
+ *
+ * Note: The constraint vector length and state vector length can differ.
+ * The adjoint method supports both square and non-square constraint Jacobians.
+ */
+export type ConstraintFn = (parameters: Float64Array, states: Float64Array) => Float64Array;
+/**
+ * Function that computes the cost (objective function value) for constrained optimization.
+ * Takes parameter vector and state vector, returns scalar cost value.
+ *
+ * Note: The state vector x must satisfy c(p, x) = 0.
+ */
+export type ConstrainedCostFn = (parameters: Float64Array, states: Float64Array) => number;
+/**
+ * Function that computes the residual vector for constrained nonlinear least squares problems.
+ * Takes parameter vector and state vector, returns residual vector.
+ * The cost function is f(p, x) = 1/2 r(p, x)^T r(p, x).
+ *
+ * Note: The state vector x must satisfy c(p, x) = 0.
+ */
+export type ConstrainedResidualFn = (parameters: Float64Array, states: Float64Array) => Float64Array;
+/**
+ * Common options shared across optimization algorithms.
+ */
+export interface CommonOptimizationOptions {
+    /**
+     * Maximum number of iterations before stopping.
+     * Default: 1000
+     */
+    maxIterations?: number;
+    /**
+     * Tolerance for convergence check (gradient norm, step size, etc.).
+     * Default: 1e-6
+     */
+    tolerance?: number;
+    /**
+     * Callback function called at each iteration for progress monitoring.
+     * Useful for debugging and monitoring convergence.
+     */
+    onIteration?: (iteration: number, cost: number, parameters: Float64Array) => void;
+    /**
+     * Enable verbose logging for debugging.
+     * When true, detailed information is logged to console.
+     * Default: false
+     *
+     * @deprecated Use logLevel instead for more fine-grained control.
+     * If both logLevel and verbose are specified, logLevel takes precedence.
+     */
+    verbose?: boolean;
+    /**
+     * Log level for detailed logging output.
+     * Controls which log messages are displayed:
+     * - DEBUG: Detailed progress information (cost, gradient norm, step size, etc.)
+     * - INFO: Convergence messages and important state changes
+     * - WARN: Warnings (singular matrix, max iterations reached, line search failure, etc.)
+     * - ERROR: Fatal errors (currently not used, reserved for future extensions)
+     *
+     * If verbose is true and logLevel is not specified, logLevel defaults to INFO.
+     * If both logLevel and verbose are specified, logLevel takes precedence.
+     * Default: undefined (no logging)
+     */
+    logLevel?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+}
+/**
+ * Options specific to gradient descent algorithm.
+ */
+export interface GradientDescentOptions extends CommonOptimizationOptions {
+    /**
+     * Step size (learning rate) for gradient descent.
+     * If not provided, line search will be used to determine step size.
+     * Default: undefined (use line search)
+     */
+    stepSize?: number;
+    /**
+     * Use line search to determine optimal step size.
+     * Default: true
+     */
+    useLineSearch?: boolean;
+}
+/**
+ * Options for line search algorithm.
+ */
+export interface LineSearchOptions {
+    /**
+     * Initial step size to try.
+     * If not provided, the initial step size is automatically scaled by the gradient norm:
+     * α₀ = 1.0 / ||∇f(x)||
+     * This prevents steps from being too large when gradients are large, improving
+     * convergence performance. If the gradient norm is very small (< 1e-10) or the
+     * computed step size is not finite, the default value of 1.0 is used.
+     */
+    initialStepSize?: number;
+    /**
+     * Contraction factor for backtracking line search.
+     * Step size is multiplied by this factor when condition is not met.
+     * Default: 0.5
+     */
+    contractionFactor?: number;
+    /**
+     * Armijo condition parameter (sufficient decrease).
+     * Default: 0.1
+     */
+    armijoParameter?: number;
+    /**
+     * Maximum number of line search iterations.
+     * Default: 50
+     */
+    maxIterations?: number;
+}
+/**
+ * Options for numerical differentiation.
+ */
+export interface NumericalDifferentiationOptions {
+    /**
+     * Step size for finite difference approximation.
+     * Default: 1e-6
+     */
+    stepSize?: number;
+}
+/**
+ * Options for Gauss-Newton method.
+ */
+export interface GaussNewtonOptions extends CommonOptimizationOptions {
+    /**
+     * Analytical Jacobian function. If provided, this will be used instead of numerical differentiation.
+     * If not provided, numerical Jacobian will be used (if useNumericJacobian is true).
+     */
+    jacobian?: JacobianFn;
+    /**
+     * Use numerical differentiation to compute Jacobian if user doesn't provide it.
+     * Default: true
+     */
+    useNumericJacobian?: boolean;
+    /**
+     * Step size for numerical Jacobian computation.
+     * Default: 1e-6
+     */
+    jacobianStep?: number;
+}
+/**
+ * Options for Levenberg-Marquardt algorithm.
+ */
+export interface LevenbergMarquardtOptions extends GaussNewtonOptions {
+    /**
+     * Initial value of damping parameter lambda.
+     * Default: 1e-3
+     */
+    lambdaInitial?: number;
+    /**
+     * Factor for updating lambda (success: divide, failure: multiply).
+     * Default: 10.0
+     */
+    lambdaFactor?: number;
+    /**
+     * Tolerance for gradient norm convergence check.
+     * Default: 1e-6
+     */
+    tolGradient?: number;
+    /**
+     * Tolerance for step size convergence check.
+     * Default: 1e-6
+     */
+    tolStep?: number;
+    /**
+     * Tolerance for residual norm convergence check.
+     * Default: 1e-6
+     */
+    tolResidual?: number;
+}
+/**
+ * Result returned by optimization algorithms.
+ */
+export interface OptimizationResult {
+    /**
+     * Optimized parameter vector.
+     */
+    parameters: Float64Array;
+    /**
+     * Number of iterations performed.
+     */
+    iterations: number;
+    /**
+     * Whether the algorithm converged successfully.
+     */
+    converged: boolean;
+    /**
+     * Final cost (objective function value).
+     */
+    finalCost: number;
+    /**
+     * Final gradient norm (if applicable).
+     */
+    finalGradientNorm?: number;
+    /**
+     * Final residual norm (for least squares problems).
+     * Available for algorithms that work with residual functions.
+     */
+    finalResidualNorm?: number;
+}
+/**
+ * Result returned by Levenberg-Marquardt algorithm.
+ */
+export interface LevenbergMarquardtResult extends OptimizationResult {
+    /**
+     * Final residual norm.
+     */
+    finalResidualNorm: number;
+    /**
+     * Final lambda (damping parameter) value.
+     */
+    finalLambda: number;
+}
+/**
+ * Result returned by gradient descent algorithm.
+ */
+export interface GradientDescentResult extends OptimizationResult {
+    /**
+     * Whether line search was used.
+     */
+    usedLineSearch: boolean;
+}
+/**
+ * Options for adjoint gradient descent algorithm.
+ */
+export interface AdjointGradientDescentOptions extends GradientDescentOptions {
+    /**
+     * Analytical partial derivative of cost function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Function signature: (p: Float64Array, x: Float64Array) => Float64Array
+     */
+    dfdp?: (parameters: Float64Array, states: Float64Array) => Float64Array;
+    /**
+     * Analytical partial derivative of cost function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Function signature: (p: Float64Array, x: Float64Array) => Float64Array
+     */
+    dfdx?: (parameters: Float64Array, states: Float64Array) => Float64Array;
+    /**
+     * Analytical partial derivative of constraint function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × parameterCount).
+     */
+    dcdp?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of constraint function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × stateCount).
+     * Must be square (constraintCount == stateCount) for the adjoint method.
+     */
+    dcdx?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Step size for numerical differentiation with respect to parameters.
+     * Default: 1e-6
+     */
+    stepSizeP?: number;
+    /**
+     * Step size for numerical differentiation with respect to states.
+     * Default: 1e-6
+     */
+    stepSizeX?: number;
+    /**
+     * Tolerance for checking constraint satisfaction c(p, x) = 0.
+     * If ||c(p, x)|| exceeds this value, a warning will be issued.
+     * Default: 1e-6
+     */
+    constraintTolerance?: number;
+}
+/**
+ * Result returned by adjoint gradient descent algorithm.
+ */
+export interface AdjointGradientDescentResult extends GradientDescentResult {
+    /**
+     * Final state vector (satisfies constraint c(p, x) = 0).
+     */
+    finalStates: Float64Array;
+    /**
+     * Final constraint violation norm ||c(p, x)||.
+     */
+    finalConstraintNorm?: number;
+}
+/**
+ * Options for constrained Gauss-Newton method.
+ */
+export interface ConstrainedGaussNewtonOptions extends CommonOptimizationOptions {
+    /**
+     * Analytical partial derivative of residual function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (residualCount × parameterCount).
+     */
+    drdp?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of residual function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (residualCount × stateCount).
+     */
+    drdx?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of constraint function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × parameterCount).
+     */
+    dcdp?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of constraint function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × stateCount).
+     * Supports both square (constraintCount == stateCount) and non-square matrices.
+     * For non-square matrices, the adjoint method uses normal equations with Cholesky decomposition.
+     */
+    dcdx?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Step size for numerical differentiation with respect to parameters.
+     * Default: 1e-6
+     */
+    stepSizeP?: number;
+    /**
+     * Step size for numerical differentiation with respect to states.
+     * Default: 1e-6
+     */
+    stepSizeX?: number;
+    /**
+     * Tolerance for checking constraint satisfaction c(p, x) = 0.
+     * If ||c(p, x)|| exceeds this value, a warning will be issued.
+     * Default: 1e-6
+     */
+    constraintTolerance?: number;
+}
+/**
+ * Result returned by constrained Gauss-Newton algorithm.
+ */
+export interface ConstrainedGaussNewtonResult extends OptimizationResult {
+    /**
+     * Final state vector (satisfies constraint c(p, x) = 0).
+     */
+    finalStates: Float64Array;
+    /**
+     * Final constraint violation norm ||c(p, x)||.
+     */
+    finalConstraintNorm?: number;
+}
+/**
+ * Options for constrained Levenberg-Marquardt algorithm.
+ */
+export interface ConstrainedLevenbergMarquardtOptions extends ConstrainedGaussNewtonOptions {
+    /**
+     * Initial value of damping parameter lambda.
+     * Default: 1e-3
+     */
+    lambdaInitial?: number;
+    /**
+     * Factor for updating lambda (success: divide, failure: multiply).
+     * Default: 10.0
+     */
+    lambdaFactor?: number;
+    /**
+     * Tolerance for gradient norm convergence check.
+     * Default: 1e-6
+     */
+    tolGradient?: number;
+    /**
+     * Tolerance for step size convergence check.
+     * Default: 1e-6
+     */
+    tolStep?: number;
+    /**
+     * Tolerance for residual norm convergence check.
+     * Default: 1e-6
+     */
+    tolResidual?: number;
+}
+/**
+ * Result returned by constrained Levenberg-Marquardt algorithm.
+ */
+export interface ConstrainedLevenbergMarquardtResult extends ConstrainedGaussNewtonResult {
+    /**
+     * Final lambda (damping parameter) value.
+     */
+    finalLambda: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/types.js

@@ -0,0 +1,15 @@
+/**
+ * This file defines the core type definitions for the numopt-js library.
+ *
+ * Role in system:
+ * - Provides type contracts for all optimization algorithms
+ * - Defines function signatures for cost functions, gradients, and Jacobians
+ * - Establishes option and result interfaces for consistent API design
+ *
+ * For first-time readers:
+ * - Start with ResidualFn and CostFn to understand function signatures
+ * - Check option interfaces to see what can be configured
+ * - Review result interfaces to understand what each algorithm returns
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * This file is the main entry point for the numopt-js library.
+ *
+ * Role in system:
+ * - Exports all public API functions and types
+ * - Provides clean, focused interface for users
+ * - Single import point for the entire library
+ *
+ * For first-time readers:
+ * - Import everything you need from this file
+ * - Check individual algorithm files for detailed documentation
+ * - All algorithms follow consistent patterns
+ */
+export { gradientDescent } from './core/gradientDescent.js';
+export { backtrackingLineSearch } from './core/lineSearch.js';
+export { gaussNewton } from './core/gaussNewton.js';
+export { levenbergMarquardt } from './core/levenbergMarquardt.js';
+export { adjointGradientDescent } from './core/adjointGradientDescent.js';
+export { constrainedGaussNewton } from './core/constrainedGaussNewton.js';
+export { constrainedLevenbergMarquardt } from './core/constrainedLevenbergMarquardt.js';
+export { finiteDiffGradient, finiteDiffJacobian, finiteDiffPartialP, finiteDiffPartialX, finiteDiffConstraintPartialP, finiteDiffConstraintPartialX, finiteDiffResidualPartialP, finiteDiffResidualPartialX } from './core/finiteDiff.js';
+export { createFiniteDiffGradient, createFiniteDiffJacobian } from './core/createGradientFunction.js';
+export type { ResidualFn, JacobianFn, CostFn, GradientFn, ConstraintFn, ConstrainedCostFn, ConstrainedResidualFn, CommonOptimizationOptions, GradientDescentOptions, LineSearchOptions, NumericalDifferentiationOptions, GaussNewtonOptions, LevenbergMarquardtOptions, AdjointGradientDescentOptions, ConstrainedGaussNewtonOptions, ConstrainedLevenbergMarquardtOptions, OptimizationResult, LevenbergMarquardtResult, GradientDescentResult, AdjointGradientDescentResult, ConstrainedGaussNewtonResult, ConstrainedLevenbergMarquardtResult } from './core/types.js';
+export { float64ArrayToMatrix, matrixToFloat64Array, matrixToFloat64Array2D, vectorNorm, dotProduct, addVectors, subtractVectors, scaleVector } from './utils/matrix.js';
+export { formatOptimizationResult, formatGradientDescentResult, formatLevenbergMarquardtResult, formatConstrainedGaussNewtonResult, formatConstrainedLevenbergMarquardtResult, formatAdjointGradientDescentResult, formatResult, printOptimizationResult, printGradientDescentResult, printLevenbergMarquardtResult, printConstrainedGaussNewtonResult, printConstrainedLevenbergMarquardtResult, printAdjointGradientDescentResult, printResult, type ResultFormatterOptions } from './utils/resultFormatter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,6BAA6B,EAAE,MAAM,yCAAyC,CAAC;AAGxF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGtG,YAAY,EACV,UAAU,EACV,UAAU,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,+BAA+B,EAC/B,kBAAkB,EAClB,yBAAyB,EACzB,6BAA6B,EAC7B,6BAA6B,EAC7B,oCAAoC,EACpC,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,4BAA4B,EAC5B,4BAA4B,EAC5B,mCAAmC,EACpC,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,8BAA8B,EAC9B,kCAAkC,EAClC,yCAAyC,EACzC,kCAAkC,EAClC,YAAY,EACZ,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,EAC7B,iCAAiC,EACjC,wCAAwC,EACxC,iCAAiC,EACjC,WAAW,EACX,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * This file is the main entry point for the numopt-js library.
+ *
+ * Role in system:
+ * - Exports all public API functions and types
+ * - Provides clean, focused interface for users
+ * - Single import point for the entire library
+ *
+ * For first-time readers:
+ * - Import everything you need from this file
+ * - Check individual algorithm files for detailed documentation
+ * - All algorithms follow consistent patterns
+ */
+// Core algorithms
+export { gradientDescent } from './core/gradientDescent.js';
+export { backtrackingLineSearch } from './core/lineSearch.js';
+export { gaussNewton } from './core/gaussNewton.js';
+export { levenbergMarquardt } from './core/levenbergMarquardt.js';
+export { adjointGradientDescent } from './core/adjointGradientDescent.js';
+export { constrainedGaussNewton } from './core/constrainedGaussNewton.js';
+export { constrainedLevenbergMarquardt } from './core/constrainedLevenbergMarquardt.js';
+// Numerical differentiation utilities
+export { finiteDiffGradient, finiteDiffJacobian, finiteDiffPartialP, finiteDiffPartialX, finiteDiffConstraintPartialP, finiteDiffConstraintPartialX, finiteDiffResidualPartialP, finiteDiffResidualPartialX } from './core/finiteDiff.js';
+export { createFiniteDiffGradient, createFiniteDiffJacobian } from './core/createGradientFunction.js';
+// Utility functions (exported for advanced users)
+export { float64ArrayToMatrix, matrixToFloat64Array, matrixToFloat64Array2D, vectorNorm, dotProduct, addVectors, subtractVectors, scaleVector } from './utils/matrix.js';
+// Result formatting utilities
+export { formatOptimizationResult, formatGradientDescentResult, formatLevenbergMarquardtResult, formatConstrainedGaussNewtonResult, formatConstrainedLevenbergMarquardtResult, formatAdjointGradientDescentResult, formatResult, printOptimizationResult, printGradientDescentResult, printLevenbergMarquardtResult, printConstrainedGaussNewtonResult, printConstrainedLevenbergMarquardtResult, printAdjointGradientDescentResult, printResult } from './utils/resultFormatter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kBAAkB;AAClB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,6BAA6B,EAAE,MAAM,yCAAyC,CAAC;AAExF,sCAAsC;AACtC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AA4BtG,kDAAkD;AAClD,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,8BAA8B;AAC9B,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,8BAA8B,EAC9B,kCAAkC,EAClC,yCAAyC,EACzC,kCAAkC,EAClC,YAAY,EACZ,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,EAC7B,iCAAiC,EACjC,wCAAwC,EACxC,iCAAiC,EACjC,WAAW,EAEZ,MAAM,4BAA4B,CAAC"}

package/dist/utils/formatting.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This file provides number formatting utilities for consistent display
+ * of optimization results across the library.
+ *
+ * Role in system:
+ * - Shared formatting logic used by Logger and ResultFormatter
+ * - Ensures consistent number representation in console output
+ * - Handles edge cases (NaN, Infinity, very small/large numbers)
+ *
+ * For first-time readers:
+ * - formatNumber() is the main function for formatting numbers
+ * - Uses scientific notation for very small/large numbers
+ * - Uses fixed notation for standard range numbers
+ */
+/**
+ * Formats a number using scientific notation for readability.
+ * Small numbers (< 0.01) and large numbers (> 1000) use scientific notation.
+ * Otherwise, uses standard decimal notation.
+ * Handles non-numeric values gracefully.
+ */
+export declare function formatNumber(value: number | string): string;
+/**
+ * Formats a number with a specific number of decimal places.
+ * Used when precise control over formatting is needed.
+ */
+export declare function formatNumberWithPrecision(value: number, precision: number): string;
+//# sourceMappingURL=formatting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAgB3D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUlF"}

package/dist/utils/formatting.js

@@ -0,0 +1,54 @@
+/**
+ * This file provides number formatting utilities for consistent display
+ * of optimization results across the library.
+ *
+ * Role in system:
+ * - Shared formatting logic used by Logger and ResultFormatter
+ * - Ensures consistent number representation in console output
+ * - Handles edge cases (NaN, Infinity, very small/large numbers)
+ *
+ * For first-time readers:
+ * - formatNumber() is the main function for formatting numbers
+ * - Uses scientific notation for very small/large numbers
+ * - Uses fixed notation for standard range numbers
+ */
+const SCIENTIFIC_NOTATION_LOWER_THRESHOLD = 0.01;
+const SCIENTIFIC_NOTATION_UPPER_THRESHOLD = 1000;
+const SCIENTIFIC_NOTATION_FRACTION_DIGITS = 3;
+const FIXED_NOTATION_FRACTION_DIGITS = 6;
+/**
+ * Formats a number using scientific notation for readability.
+ * Small numbers (< 0.01) and large numbers (> 1000) use scientific notation.
+ * Otherwise, uses standard decimal notation.
+ * Handles non-numeric values gracefully.
+ */
+export function formatNumber(value) {
+    // Handle non-numeric values
+    if (typeof value !== 'number' || !isFinite(value)) {
+        return String(value);
+    }
+    const absoluteValue = Math.abs(value);
+    if (absoluteValue === 0) {
+        return '0';
+    }
+    // Use scientific notation for very small or very large numbers to avoid long strings of zeros
+    if (absoluteValue < SCIENTIFIC_NOTATION_LOWER_THRESHOLD || absoluteValue >= SCIENTIFIC_NOTATION_UPPER_THRESHOLD) {
+        return value.toExponential(SCIENTIFIC_NOTATION_FRACTION_DIGITS);
+    }
+    // Use fixed notation for standard range numbers for easier reading
+    return value.toFixed(FIXED_NOTATION_FRACTION_DIGITS).replace(/\.?0+$/, '');
+}
+/**
+ * Formats a number with a specific number of decimal places.
+ * Used when precise control over formatting is needed.
+ */
+export function formatNumberWithPrecision(value, precision) {
+    if (typeof value !== 'number' || !isFinite(value)) {
+        return String(value);
+    }
+    if (value === 0) {
+        return '0.' + '0'.repeat(precision);
+    }
+    return value.toFixed(precision);
+}
+//# sourceMappingURL=formatting.js.map

package/dist/utils/formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,mCAAmC,GAAG,IAAI,CAAC;AACjD,MAAM,mCAAmC,GAAG,IAAI,CAAC;AACjD,MAAM,mCAAmC,GAAG,CAAC,CAAC;AAC9C,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAsB;IACjD,4BAA4B;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,8FAA8F;IAC9F,IAAI,aAAa,GAAG,mCAAmC,IAAI,aAAa,IAAI,mCAAmC,EAAE,CAAC;QAChH,OAAO,KAAK,CAAC,aAAa,CAAC,mCAAmC,CAAC,CAAC;IAClE,CAAC;IACD,mEAAmE;IACnE,OAAO,KAAK,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAa,EAAE,SAAiB;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}