numopt-js 0.1.0

package/dist/core/lineSearch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * This file implements line search algorithms for determining optimal step sizes
+ * in optimization algorithms. The implementation follows the backtracking
+ * Armijo line search described in Nocedal & Wright, "Numerical Optimization"
+ * (2nd ed.), Algorithm 3.1.
+ *
+ * Role in system:
+ * - Used by gradient descent to find appropriate step sizes
+ * - Implements backtracking line search with Armijo condition
+ * - Critical for convergence of gradient-based methods
+ *
+ * For first-time readers:
+ * - Start with backtrackingLineSearch function
+ * - Understand Armijo condition (sufficient decrease)
+ * - Line search prevents overshooting the minimum
+ */
+import type { CostFn, GradientFn, LineSearchOptions } from './types.js';
+/**
+ * Performs backtracking line search to find a step size that satisfies
+ * the Armijo condition (sufficient decrease). This follows the textbook
+ * backtracking scheme in Nocedal & Wright, "Numerical Optimization"
+ * (2nd ed.), Algorithm 3.1.
+ *
+ * The Armijo condition ensures that the function value decreases sufficiently:
+ * f(x + α * d) <= f(x) + c * α * ∇f(x)^T * d
+ *
+ * where:
+ * - α is the step size
+ * - d is the search direction (typically -gradient)
+ * - c is the Armijo parameter (typically chosen around 1e-4 per Nocedal & Wright)
+ * - β is the backtracking contraction factor (Algorithm 3.1 suggests β = 0.5)
+ *
+ * Initial step size selection:
+ * - If `initialStepSize` is explicitly provided in options, it is used as-is.
+ * - Otherwise, 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.
+ */
+export declare function backtrackingLineSearch(costFunction: CostFn, gradientFunction: GradientFn, currentParameters: Float64Array, searchDirection: Float64Array, options?: LineSearchOptions): number;
+//# sourceMappingURL=lineSearch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lineSearch.d.ts","sourceRoot":"","sources":["../../src/core/lineSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAYxE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,UAAU,EAC5B,iBAAiB,EAAE,YAAY,EAC/B,eAAe,EAAE,YAAY,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAmER"}

package/dist/core/lineSearch.js

@@ -0,0 +1,106 @@
+/**
+ * This file implements line search algorithms for determining optimal step sizes
+ * in optimization algorithms. The implementation follows the backtracking
+ * Armijo line search described in Nocedal & Wright, "Numerical Optimization"
+ * (2nd ed.), Algorithm 3.1.
+ *
+ * Role in system:
+ * - Used by gradient descent to find appropriate step sizes
+ * - Implements backtracking line search with Armijo condition
+ * - Critical for convergence of gradient-based methods
+ *
+ * For first-time readers:
+ * - Start with backtrackingLineSearch function
+ * - Understand Armijo condition (sufficient decrease)
+ * - Line search prevents overshooting the minimum
+ */
+import { vectorNorm } from '../utils/matrix.js';
+const DEFAULT_INITIAL_STEP_SIZE = 1.0;
+const GRADIENT_NORM_THRESHOLD = 1e-10; // Threshold below which we use default step size to avoid numerical instability
+// Typical values recommended in Nocedal & Wright (Algorithm 3.1) are β = 0.5 and c = 1e-4.
+const DEFAULT_CONTRACTION_FACTOR = 0.5;
+const DEFAULT_ARMIJO_PARAMETER = 1e-4;
+const DEFAULT_MAX_LINE_SEARCH_ITERATIONS = 50;
+const INVALID_STEP_SIZE = 0.0; // Returned when search direction is not a descent direction
+const NON_DESCENT_DIRECTION_THRESHOLD = 0.0; // Threshold for directional derivative: >= 0 means not a descent direction
+/**
+ * Performs backtracking line search to find a step size that satisfies
+ * the Armijo condition (sufficient decrease). This follows the textbook
+ * backtracking scheme in Nocedal & Wright, "Numerical Optimization"
+ * (2nd ed.), Algorithm 3.1.
+ *
+ * The Armijo condition ensures that the function value decreases sufficiently:
+ * f(x + α * d) <= f(x) + c * α * ∇f(x)^T * d
+ *
+ * where:
+ * - α is the step size
+ * - d is the search direction (typically -gradient)
+ * - c is the Armijo parameter (typically chosen around 1e-4 per Nocedal & Wright)
+ * - β is the backtracking contraction factor (Algorithm 3.1 suggests β = 0.5)
+ *
+ * Initial step size selection:
+ * - If `initialStepSize` is explicitly provided in options, it is used as-is.
+ * - Otherwise, 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.
+ */
+export function backtrackingLineSearch(costFunction, gradientFunction, currentParameters, searchDirection, options = {}) {
+    const contractionFactor = options.contractionFactor ?? DEFAULT_CONTRACTION_FACTOR;
+    const armijoParameter = options.armijoParameter ?? DEFAULT_ARMIJO_PARAMETER;
+    const maxIterations = options.maxIterations ?? DEFAULT_MAX_LINE_SEARCH_ITERATIONS;
+    const currentCost = costFunction(currentParameters);
+    const currentGradient = gradientFunction(currentParameters);
+    // Determine initial step size: use provided value, or scale by gradient norm if not provided
+    let initialStepSize;
+    if (options.initialStepSize !== undefined) {
+        // Use explicitly provided initial step size (maintains backward compatibility)
+        initialStepSize = options.initialStepSize;
+    }
+    else {
+        // Scale initial step size by gradient norm: 1.0 / ||gradient||
+        // This prevents steps from being too large when gradients are large
+        const gradientNorm = vectorNorm(currentGradient);
+        // Handle edge cases: very small or zero gradient norm
+        if (gradientNorm < GRADIENT_NORM_THRESHOLD) {
+            initialStepSize = DEFAULT_INITIAL_STEP_SIZE;
+        }
+        else {
+            initialStepSize = 1.0 / gradientNorm;
+            // Additional safety check for NaN or Infinity
+            if (!isFinite(initialStepSize)) {
+                initialStepSize = DEFAULT_INITIAL_STEP_SIZE;
+            }
+        }
+    }
+    // Compute directional derivative: ∇f(x)^T * d
+    let directionalDerivative = 0.0;
+    for (let i = 0; i < currentGradient.length; i++) {
+        directionalDerivative += currentGradient[i] * searchDirection[i];
+    }
+    // Early return if search direction is not a descent direction
+    // Directional derivative >= 0 means moving in this direction increases the cost
+    if (directionalDerivative >= NON_DESCENT_DIRECTION_THRESHOLD) {
+        return INVALID_STEP_SIZE;
+    }
+    let stepSize = initialStepSize;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        // Compute trial point: x + α * d
+        const trialParameters = new Float64Array(currentParameters.length);
+        for (let i = 0; i < currentParameters.length; i++) {
+            trialParameters[i] = currentParameters[i] + stepSize * searchDirection[i];
+        }
+        const trialCost = costFunction(trialParameters);
+        // Armijo condition: f(x + αd) <= f(x) + c * α * ∇f(x)^T * d
+        const armijoThreshold = currentCost + armijoParameter * stepSize * directionalDerivative;
+        if (trialCost <= armijoThreshold) {
+            return stepSize;
+        }
+        // Reduce step size and try again
+        stepSize *= contractionFactor;
+    }
+    // If we couldn't find a suitable step size, return a very small value
+    return stepSize;
+}
+//# sourceMappingURL=lineSearch.js.map

package/dist/core/lineSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineSearch.js","sourceRoot":"","sources":["../../src/core/lineSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,yBAAyB,GAAG,GAAG,CAAC;AACtC,MAAM,uBAAuB,GAAG,KAAK,CAAC,CAAC,gFAAgF;AACvH,2FAA2F;AAC3F,MAAM,0BAA0B,GAAG,GAAG,CAAC;AACvC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AACtC,MAAM,kCAAkC,GAAG,EAAE,CAAC;AAC9C,MAAM,iBAAiB,GAAG,GAAG,CAAC,CAAC,4DAA4D;AAC3F,MAAM,+BAA+B,GAAG,GAAG,CAAC,CAAC,2EAA2E;AAExH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAAoB,EACpB,gBAA4B,EAC5B,iBAA+B,EAC/B,eAA6B,EAC7B,UAA6B,EAAE;IAE/B,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;IAClF,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC5E,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,kCAAkC,CAAC;IAElF,MAAM,WAAW,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACpD,MAAM,eAAe,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IAE5D,6FAA6F;IAC7F,IAAI,eAAuB,CAAC;IAC5B,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC1C,+EAA+E;QAC/E,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,+DAA+D;QAC/D,oEAAoE;QACpE,MAAM,YAAY,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;QAEjD,sDAAsD;QACtD,IAAI,YAAY,GAAG,uBAAuB,EAAE,CAAC;YAC3C,eAAe,GAAG,yBAAyB,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,eAAe,GAAG,GAAG,GAAG,YAAY,CAAC;YAErC,8CAA8C;YAC9C,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;gBAC/B,eAAe,GAAG,yBAAyB,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,IAAI,qBAAqB,GAAG,GAAG,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,qBAAqB,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,8DAA8D;IAC9D,gFAAgF;IAChF,IAAI,qBAAqB,IAAI,+BAA+B,EAAE,CAAC;QAC7D,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,QAAQ,GAAG,eAAe,CAAC;IAE/B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,aAAa,EAAE,SAAS,EAAE,EAAE,CAAC;QAC/D,iCAAiC;QACjC,MAAM,eAAe,GAAG,IAAI,YAAY,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,eAAe,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,SAAS,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;QAEhD,4DAA4D;QAC5D,MAAM,eAAe,GAAG,WAAW,GAAG,eAAe,GAAG,QAAQ,GAAG,qBAAqB,CAAC;QAEzF,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,iCAAiC;QACjC,QAAQ,IAAI,iBAAiB,CAAC;IAChC,CAAC;IAED,sEAAsE;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/logger.d.ts

@@ -0,0 +1,77 @@
+/**
+ * This file implements a user-friendly and trackable logging system for optimization algorithms.
+ *
+ * Role in system:
+ * - Provides structured logging with log levels (DEBUG, INFO, WARN, ERROR)
+ * - Formats logs with timestamps, emojis, and aligned indentation
+ * - Optimized for performance when logging is disabled
+ *
+ * For first-time readers:
+ * - Start with LogLevel enum and Logger class
+ * - Understand how logLevel and verbose options work together
+ * - Check formatLogMessage for formatting details
+ */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+/**
+ * Determines the effective log level from options.
+ * Handles backward compatibility with verbose option.
+ *
+ * Priority: logLevel > verbose
+ * - If logLevel is specified, use it
+ * - If verbose is true, treat as INFO level
+ * - Otherwise, logging is disabled (returns undefined)
+ */
+export declare function getEffectiveLogLevel(logLevel: LogLevel | undefined, verbose: boolean | undefined): LogLevel | undefined;
+/**
+ * Checks if a log message should be displayed based on the effective log level.
+ *
+ * A message is displayed if its level priority is >= the effective log level priority.
+ * For example, if effective level is INFO, then INFO, WARN, and ERROR are shown, but DEBUG is not.
+ */
+export declare function shouldLog(messageLevel: LogLevel, effectiveLogLevel: LogLevel | undefined): boolean;
+/**
+ * Logger class for optimization algorithms.
+ * Provides structured logging with log levels and formatted output.
+ */
+export declare class Logger {
+    private effectiveLogLevel;
+    constructor(logLevel: LogLevel | undefined, verbose: boolean | undefined);
+    /**
+     * Internal log method to handle common logging logic.
+     * Checks log level, formats message, and outputs to console.
+     */
+    private log;
+    /**
+     * Logs a DEBUG level message.
+     * Used for detailed progress information (cost, gradient norm, step size, etc.).
+     */
+    debug(algorithm: string, iteration: number | undefined, message: string, details?: Array<{
+        key: string;
+        value: number;
+    }>): void;
+    /**
+     * Logs an INFO level message.
+     * Used for convergence messages and important state changes.
+     */
+    info(algorithm: string, iteration: number | undefined, message: string, details?: Array<{
+        key: string;
+        value: number;
+    }>): void;
+    /**
+     * Logs a WARN level message.
+     * Used for warnings (singular matrix, max iterations reached, line search failure, etc.).
+     */
+    warn(algorithm: string, iteration: number | undefined, message: string, details?: Array<{
+        key: string;
+        value: number;
+    }>): void;
+    /**
+     * Logs an ERROR level message.
+     * Used for fatal errors (currently not used, reserved for future extensions).
+     */
+    error(algorithm: string, iteration: number | undefined, message: string, details?: Array<{
+        key: string;
+        value: number;
+    }>): void;
+}
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAwB3D;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,QAAQ,GAAG,SAAS,CAQtB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,QAAQ,EACtB,iBAAiB,EAAE,QAAQ,GAAG,SAAS,GACtC,OAAO,CAKT;AA2DD;;;GAGG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,iBAAiB,CAAuB;gBAEpC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS;IAIxE;;;OAGG;IACH,OAAO,CAAC,GAAG;IAmBX;;;OAGG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,IAAI;IAIP;;;OAGG;IACH,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,IAAI;IAIP;;;OAGG;IACH,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,IAAI;IAIP;;;OAGG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,IAAI;CAGR"}

package/dist/core/logger.js

@@ -0,0 +1,162 @@
+/**
+ * This file implements a user-friendly and trackable logging system for optimization algorithms.
+ *
+ * Role in system:
+ * - Provides structured logging with log levels (DEBUG, INFO, WARN, ERROR)
+ * - Formats logs with timestamps, emojis, and aligned indentation
+ * - Optimized for performance when logging is disabled
+ *
+ * For first-time readers:
+ * - Start with LogLevel enum and Logger class
+ * - Understand how logLevel and verbose options work together
+ * - Check formatLogMessage for formatting details
+ */
+import { formatNumber } from '../utils/formatting.js';
+/**
+ * Log level priority order (higher number = higher priority).
+ * Used to determine if a log message should be displayed.
+ */
+const LOG_LEVEL_PRIORITY = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3
+};
+/**
+ * Emoji symbols for each log level.
+ * Used to provide visual distinction while maintaining academic tone.
+ */
+const LOG_LEVEL_EMOJI = {
+    DEBUG: '🔍',
+    INFO: '✅',
+    WARN: '⚠️',
+    ERROR: '❌'
+};
+/**
+ * Determines the effective log level from options.
+ * Handles backward compatibility with verbose option.
+ *
+ * Priority: logLevel > verbose
+ * - If logLevel is specified, use it
+ * - If verbose is true, treat as INFO level
+ * - Otherwise, logging is disabled (returns undefined)
+ */
+export function getEffectiveLogLevel(logLevel, verbose) {
+    if (logLevel !== undefined) {
+        return logLevel;
+    }
+    if (verbose === true) {
+        return 'INFO';
+    }
+    return undefined;
+}
+/**
+ * Checks if a log message should be displayed based on the effective log level.
+ *
+ * A message is displayed if its level priority is >= the effective log level priority.
+ * For example, if effective level is INFO, then INFO, WARN, and ERROR are shown, but DEBUG is not.
+ */
+export function shouldLog(messageLevel, effectiveLogLevel) {
+    if (effectiveLogLevel === undefined) {
+        return false;
+    }
+    return LOG_LEVEL_PRIORITY[messageLevel] >= LOG_LEVEL_PRIORITY[effectiveLogLevel];
+}
+/**
+ * Formats key-value pairs with aligned indentation.
+ * All labels are padded to the same width so values align vertically.
+ *
+ * Example:
+ *   Cost:           1.234e-6
+ *   Gradient norm:  9.876e-7
+ *   Step size:      1.234e-8
+ */
+function formatKeyValuePairs(pairs) {
+    if (pairs.length === 0) {
+        return '';
+    }
+    // Find maximum label length to align values
+    const maxLabelLength = Math.max(...pairs.map(pair => pair.key.length));
+    // Format each pair with aligned labels
+    return pairs
+        .map(({ key, value }) => {
+        const paddedKey = key.padEnd(maxLabelLength);
+        const formattedValue = formatNumber(value);
+        return `  ${paddedKey}  ${formattedValue}`;
+    })
+        .join('\n');
+}
+/**
+ * Formats a log message with timestamp, level, algorithm, iteration, and details.
+ *
+ * Format: emoji [timestamp] [LEVEL] [algorithm] [iteration] message
+ *
+ * Emoji is placed at the beginning for better visual scanning.
+ * If details are provided as key-value pairs, they are formatted with aligned indentation.
+ */
+function formatLogMessage(level, algorithm, iteration, message, details) {
+    const timestamp = new Date().toISOString();
+    const emoji = LOG_LEVEL_EMOJI[level];
+    const levelLabel = `[${level}]`;
+    const iterationPart = iteration !== undefined ? `Iteration ${iteration}` : '';
+    const header = `${emoji} [${timestamp}] ${levelLabel} [${algorithm}]${iterationPart ? ` ${iterationPart}` : ''}: ${message}`;
+    if (details && details.length > 0) {
+        const detailsFormatted = formatKeyValuePairs(details);
+        return `${header}\n${detailsFormatted}`;
+    }
+    return header;
+}
+/**
+ * Logger class for optimization algorithms.
+ * Provides structured logging with log levels and formatted output.
+ */
+export class Logger {
+    constructor(logLevel, verbose) {
+        this.effectiveLogLevel = getEffectiveLogLevel(logLevel, verbose);
+    }
+    /**
+     * Internal log method to handle common logging logic.
+     * Checks log level, formats message, and outputs to console.
+     */
+    log(level, algorithm, iteration, message, details) {
+        if (!shouldLog(level, this.effectiveLogLevel)) {
+            return;
+        }
+        const formatted = formatLogMessage(level, algorithm, iteration, message, details);
+        if (level === 'ERROR') {
+            console.error(formatted);
+        }
+        else {
+            console.log(formatted);
+        }
+    }
+    /**
+     * Logs a DEBUG level message.
+     * Used for detailed progress information (cost, gradient norm, step size, etc.).
+     */
+    debug(algorithm, iteration, message, details) {
+        this.log('DEBUG', algorithm, iteration, message, details);
+    }
+    /**
+     * Logs an INFO level message.
+     * Used for convergence messages and important state changes.
+     */
+    info(algorithm, iteration, message, details) {
+        this.log('INFO', algorithm, iteration, message, details);
+    }
+    /**
+     * Logs a WARN level message.
+     * Used for warnings (singular matrix, max iterations reached, line search failure, etc.).
+     */
+    warn(algorithm, iteration, message, details) {
+        this.log('WARN', algorithm, iteration, message, details);
+    }
+    /**
+     * Logs an ERROR level message.
+     * Used for fatal errors (currently not used, reserved for future extensions).
+     */
+    error(algorithm, iteration, message, details) {
+        this.log('ERROR', algorithm, iteration, message, details);
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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