nlsq.error_messages module

Enhanced error messages with diagnostics and recommendations.

This module provides informative error messages that help users debug optimization failures by providing diagnostics and actionable recommendations.

The main component is the OptimizationError exception, which is raised when curve fitting fails to converge. Unlike generic errors, it provides:

  • Diagnostics: Final cost, gradient norm, iterations, function evaluations

  • Reasons: Why the optimization failed (e.g., max iterations, gradient too large)

  • Recommendations: Actionable suggestions to fix the issue

Examples

The enhanced error messages are raised automatically when optimization fails:

>>> from nlsq import curve_fit
>>> import jax.numpy as jnp
>>> import numpy as np
>>>
>>> def difficult_func(x, a, b):
...     return a * jnp.exp(b * x**2)
>>>
>>> xdata = np.linspace(0, 1, 10)
>>> ydata = difficult_func(xdata, 1, -5)
>>>
>>> try:
...     popt, pcov = curve_fit(difficult_func, xdata, ydata, p0=[0.1, 0.1], max_nfev=5)
... except OptimizationError as e:
...     print(e)
...     # Prints detailed diagnostics and recommendations
...     print(f"Reasons: {e.reasons}")
...     print(f"Recommendations: {e.recommendations}")

See also

nlsq.minpack.curve_fit

Main curve fitting function

nlsq.parameter_estimation

Automatic parameter estimation

class nlsq.utils.error_messages.OptimizationDiagnostics(result)[source]

Bases: object

Collect and analyze optimization diagnostics.

Parameters:

result (OptimizeResult) – Optimization result object

cost

Final cost function value

Type:

float or None

gradient_norm

Norm of final gradient

Type:

float or None

nfev

Number of function evaluations

Type:

int

nit

Number of iterations

Type:

int

__init__(result)[source]
nlsq.utils.error_messages.analyze_failure(result, gtol, ftol, xtol, max_nfev)[source]

Analyze why optimization failed and generate recommendations.

Parameters:

  • result (OptimizeResult) – Optimization result object

  • gtol (float) – Gradient tolerance

  • ftol (float) – Function tolerance

  • xtol (float) – Parameter tolerance

  • max_nfev (int) – Maximum number of function evaluations

Returns:

  • reasons (list of str) – Why the optimization failed

  • recommendations (list of str) – What the user should try

Return type:

tuple[list[str], list[str]]

nlsq.utils.error_messages.format_error_message(reasons, recommendations, diagnostics)[source]

Format comprehensive error message.

Parameters:

  • reasons (list of str) – Reasons for optimization failure

  • recommendations (list of str) – Recommended actions

  • diagnostics (dict) – Diagnostic information

Returns:

message – Formatted error message

Return type:

str

exception nlsq.utils.error_messages.OptimizationError(result, gtol, ftol, xtol, max_nfev)[source]

Bases: RuntimeError

Enhanced optimization error with diagnostics and recommendations.

This exception provides detailed information about why an optimization failed and actionable recommendations for fixing the issue.

Parameters:

  • result (OptimizeResult) – Optimization result object

  • gtol (float) – Gradient tolerance used

  • ftol (float) – Function tolerance used

  • xtol (float) – Parameter tolerance used

  • max_nfev (int) – Maximum function evaluations used

result

The optimization result

Type:

OptimizeResult

reasons

Reasons for failure

Type:

list of str

recommendations

Recommended actions

Type:

list of str

diagnostics

Diagnostic information

Type:

dict

Examples

The error is raised automatically by curve_fit when optimization fails:

>>> from nlsq import curve_fit
>>> from nlsq.utils.error_messages import OptimizationError
>>> import jax.numpy as jnp
>>> import numpy as np
>>>
>>> def exponential(x, a, b, c):
...     return a * jnp.exp(-b * x) + c
>>>
>>> x = np.linspace(0, 5, 50)
>>> y = 3 * np.exp(-0.5 * x) + 1
>>>
>>> try:
...     # Force failure with very low max_nfev
...     popt, pcov = curve_fit(exponential, x, y, p0=[1, 1, 1], max_nfev=3)
... except OptimizationError as e:
...     # Access error attributes programmatically
...     if any("maximum" in r.lower() for r in e.reasons):
...         # Auto-retry with higher max_nfev
...         popt, pcov = curve_fit(exponential, x, y, p0=[1, 1, 1], max_nfev=200)
...         print("Auto-retry succeeded!")

See also

analyze_failure

Function that analyzes why optimization failed

format_error_message

Function that formats the error message

__init__(result, gtol, ftol, xtol, max_nfev)[source]
exception nlsq.utils.error_messages.ConvergenceWarning[source]

Bases: UserWarning

Warning for optimization that converged but may have issues.

This warning is raised when optimization technically converged but there are potential quality issues (e.g., poor fit, covariance issues).

nlsq.utils.error_messages.check_convergence_quality(result, pcov)[source]

Check quality of converged solution and generate warnings.

Parameters:

  • result (OptimizeResult) – Optimization result

  • pcov (ndarray or None) – Parameter covariance matrix

Returns:

warnings – Warning messages about solution quality

Return type:

list of str

Overview

The error_messages module provides standardized error messages with helpful debugging information.

Key Features

  • Standardized error messages across the library

  • Helpful context for debugging

  • Actionable suggestions for fixing errors

  • Error classification by category

Functions

nlsq.utils.error_messages.format_error_message(reasons, recommendations, diagnostics)[source]

Format comprehensive error message.

Parameters:

  • reasons (list of str) – Reasons for optimization failure

  • recommendations (list of str) – Recommended actions

  • diagnostics (dict) – Diagnostic information

Returns:

message – Formatted error message

Return type:

str

Example Usage

from nlsq.utils.error_messages import format_error_message

try:
    # Some operation that might fail
    result = fit_function(data)
except ValueError as e:
    # Get formatted error with helpful context
    error_msg = format_error_message(
        error_type="ValueError", message=str(e), context={"data_shape": data.shape}
    )
    raise ValueError(error_msg) from e

Error Categories

  • Input Validation Errors: Invalid input data or parameters

  • Convergence Errors: Optimization failed to converge

  • Numerical Errors: Numerical stability issues

  • JAX Errors: JAX-specific errors with workarounds

See Also