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 before the run; 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.

methods class-attribute

methods: MethodSpec

The estimator methods this class provides.

Either a set of names, which the registry matches case-insensitively, or a predicate for classes that cannot enumerate them. Include "default" in the set if this class has one. See MethodSpec.

__init__ abstractmethod

__init__(estimator_config: FunctionEstimatorConfig) -> None

Create a new function estimator instance.

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

Parameters:

Name	Type	Description	Default
estimator_config	FunctionEstimatorConfig	The estimator configuration.	required

init abstractmethod

init(*, merge_realizations: bool) -> None

Finalize initialization before the optimization starts.

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

Parameters:

Name	Type	Description	Default
merge_realizations	bool	Whether gradients arrive merged across realizations, as described in calculate_gradient.	required

calculate_function abstractmethod

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

Aggregate function values across realizations.

The values arrive as the evaluator returned them. Scales are applied to the aggregate this method produces, so an implementation does not need to account for them.

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 instead — suitable only for estimators that aggregate by a simple weighted combination (for example the mean). Estimators that need each realization's own gradient (for example standard deviation, via the chain rule) are incompatible with merging and should raise ValueError from init.

Parameters:

Name	Type	Description	Default
functions	NDArray[float64]	Shape (n_realizations,) — needed for chain-rule estimators (for example 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.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.

__init__

__init__(estimator_config: FunctionEstimatorConfig) -> None

Initialize the function estimator.

Parameters:

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