Function Estimators

ropt.function_estimator

Public API for function estimator implementations.

Function estimators define how realization-level results are aggregated into the values used by the optimizer. In ensemble-based workflows, each realization contributes objective/constraint function values and gradients; estimators combine those per-realization arrays with realization weights to produce one representative function value and one representative gradient.

Core Interface

All estimator implementations inherit from the FunctionEstimator base class, which defines the estimator lifecycle (__init__, init) and the two required aggregation methods (calculate_function, calculate_gradient).

Integration with Optimization

Function estimators are accessed via an EnOptContext object through its function_estimators field, a tuple of function estimator instances. Estimators are instantiated either directly as objects or via FunctionEstimatorConfig objects, which are used by the plugin system to create instances based on the configured method string (e.g., "mean" or "stddev").

Built-in and Custom Estimators

The DefaultFunctionEstimator class provides two commonly used aggregation strategies:

• mean: Weighted average of realization values/gradients.
• stddev: Weighted standard deviation of values with chain-rule gradients.

Users can implement custom estimators by subclassing FunctionEstimator. Those subclasses can be instantiated directly and passed into an EnOptContext object through its function_estimators field. Registering a custom estimator with the plugin system is optional and only required when the estimator should be selected and configured via FunctionEstimatorConfig objects instead of being instantiated explicitly by the user.

ropt.function_estimator.FunctionEstimator

Bases: ABC

Abstract base class for function estimator implementations.

All concrete function estimator implementations must inherit from this class and implement the required aggregation methods. Estimators are responsible for combining per-realization objective/constraint function values and gradients into single representative values using realization weights.

The aggregated values produced by estimators are used directly by the optimizer during each iteration.

Lifecycle

1. Instantiation via __init__: Called by the plugin system with a configuration object.
2. Setup via init: Called once per optimization workflow with the EnOptContext, allowing final initialization based on the full optimization configuration.
3. Evaluation via calculate_function and calculate_gradient: Called repeatedly during optimization as new function/gradient values become available.

Subclasses must implement:

• __init__: Stores estimator configuration and performs lightweight setup.
• init: Receives the optimization context for context-dependent initialization.
• calculate_function: Combines function values from all realizations.
• calculate_gradient: Combines gradients from all realizations.

__init__ abstractmethod

__init__(estimator_config: FunctionEstimatorConfig) -> None

Create a new function estimator instance.

Called by the plugin system during instantiation. Subclasses should store the configuration and perform any lightweight initialization. Validation and context-dependent setup should be deferred to the init method.

Parameters:

Name	Type	Description	Default
estimator_config	FunctionEstimatorConfig	Configuration object specifying the estimator method and any method-specific options.	required

init abstractmethod

init(context: EnOptContext) -> None

Finalize initialization after the optimization context is known.

Called once at the start of each optimization workflow, after all configuration is finalized. Use this method to perform context-dependent initialization such as validation of gradient settings, setup of internal state, or computation of method-specific parameters.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The full optimization context, containing all configuration and state for the current workflow.	required

calculate_function abstractmethod

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

Aggregate function values across realizations into a single value.

Combines per-realization objective or constraint function values into one representative value using the provided realization weights. The aggregation method is defined by the concrete estimator implementation.

Parameters:

Name	Type	Description	Default
functions	NDArray[float64]	Array of shape (n_realizations,) containing function values from each realization.	required
weights	NDArray[float64]	Array of shape (n_realizations,) containing the weight for each realization. Typically represents the probability mass or importance of each realization.	required

Returns:

Type	Description
NDArray[float64]	Aggregated function value as a scalar or 1D array.

calculate_gradient abstractmethod

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

Aggregate gradients across realizations into a single gradient.

Combines per-realization gradients into one representative gradient vector using the provided realization weights and potentially the function values themselves. The aggregation method is defined by the concrete estimator implementation.

This method is called after function values have been evaluated for all realizations. Some estimators (e.g., standard deviation) require the function values to correctly compute gradients via the chain rule.

Parameters:

Name	Type	Description	Default
functions	NDArray[float64]	Array of shape (n_realizations,) containing function values from each realization. Used by some estimators to compute gradients correctly (e.g., chain rule for standard deviation).	required
gradient	NDArray[float64]	Array of shape (n_realizations, n_variables) containing gradient estimates for each realization. Depending on the GradientConfig.merge_realizations setting, this may be either per-realization or pre-merged estimates (see note below).	required
weights	NDArray[float64]	Array of shape (n_realizations,) containing the weight for each realization.	required

Returns:

Type	Description
NDArray[float64]	Aggregated gradient as a 1D array of shape (n_variables,).

merge_realizations setting

The GradientConfig.merge_realizations flag determines how gradient inputs are prepared:

• If False (default): ropt estimates a separate gradient for each realization with non-zero weight. The implementation must combine these per-realization gradients using weights (e.g., weighted average or chain-rule-adjusted aggregation).
• If True: ropt estimates a single merged gradient by treating all perturbations across all realizations collectively, then passes that single estimate. The implementation should handle this appropriately (e.g., return it unchanged for averaging-like operations).

The merge_realizations=True option is useful for workflows with few perturbations (even just one) but is only suitable for estimators performing simple averaging. Implementations should validate compatibility during init and raise ValueError if the configured setting is incompatible with the estimator's logic (e.g., standard deviation).

ropt.plugins.function_estimator.default.DefaultFunctionEstimator

Bases: FunctionEstimator

Default implementation of function estimator with mean and stddev methods.

Implements the FunctionEstimator interface to provide two standard aggregation strategies for combining objective/constraint function values and gradients from multiple realizations.

The specific method is selected via the method field of the FunctionEstimatorConfig, which is passed to the parent class during initialization.

Supported Aggregation Methods

• mean (or default): Computes the weighted average of realization function values and gradients. For functions, returns: sum(functions[i] * weights[i]). For gradients, returns the weighted average of per-realization gradients, or the pre-merged gradient if merge_realizations=True in the gradient configuration.
• stddev: Computes the weighted standard deviation of realization function values. For functions, returns the sample standard deviation weighted by realization weights. For gradients, applies the chain rule to combine function values and per-realization gradients.
  • Requires at least two realizations with non-zero weights.
  • Incompatible with merge_realizations=True; raises ValueError during init if this setting is detected.