Samplers

ropt.sampler

Samplers: generators of the perturbation values used for gradient estimation.

A sampler is selected through the samplers field of an EnOptContext, either as an instance or as a SamplerConfig naming a method. SciPySampler provides the methods backed by scipy.stats and scipy.stats.qmc.

See Stochastic Gradients for how sampling fits into the gradient pipeline, and Writing a Plugin for implementing one.

Sampler

Bases: ABC

Abstract base class for sampler implementations.

A sampler generates the perturbation values that are applied to the optimization variables when estimating gradients.

See Stochastic Gradients.

methods class-attribute

methods: MethodSpec

The sampling methods this class provides.

Either a set of names, which the registry matches case-insensitively, or a predicate for classes that cannot enumerate them. Include "default" in the set if this class has one. See MethodSpec.

__init__ abstractmethod

__init__(sampler_config: SamplerConfig) -> None

Create a new sampler instance.

Called during instantiation. Subclasses should store the configuration and perform any lightweight initialization. Validation and run-dependent setup should usually be deferred to init.

Parameters:

Name	Type	Description	Default
sampler_config	SamplerConfig	Configuration specifying the method and its options.	required

init abstractmethod

init(
    *,
    realization_count: int,
    perturbation_count: int,
    variable_count: int,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> None

Finalize initialization before the optimization starts.

Called once at the start of each optimization workflow, after all configuration is finalized. The three counts are the shape of the array generate_samples must return. A mask of None makes the sampler responsible for every variable.

Parameters:

Name	Type	Description	Default
realization_count	int	The number of realizations in the ensemble.	required
perturbation_count	int	The number of perturbations to generate.	required
variable_count	int	The total number of optimization variables.	required
mask	NDArray[bool_] | None	Optional mask selecting this sampler's variables.	required
rng	Generator	NumPy random number generator.	required

generate_samples abstractmethod

generate_samples() -> NDArray[np.float64]

Generate perturbation samples for optimization variables.

Returns a three-dimensional NumPy array with shape (n_realizations, n_perturbations, n_variables), where:

• n_realizations is the number of realizations in the ensemble.
• n_perturbations is the number of perturbations requested.
• n_variables is the total number of optimization variables.

If the shared flag is True in the associated SamplerConfig, the first dimension still has size n_realizations. Implementations may internally generate a single realization of samples and broadcast that internally before returning.

If a boolean mask was provided during initialization, this sampler instance is responsible only for a subset of variables (where the mask is True). The returned array must still have the full n_variables size along the last axis. However, values corresponding to variables not handled by this sampler (where the mask is False) must be zero.

Sample Scaling and Perturbation Magnitudes

The generated samples represent unscaled perturbations. During the gradient estimation process, these samples are multiplied element-wise by the perturbation_magnitudes defined in the VariablesConfig.

Samples with a characteristic scale of approximately one — drawn, for example, from a distribution with a standard deviation of 1, or uniformly from [-1, 1] — let the perturbation_magnitudes control the effective size of the perturbations applied to the variables directly.

Returns:

Type	Description
NDArray[float64]	A 3D NumPy array of perturbation values.

ropt.sampler.Sampler

Bases: ABC

Abstract base class for sampler implementations.

A sampler generates the perturbation values that are applied to the optimization variables when estimating gradients.

See Stochastic Gradients.

methods class-attribute

methods: MethodSpec

The sampling methods this class provides.

Either a set of names, which the registry matches case-insensitively, or a predicate for classes that cannot enumerate them. Include "default" in the set if this class has one. See MethodSpec.

__init__ abstractmethod

__init__(sampler_config: SamplerConfig) -> None

Create a new sampler instance.

Called during instantiation. Subclasses should store the configuration and perform any lightweight initialization. Validation and run-dependent setup should usually be deferred to init.

Parameters:

Name	Type	Description	Default
sampler_config	SamplerConfig	Configuration specifying the method and its options.	required

init abstractmethod

init(
    *,
    realization_count: int,
    perturbation_count: int,
    variable_count: int,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> None

Finalize initialization before the optimization starts.

Called once at the start of each optimization workflow, after all configuration is finalized. The three counts are the shape of the array generate_samples must return. A mask of None makes the sampler responsible for every variable.

Parameters:

Name	Type	Description	Default
realization_count	int	The number of realizations in the ensemble.	required
perturbation_count	int	The number of perturbations to generate.	required
variable_count	int	The total number of optimization variables.	required
mask	NDArray[bool_] | None	Optional mask selecting this sampler's variables.	required
rng	Generator	NumPy random number generator.	required

generate_samples abstractmethod

generate_samples() -> NDArray[np.float64]

Generate perturbation samples for optimization variables.

Returns a three-dimensional NumPy array with shape (n_realizations, n_perturbations, n_variables), where:

• n_realizations is the number of realizations in the ensemble.
• n_perturbations is the number of perturbations requested.
• n_variables is the total number of optimization variables.

If the shared flag is True in the associated SamplerConfig, the first dimension still has size n_realizations. Implementations may internally generate a single realization of samples and broadcast that internally before returning.

If a boolean mask was provided during initialization, this sampler instance is responsible only for a subset of variables (where the mask is True). The returned array must still have the full n_variables size along the last axis. However, values corresponding to variables not handled by this sampler (where the mask is False) must be zero.

Sample Scaling and Perturbation Magnitudes

The generated samples represent unscaled perturbations. During the gradient estimation process, these samples are multiplied element-wise by the perturbation_magnitudes defined in the VariablesConfig.

Samples with a characteristic scale of approximately one — drawn, for example, from a distribution with a standard deviation of 1, or uniformly from [-1, 1] — let the perturbation_magnitudes control the effective size of the perturbations applied to the variables directly.

Returns:

Type	Description
NDArray[float64]	A 3D NumPy array of perturbation values.

ropt.sampler.scipy.SciPySampler

Bases: Sampler

A sampler implementation utilizing SciPy's statistical functions.

This sampler leverages functions from the scipy.stats and scipy.stats.qmc modules to generate perturbation samples for optimization.

Supported Sampling Methods:

• From Probability Distributions (scipy.stats):

  • norm: Samples from a standard normal distribution (mean 0, standard deviation 1). This is the default method if none is specified or if "default" is requested.
  • truncnorm: Samples from a truncated normal distribution (mean 0, std dev 1), truncated to the range [-1, 1] by default.
  • uniform: Samples from a uniform distribution. Defaults to the range [-1, 1].

• From Quasi-Monte Carlo Sequences (scipy.stats.qmc):

  • sobol: Uses Sobol' sequences.
  • halton: Uses Halton sequences.
  • lhs: Uses Latin Hypercube Sampling. (Note: QMC samples are generated in the unit hypercube [0, 1]^d and then scaled to the hypercube [-1, 1]^d)

Configuration:

The specific sampling method is chosen via the method field in the SamplerConfig. Additional method-specific parameters (for example distribution parameters like loc, scale, a, b for stats methods, or engine parameters for qmc methods) can be passed through the options dictionary within the SamplerConfig. Refer to the scipy.stats and documentation for available options.