nlsq.interfaces¶

Protocol definitions for dependency injection and loose coupling.

Added in version 1.2.0: Extracted from core modules to enable cleaner architecture.

This package provides Protocol classes that define interfaces for key components in the NLSQ system. Using protocols enables:

Dependency injection for testing
Loose coupling between modules
Clear contracts for implementations

All protocols are re-exported from the nlsq.interfaces package for convenient imports:

from nlsq.interfaces import CacheProtocol, OptimizerProtocol

Available Protocols¶

CacheProtocol¶

Protocol for cache implementations.

Protocol definition for caching mechanisms.

This module defines the CacheProtocol that caching implementations should follow, enabling different caching strategies.

class nlsq.interfaces.cache_protocol.CacheProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for caching mechanisms.

This protocol defines the interface for cache implementations, allowing different strategies (LRU, TTL, memory-bounded) to be used.

get(key, default)[source]

Retrieve value from cache.

set(key, value)[source]

Store value in cache.

clear()[source]

Clear all cached values.

get(key, default=None)[source]

Retrieve value from cache.

Parameters:

key (str) – Cache key.
default (Any) – Value to return if key not found.

Returns:

Cached value or default.

Return type:

Any

set(key, value)[source]

Store value in cache.

Parameters:

key (str) – Cache key.
value (Any) – Value to store.

clear()[source]

Clear all cached values.

__init__(*args, **kwargs)

class nlsq.interfaces.cache_protocol.BoundedCacheProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for memory-bounded caches.

Extended protocol for caches that track memory usage and can evict items based on size limits.

get(key, default=None)[source]

Retrieve value from cache.

set(key, value)[source]

Store value in cache.

clear()[source]

Clear all cached values.

property size_bytes: int: Current cache size in bytes.

property max_size_bytes: int: Maximum cache size in bytes.

evict(n_bytes)[source]

Evict items to free at least n_bytes.

Parameters:: n_bytes (int) – Minimum bytes to free.
Returns:: Actual bytes freed.
Return type:: int

__init__(*args, **kwargs)

class nlsq.interfaces.cache_protocol.DictCache[source]

Bases: object

Simple dictionary-based cache implementation.

A minimal cache implementation for testing and simple use cases.

__init__()[source]

get(key, default=None)[source]

Retrieve value from cache.

set(key, value)[source]

Store value in cache.

clear()[source]

Clear all cached values.

__contains__(key)[source]

Check if key exists in cache.

__len__()[source]

Return number of cached items.

OptimizerProtocol¶

Protocol for optimizer implementations.

Protocol definition for optimizers.

This module defines the OptimizerProtocol that all optimization algorithms should implement, enabling loose coupling and dependency injection.

class nlsq.interfaces.optimizer_protocol.OptimizerProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for optimization algorithms.

This protocol defines the interface that all optimization algorithms must implement. It allows modules to depend on the abstraction rather than concrete implementations, breaking circular dependencies.

optimize(fun, x0, args, \*\*kwargs)[source]

Perform optimization on the given objective function.

Examples

>>> class MyOptimizer:
...     def optimize(self, fun, x0, args=(), **kwargs):
...         # Implementation
...         pass
>>> isinstance(MyOptimizer(), OptimizerProtocol)
True

optimize(fun, x0, args=(), **kwargs)[source]

Perform optimization on the given objective function.

Parameters:

fun (Callable) – Objective function to minimize. Should return residuals array.
x0 (np.ndarray) – Initial parameter guess.
args (tuple) – Additional arguments to pass to the objective function.
**kwargs (Any) – Additional keyword arguments for the optimizer.

Returns:

Optimization result (typically an OptimizeResult-like object).

Return type:

Any

__init__(*args, **kwargs)

class nlsq.interfaces.optimizer_protocol.LeastSquaresOptimizerProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for least squares optimizers.

Extended protocol for optimizers that specifically handle least squares problems with Jacobian computation and bounds support.

least_squares(fun, x0, jac=None, bounds=None, args=(), **kwargs)[source]

Perform least squares optimization.

Parameters:

fun (Callable) – Residual function to minimize.
x0 (np.ndarray) – Initial parameter guess.
jac (Callable, str, or None) – Jacobian of the residual function, or ‘auto’ for autodiff.
bounds (tuple or None) – (lower, upper) bounds for parameters.
args (tuple) – Additional arguments to pass to fun and jac.
**kwargs (Any) – Additional keyword arguments.

Returns:

Optimization result.

Return type:

Any

__init__(*args, **kwargs)

class nlsq.interfaces.optimizer_protocol.CurveFitProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for curve fitting interfaces.

This protocol defines the interface for curve_fit-like functions, enabling different implementations (standard, streaming, global).

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

Fit a function to data.

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]

__init__(*args, **kwargs)

DataSourceProtocol¶

Protocol for data source implementations.

Protocol definition for data sources.

This module defines the DataSourceProtocol that data providers should implement, enabling support for different data backends (arrays, HDF5, streaming).

class nlsq.interfaces.data_source_protocol.DataSourceProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for data sources.

This protocol defines the interface for data providers, allowing support for various backends like NumPy arrays, HDF5 files, or streaming data without coupling to specific implementations.

Properties¶

n_pointsint: Total number of data points.
n_dimsint: Number of dimensions in x data (1 for scalar x).
dtypenp.dtype: Data type of the arrays.

get_chunk(start, end)[source]

Get a chunk of data from start to end indices.

__len__()[source]

Return the total number of data points.

property n_points: int: Total number of data points.

property n_dims: int: Number of dimensions in x data.

property dtype: dtype: Data type of the arrays.

get_chunk(start, end)[source]

Get a chunk of data.

Parameters:

start (int) – Start index (inclusive).
end (int) – End index (exclusive).

Returns:

(xdata, ydata) arrays for the requested chunk.

Return type:

tuple[np.ndarray, np.ndarray]

__len__()[source]

Return total number of data points.

__init__(*args, **kwargs)

class nlsq.interfaces.data_source_protocol.StreamingDataSourceProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for streaming data sources.

Extended protocol for data sources that support streaming iteration over batches, useful for datasets that don’t fit in memory.

property n_points: int: Total number of data points.

property batch_size: int: Size of each batch.

__iter__()[source]

Return iterator over batches.

__next__()[source]

Get next batch of (xdata, ydata).

reset()[source]

Reset iterator to beginning.

__init__(*args, **kwargs)

class nlsq.interfaces.data_source_protocol.ArrayDataSource(xdata, ydata)[source]

Bases: object

Concrete implementation of DataSourceProtocol for NumPy arrays.

This is the default data source for in-memory arrays.

Parameters:

xdata (np.ndarray) – Independent variable data.
ydata (np.ndarray) – Dependent variable data.

__init__(xdata, ydata)[source]

property n_points: int: Total number of data points.

property n_dims: int: Number of dimensions in x data.

property dtype: dtype: Data type of the arrays.

get_chunk(start, end)[source]

Get a chunk of data.

__len__()[source]

Return total number of data points.

JacobianProtocol¶

Protocol for Jacobian computation implementations.

Protocol definition for Jacobian computation strategies.

This module defines the JacobianProtocol that Jacobian computation strategies should implement, enabling different approaches (autodiff, finite differences, analytical, sparse).

class nlsq.interfaces.jacobian_protocol.JacobianProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for Jacobian computation strategies.

This protocol defines the interface for computing Jacobians of residual functions, allowing different strategies to be swapped.

compute(fun, x, args)[source]

Compute the Jacobian matrix at point x.

compute(fun, x, args=())[source]

Compute Jacobian matrix.

Parameters:

fun (Callable) – Residual function f(x, *args) -> residuals.
x (np.ndarray) – Point at which to evaluate Jacobian.
args (tuple) – Additional arguments to pass to fun.

Returns:

Jacobian matrix of shape (n_residuals, n_params).

Return type:

np.ndarray

__init__(*args, **kwargs)

class nlsq.interfaces.jacobian_protocol.SparseJacobianProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for sparse Jacobian computation.

Extended protocol for Jacobians that may have sparse structure, returning sparse matrices when beneficial.

compute(fun, x, args=())[source]

Compute Jacobian matrix (possibly sparse).

compute_sparse(fun, x, args=(), sparsity_threshold=0.5)[source]

Compute sparse Jacobian if beneficial.

Parameters:

fun (Callable) – Residual function.
x (np.ndarray) – Point at which to evaluate.
args (tuple) – Additional arguments.
sparsity_threshold (float) – Fraction of zeros above which to use sparse format.

Returns:

Jacobian in appropriate format.

Return type:

np.ndarray or scipy.sparse matrix

property sparsity_pattern: ndarray | None: Known sparsity pattern, if any.

__init__(*args, **kwargs)

class nlsq.interfaces.jacobian_protocol.AutodiffJacobian(use_forward_mode=False)[source]

Bases: object

Jacobian computation using JAX automatic differentiation.

This is the default Jacobian computation strategy for NLSQ.

Parameters:: use_forward_mode (bool, default=False) – Use forward-mode AD (vmap of jvp) instead of reverse-mode. Forward mode is faster when n_params << n_residuals.

__init__(use_forward_mode=False)[source]

compute(fun, x, args=())[source]

Compute Jacobian using JAX autodiff.

ResultProtocol¶

Protocol for optimization result containers.

Protocol definition for optimization results.

This module defines the ResultProtocol that optimization results should implement, enabling consistent access to optimization outcomes.

class nlsq.interfaces.result_protocol.ResultProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for optimization results.

This protocol defines the minimum interface that optimization results must implement, enabling consistent handling across different optimizers.

x

Optimal parameter values.

Type:: np.ndarray

success

Whether optimization converged successfully.

Type:: bool

message

Description of termination reason.

Type:: str

property x: ndarray: Optimal parameter values.

property success: bool: Whether optimization converged successfully.

property message: str: Description of termination reason.

__init__(*args, **kwargs)

class nlsq.interfaces.result_protocol.LeastSquaresResultProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for least squares optimization results.

Extended protocol with additional attributes specific to least squares.

x

Optimal parameter values.

Type:: np.ndarray

cost

Final cost value (0.5 * sum(residuals**2)).

Type:: float

fun

Residuals at the solution.

Type:: np.ndarray

jac

Jacobian at the solution.

Type:: np.ndarray

success

Whether optimization converged successfully.

Type:: bool

message

Description of termination reason.

Type:: str

nfev

Number of function evaluations.

Type:: int

njev

Number of Jacobian evaluations.

Type:: int

property x: ndarray: Optimal parameter values.

property cost: float: Final cost value.

property fun: ndarray: Residuals at the solution.

property jac: ndarray: Jacobian at the solution.

property success: bool: Whether optimization converged successfully.

property message: str: Description of termination reason.

property nfev: int: Number of function evaluations.

property njev: int: Number of Jacobian evaluations.

__init__(*args, **kwargs)

class nlsq.interfaces.result_protocol.CurveFitResultProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for curve fit results.

Extended protocol with covariance information for curve fitting.

popt

Optimal parameter values.

Type:: np.ndarray

pcov

Covariance matrix of parameters.

Type:: np.ndarray

success

Whether fitting converged successfully.

Type:: bool

property popt: ndarray: Optimal parameter values.

property pcov: ndarray: Covariance matrix of parameters.

property success: bool: Whether fitting converged successfully.

get(key, default=None)[source]

Get attribute by name with default.

__init__(*args, **kwargs)

Orchestration Protocols¶

Protocols for the decomposed CurveFit orchestration components.

Protocol definitions for CurveFit orchestration components.

This module defines protocols for the decomposed CurveFit components: - DataPreprocessorProtocol: Input validation and array conversion - OptimizationSelectorProtocol: Method selection and configuration - CovarianceComputerProtocol: Covariance matrix computation - StreamingCoordinatorProtocol: Streaming strategy selection

These protocols enable dependency injection and facilitate testing of individual components in isolation.

class nlsq.interfaces.orchestration_protocol.PreprocessedData(xdata, ydata, sigma, mask, n_points, is_padded, original_length, has_nans_removed, has_infs_removed)[source]

Bases: object

Result of data preprocessing.

All arrays are validated and converted to JAX arrays. Padding may be applied for JAX compilation efficiency.

xdata

Independent variable data, shape (n,) or (k, n)

Type:: jax.Array

ydata

Dependent variable data, shape (n,)

Type:: jax.Array

sigma

Uncertainty/weights, shape (n,), (n, n), or None

Type:: jax.Array | None

mask

Boolean mask for valid data points, shape (n,)

Type:: jax.Array

n_points

Number of valid data points

Type:: int

is_padded

Whether arrays were padded for fixed-size compilation

Type:: bool

original_length

Length before padding (equals n_points if not padded)

Type:: int

has_nans_removed

True if NaN values were filtered during preprocessing

Type:: bool

has_infs_removed

True if Inf values were filtered during preprocessing

Type:: bool

xdata: jax.Array

ydata: jax.Array

sigma: jax.Array | None

mask: jax.Array

n_points: int

is_padded: bool

original_length: int

has_nans_removed: bool

has_infs_removed: bool

__init__(xdata, ydata, sigma, mask, n_points, is_padded, original_length, has_nans_removed, has_infs_removed)

class nlsq.interfaces.orchestration_protocol.DataPreprocessorProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for data preprocessing component.

Implementations handle: 1. Input validation (type checking, finiteness) 2. Array conversion (numpy/list to JAX) 3. Length consistency checking 4. Data masking for invalid points 5. Padding for JAX compilation efficiency

preprocess(f, xdata, ydata, *, sigma=None, absolute_sigma=False, check_finite=True, nan_policy='raise', stability_check=False)[source]

Validate and preprocess input data for curve fitting.

Parameters:

f (Callable[..., ArrayLike]) – Model function to fit (used for parameter count detection)
xdata (ArrayLike) – Independent variable data
ydata (ArrayLike) – Dependent variable data (observations)
sigma (ArrayLike | None) – Uncertainty/weights for observations
absolute_sigma (bool) – If True, sigma is absolute; else relative
check_finite (bool) – If True, raise on NaN/Inf values
nan_policy (str) – How to handle NaN: ‘raise’, ‘omit’, or ‘propagate’
stability_check (bool) – If True, run additional stability checks

Returns:

PreprocessedData with validated, converted arrays

Raises:

ValueError – If inputs are invalid (wrong shape, non-finite, etc.)
TypeError – If inputs have wrong types

Return type:

PreprocessedData

validate_sigma(sigma, ydata_shape)[source]

Validate and convert sigma to appropriate format.

Parameters:

sigma (ArrayLike | None) – Input sigma (1D for diagonal, 2D for full covariance)
ydata_shape (tuple[int, ...]) – Shape of ydata for compatibility check

Returns:

Validated JAX array or None

Raises:

ValueError – If sigma shape is incompatible with ydata

Return type:

jax.Array | None

__init__(*args, **kwargs)

class nlsq.interfaces.orchestration_protocol.OptimizationConfig(method, tr_solver, n_params, p0, bounds, max_nfev, ftol, xtol, gtol, jac, x_scale)[source]

Bases: object

Configuration for optimization execution.

Contains all settings needed by LeastSquares optimizer.

method

Optimization algorithm (‘trf’, ‘lm’, ‘dogbox’)

Type:: Literal[‘trf’, ‘lm’, ‘dogbox’]

tr_solver

Trust region subproblem solver (‘exact’, ‘lsmr’, None)

Type:: Literal[‘exact’, ‘lsmr’] | None

n_params

Number of parameters to fit

Type:: int

p0

Initial parameter guess

Type:: jax.Array

bounds

Lower and upper bounds as (lb, ub) tuple

Type:: tuple[jax.Array, jax.Array]

max_nfev

Maximum function evaluations

Type:: int

ftol

Relative tolerance for cost function

Type:: float

xtol

Relative tolerance for parameters

Type:: float

gtol

Relative tolerance for gradient

Type:: float

jac

Jacobian specification (‘2-point’, ‘3-point’, callable, None)

Type:: str | Callable | None

x_scale

Parameter scaling (‘jac’ or array)

Type:: jax.Array | str

method: Literal['trf', 'lm', 'dogbox']

tr_solver: Literal['exact', 'lsmr'] | None

n_params: int

p0: jax.Array

bounds: tuple[jax.Array, jax.Array]

max_nfev: int

ftol: float

xtol: float

gtol: float

jac: str | Callable | None

x_scale: jax.Array | str

__init__(method, tr_solver, n_params, p0, bounds, max_nfev, ftol, xtol, gtol, jac, x_scale)

class nlsq.interfaces.orchestration_protocol.OptimizationSelectorProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for optimization method selection component.

Implementations handle: 1. Parameter count detection from function signature 2. Method selection based on bounds and problem type 3. Bounds validation and preparation 4. Initial guess generation if not provided 5. Solver configuration validation

select(f, xdata, ydata, *, p0=None, bounds=None, method=None, jac=None, tr_solver=None, x_scale=1.0, ftol=1e-08, xtol=1e-08, gtol=1e-08, max_nfev=None)[source]

Select optimization method and prepare configuration.

Parameters:

f (Callable[..., ArrayLike]) – Model function to fit
xdata (jax.Array) – Independent variable data
ydata (jax.Array) – Dependent variable data
p0 (ArrayLike | None) – Initial parameter guess (auto-detected if None)
bounds (tuple[ArrayLike, ArrayLike] | None) – Parameter bounds as (lower, upper)
method (str | None) – Optimization method (‘trf’, ‘lm’, ‘dogbox’, or None for auto)
jac (str | Callable | None) – Jacobian computation method
tr_solver (str | None) – Trust region solver (‘exact’, ‘lsmr’, or None for auto)
x_scale (ArrayLike | str | float) – Parameter scaling
ftol (float) – Function tolerance
xtol (float) – Parameter tolerance
gtol (float) – Gradient tolerance
max_nfev (int | None) – Maximum function evaluations (auto if None)

Returns:

OptimizationConfig with all settings resolved

Raises:

ValueError – If configuration is invalid

Return type:

OptimizationConfig

detect_parameter_count(f, xdata)[source]

Detect number of parameters from function signature.

Uses inspection of function signature and optional probing with sample data to determine parameter count.

Parameters:

f (Callable[..., ArrayLike]) – Model function to analyze
xdata (jax.Array) – Sample data for probing

Returns:

Number of parameters (excluding x)

Raises:

ValueError – If parameter count cannot be determined

Return type:

int

auto_initial_guess(n_params, bounds)[source]

Generate automatic initial parameter guess.

Uses bounds midpoint if available, otherwise ones.

Parameters:

n_params (int) – Number of parameters
bounds (tuple[jax.Array, jax.Array] | None) – Parameter bounds or None

Returns:

Initial guess array of shape (n_params,)

Return type:

jax.Array

__init__(*args, **kwargs)

class nlsq.interfaces.orchestration_protocol.CovarianceResult(pcov, perr, method, condition_number, is_singular, sigma_used, absolute_sigma)[source]

Bases: object

Result of covariance matrix computation.

pcov

Parameter covariance matrix, shape (n, n)

Type:: jax.Array

perr

Parameter standard errors (sqrt of diagonal), shape (n,)

Type:: jax.Array

method

Computation method used (‘svd’, ‘cholesky’, ‘qr’)

Type:: Literal[‘svd’, ‘cholesky’, ‘qr’]

condition_number

Condition number of Jacobian

Type:: float

is_singular

True if Jacobian was singular/ill-conditioned

Type:: bool

sigma_used

True if sigma weights were applied

Type:: bool

absolute_sigma

True if sigma was treated as absolute

Type:: bool

pcov: jax.Array

perr: jax.Array

method: Literal['svd', 'cholesky', 'qr']

condition_number: float

is_singular: bool

sigma_used: bool

absolute_sigma: bool

__init__(pcov, perr, method, condition_number, is_singular, sigma_used, absolute_sigma)

class nlsq.interfaces.orchestration_protocol.CovarianceComputerProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for covariance computation component.

Implementations handle: 1. Jacobian-based covariance via SVD 2. Sigma transformation (1D and 2D) 3. Absolute vs relative sigma handling 4. Singularity detection and handling

compute(result, n_data, *, sigma=None, absolute_sigma=False, full_output=False)[source]

Compute parameter covariance from optimization result.

Uses the Jacobian at the solution to compute covariance via: pcov = (J^T @ J)^(-1) * s_sq

where s_sq is the residual variance.

Parameters:

result (OptimizeResult) – OptimizeResult from LeastSquares
n_data (int) – Number of data points
sigma (jax.Array | None) – Observation uncertainties/weights
absolute_sigma (bool) – If True, sigma is absolute uncertainty
full_output (bool) – If True, include additional diagnostics

Returns:

CovarianceResult with covariance matrix and metadata

Raises:

ValueError – If Jacobian is unavailable or invalid

Return type:

CovarianceResult

create_sigma_transform(sigma, n_data)[source]

Create sigma transformation function.

Handles both 1D (diagonal) and 2D (full covariance) sigma.

Parameters:

sigma (jax.Array) – Sigma array, shape (n,) or (n, n)
n_data (int) – Number of data points

Returns:

Tuple of (transform_func, is_2d) - transform_func: Function to apply sigma weighting - is_2d: True if sigma is full covariance matrix

Return type:

tuple[Callable, bool]

compute_condition_number(jacobian)[source]

Compute condition number of Jacobian.

Uses singular values: cond = max(s) / min(s)

Parameters:: jacobian (jax.Array) – Jacobian matrix at solution
Returns:: Condition number (inf if singular)
Return type:: float

__init__(*args, **kwargs)

class nlsq.interfaces.orchestration_protocol.StreamingDecision(strategy, reason, estimated_memory_mb, available_memory_mb, memory_pressure, chunk_size, n_chunks, hybrid_config)[source]

Bases: object

Decision about streaming execution strategy.

strategy

Execution strategy to use - ‘direct’: Normal non-streaming fit - ‘chunked’: Simple chunked processing - ‘hybrid’: AdaptiveHybridStreamingOptimizer - ‘auto_memory’: Memory-aware automatic selection

Type:: Literal[‘direct’, ‘chunked’, ‘hybrid’, ‘auto_memory’]

reason

Human-readable explanation of decision

Type:: str

estimated_memory_mb

Estimated memory requirement

Type:: float

available_memory_mb

Available system memory

Type:: float

memory_pressure

Memory pressure ratio (0.0 to 1.0)

Type:: float

chunk_size

Chunk size for chunked/hybrid strategies

Type:: int | None

n_chunks

Number of chunks for chunked strategy

Type:: int | None

hybrid_config

Configuration for hybrid strategy

Type:: HybridStreamingConfig | None

strategy: Literal['direct', 'chunked', 'hybrid', 'auto_memory']

reason: str

estimated_memory_mb: float

available_memory_mb: float

memory_pressure: float

chunk_size: int | None

n_chunks: int | None

hybrid_config: HybridStreamingConfig | None

__init__(strategy, reason, estimated_memory_mb, available_memory_mb, memory_pressure, chunk_size, n_chunks, hybrid_config)

class nlsq.interfaces.orchestration_protocol.StreamingCoordinatorProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for streaming strategy coordination.

Implementations handle: 1. Memory estimation for dataset + Jacobian 2. Available memory detection 3. Strategy selection based on memory pressure 4. Configuration of chunked/hybrid strategies

decide(xdata, ydata, n_params, *, workflow='auto', memory_limit_mb=None, force_streaming=False)[source]

Decide on streaming strategy for the dataset.

Analyzes memory requirements and available resources to select the optimal execution strategy.

Parameters:

xdata (jax.Array) – Independent variable data
ydata (jax.Array) – Dependent variable data
n_params (int) – Number of parameters
workflow (str) – Workflow hint (‘auto’, ‘streaming’, ‘hybrid’, ‘normal’)
memory_limit_mb (float | None) – Override for memory limit detection
force_streaming (bool) – If True, always use streaming

Returns:

StreamingDecision with strategy and configuration

Raises:

MemoryError – If dataset too large even for streaming

Return type:

StreamingDecision

estimate_memory(n_data, n_params, dtype_bytes=8)[source]

Estimate memory requirement in MB.

Accounts for: - Data arrays (x, y, residuals) - Jacobian matrix (n_data x n_params) - Working arrays for optimization - JAX compilation overhead

Parameters:

n_data (int) – Number of data points
n_params (int) – Number of parameters
dtype_bytes (int) – Bytes per element (8 for float64)

Returns:

Estimated memory in MB

Return type:

float

get_available_memory()[source]

Get available system memory in MB.

Uses psutil with caching for efficiency.

Returns:: Available memory in MB
Return type:: float

configure_hybrid(n_data, n_params, available_memory_mb)[source]

Configure hybrid streaming for dataset.

Calculates optimal chunk size and strategy parameters.

Parameters:

n_data (int) – Number of data points
n_params (int) – Number of parameters
available_memory_mb (float) – Available memory

Returns:

HybridStreamingConfig for the dataset

Return type:

HybridStreamingConfig

__init__(*args, **kwargs)

nlsq.interfaces.orchestration_protocol.DataPreprocessor: alias of DataPreprocessorProtocol

nlsq.interfaces.orchestration_protocol.OptimizationSelector: alias of OptimizationSelectorProtocol

nlsq.interfaces.orchestration_protocol.CovarianceComputer: alias of CovarianceComputerProtocol

nlsq.interfaces.orchestration_protocol.StreamingCoordinator: alias of StreamingCoordinatorProtocol