Skip to content

Realization Filters

A realization filter selects which realizations contribute to a function or gradient value at each evaluation. The default provides CVaR-style tail selection, enabling risk-aware objectives.

See Realization Filters for usage.

ropt.realization_filter

Public API for realization filter implementations.

See Realization Filters for usage and algorithm descriptions.

ropt.realization_filter.RealizationFilter

Bases: ABC

Abstract base class for realization filter implementations.

Subclasses must implement two methods:

  1. __init__ — store configuration and pre-compute method-specific state.
  2. get_realization_weights — called at each evaluation; return a non-negative weight per realization.

See Realization Filters for examples and further guidance.

methods class-attribute 

methods: MethodSpec

The filter 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__(filter_config: RealizationFilterConfig) -> None

Create a new realization filter instance.

Store the configuration and pre-compute any method-specific state.

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The realization filter configuration.

 required

get_realization_weights abstractmethod 

get_realization_weights(
    objectives: NDArray[float64],
    constraints: NDArray[float64] | None,
    *,
    objective_scales: NDArray[float64],
    maximize: NDArray[bool_],
    objective_weights: NDArray[float64],
) -> NDArray[np.float64]

Compute one weight per realization from current evaluation results.

Called once per function evaluation, and only if at least one objective or nonlinear constraint refers to this filter. The weights returned by a single call are applied to all of them, and are reused for the gradients derived from that evaluation.

objectives and constraints are two-dimensional arrays with one row per realization and one column per objective or per nonlinear constraint, in the order in which they are configured: objectives[i, j] is the value of objective j for realization i. The number of realizations is therefore objectives.shape[0]. The values are as the evaluator returned them: neither scaled nor negated for maximization, since both apply to aggregates and these are per-realization. A filter that ranks by what the optimizer minimizes should apply objective_scales and maximize itself.

A realization that failed to evaluate carries nan values. The filter should check for these and handle them, for instance by assigning such realizations a weight of zero.

The returned weights replace the weights configured in the realizations section, and are normalized to sum to one before use. If no realization can be given a positive weight, raise TooFewRealizations to record the evaluation as failed.

Parameters:

Name Type Description Default
objectives NDArray[float64]

Objectives, shape (n_realizations, n_objectives).

 required
constraints NDArray[float64] | None

Nonlinear constraints, shape (n_realizations, n_constraints), or None if no nonlinear constraints are configured.

 required
objective_scales NDArray[float64]

The scale applied to each objective. Passed on every call because auto-scaling only fixes these after the first batch.

 required
maximize NDArray[bool_]

Which objectives are maximized.

 required
objective_weights NDArray[float64]

The configured weight of each objective.

 required

Returns:

Type Description
NDArray[float64]

The non-negative weights, shape (n_realizations,).

ropt.realization_filter.default.DefaultRealizationFilter

Bases: RealizationFilter

Default filter implementation providing CVaR methods.

The method is selected via the method field of RealizationFilterConfig. See Realization Filters for usage.

__init__ 

__init__(filter_config: RealizationFilterConfig) -> None

Initialize the realization filter.

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The realization filter configuration.

 required

ropt.realization_filter.default.CVaRObjectiveOptions

Bases: _ConfigBaseModel

Options for the cvar-objective filter method.

Assigns CVaR-derived weights to the worst-performing realizations based on a weighted sum of objectives. See Realization Filters for the algorithm.

Attributes:

Name Type Description
sort tuple[NonNegativeInt, ...]

Objective indices used for the weighted sum.
percentile Annotated[float, Field(gt=0.0, le=1.0)]

Fraction (0, 1] of worst realizations to include.

ropt.realization_filter.default.CVaRConstraintOptions

Bases: _ConfigBaseModel

Options for the cvar-constraint filter method.

Assigns CVaR-derived weights based on a single constraint function value, with "worst" defined by the constraint type (LE/GE/EQ). See Realization Filters for the algorithm.

Attributes:

Name Type Description
sort NonNegativeInt

Index of the constraint function to use.
percentile Annotated[float, Field(gt=0.0, le=1.0)]

Fraction (0, 1] of worst realizations to include.