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.

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.

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 (EnOptContext) 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 workflow execution.

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 optimization 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(
    estimator_config: FunctionEstimatorConfig,
) -> 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 the optimization requires a function estimator provided by this plugin.

Parameters:

Name	Type	Description	Default
estimator_config	FunctionEstimatorConfig	The configuration object for this function estimator.	required

Returns:

Type	Description
FunctionEstimator	An initialized FunctionEstimator object ready for use.

ropt.plugins.function_estimator.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 optimization 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(
    estimator_config: FunctionEstimatorConfig,
) -> 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 the optimization requires a function estimator provided by this plugin.

Parameters:

Name	Type	Description	Default
estimator_config	FunctionEstimatorConfig	The configuration object for this function estimator.	required

Returns:

Type	Description
FunctionEstimator	An initialized FunctionEstimator object ready for use.

ropt.function_estimator.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 estimators 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.

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:

• calculate_function: To combine function values from realizations.
• calculate_gradient: To combine gradient values from realizations.

init abstractmethod

init(context: EnOptContext) -> None

Initialize the function estimator object.

This method is called by ropt during the setup phase of the optimization process. It allows the function estimator to perform any necessary initialization based on the provided configuration.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The EnOpt context object.	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.

ropt.plugins.function_estimator.default.DefaultFunctionEstimator

Bases: FunctionEstimator

The default implementation for function estimation strategies.

This class provides methods for combining objective function values and gradients from an ensemble of realizations into a single representative value or gradient. The specific method is configured via the FunctionEstimatorConfig in the main EnOptContext.

Supported Methods:

• mean (or default): Calculates the combined function value as the weighted mean of the individual realization function values. The combined gradient is calculated as the weighted mean of the individual realization gradients (unless merge_realizations is true, in which case the pre-merged gradient is used directly).

• stddev: Calculates the combined function value as the weighted standard deviation of the individual realization function values. The combined gradient is calculated using the chain rule based on the standard deviation formula. This method requires at least two realizations with non-zero weights and is incompatible with merge_realizations=True for gradient calculation.