Facades¶

Added in version 0.6.4.

Facades provide lazy-loading wrappers that break circular dependencies while maintaining clean import paths. Components load only when accessed.

Overview¶

Facade	Purpose
`OptimizationFacade`	CMA-ES and multi-start optimizers
`StabilityFacade`	SVD fallback and stability guards
`DiagnosticsFacade`	Convergence monitoring and diagnostics

OptimizationFacade¶

class nlsq.facades.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

Example:

from nlsq.facades import OptimizationFacade

facade = OptimizationFacade()

# Get CMA-ES optimizer (loads only when accessed)
CMAESOptimizer = facade.get_cmaes_optimizer()

# Get multi-start optimizer
MultiStartOptimizer = facade.get_multistart_optimizer()

StabilityFacade¶

class nlsq.facades.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

Example:

from nlsq.facades import StabilityFacade

facade = StabilityFacade()

# Get SVD fallback function
svd_with_fallback = facade.get_fallback_svd()

# Get stability guard
StabilityGuard = facade.get_stability_guard()

DiagnosticsFacade¶

class nlsq.facades.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

Example:

from nlsq.facades import DiagnosticsFacade

facade = DiagnosticsFacade()

# Get diagnostic level enum
DiagnosticLevel = facade.get_diagnostic_level()

# Get convergence monitor
ConvergenceMonitor = facade.get_convergence_monitor()

Benefits¶

Reduced Import Time: Dependencies load only when needed
Circular Dependency Breaking: Clean separation between modules
Testing Isolation: Easy to mock for unit tests
Gradual Migration: Supports feature flag-based rollout

Facades¶

Overview¶

OptimizationFacade¶

StabilityFacade¶

DiagnosticsFacade¶

Benefits¶

See Also¶