Sampling (evopt.sampler)

The sampler module provides functionality for exploring parameter spaces using Sobol sequences, which generate well-distributed points throughout the parameter space. This is useful for understanding the landscape of your problem before optimization or for gathering training data for surrogate models.

Functions

evopt.sampler.sample(params: dict, evaluator: callable, n_samples: int = 32, rand_seed: int | None = None, target_dict: dict | None = None, max_workers: int = 1, cores_per_worker: int = 1, base_dir: str | None = None, dir_id: str | None = None, verbose: bool = False, **kwargs) → list[source]

Sample Sobol sequences and evaluate them using the provided evaluator.

Parameters:

  • params (dict) – Parameter space definition as a dictionary where keys are parameter names and values are tuples of (min_value, max_value) bounds.

  • evaluator (callable) – Function that evaluates a parameter set and returns either: - A single float value representing the error/fitness (lower is better) - A dictionary of observed values to be compared with target_dict

  • n_samples (int) – Number of Sobol samples to generate. Default is 32.

  • rand_seed (int) – Random seed for reproducibility. Default is None.

  • target_dict (dict) – Dictionary of target values for comparison. Default is None.

  • max_workers (int) – Maximum number of worker processes. Default is 1.

  • cores_per_worker (int) – Number of CPU cores per worker process. Default is 1.

  • base_dir (str) – Base directory for storing optimization results. If None, uses current directory.

  • dir_id (str) – Directory ID for organizing results. Default is None.

  • verbose (bool) – Whether to print detailed information during sampling and evaluation. Default is False.

Returns:

A list containing the results for each sample. Each element is

a tuple: (sample_idx, error, result_dict, param_dict). Returns None for samples that failed evaluation.

Return type:

list

Raises:

RuntimeError – If sample generation fails or produces incorrect number of samples.

Core Functionality

This function enables efficient parameter space exploration. It supports:

  • Parameter space definition with min/max bounds

  • Sobol sequence generation for quasi-random sampling

  • Parallel evaluation of samples

  • Multi-objective evaluation with target dictionaries

  • CSV output for analysis

  • Directory organization similar to the optimization module

Key Features

  • Quasi-Random Sampling: Uses Sobol sequences to ensure better coverage of the parameter space than purely random sampling

  • Parallelization: Supports multi-core and multi-node evaluation of samples

  • Consistent Storage: Results are stored in a structured directory format compatible with plotting tools

  • Target Support: Works with the same target dictionary format as the optimizer module

  • Resumability: Can resume from interrupted sampling runs by tracking completed samples

Usage Examples

Basic sampling of a parameter space:

results = evopt.sample(
    params={'x': (-5, 5), 'y': (-5, 5)},
    evaluator=my_function,
    n_samples=64
)

Parallel sampling with targets:

results = evopt.sample(
    params=params_dict,
    evaluator=my_evaluator,
    target_dict=targets,
    n_samples=100,
    max_workers=4,
    cores_per_worker=2
)