nlsq.core.factories

Factory functions for creating and configuring NLSQ optimization components.

This module provides builder functions that simplify the creation of optimizers and configuration objects with sensible defaults.

Factory functions for composing curve fitting configurations.

This module provides factory functions that enable runtime composition of curve fitting features like global optimization and diagnostics. These factories follow the Builder pattern to provide a clean API for configuring optimization pipelines.

The factories decouple feature composition from the core curve_fit implementation, reducing the dependency count in minpack.py.

Examples

>>> from nlsq.core.factories import create_optimizer, configure_curve_fit
>>>
>>> # Configure curve_fit with custom settings
>>> curve_fit = configure_curve_fit(
...     enable_diagnostics=True,
...     enable_recovery=True,
... )
>>> popt, pcov = curve_fit(model, xdata, ydata)
class nlsq.core.factories.OptimizerConfig(enable_global=False, enable_diagnostics=False, enable_recovery=True, n_starts=10, extra_kwargs=<factory>)[source]

Bases: object

Configuration for optimizer creation.

enable_global

Enable global optimization with multi-start.

Type:

bool

enable_diagnostics

Enable diagnostic reporting.

Type:

bool

enable_recovery

Enable automatic recovery from numerical issues.

Type:

bool

n_starts

Number of starts for global optimization.

Type:

int

enable_global: bool = False
enable_diagnostics: bool = False
enable_recovery: bool = True
n_starts: int = 10
extra_kwargs: dict[str, Any]
__init__(enable_global=False, enable_diagnostics=False, enable_recovery=True, n_starts=10, extra_kwargs=<factory>)
nlsq.core.factories.create_optimizer(*, global_optimization=False, diagnostics=False, recovery=True, n_starts=10, cache=None, stability_guard=None, diagnostics_config=None, **kwargs)[source]

Create a configured optimizer with specified features.

This factory function composes various optimization features (global optimization, diagnostics) into a single optimizer instance.

Parameters:

  • global_optimization (bool, default=False) – Enable global optimization with multi-start.

  • diagnostics (bool, default=False) – Enable diagnostic reporting.

  • recovery (bool, default=True) – Enable automatic recovery from numerical issues.

  • n_starts (int, default=10) – Number of starts for global optimization.

  • cache (UnifiedCache | None, default=None) – Optional cache for JIT compilation.

  • stability_guard (NumericalStabilityGuard | None, default=None) – Optional numerical stability guard.

  • diagnostics_config (DiagnosticsConfig | None, default=None) – Optional diagnostics configuration.

  • **kwargs (Any) – Additional keyword arguments passed to curve_fit.

Returns:

A configured optimizer ready for use.

Return type:

ConfiguredOptimizer

Examples

>>> # Standard optimizer
>>> optimizer = create_optimizer()
>>> popt, pcov = optimizer.fit(model, xdata, ydata)
>>>
>>> # Global optimizer with diagnostics
>>> optimizer = create_optimizer(global_optimization=True, diagnostics=True)
class nlsq.core.factories.ConfiguredOptimizer(config, cache=None, stability_guard=None, diagnostics_config=None)[source]

Bases: object

An optimizer configured with specific features.

This class encapsulates the configuration for curve fitting and provides a clean interface for performing fits.

Parameters:

  • config (OptimizerConfig) – The optimizer configuration.

  • cache (UnifiedCache | None) – Optional cache for JIT compilation.

  • stability_guard (NumericalStabilityGuard | None) – Optional numerical stability guard.

  • diagnostics_config (DiagnosticsConfig | None) – Optional diagnostics configuration.

__init__(config, cache=None, stability_guard=None, diagnostics_config=None)[source]

Initialize the configured optimizer.

fit(f, xdata, ydata, p0=None, sigma=None, bounds=None, **kwargs)[source]

Fit a function to data using the configured optimizer.

Parameters:

  • f (Callable) – Model function f(x, *params) -> y.

  • xdata (np.ndarray) – Independent variable data.

  • ydata (np.ndarray) – Dependent variable data.

  • p0 (np.ndarray or None) – Initial parameter guess.

  • sigma (np.ndarray or None) – Uncertainty in ydata.

  • bounds (tuple or None) – (lower, upper) bounds for parameters.

  • **kwargs (Any) – Additional keyword arguments.

Returns:

(popt, pcov) - optimal parameters and covariance matrix.

Return type:

tuple[np.ndarray, np.ndarray]

nlsq.core.factories.configure_curve_fit(*, enable_diagnostics=False, enable_recovery=True, enable_caching=True, **default_kwargs)[source]

Configure a curve_fit function with default settings.

Returns a callable that wraps curve_fit with pre-configured defaults, allowing for consistent settings across an application.

Parameters:

  • enable_diagnostics (bool, default=False) – Enable diagnostic reporting by default.

  • enable_recovery (bool, default=True) – Enable automatic recovery by default.

  • enable_caching (bool, default=True) – Enable JIT caching by default.

  • **default_kwargs (Any) – Additional default keyword arguments.

Returns:

A configured curve_fit function.

Return type:

Callable

Examples

>>> curve_fit = configure_curve_fit(enable_diagnostics=True)
>>> popt, pcov = curve_fit(model, xdata, ydata)

Classes

OptimizerConfig

Configuration dataclass for optimizer creation.

class nlsq.core.factories.OptimizerConfig(enable_global=False, enable_diagnostics=False, enable_recovery=True, n_starts=10, extra_kwargs=<factory>)[source]

Bases: object

Configuration for optimizer creation.

enable_global

Enable global optimization with multi-start.

Type:

bool

enable_diagnostics

Enable diagnostic reporting.

Type:

bool

enable_recovery

Enable automatic recovery from numerical issues.

Type:

bool

n_starts

Number of starts for global optimization.

Type:

int

enable_global: bool = False
enable_diagnostics: bool = False
enable_recovery: bool = True
n_starts: int = 10
extra_kwargs: dict[str, Any]
__init__(enable_global=False, enable_diagnostics=False, enable_recovery=True, n_starts=10, extra_kwargs=<factory>)

ConfiguredOptimizer

Pre-configured optimizer that encapsulates curve fitting settings.

class nlsq.core.factories.ConfiguredOptimizer(config, cache=None, stability_guard=None, diagnostics_config=None)[source]

Bases: object

An optimizer configured with specific features.

This class encapsulates the configuration for curve fitting and provides a clean interface for performing fits.

Parameters:

  • config (OptimizerConfig) – The optimizer configuration.

  • cache (UnifiedCache | None) – Optional cache for JIT compilation.

  • stability_guard (NumericalStabilityGuard | None) – Optional numerical stability guard.

  • diagnostics_config (DiagnosticsConfig | None) – Optional diagnostics configuration.

__init__(config, cache=None, stability_guard=None, diagnostics_config=None)[source]

Initialize the configured optimizer.

fit(f, xdata, ydata, p0=None, sigma=None, bounds=None, **kwargs)[source]

Fit a function to data using the configured optimizer.

Parameters:

  • f (Callable) – Model function f(x, *params) -> y.

  • xdata (np.ndarray) – Independent variable data.

  • ydata (np.ndarray) – Dependent variable data.

  • p0 (np.ndarray or None) – Initial parameter guess.

  • sigma (np.ndarray or None) – Uncertainty in ydata.

  • bounds (tuple or None) – (lower, upper) bounds for parameters.

  • **kwargs (Any) – Additional keyword arguments.

Returns:

(popt, pcov) - optimal parameters and covariance matrix.

Return type:

tuple[np.ndarray, np.ndarray]

Functions

create_optimizer

Create an optimizer instance with the specified configuration.

nlsq.core.factories.create_optimizer(*, global_optimization=False, diagnostics=False, recovery=True, n_starts=10, cache=None, stability_guard=None, diagnostics_config=None, **kwargs)[source]

Create a configured optimizer with specified features.

This factory function composes various optimization features (global optimization, diagnostics) into a single optimizer instance.

Parameters:

  • global_optimization (bool, default=False) – Enable global optimization with multi-start.

  • diagnostics (bool, default=False) – Enable diagnostic reporting.

  • recovery (bool, default=True) – Enable automatic recovery from numerical issues.

  • n_starts (int, default=10) – Number of starts for global optimization.

  • cache (UnifiedCache | None, default=None) – Optional cache for JIT compilation.

  • stability_guard (NumericalStabilityGuard | None, default=None) – Optional numerical stability guard.

  • diagnostics_config (DiagnosticsConfig | None, default=None) – Optional diagnostics configuration.

  • **kwargs (Any) – Additional keyword arguments passed to curve_fit.

Returns:

A configured optimizer ready for use.

Return type:

ConfiguredOptimizer

Examples

>>> # Standard optimizer
>>> optimizer = create_optimizer()
>>> popt, pcov = optimizer.fit(model, xdata, ydata)
>>>
>>> # Global optimizer with diagnostics
>>> optimizer = create_optimizer(global_optimization=True, diagnostics=True)

configure_curve_fit

Configure curve_fit with custom settings.

nlsq.core.factories.configure_curve_fit(*, enable_diagnostics=False, enable_recovery=True, enable_caching=True, **default_kwargs)[source]

Configure a curve_fit function with default settings.

Returns a callable that wraps curve_fit with pre-configured defaults, allowing for consistent settings across an application.

Parameters:

  • enable_diagnostics (bool, default=False) – Enable diagnostic reporting by default.

  • enable_recovery (bool, default=True) – Enable automatic recovery by default.

  • enable_caching (bool, default=True) – Enable JIT caching by default.

  • **default_kwargs (Any) – Additional default keyword arguments.

Returns:

A configured curve_fit function.

Return type:

Callable

Examples

>>> curve_fit = configure_curve_fit(enable_diagnostics=True)
>>> popt, pcov = curve_fit(model, xdata, ydata)

Usage Example

from nlsq.core.factories import create_optimizer, configure_curve_fit

# Create a streaming optimizer
optimizer = create_optimizer("streaming", memory_limit_gb=16.0)

# Configure curve_fit with defaults
curve_fit_fn = configure_curve_fit(
    method="trf",
    max_nfev=1000,
    verbose=2,
)
popt, pcov = curve_fit_fn(model, xdata, ydata, p0=p0)