Function estimator Plugins

ropt.plugins.function_estimator

Provides plugin functionality for adding function estimators.

Function estimators are used by the optimization process to combine the results (objective function values and gradients) from a set of realizations into a single representative value. This module allows for the extension of ropt with custom strategies for aggregating ensemble results.

Core Concepts:

• Plugin Interface: Function estimator plugins must inherit from the FunctionEstimatorPlugin base class. This class acts as a factory, defining a create method to instantiate estimator objects.
• Estimator Implementation: The actual aggregation logic resides in classes that inherit from the FunctionEstimator abstract base class. These classes are initialized with the optimization configuration (EnOptConfig) and the index of the specific estimator configuration to use (estimator_index). The core functionality is provided by the calculate_function and calculate_gradient methods, which combine the function values and gradients from multiple realizations, respectively, using realization weights.
• Discovery: The PluginManager discovers available FunctionEstimatorPlugin implementations (typically via entry points) and uses them to create FunctionEstimator instances as needed during plan execution.

Built-in Function Estimator Plugins:

The default DefaultFunctionEstimator class provides methods for calculating the weighted mean (mean) and standard deviation (stddev) of the realization results.

ropt.plugins.function_estimator.base.FunctionEstimatorPlugin

Bases: Plugin

Abstract Base Class for Function Estimator Plugins (Factories).

This class defines the interface for plugins responsible for creating FunctionEstimator instances. These plugins act as factories for specific function estimation strategies.

During plan execution, the PluginManager identifies the appropriate function estimator plugin based on the configuration and uses its create class method to instantiate the actual FunctionEstimator object that will perform the aggregation of ensemble results (function values and gradients).

create abstractmethod classmethod

create(
    enopt_config: EnOptConfig, estimator_index: int
) -> FunctionEstimator

Factory method to create a concrete FunctionEstimator instance.

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

The PluginManager calls this method when an optimization step requires a function estimator provided by this plugin.

Parameters:

Name	Type	Description	Default
enopt_config	EnOptConfig	The main EnOpt configuration object.	required
estimator_index	int	Index into enopt_config.function_estimators for this estimator.	required

Returns:

Type	Description
FunctionEstimator	An initialized FunctionEstimator object ready for use.

ropt.plugins.function_estimator.base.FunctionEstimator

Bases: ABC

Abstract Base Class for Function Estimator Implementations.

This class defines the fundamental interface for all concrete function estimator implementations within the ropt framework. Function estimator plugins provide classes derived from FunctionEstimator that encapsulate the logic for combining the objective function values and gradients from an ensemble of realizations into a single representative value. This aggregated value is then used by the core optimization algorithm.

Instances of FunctionEstimator subclasses are created by their corresponding FunctionEstimatorPlugin factories. They are initialized with an EnOptConfig object detailing the optimization setup and the estimator_index identifying the specific estimator configuration to use from the config.

The core functionality involves combining results using realization weights, performed by the calculate_function and calculate_gradient methods, which must be implemented by subclasses.

Subclasses must implement:

• __init__: To accept the configuration and index.
• calculate_function: To combine function values from realizations.
• calculate_gradient: To combine gradient values from realizations.

__init__

__init__(
    enopt_config: EnOptConfig, estimator_index: int
) -> None

Initialize the function estimator object.

The function_estimators field in the enopt_config is a tuple of estimator configurations (FunctionEstimatorConfig). The estimator_index identifies which configuration from this tuple should be used to initialize this specific estimator instance.

Parameters:

Name	Type	Description	Default
enopt_config	EnOptConfig	The configuration of the optimizer.	required
estimator_index	int	The index of the estimator configuration to use.	required

calculate_function abstractmethod

calculate_function(
    functions: NDArray[float64], weights: NDArray[float64]
) -> NDArray[np.float64]

Combine function values from realizations into an expected value.

This method takes the function (objective or constraint) values evaluated for each realization in the ensemble and combines them into a single representative value or vector of values, using the provided realization weights.

Parameters:

Name	Type	Description	Default
functions	NDArray[float64]	The function values for each realization.	required
weights	NDArray[float64]	The weight for each realization.	required

Returns:

Type	Description
NDArray[float64]	A scalar or 1D array representing the combined function value(s).

calculate_gradient abstractmethod

calculate_gradient(
    functions: NDArray[float64],
    gradient: NDArray[float64],
    weights: NDArray[float64],
) -> NDArray[np.float64]

Combine gradients from realizations into an expected gradient.

This method takes the gradients evaluated for each realization and combines them into a single representative gradient vector or matrix, using the provided realization weights and potentially the function values themselves (e.g., for estimators like standard deviation where the chain rule applies).

Interaction with merge_realizations

The merge_realizations flag in the GradientConfig determines how the initial gradient estimate(s) are computed by ropt before being passed to this calculate_gradient method.

• If False (default): ropt estimates a separate gradient for each realization that has a non-zero weight. The implementation must then combine these gradients using the provided weights.
• If True: ropt computes a single, merged gradient estimate by treating all perturbations across all realizations collectively. The implementation must handle this input appropriately. For simple averaging estimators, this might involve returning the input gradient unchanged.

The merge_realizations=True option allows gradient estimation even with a low number of perturbations (potentially just one) but is generally only suitable for estimators performing averaging-like operations. Estimator implementations should check this flag during initialization (__init__) and raise a ValueError if merge_realizations=True is incompatible with the estimator's logic (e.g., standard deviation).

Parameters:

Name	Type	Description	Default
functions	NDArray[float64]	The functions for each realization.	required
gradient	NDArray[float64]	The gradient for each realization.	required
weights	NDArray[float64]	The weight of each realization.	required

Returns:

Type	Description
NDArray[float64]	The expected gradients.