nlsq.facades¶

Facades for breaking circular dependencies in NLSQ.

This package provides lazy-loading facades that break circular import cycles:

OptimizationFacade: Breaks global_optimization <-> minpack cycle
StabilityFacade: Breaks stability.fallback <-> minpack cycle
DiagnosticsFacade: Breaks diagnostics.types <-> health_report cycle

All facades use function-level lazy imports to defer module loading.

Submodules¶

nlsq.facades.optimization_facade¶

Optimization facade for breaking circular dependencies.

This facade provides lazy access to global_optimization components, breaking the circular import cycle between minpack and global_optimization.

Reference: specs/017-curve-fit-decomposition/spec.md FR-011

class nlsq.facades.optimization_facade.OptimizationFacade[source]¶

Bases: object

Facade for global optimization components with lazy loading.

This facade breaks the circular dependency between minpack.py and global_optimization by deferring all imports to method call time.

Examples

>>> facade = OptimizationFacade()
>>> CMAESOptimizer = facade.get_cmaes_optimizer()
>>> optimizer = CMAESOptimizer(bounds=([0, 0], [10, 10]))

get_cmaes_optimizer()[source]¶

Get the CMAESOptimizer class.

Returns:: The CMAESOptimizer class for creating optimizer instances.
Return type:: type[CMAESOptimizer]

get_method_selector()[source]¶

Get the MethodSelector class.

Returns:: The MethodSelector class for automatic method selection.
Return type:: type[MethodSelector]

get_bipop_optimizer()[source]¶

Get the BIPOPRestarter class.

Returns:: The BIPOPRestarter class for BIPOP restart strategy.
Return type:: type[BIPOPRestarter]

get_multistart_optimizer()[source]¶

Get the MultiStartOrchestrator class.

Returns:: The MultiStartOrchestrator class for multi-start optimization.
Return type:: type[MultiStartOrchestrator]

create_cmaes_optimizer(**kwargs)[source]¶

Create a CMAESOptimizer instance with given parameters.

Parameters:: **kwargs (Any) – Keyword arguments passed to CMAESOptimizer constructor.
Returns:: A configured CMAESOptimizer instance.
Return type:: CMAESOptimizer

create_multistart_orchestrator(**kwargs)[source]¶

Create a MultiStartOrchestrator instance with given parameters.

Parameters:: **kwargs (Any) – Keyword arguments passed to MultiStartOrchestrator constructor.
Returns:: A configured MultiStartOrchestrator instance.
Return type:: MultiStartOrchestrator

nlsq.facades.stability_facade¶

Stability facade for breaking circular dependencies.

This facade provides lazy access to stability components, breaking the circular import cycle between minpack and stability.fallback.

Reference: specs/017-curve-fit-decomposition/spec.md FR-012

class nlsq.facades.stability_facade.StabilityFacade[source]¶

Bases: object

Facade for stability components with lazy loading.

This facade breaks the circular dependency between minpack.py and stability.fallback by deferring all imports to method call time.

Examples

>>> facade = StabilityFacade()
>>> svd_func = facade.get_fallback_svd()
>>> U, s, V = svd_func(jacobian_matrix)

get_fallback_svd()[source]¶

Get the SVD function with GPU/CPU fallback.

Returns:: Function that computes SVD with automatic fallback: compute_svd_with_fallback(J_h, full_matrices=False) -> (U, s, V)
Return type:: Callable

get_stability_guard()[source]¶

Get the NumericalStabilityGuard class.

Returns:: The NumericalStabilityGuard class for detecting numerical issues.
Return type:: type[NumericalStabilityGuard]

get_condition_monitor()[source]¶

Get the condition number estimation function.

Returns:: Function estimating condition number of xdata: estimate_condition_number(xdata: np.ndarray) -> float
Return type:: Callable

get_recovery_handler()[source]¶

Get the OptimizationRecovery class.

Returns:: The OptimizationRecovery class for recovering from failures.
Return type:: type[OptimizationRecovery]

get_fallback_orchestrator()[source]¶

Get the FallbackOrchestrator class.

Returns:: The FallbackOrchestrator class for managing fallback strategies.
Return type:: type[FallbackOrchestrator]

create_stability_guard(**kwargs)[source]¶

Create a NumericalStabilityGuard instance.

Parameters:: **kwargs (Any) – Keyword arguments passed to NumericalStabilityGuard constructor.
Returns:: A configured NumericalStabilityGuard instance.
Return type:: NumericalStabilityGuard

create_recovery_handler(**kwargs)[source]¶

Create an OptimizationRecovery instance.

Parameters:: **kwargs (Any) – Keyword arguments passed to OptimizationRecovery constructor.
Returns:: A configured OptimizationRecovery instance.
Return type:: OptimizationRecovery

nlsq.facades.diagnostics_facade¶

Diagnostics facade for breaking circular dependencies.

This facade provides lazy access to diagnostics components, breaking the circular import cycle between diagnostics.types and health_report.

Reference: specs/017-curve-fit-decomposition/spec.md FR-013

class nlsq.facades.diagnostics_facade.DiagnosticsFacade[source]¶

Bases: object

Facade for diagnostics components with lazy loading.

This facade breaks the circular dependency between diagnostics.types and health_report by deferring all imports to method call time.

Examples

>>> facade = DiagnosticsFacade()
>>> DiagnosticLevel = facade.get_diagnostic_level()
>>> level = DiagnosticLevel.DETAILED

get_diagnostic_level()[source]¶

Get the DiagnosticLevel enum.

Returns:: The DiagnosticLevel enum for specifying diagnostic verbosity.
Return type:: type[DiagnosticLevel]

get_diagnostics_config()[source]¶

Get the DiagnosticsConfig class.

Returns:: The DiagnosticsConfig class for configuring diagnostics.
Return type:: type[DiagnosticsConfig]

get_convergence_monitor()[source]¶

Get the ConvergenceMonitor class.

Returns:: The ConvergenceMonitor class for monitoring convergence patterns.
Return type:: type[ConvergenceMonitor]

create_diagnostics_config(**kwargs)[source]¶

Create a DiagnosticsConfig instance.

Parameters:: **kwargs (Any) – Keyword arguments passed to DiagnosticsConfig constructor.
Returns:: A configured DiagnosticsConfig instance.
Return type:: DiagnosticsConfig

create_convergence_monitor(window_size=10, sensitivity=1.0)[source]¶

Create a ConvergenceMonitor instance.

Parameters:

window_size (int) – Size of sliding window for pattern detection.
sensitivity (float) – Sensitivity factor for pattern detection thresholds.

Returns:

A configured ConvergenceMonitor instance.

Return type:

ConvergenceMonitor