Skip to content

Realization Filters

A realization filter selects which realizations contribute to a function or gradient value at each evaluation. The defaults provide worst-/best-N sorting and 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 three methods:

  1. __init__ — store configuration; defer heavy work to init.
  2. init — called once with the full optimization context; validate settings and pre-compute any method-specific state here.
  3. get_realization_weights — called at each evaluation; return a non-negative weight per realization.

See Realization Filters for examples and further guidance.

__init__ abstractmethod 

__init__(filter_config: RealizationFilterConfig) -> None

Create a new realization filter instance.

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

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The realization filter configuration.

 required

init abstractmethod 

init(context: EnOptContext) -> None

Finalize initialization with the optimization context.

Called once after configuration is finalized. Use for validation, internal state setup, or precomputation.

Parameters:

Name Type Description Default
context EnOptContext

The optimization context.

 required

get_realization_weights abstractmethod 

get_realization_weights(
    objectives: NDArray[float64],
    constraints: NDArray[float64] | None,
) -> NDArray[np.float64]

Compute one weight per realization from current evaluation results.

Return a non-negative weight for each realization. The optimizer normalizes weights to sum to one before use.

Parameters:

Name Type Description Default
objectives NDArray[float64]

Shape (n_realizations, n_objectives).

 required
constraints NDArray[float64] | None

Shape (n_realizations, n_constraints), or None.

 required

Returns:

Type Description
NDArray[float64]

1-D array of shape (n_realizations,).

ropt.realization_filter.default.DefaultRealizationFilter

Bases: RealizationFilter

Default filter implementation providing sort and CVaR methods.

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

ropt.realization_filter.default.SortObjectiveOptions

Bases: _ConfigBaseModel

Options for the sort-objective filter method.

Selects realizations by ranking 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.
first NonNegativeInt

Starting rank (0-based, inclusive) of selected realizations.
last NonNegativeInt

Ending rank (0-based, inclusive) of selected realizations.

ropt.realization_filter.default.SortConstraintOptions

Bases: _ConfigBaseModel

Options for the sort-constraint filter method.

Selects realizations by ranking a single constraint function value. See Realization Filters for the algorithm.

Attributes:

Name Type Description
sort NonNegativeInt

Index of the constraint function to sort by.
first NonNegativeInt

Starting rank (0-based, inclusive) of selected realizations.
last NonNegativeInt

Ending rank (0-based, inclusive) of selected realizations.

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.