nlsq.streaming.validators

Configuration validators for hybrid streaming optimization.

Added in version 1.2.0: Extracted from nlsq.streaming.hybrid_config for maintainability.

This module provides validation functions for HybridStreamingConfig parameters. Each validator ensures configuration values are within acceptable ranges and provides informative error messages.

Validation Functions

The module provides validators for:

  • Chunk size: Ensures reasonable memory usage

  • Learning rates: Validates warmup learning rate bounds

  • Tolerance values: Checks convergence tolerances

  • Iteration limits: Validates max iteration counts

  • Defense layer thresholds: Ensures layer thresholds are sensible

Module Contents

Validators for streaming configuration parameters.

This module provides validation functions for HybridStreamingConfig parameters, extracted from the monolithic __post_init__ method to reduce complexity and improve testability.

exception nlsq.streaming.validators.ConfigValidationError[source]

Bases: ValueError

Exception raised when configuration validation fails.

nlsq.streaming.validators.validate_enum_value(value, valid_options, param_name)[source]

Validate that value is one of the valid options.

Parameters:

  • value (Any) – The value to validate.

  • valid_options (tuple[str, ...]) – Tuple of valid option strings.

  • param_name (str) – Name of the parameter for error messages.

Raises:

ConfigValidationError – If value is not in valid_options.

nlsq.streaming.validators.validate_positive(value, param_name)[source]

Validate that value is strictly positive.

Parameters:

  • value (float or int) – The value to validate.

  • param_name (str) – Name of the parameter for error messages.

Raises:

ConfigValidationError – If value is not positive.

nlsq.streaming.validators.validate_non_negative(value, param_name)[source]

Validate that value is non-negative.

Parameters:

  • value (float or int) – The value to validate.

  • param_name (str) – Name of the parameter for error messages.

Raises:

ConfigValidationError – If value is negative.

nlsq.streaming.validators.validate_range(value, min_val, max_val, param_name, inclusive_min=True, inclusive_max=True)[source]

Validate that value is within a range.

Parameters:

  • value (float) – The value to validate.

  • min_val (float) – Minimum value.

  • max_val (float) – Maximum value.

  • param_name (str) – Name of the parameter for error messages.

  • inclusive_min (bool) – Whether min is inclusive.

  • inclusive_max (bool) – Whether max is inclusive.

Raises:

ConfigValidationError – If value is out of range.

nlsq.streaming.validators.validate_less_than_or_equal(value1, value2, name1, name2)[source]

Validate that value1 <= value2.

Parameters:

  • value1 (float or int) – First value.

  • value2 (float or int) – Second value.

  • name1 (str) – Name of first parameter.

  • name2 (str) – Name of second parameter.

Raises:

ConfigValidationError – If value1 > value2.

nlsq.streaming.validators.validate_normalization_strategy(strategy)[source]

Validate normalization strategy parameter.

nlsq.streaming.validators.validate_loop_strategy(strategy)[source]

Validate loop strategy parameter.

Validate L-BFGS line search method.

nlsq.streaming.validators.validate_multistart_sampler(sampler)[source]

Validate multi-start sampler method.

nlsq.streaming.validators.validate_warmup_config(warmup_iterations, max_warmup_iterations, warmup_learning_rate, loss_plateau_threshold, gradient_norm_threshold)[source]

Validate Phase 1 warmup configuration parameters.

Parameters:

  • warmup_iterations (int) – Number of warmup iterations.

  • max_warmup_iterations (int) – Maximum warmup iterations.

  • warmup_learning_rate (float) – Learning rate for warmup.

  • loss_plateau_threshold (float) – Loss plateau detection threshold.

  • gradient_norm_threshold (float) – Gradient norm threshold.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_lbfgs_config(history_size, initial_step_size, line_search, exploration_step_size, refinement_step_size)[source]

Validate L-BFGS configuration parameters.

Parameters:

  • history_size (int) – L-BFGS history size.

  • initial_step_size (float) – Initial step size.

  • line_search (str) – Line search method.

  • exploration_step_size (float) – Step size for exploration mode.

  • refinement_step_size (float) – Step size for refinement mode.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_gauss_newton_config(max_iterations, tol, trust_region_initial, regularization_factor)[source]

Validate Phase 2 Gauss-Newton configuration parameters.

Parameters:

  • max_iterations (int) – Maximum iterations.

  • tol (float) – Convergence tolerance.

  • trust_region_initial (float) – Initial trust region radius.

  • regularization_factor (float) – Regularization factor.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_cg_config(max_iterations, relative_tolerance, absolute_tolerance, param_threshold)[source]

Validate Conjugate Gradient solver configuration.

Parameters:

  • max_iterations (int) – Maximum CG iterations.

  • relative_tolerance (float) – Relative tolerance.

  • absolute_tolerance (float) – Absolute tolerance.

  • param_threshold (int) – Parameter count threshold.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_group_variance_config(enabled, lambda_val, indices)[source]

Validate group variance regularization configuration.

Parameters:

  • enabled (bool) – Whether regularization is enabled.

  • lambda_val (float) – Regularization strength.

  • indices (list of tuple or None) – Parameter group indices.

Raises:

ConfigValidationError – If any parameter is invalid when enabled.

nlsq.streaming.validators.validate_streaming_config(chunk_size, checkpoint_frequency, callback_frequency)[source]

Validate streaming configuration parameters.

Parameters:

  • chunk_size (int) – Data chunk size.

  • checkpoint_frequency (int) – Checkpoint save frequency.

  • callback_frequency (int) – Callback frequency.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_lr_schedule_config(enabled, warmup_steps, decay_steps, end_value)[source]

Validate learning rate schedule configuration.

Parameters:

  • enabled (bool) – Whether schedule is enabled.

  • warmup_steps (int) – Warmup steps.

  • decay_steps (int) – Decay steps.

  • end_value (float) – End learning rate value.

Raises:

ConfigValidationError – If any parameter is invalid when enabled.

nlsq.streaming.validators.validate_gradient_clip(clip_value)[source]

Validate gradient clipping value.

Parameters:

clip_value (float or None) – Gradient clip value.

Raises:

ConfigValidationError – If clip_value is not None and not positive.

nlsq.streaming.validators.validate_defense_layer_config(enable_warm_start, warm_start_threshold, enable_adaptive_lr, lr_refinement, lr_careful, lr_default, enable_cost_guard, cost_tolerance, enable_step_clipping, max_step_size)[source]

Validate 4-layer defense strategy configuration.

Parameters:

  • enable_warm_start (bool) – Enable Layer 1.

  • warm_start_threshold (float) – Warm start threshold.

  • enable_adaptive_lr (bool) – Enable Layer 2.

  • lr_refinement (float) – Refinement learning rate.

  • lr_careful (float) – Careful learning rate.

  • lr_default (float) – Default learning rate.

  • enable_cost_guard (bool) – Enable Layer 3.

  • cost_tolerance (float) – Cost increase tolerance.

  • enable_step_clipping (bool) – Enable Layer 4.

  • max_step_size (float) – Maximum step size.

Raises:

ConfigValidationError – If any parameter is invalid.

nlsq.streaming.validators.validate_residual_weighting_config(enabled, weights)[source]

Validate residual weighting configuration.

Residual weighting allows users to assign different importance to different data points or groups of data points during optimization. This is useful for: - Heteroscedastic data (varying noise levels) - Emphasizing certain regions of the data - Down-weighting outliers - Domain-specific weighting schemes

Parameters:

  • enabled (bool) – Whether residual weighting is enabled.

  • weights (array-like or None) – Weight array. Can be either: - Per-group weights of shape (n_groups,) with group_indices provided - Per-point weights of shape (n_data,) for direct weighting

Raises:

ConfigValidationError – If configuration is invalid.

nlsq.streaming.validators.validate_multistart_config(enabled, n_starts, sampler, elimination_fraction, elimination_rounds, batches_per_round, scale_factor)[source]

Validate multi-start optimization configuration.

Parameters:

  • enabled (bool) – Whether multi-start is enabled.

  • n_starts (int) – Number of starting points.

  • sampler (str) – Sampling method.

  • elimination_fraction (float) – Fraction to eliminate per round.

  • elimination_rounds (int) – Number of rounds.

  • batches_per_round (int) – Batches per round.

  • scale_factor (float) – Scale factor for sampling.

Raises:

ConfigValidationError – If any parameter is invalid when enabled.

Usage Example

from nlsq.streaming.validators import (
    validate_chunk_size,
    validate_learning_rate,
    validate_tolerance,
)

# Validate configuration values
chunk_size = validate_chunk_size(10000)  # Returns validated value
lr = validate_learning_rate(0.001, "warmup_lr")
tol = validate_tolerance(1e-8, "ftol")

See Also