Skip to content

Realization Filters

ropt.realization_filter

Realization filters: select which realizations contribute to a value.

A filter is applied per evaluation, to a function or a gradient. The default provides CVaR-style tail selection, for risk-aware objectives.

See Realization Filters for usage and algorithm descriptions.

ropt.realization_filter.RealizationFilter

Bases: ABC

Abstract base class for realization filter implementations.

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],
    constraint_lower_bounds: NDArray[float64] | None,
    constraint_upper_bounds: NDArray[float64] | None,
) -> 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.

The constraint bounds are given in the same domain as constraints, so a filter that ranks by constraint violation can subtract them directly. A constraint is violated below constraint_lower_bounds and above constraint_upper_bounds; equal bounds make it an equality. Both are None when no nonlinear constraints are configured.

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.

objective_scales is passed on every call because auto-scaling only fixes the scales after the first batch.

Parameters:

Name Type Description Default
objectives NDArray[float64]

Objectives, shape (n_realizations, n_objectives).

 required
constraints NDArray[float64] | None

Constraints, shape (n_realizations, n_constraints).

 required
objective_scales NDArray[float64]

The scale applied to each objective.

 required
maximize NDArray[bool_]

Which objectives are maximized.

 required
objective_weights NDArray[float64]

The configured weight of each objective.

 required
constraint_lower_bounds NDArray[float64] | None

The lower bound of each constraint.

 required
constraint_upper_bounds NDArray[float64] | None

The upper bound of each constraint.

 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, ranking realizations by how far each violates that constraint. 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.