Sampler Plugins

ropt.plugins.sampler

Provides plugin functionality for adding sampler plugins.

Samplers are used by the optimization process to generate perturbed variable vectors. This module allows for the extension of ropt with custom samplers.

Built-in Sampler Plugins:

By default, the SciPySampler sampler is installed, which provides several sampling methods based on the scipy.stats and scipy.stats.qmc packages.

Core Concepts:

Plugin Interface: Sampler plugins must inherit from the SamplerPlugin base class. This class acts as a factory, defining a create method to instantiate sampler objects.
Sampler Implementation: The actual sampling logic resides in classes that inherit from the Sampler abstract base class. These classes are initialized with the optimization configuration (EnOptContext), the index of the specific sampler configuration to use (sampler_index), an optional variable mask (mask), and a random number generator (rng). Samples are generated by calling the sampler's generate_samples method.
Discovery: The PluginManager discovers available SamplerPlugin implementations (typically via entry points) and uses them to create Sampler instances as needed.

SamplerPlugin

Bases: Plugin

Abstract Base Class for Sampler Plugins (Factories).

This class defines the interface for plugins responsible for creating Sampler instances. These plugins act as factories for specific sampling algorithms or strategies.

create `abstractmethod` `classmethod`

create(sampler_config: SamplerConfig) -> Sampler

Factory method to create a concrete Sampler instance.

This abstract class method serves as a factory for creating concrete Sampler objects. Plugin implementations must override this method to return an instance of their specific Sampler subclass.

The PluginManager calls this method when an optimization requires samples generated by this plugin.

Parameters:

Name	Type	Description	Default
`sampler_config`	`SamplerConfig`	The sampler configuration object.	required

Returns:

Type	Description
`Sampler`	An initialized Sampler object ready for use.

ropt.plugins.sampler.SamplerPlugin

Bases: Plugin

Abstract Base Class for Sampler Plugins (Factories).

This class defines the interface for plugins responsible for creating Sampler instances. These plugins act as factories for specific sampling algorithms or strategies.

create `abstractmethod` `classmethod`

create(sampler_config: SamplerConfig) -> Sampler

Factory method to create a concrete Sampler instance.

This abstract class method serves as a factory for creating concrete Sampler objects. Plugin implementations must override this method to return an instance of their specific Sampler subclass.

The PluginManager calls this method when an optimization requires samples generated by this plugin.

Parameters:

Name	Type	Description	Default
`sampler_config`	`SamplerConfig`	The sampler configuration object.	required

Returns:

Type	Description
`Sampler`	An initialized Sampler object ready for use.

ropt.sampler

Provides functionality for sampler objects.

Samplers are used by the optimization process to generate perturbed variable vectors. This module allows for the extension of ropt with custom samplers.

Sampler

Bases: ABC

Abstract Base Class for Sampler Implementations.

This class defines the fundamental interface for all concrete sampler implementations within the ropt framework. Samplers provide classes derived from Sampler that encapsulate the logic of specific sampling algorithms or strategies used to generate perturbed variable vectors for the optimization process.

The core functionality, generating samples, is performed by the generate_samples method, which must be implemented by subclasses.

Subclasses must implement a generate_samples that contains the sample generation logic.

init `abstractmethod`

init(
    context: EnOptContext,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> None

Initialize the sampler object.

Sets the internal state of the sampler, including the variable mask and random number generator.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The main EnOpt context object.	required
`mask`	`NDArray[bool_] \| None`	Optional boolean mask for variable subset sampling.	required
`rng`	`Generator`	NumPy random number generator instance.	required

generate_samples `abstractmethod`

generate_samples() -> NDArray[np.float64]

Generate and return an array of sampled perturbation values.

This method must return a three-dimensional NumPy array containing the generated perturbation samples. The shape of the array should be (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 (realizations) should have a size of 1. The framework will broadcast these shared samples across all realizations.

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 will be multiplied element-wise by the perturbation_magnitudes defined in the GradientConfig.

Therefore, it is generally recommended that sampler implementations produce samples with a characteristic scale of approximately one (e.g., drawn from a distribution with a standard deviation of 1, or uniformly distributed within [-1, 1]). This allows the perturbation_magnitudes to directly control the effective size of the perturbations applied to the variables.

Returns:

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

ropt.sampler.Sampler

Bases: ABC

Abstract Base Class for Sampler Implementations.

This class defines the fundamental interface for all concrete sampler implementations within the ropt framework. Samplers provide classes derived from Sampler that encapsulate the logic of specific sampling algorithms or strategies used to generate perturbed variable vectors for the optimization process.

The core functionality, generating samples, is performed by the generate_samples method, which must be implemented by subclasses.

Subclasses must implement a generate_samples that contains the sample generation logic.

init `abstractmethod`

init(
    context: EnOptContext,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> None

Initialize the sampler object.

Sets the internal state of the sampler, including the variable mask and random number generator.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The main EnOpt context object.	required
`mask`	`NDArray[bool_] \| None`	Optional boolean mask for variable subset sampling.	required
`rng`	`Generator`	NumPy random number generator instance.	required

generate_samples `abstractmethod`

generate_samples() -> NDArray[np.float64]

Generate and return an array of sampled perturbation values.

This method must return a three-dimensional NumPy array containing the generated perturbation samples. The shape of the array should be (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 (realizations) should have a size of 1. The framework will broadcast these shared samples across all realizations.

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 will be multiplied element-wise by the perturbation_magnitudes defined in the GradientConfig.

Therefore, it is generally recommended that sampler implementations produce samples with a characteristic scale of approximately one (e.g., drawn from a distribution with a standard deviation of 1, or uniformly distributed within [-1, 1]). This allows the perturbation_magnitudes to directly control the effective size of the perturbations applied to the variables.

Returns:

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

ropt.plugins.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 (e.g., 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.

Sampler Plugins

ropt.plugins.sampler

SamplerPlugin

create abstractmethod classmethod

ropt.plugins.sampler.SamplerPlugin

create abstractmethod classmethod

ropt.sampler

Sampler

init abstractmethod

generate_samples abstractmethod

ropt.sampler.Sampler

init abstractmethod

generate_samples abstractmethod

ropt.plugins.sampler.scipy.SciPySampler

create `abstractmethod` `classmethod`

create `abstractmethod` `classmethod`

init `abstractmethod`

generate_samples `abstractmethod`

init `abstractmethod`

generate_samples `abstractmethod`