nlsq.streaming.adaptive_hybrid.AdaptiveHybridStreamingOptimizer¶

class nlsq.streaming.adaptive_hybrid.AdaptiveHybridStreamingOptimizer(config=None)[source]¶

Bases: object

Adaptive hybrid streaming optimizer with four-phase optimization.

This optimizer combines parameter normalization, L-BFGS warmup, streaming Gauss-Newton, and exact covariance computation to provide:

Fast convergence for parameters with different scales
Accurate uncertainty estimates on large datasets
Memory-efficient streaming for unlimited dataset sizes
Production-ready fault tolerance

The optimization proceeds through four phases:

Phase 0: Setup parameter normalization and bounds transformation
Phase 1: L-BFGS warmup with adaptive switching to Phase 2
Phase 2: Streaming Gauss-Newton with exact J^T J accumulation
Phase 3: Denormalize parameters and transform covariance matrix

Parameters:: config (HybridStreamingConfig, optional) – Configuration for all phases of optimization. If None, uses default configuration. See HybridStreamingConfig for details.

config¶

Configuration object controlling all phases

Type:: HybridStreamingConfig

current_phase¶

Current optimization phase (0, 1, 2, or 3)

Type:: int

phase_history¶

History of phase transitions with timing information

Type:: list

phase_start_time¶

Start time of current phase (seconds since epoch)

Type:: float or None

normalized_params¶

Current parameters in normalized space

Type:: jax.Array or None

normalizer¶

Parameter normalizer instance (created in Phase 0)

Type:: ParameterNormalizer or None

normalized_model¶

Wrapped model function operating in normalized space

Type:: NormalizedModelWrapper or None

normalized_bounds¶

Bounds transformed to normalized space

Type:: tuple of jax.Array or None

normalization_jacobian¶

Denormalization Jacobian for covariance transform

Type:: jax.Array or None

Examples

Basic usage with default configuration:

>>> from nlsq import AdaptiveHybridStreamingOptimizer, HybridStreamingConfig
>>> import jax.numpy as jnp
>>> config = HybridStreamingConfig()
>>> optimizer = AdaptiveHybridStreamingOptimizer(config)

With bounds-based normalization:

>>> config = HybridStreamingConfig(
...     normalize=True,
...     normalization_strategy='bounds'
... )
>>> optimizer = AdaptiveHybridStreamingOptimizer(config)

With custom warmup settings:

>>> config = HybridStreamingConfig(
...     warmup_iterations=300,
...     lbfgs_initial_step_size=0.5,
...     gauss_newton_tol=1e-10
... )
>>> optimizer = AdaptiveHybridStreamingOptimizer(config)

See also

HybridStreamingConfig: Configuration for all phases
ParameterNormalizer: Parameter normalization implementation
curve_fit: High-level interface with method=’hybrid_streaming’

Notes

Based on Adaptive Hybrid Streaming Optimizer specification: agent-os/specs/2025-12-18-adaptive-hybrid-streaming-optimizer/spec.md

__init__(config=None)[source]¶

Initialize adaptive hybrid streaming optimizer.

Parameters:: config (HybridStreamingConfig, optional) – Configuration for all phases. If None, uses default configuration.

set_residual_weights(weights)[source]¶

Set residual weights for weighted least squares optimization.

This method allows updating weights during optimization, for example when weights need to be recomputed based on current parameter estimates.

Parameters:: weights (np.ndarray) – Per-group weights of shape (n_groups,). Higher weights give more importance to residuals in that group. The group index for each data point is determined by the first column of x_data.

Notes

Weights must be positive. The weighted MSE is computed as:: wMSE = sum(w[group_idx] * residuals^2) / sum(w[group_idx])

clear_cache()[source]¶

Release cached padded arrays to free memory.

Call this after optimization completes or when reusing the optimizer with different data. The cache is automatically invalidated when data identity changes, but explicit clearing frees memory sooner.

fit(data_source, func, p0, bounds=None, sigma=None, absolute_sigma=False, callback=None, verbose=1)[source]¶

Fit model parameters using four-phase hybrid optimization.

This method orchestrates all four phases: - Phase 0: Setup normalization - Phase 1: L-BFGS warmup - Phase 2: Streaming Gauss-Newton - Phase 3: Denormalization and covariance

Parameters:

data_source (various types) – Data source for optimization. Can be: - Tuple of arrays: (x_data, y_data) - Generator yielding (x_batch, y_batch) - HDF5 file path with datasets
func (Callable) – Model function with signature: func(x, *params) -> predictions
p0 (array_like) – Initial parameter guess of shape (n_params,)
bounds (tuple of array_like, optional) – Parameter bounds as (lb, ub)
sigma (array_like, optional) – Uncertainties in y_data for weighted least squares
absolute_sigma (bool, default=False) – If True, sigma is used in absolute sense (pcov not scaled)
callback (Callable, optional) – Callback with signature callback(params, loss, iteration) Called every config.callback_frequency iterations
verbose (int, default=1) – Verbosity level (0=silent, 1=progress, 2=debug)

Returns:

result – Optimization result dictionary with keys: - ‘x’: Optimized parameters in original space - ‘success’: Boolean indicating success - ‘message’: Status message - ‘fun’: Final residuals - ‘pcov’: Covariance matrix (Phase 3) - ‘perr’: Standard errors (Phase 3) - ‘streaming_diagnostics’: Phase information, timing, etc.

Return type:

dict

Notes

The result dictionary is compatible with scipy.optimize.curve_fit and can be used interchangeably.

property phase_status: dict[str, Any]¶

Get current phase status and history.

Returns:: status – Phase status dictionary with keys: - ‘current_phase’: Current phase number - ‘phase_name’: Name of current phase - ‘phase_history’: List of completed phases with timing - ‘total_phases’: Total number of phases (4)
Return type:: dict

Examples

>>> config = HybridStreamingConfig()
>>> optimizer = AdaptiveHybridStreamingOptimizer(config)
>>> status = optimizer.phase_status
>>> print(status['current_phase'])
0
>>> print(status['phase_name'])
Phase 0: Normalization Setup