Function Estimators

ropt.function_estimator

Function estimators: aggregate per-realization values into one total.

An estimator reduces the function and gradient values of the ensemble to the single numbers the optimizer consumes.

See Function Estimators for usage and algorithm descriptions.

ropt.function_estimator.FunctionEstimator

Bases: ABC

Abstract base class for function estimator implementations.

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. Setup that depends on the optimization 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. merge_realizations is described under calculate_gradient.

Parameters:

Name	Type	Description	Default
merge_realizations	bool	Whether gradients arrive merged across realizations.	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_variables, n_realizations) 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,) — the per-realization values.	required
gradient	NDArray[float64]	Shape (n_variables, n_realizations), or (n_variables,).	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

init

init(*, merge_realizations: bool) -> None

Record whether the gradient keeps its realizations separate.

calculate_function

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

Estimate the function value as a weighted mean or standard deviation.

Returns:

Type	Description
NDArray[float64]	The estimated function value for each objective or constraint.

Raises:

Type	Description
ValueError	If the configured method is not supported, or stddev is combined with merged realizations.

calculate_gradient

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

Estimate the gradient to match the function the estimator returns.

Returns:

Type	Description
NDArray[float64]	The estimated gradient.

Raises:

Type	Description
ValueError	If the configured method is not supported, or stddev is combined with merged realizations.