Skip to content

Function Estimators

A function estimator aggregates per-realization function and gradient values into the single totals consumed by the optimizer.

See Function Estimators for usage and algorithm descriptions.

ropt.function_estimator

Public API for function estimator implementations.

See Function Estimators for usage and algorithm descriptions.

ropt.function_estimator.FunctionEstimator

Bases: ABC

Abstract base class for function estimator implementations.

Subclasses must implement four methods:

  1. __init__ — store configuration; defer heavy work to init.
  2. init — called once with the full optimization context; validate settings and pre-compute state here.
  3. calculate_function — aggregate per-realization function values.
  4. calculate_gradient — aggregate per-realization gradients.

See Function Estimators for examples and further guidance.

__init__ abstractmethod 

__init__(estimator_config: FunctionEstimatorConfig) -> None

Create a new function estimator instance.

Store the configuration; keep initialization lightweight. Context-dependent setup belongs in init.

Parameters:

Name Type Description Default
estimator_config FunctionEstimatorConfig

The estimator configuration.

 required

init abstractmethod 

init(context: EnOptContext) -> None

Finalize initialization with the optimization context.

Called once after configuration is finalized. Use for validation (e.g., compatibility with merge_realizations) and precomputation.

Parameters:

Name Type Description Default
context EnOptContext

The optimization context.

 required

calculate_function abstractmethod 

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

Aggregate function values across realizations.

Parameters:

Name Type Description Default
functions NDArray[float64]

Shape (n_realizations,) — per-realization values.

 required
weights NDArray[float64]

Shape (n_realizations,) — realization weights.

 required

Returns:

Type Description
NDArray[float64]

Aggregated value (scalar or 1-D array).

calculate_gradient abstractmethod 

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

Aggregate gradients across realizations.

When merge_realizations is False (default), gradient has shape (n_realizations, n_variables) and must be combined using weights. When True, a single pre-merged gradient of shape (n_variables,) is passed. Incompatible estimators should raise ValueError from init.

Parameters:

Name Type Description Default
functions NDArray[float64]

Shape (n_realizations,) — needed for chain-rule estimators (e.g., standard deviation).

 required
gradient NDArray[float64]

Shape (n_realizations, n_variables) or (n_variables,) if merged.

 required
weights NDArray[float64]

Shape (n_realizations,) — realization weights.

 required

Returns:

Type Description
NDArray[float64]

1-D array of shape (n_variables,).

ropt.plugins.function_estimator.default.DefaultFunctionEstimator

Bases: FunctionEstimator

Default estimator providing mean and stddev methods.

The method is selected via the method field of FunctionEstimatorConfig. See Function Estimators for usage.