nlsq.utils.diagnostics module

Optimization diagnostics and monitoring for NLSQ.

This module provides real-time monitoring, convergence detection, and diagnostic reporting for optimization processes.

class nlsq.utils.diagnostics.ConvergenceMonitor(window_size=10, sensitivity=1.0)[source]

Bases: object

Monitor convergence patterns and detect problems.

Detects: - Oscillation in parameter or cost values - Stagnation (no progress) - Divergence (increasing cost) - Slow convergence - Numerical instability

__init__(window_size=10, sensitivity=1.0)[source]

Initialize convergence monitor.

Parameters:

  • window_size (int) – Size of sliding window for pattern detection

  • sensitivity (float) – Sensitivity factor (1.0 = normal, <1 = less sensitive, >1 = more sensitive)

update(cost, params, gradient=None, step_size=None)[source]

Update monitor with new iteration data.

Parameters:

  • cost (float) – Current cost value

  • params (np.ndarray) – Current parameter values

  • gradient (np.ndarray, optional) – Current gradient

  • step_size (float, optional) – Step size taken

add_iteration(cost, params, gradient=None, step_size=None)[source]

Alias for update() method for backward compatibility.

Parameters:

  • cost (float) – Current cost value

  • params (np.ndarray) – Current parameter values

  • gradient (np.ndarray, optional) – Current gradient

  • step_size (float, optional) – Step size taken

detect_oscillation()[source]

Detect oscillation in optimization.

Returns:

  • is_oscillating (bool) – Whether oscillation is detected

  • oscillation_score (float) – Oscillation severity score (0-1)

Return type:

tuple[bool, float]

detect_stagnation()[source]

Detect stagnation in optimization.

Returns:

  • is_stagnant (bool) – Whether stagnation is detected

  • stagnation_score (float) – Stagnation severity score

Return type:

tuple[bool, float]

detect_divergence()[source]

Detect divergence in optimization.

Returns:

  • is_diverging (bool) – Whether divergence is detected

  • divergence_score (float) – Divergence severity score

Return type:

tuple[bool, float]

get_convergence_rate()[source]

Estimate convergence rate.

Returns:

rate – Convergence rate (negative = diverging, positive = converging)

Return type:

float or None

class nlsq.utils.diagnostics.OptimizationDiagnostics(verbosity=1)[source]

Bases: object

Comprehensive optimization diagnostics and reporting.

Tracks: - Iteration data (parameters, cost, gradients) - Convergence metrics - Memory usage - Timing information - Numerical stability indicators

__init__(verbosity=1)[source]

Initialize diagnostics system.

Parameters:

verbosity (int) – Verbosity level: - 0: Minimal diagnostics (no condition number computation) - 1: Normal (cheap 1-norm condition estimate, O(nm)) - 2: Detailed (full SVD condition number, O(mn²))

start_optimization(x0=None, problem_name='optimization', *, n_params=None, n_data=None, method=None, loss=None)[source]

Initialize diagnostics for new optimization.

Parameters:

  • x0 (np.ndarray, optional) – Initial parameters (legacy API)

  • problem_name (str) – Name for this optimization problem

  • n_params (int, optional) – Number of parameters (new API from LeastSquares)

  • n_data (int, optional) – Number of data points (new API from LeastSquares)

  • method (str, optional) – Optimization method (new API from LeastSquares)

  • loss (str, optional) – Loss function name (new API from LeastSquares)

record_iteration(iteration, x, cost, gradient=None, jacobian=None, step_size=None, method_info=None)[source]

Record data for current iteration.

Parameters:

  • iteration (int) – Iteration number

  • x (np.ndarray) – Current parameters

  • cost (float) – Current cost value

  • gradient (np.ndarray, optional) – Current gradient

  • jacobian (np.ndarray, optional) – Current Jacobian matrix

  • step_size (float, optional) – Step size taken

  • method_info (dict, optional) – Algorithm-specific information

record_event(event_type, data=None)[source]

Record a special event during optimization.

Parameters:

  • event_type (str) – Type of event (e.g., ‘recovery_success’, ‘recovery_failed’)

  • data (dict, optional) – Additional event data

get_summary_statistics()[source]

Get summary statistics for the optimization.

Returns:

stats – Summary statistics

Return type:

dict

generate_report(verbose=True)[source]

Generate human-readable optimization report.

Parameters:

verbose (bool) – Whether to include detailed information

Returns:

report – Formatted report

Return type:

str

plot_convergence(save_path=None)[source]

Plot convergence history.

Parameters:

save_path (str, optional) – Path to save plot

nlsq.utils.diagnostics.get_diagnostics(verbosity=None)[source]

Get global diagnostics instance.

Parameters:

verbosity (int, optional) – Verbosity level for new instance (0=minimal, 1=normal, 2=detailed). Only used when creating a new instance.

Returns:

diagnostics – Global diagnostics instance

Return type:

OptimizationDiagnostics

nlsq.utils.diagnostics.reset_diagnostics(verbosity=1)[source]

Reset global diagnostics.

Parameters:

verbosity (int) – Verbosity level (0=minimal, 1=normal, 2=detailed)

Overview

The diagnostics module provides real-time monitoring, convergence detection, and diagnostic reporting for optimization processes.

Key Features

  • Convergence monitoring with sliding-window pattern detection

  • Oscillation, stagnation, and divergence detection

  • Memory usage tracking (via psutil when available)

  • Iteration-level diagnostic reporting with configurable verbosity

Classes

class nlsq.utils.diagnostics.ConvergenceMonitor(window_size=10, sensitivity=1.0)[source]

Bases: object

Monitor convergence patterns and detect problems.

Detects: - Oscillation in parameter or cost values - Stagnation (no progress) - Divergence (increasing cost) - Slow convergence - Numerical instability

__init__(window_size=10, sensitivity=1.0)[source]

Initialize convergence monitor.

Parameters:

  • window_size (int) – Size of sliding window for pattern detection

  • sensitivity (float) – Sensitivity factor (1.0 = normal, <1 = less sensitive, >1 = more sensitive)

update(cost, params, gradient=None, step_size=None)[source]

Update monitor with new iteration data.

Parameters:

  • cost (float) – Current cost value

  • params (np.ndarray) – Current parameter values

  • gradient (np.ndarray, optional) – Current gradient

  • step_size (float, optional) – Step size taken

add_iteration(cost, params, gradient=None, step_size=None)[source]

Alias for update() method for backward compatibility.

Parameters:

  • cost (float) – Current cost value

  • params (np.ndarray) – Current parameter values

  • gradient (np.ndarray, optional) – Current gradient

  • step_size (float, optional) – Step size taken

detect_oscillation()[source]

Detect oscillation in optimization.

Returns:

  • is_oscillating (bool) – Whether oscillation is detected

  • oscillation_score (float) – Oscillation severity score (0-1)

Return type:

tuple[bool, float]

detect_stagnation()[source]

Detect stagnation in optimization.

Returns:

  • is_stagnant (bool) – Whether stagnation is detected

  • stagnation_score (float) – Stagnation severity score

Return type:

tuple[bool, float]

detect_divergence()[source]

Detect divergence in optimization.

Returns:

  • is_diverging (bool) – Whether divergence is detected

  • divergence_score (float) – Divergence severity score

Return type:

tuple[bool, float]

get_convergence_rate()[source]

Estimate convergence rate.

Returns:

rate – Convergence rate (negative = diverging, positive = converging)

Return type:

float or None

class nlsq.utils.diagnostics.OptimizationDiagnostics(verbosity=1)[source]

Bases: object

Comprehensive optimization diagnostics and reporting.

Tracks: - Iteration data (parameters, cost, gradients) - Convergence metrics - Memory usage - Timing information - Numerical stability indicators

__init__(verbosity=1)[source]

Initialize diagnostics system.

Parameters:

verbosity (int) – Verbosity level: - 0: Minimal diagnostics (no condition number computation) - 1: Normal (cheap 1-norm condition estimate, O(nm)) - 2: Detailed (full SVD condition number, O(mn²))

start_optimization(x0=None, problem_name='optimization', *, n_params=None, n_data=None, method=None, loss=None)[source]

Initialize diagnostics for new optimization.

Parameters:

  • x0 (np.ndarray, optional) – Initial parameters (legacy API)

  • problem_name (str) – Name for this optimization problem

  • n_params (int, optional) – Number of parameters (new API from LeastSquares)

  • n_data (int, optional) – Number of data points (new API from LeastSquares)

  • method (str, optional) – Optimization method (new API from LeastSquares)

  • loss (str, optional) – Loss function name (new API from LeastSquares)

record_iteration(iteration, x, cost, gradient=None, jacobian=None, step_size=None, method_info=None)[source]

Record data for current iteration.

Parameters:

  • iteration (int) – Iteration number

  • x (np.ndarray) – Current parameters

  • cost (float) – Current cost value

  • gradient (np.ndarray, optional) – Current gradient

  • jacobian (np.ndarray, optional) – Current Jacobian matrix

  • step_size (float, optional) – Step size taken

  • method_info (dict, optional) – Algorithm-specific information

record_event(event_type, data=None)[source]

Record a special event during optimization.

Parameters:

  • event_type (str) – Type of event (e.g., ‘recovery_success’, ‘recovery_failed’)

  • data (dict, optional) – Additional event data

get_summary_statistics()[source]

Get summary statistics for the optimization.

Returns:

stats – Summary statistics

Return type:

dict

generate_report(verbose=True)[source]

Generate human-readable optimization report.

Parameters:

verbose (bool) – Whether to include detailed information

Returns:

report – Formatted report

Return type:

str

plot_convergence(save_path=None)[source]

Plot convergence history.

Parameters:

save_path (str, optional) – Path to save plot

Functions

nlsq.utils.diagnostics.get_diagnostics(verbosity=None)[source]

Get global diagnostics instance.

Parameters:

verbosity (int, optional) – Verbosity level for new instance (0=minimal, 1=normal, 2=detailed). Only used when creating a new instance.

Returns:

diagnostics – Global diagnostics instance

Return type:

OptimizationDiagnostics

nlsq.utils.diagnostics.reset_diagnostics(verbosity=1)[source]

Reset global diagnostics.

Parameters:

verbosity (int) – Verbosity level (0=minimal, 1=normal, 2=detailed)

Example Usage

from nlsq.utils.diagnostics import get_diagnostics, reset_diagnostics

# Get a diagnostics instance with verbosity level 2
diag = get_diagnostics(verbosity=2)

# Reset diagnostics for a new optimization run
reset_diagnostics(verbosity=1)

See Also