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.

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 (EnOptConfig), 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 during plan execution.

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.

ropt.plugins.sampler.base.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.

During plan execution, the PluginManager identifies the appropriate sampler plugin based on the configuration and uses its create class method to instantiate the actual Sampler object that will generate the perturbation samples.

create `abstractmethod` `classmethod`

create(
    enopt_config: EnOptConfig,
    sampler_index: int,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> 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 step requires samples generated by this plugin.

Parameters:

Name	Type	Description	Default
`enopt_config`	`EnOptConfig`	The main EnOpt configuration object.	required
`sampler_index`	`int`	Index into `enopt_config.samplers` for this sampler.	required
`mask`	`NDArray[bool_] \| None`	Optional boolean mask for variable subset sampling.	required
`rng`	`Generator`	NumPy random number generator instance.	required

Returns:

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

ropt.plugins.sampler.base.Sampler

Bases: ABC

Abstract Base Class for Sampler Implementations.

This class defines the fundamental interface for all concrete sampler implementations within the ropt framework. Sampler plugins 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.

Instances of Sampler subclasses are created by their corresponding SamplerPlugin factories. They are initialized with an EnOptConfig object detailing the optimization setup, the sampler_index identifying the specific sampler configuration to use from the config, an optional variable mask indicating which variables this sampler instance handles, and a NumPy random number generator (rng) for stochastic methods.

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

Subclasses must implement:

__init__: To accept the configuration, index, mask, and RNG.
generate_samples: To contain the sample generation logic.

init

__init__(
    enopt_config: EnOptConfig,
    sampler_index: int,
    mask: NDArray[bool_] | None,
    rng: Generator,
) -> None

Initialize the sampler object.

The samplers field in the enopt_config is a tuple of sampler configurations (SamplerConfig). The sampler_index identifies which configuration from this tuple should be used to initialize this specific sampler instance.

If a boolean mask array is provided, it indicates that this sampler instance is responsible for generating samples only for the subset of variables where the mask is True.

Parameters:

Name	Type	Description	Default
`enopt_config`	`EnOptConfig`	The configuration of the optimizer.	required
`sampler_index`	`int`	The index of the sampler configuration to use.	required
`mask`	`NDArray[bool_] \| None`	Optional mask indicating variables handled by this sampler.	required
`rng`	`Generator`	A random generator object for stochastic methods.	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.