nlsq.global_optimization.config

Configuration classes for global optimization strategies.

Global Optimization Configuration

Configuration dataclass for multi-start optimization with Latin Hypercube Sampling.

This module provides the GlobalOptimizationConfig dataclass which controls all aspects of multi-start global optimization, including sampling strategy, starting point generation, and tournament selection for large datasets.

Examples

Basic configuration with defaults:

>>> from nlsq.global_optimization import GlobalOptimizationConfig
>>> config = GlobalOptimizationConfig()
>>> config.n_starts
10

Using presets:

>>> config = GlobalOptimizationConfig.from_preset('robust')
>>> config.n_starts
5

>>> config = GlobalOptimizationConfig.from_preset('global')
>>> config.n_starts
20

Custom configuration:

>>> config = GlobalOptimizationConfig(
...     n_starts=30,
...     sampler='sobol',
...     center_on_p0=True,
...     scale_factor=0.5,
... )
class nlsq.global_optimization.config.GlobalOptimizationConfig(n_starts=10, sampler='lhs', center_on_p0=True, scale_factor=1.0, elimination_rounds=3, elimination_fraction=0.5, batches_per_round=50, _preset=None)[source]

Bases: object

Configuration for multi-start global optimization.

This configuration class controls all aspects of multi-start optimization with Latin Hypercube Sampling or other quasi-random samplers.

Parameters:

  • n_starts (int, default=10) – Number of starting points to generate. Set to 0 to disable multi-start.

  • sampler ({'lhs', 'sobol', 'halton'}, default='lhs') –

    Sampling strategy for generating starting points:

    • ’lhs’: Latin Hypercube Sampling (recommended, stratified random)

    • ’sobol’: Sobol quasi-random sequence (deterministic, low-discrepancy)

    • ’halton’: Halton quasi-random sequence (deterministic, prime bases)

  • center_on_p0 (bool, default=True) – Whether to center starting points around the initial parameter guess (p0). When True, samples are generated in a region around p0 rather than uniformly in the full parameter bounds.

  • scale_factor (float, default=1.0) – Scale factor for exploration region when center_on_p0=True. Multiplier for the exploration range around p0. Smaller values (0.5) = tighter exploration around p0. Larger values (2.0) = wider exploration.

  • elimination_rounds (int, default=3) – Number of tournament elimination rounds for large datasets. Each round eliminates a fraction of candidates based on loss.

  • elimination_fraction (float, default=0.5) – Fraction of candidates to eliminate in each tournament round. Must be in (0, 1). Default 0.5 eliminates half in each round.

  • batches_per_round (int, default=50) – Number of data batches to use for evaluation in each tournament round. More batches = more reliable selection but slower.

Examples

>>> config = GlobalOptimizationConfig(n_starts=20, sampler='sobol')
>>> config.n_starts
20

>>> config = GlobalOptimizationConfig.from_preset('global')
>>> config.n_starts
20

Notes

  • When n_starts=0, multi-start is disabled and standard single-start optimization is used.

  • Tournament selection (elimination_rounds > 0) is designed for streaming datasets where evaluating all candidates on the full dataset is impractical.

  • LHS provides better coverage guarantees than Sobol/Halton for small N, while Sobol/Halton are deterministic and may be preferred for reproducibility.

See also

MultiStartOrchestrator

Orchestrates multi-start optimization

TournamentSelector

Implements tournament selection for large datasets

n_starts: int
sampler: Literal['lhs', 'sobol', 'halton']
center_on_p0: bool
scale_factor: float
elimination_rounds: int
elimination_fraction: float
batches_per_round: int
__post_init__()[source]

Validate configuration after initialization.

classmethod from_preset(preset_name)[source]

Create configuration from a named preset.

Parameters:

preset_name (str) – Name of the preset. One of: ‘fast’, ‘robust’, ‘global’, ‘thorough’, ‘streaming’.

Returns:

Configuration instance with preset values.

Return type:

GlobalOptimizationConfig

Raises:

ValueError – If preset_name is not a known preset.

Examples

>>> config = GlobalOptimizationConfig.from_preset('robust')
>>> config.n_starts
5

>>> config = GlobalOptimizationConfig.from_preset('global')
>>> config.n_starts
20
property is_multistart_enabled: bool

Whether multi-start optimization is enabled.

Returns:

True if n_starts > 0, False otherwise.

Return type:

bool

property preset: str | None

The preset name if this config was created from a preset.

Returns:

Preset name (‘fast’, ‘robust’, etc.) or None if custom.

Return type:

str or None

to_dict()[source]

Serialize configuration to a dictionary.

Returns:

Dictionary representation suitable for JSON serialization or checkpoint saving.

Return type:

dict

Examples

>>> config = GlobalOptimizationConfig(n_starts=20)
>>> d = config.to_dict()
>>> d['n_starts']
20
classmethod from_dict(d)[source]

Deserialize configuration from a dictionary.

Parameters:

d (dict) – Dictionary with configuration values.

Returns:

Configuration instance.

Return type:

GlobalOptimizationConfig

Examples

>>> d = {'n_starts': 20, 'sampler': 'sobol'}
>>> config = GlobalOptimizationConfig.from_dict(d)
>>> config.n_starts
20
with_overrides(**kwargs)[source]

Create a new config with specified overrides.

Parameters:

**kwargs (Any) – Configuration fields to override.

Returns:

New configuration with overrides applied.

Return type:

GlobalOptimizationConfig

Examples

>>> config = GlobalOptimizationConfig.from_preset('robust')
>>> config2 = config.with_overrides(n_starts=10)
>>> config2.n_starts
10
__init__(n_starts=10, sampler='lhs', center_on_p0=True, scale_factor=1.0, elimination_rounds=3, elimination_fraction=0.5, batches_per_round=50, _preset=None)

GlobalOptimizationConfig

class nlsq.global_optimization.config.GlobalOptimizationConfig(n_starts=10, sampler='lhs', center_on_p0=True, scale_factor=1.0, elimination_rounds=3, elimination_fraction=0.5, batches_per_round=50, _preset=None)[source]

Bases: object

Configuration for multi-start global optimization.

This configuration class controls all aspects of multi-start optimization with Latin Hypercube Sampling or other quasi-random samplers.

Parameters:

  • n_starts (int, default=10) – Number of starting points to generate. Set to 0 to disable multi-start.

  • sampler ({'lhs', 'sobol', 'halton'}, default='lhs') –

    Sampling strategy for generating starting points:

    • ’lhs’: Latin Hypercube Sampling (recommended, stratified random)

    • ’sobol’: Sobol quasi-random sequence (deterministic, low-discrepancy)

    • ’halton’: Halton quasi-random sequence (deterministic, prime bases)

  • center_on_p0 (bool, default=True) – Whether to center starting points around the initial parameter guess (p0). When True, samples are generated in a region around p0 rather than uniformly in the full parameter bounds.

  • scale_factor (float, default=1.0) – Scale factor for exploration region when center_on_p0=True. Multiplier for the exploration range around p0. Smaller values (0.5) = tighter exploration around p0. Larger values (2.0) = wider exploration.

  • elimination_rounds (int, default=3) – Number of tournament elimination rounds for large datasets. Each round eliminates a fraction of candidates based on loss.

  • elimination_fraction (float, default=0.5) – Fraction of candidates to eliminate in each tournament round. Must be in (0, 1). Default 0.5 eliminates half in each round.

  • batches_per_round (int, default=50) – Number of data batches to use for evaluation in each tournament round. More batches = more reliable selection but slower.

Examples

>>> config = GlobalOptimizationConfig(n_starts=20, sampler='sobol')
>>> config.n_starts
20

>>> config = GlobalOptimizationConfig.from_preset('global')
>>> config.n_starts
20

Notes

  • When n_starts=0, multi-start is disabled and standard single-start optimization is used.

  • Tournament selection (elimination_rounds > 0) is designed for streaming datasets where evaluating all candidates on the full dataset is impractical.

  • LHS provides better coverage guarantees than Sobol/Halton for small N, while Sobol/Halton are deterministic and may be preferred for reproducibility.

See also

MultiStartOrchestrator

Orchestrates multi-start optimization

TournamentSelector

Implements tournament selection for large datasets

n_starts: int
sampler: Literal['lhs', 'sobol', 'halton']
center_on_p0: bool
scale_factor: float
elimination_rounds: int
elimination_fraction: float
batches_per_round: int
__post_init__()[source]

Validate configuration after initialization.

classmethod from_preset(preset_name)[source]

Create configuration from a named preset.

Parameters:

preset_name (str) – Name of the preset. One of: ‘fast’, ‘robust’, ‘global’, ‘thorough’, ‘streaming’.

Returns:

Configuration instance with preset values.

Return type:

GlobalOptimizationConfig

Raises:

ValueError – If preset_name is not a known preset.

Examples

>>> config = GlobalOptimizationConfig.from_preset('robust')
>>> config.n_starts
5

>>> config = GlobalOptimizationConfig.from_preset('global')
>>> config.n_starts
20
property is_multistart_enabled: bool

Whether multi-start optimization is enabled.

Returns:

True if n_starts > 0, False otherwise.

Return type:

bool

property preset: str | None

The preset name if this config was created from a preset.

Returns:

Preset name (‘fast’, ‘robust’, etc.) or None if custom.

Return type:

str or None

to_dict()[source]

Serialize configuration to a dictionary.

Returns:

Dictionary representation suitable for JSON serialization or checkpoint saving.

Return type:

dict

Examples

>>> config = GlobalOptimizationConfig(n_starts=20)
>>> d = config.to_dict()
>>> d['n_starts']
20
classmethod from_dict(d)[source]

Deserialize configuration from a dictionary.

Parameters:

d (dict) – Dictionary with configuration values.

Returns:

Configuration instance.

Return type:

GlobalOptimizationConfig

Examples

>>> d = {'n_starts': 20, 'sampler': 'sobol'}
>>> config = GlobalOptimizationConfig.from_dict(d)
>>> config.n_starts
20
with_overrides(**kwargs)[source]

Create a new config with specified overrides.

Parameters:

**kwargs (Any) – Configuration fields to override.

Returns:

New configuration with overrides applied.

Return type:

GlobalOptimizationConfig

Examples

>>> config = GlobalOptimizationConfig.from_preset('robust')
>>> config2 = config.with_overrides(n_starts=10)
>>> config2.n_starts
10
__init__(n_starts=10, sampler='lhs', center_on_p0=True, scale_factor=1.0, elimination_rounds=3, elimination_fraction=0.5, batches_per_round=50, _preset=None)

Usage Example

from nlsq.global_optimization import GlobalOptimizationConfig

# Create config with Latin Hypercube Sampling
config = GlobalOptimizationConfig(
    n_starts=20,
    sampler="lhs",
    parallel=True,
)

# Or use a preset
config = GlobalOptimizationConfig.from_preset("multimodal")