Skip to content

Realization Filters

ropt.realization_filter

Public API for realization filter implementations.

Realization filters define how much each realization contributes to the values used by the optimizer. In ensemble-based workflows, the optimizer evaluates objective and constraint functions for multiple realizations; filters inspect those per-realization results and return a weight for each realization.

Core Interface

All filter implementations inherit from the RealizationFilter base class, which defines the filter lifecycle (__init__, init) and the required weighting method (get_realization_weights).

Integration with Optimization

Realization filters are accessed via an EnOptContext object through its realization_filters field, a tuple of realization filter instances. Filters are instantiated either directly as objects or via RealizationFilterConfig objects, which are used by the plugin system to create instances based on the configured method string (e.g., "sort" or "cvar").

Built-in and Custom Filters

The DefaultRealizationFilter class provides commonly used weighting strategies, including:

  • sort: Assign weights based on ranking objective and constraint values.
  • cvar: Assign weights based on a Conditional Value-at-Risk selection.

Users can implement custom filters by subclassing RealizationFilter. Those subclasses can be instantiated directly and passed into an EnOptContext object through its realization_filters field. Registering a custom filter with the plugin system is optional and only required when the filter should be selected and configured via RealizationFilterConfig objects instead of being instantiated explicitly by the user.

ropt.realization_filter.RealizationFilter

Bases: ABC

Abstract base class for realization filter implementations.

All concrete realization filter implementations must inherit from this class and implement the required weighting method. Filters are responsible for examining per-realization objective and constraint values and returning a non-negative weight for each realization.

The weights produced by filters are used by the optimizer to control how strongly each realization contributes to aggregated objective and constraint values.

Lifecycle

  1. Instantiation via __init__: Called by the plugin system with a configuration object.
  2. Setup via init: Called once per optimization workflow with the EnOptContext, allowing final initialization based on the full optimization configuration.
  3. Evaluation via get_realization_weights: Called repeatedly during optimization as new objective and constraint values become available.

Subclasses must implement:

  • __init__: Stores filter configuration and performs lightweight setup.
  • init: Receives the optimization context for context-dependent initialization.
  • get_realization_weights: Returns one weight per realization based on the current objective and constraint values.

__init__ abstractmethod 

__init__(filter_config: RealizationFilterConfig) -> None

Create a new realization filter instance.

Called during instantiation. Subclasses should store the configuration and perform any lightweight initialization. Validation and context-dependent setup should be deferred to the init method.

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The realization filter configuration.

 required

init abstractmethod 

init(context: EnOptContext) -> None

Finalize initialization after the optimization context is known.

Called once at the start of each optimization workflow, after all configuration is finalized. Use this method to perform context-dependent initialization such as validation of filter settings, setup of internal state, or precomputation of method-specific data.

Parameters:

Name Type Description Default
context EnOptContext

The main EnOpt context object.

 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.

Examines the current per-realization objective and constraint values and returns a non-negative weight vector that determines how strongly each realization influences subsequent aggregation steps. The exact weighting rule is defined by the concrete filter implementation.

The objectives and constraints inputs are organized with realizations along the first axis and objective or constraint indices along the second axis.

Normalization

The weights will be normalized to a sum of one by the optimizer before use, hence any non-negative weight value is permissible.

Parameters:

Name Type Description Default
objectives NDArray[float64]

Array of shape (n_realizations, n_objectives) containing objective values for each realization.

 required
constraints NDArray[float64] | None

Array of shape (n_realizations, n_constraints) containing constraint values for each realization, or None when the workflow has no constraints.

 required

Returns:

Type Description
NDArray[float64]

A 1D array of shape (n_realizations,) containing the weight of
NDArray[float64]

each realization.

ropt.realization_filter.default.DefaultRealizationFilter

Bases: RealizationFilter

Default implementation of realization filters with sort and CVaR methods.

Implements the RealizationFilter interface to provide standard strategies for selecting or reweighting realizations based on objective or constraint values.

The specific method is selected via the method field of the RealizationFilterConfig, which is passed during initialization.

Supported Filtering Methods

  • sort-objective: Sorts realizations by a weighted combination of selected objective values, then keeps only the realizations whose rank falls within the configured inclusive range [first, last].
  • sort-constraint: Sorts realizations by a selected constraint value, then keeps only the realizations whose rank falls within the configured inclusive range [first, last].
  • cvar-objective: Assigns weights to the worst-performing realizations according to a CVaR selection on a weighted combination of selected objective values.
  • cvar-constraint: Assigns weights to the worst-performing realizations according to a CVaR selection on a selected constraint value, with the definition of "worst" determined by the constraint type.

Each method validates and uses its corresponding options model:

ropt.realization_filter.default.SortObjectiveOptions

Bases: _ConfigBaseModel

Configuration settings for the sort-objective realization filter.

This method sorts realizations based on a weighted sum of objective function values and assigns weights only to those within a specified rank range.

How it works:

  1. A weighted sum is calculated for each realization using the objective values specified by the sort indices and the corresponding weights from the main EnOptContext. If only one objective index is provided in sort, no weighting is applied.
  2. Realizations are sorted based on this calculated value (ascending).
  3. Realizations whose rank falls within the range [first, last] (inclusive) are selected.
  4. The original weights (from EnOptContext.realizations.weights) of the selected realizations are retained; all other realizations receive a weight of zero. Failed realizations (NaN objective values) are effectively given the lowest rank and are excluded before selection.

Attributes:

Name Type Description
sort tuple[NonNegativeInt]

List of objective function indices to use for sorting.
first NonNegativeInt

The starting rank (0-based index) of realizations to select after sorting.
last NonNegativeInt

The ending rank (0-based index) of realizations to select after sorting.

ropt.realization_filter.default.SortConstraintOptions

Bases: _ConfigBaseModel

Configuration settings for the sort-constraint realization filter.

This method sorts realizations based on the value of a single constraint function and assigns weights only to those within a specified rank range.

How it works:

  1. The values of the constraint function specified by the sort index are retrieved for each realization.
  2. Realizations are sorted based on these constraint values (ascending).
  3. Realizations whose rank falls within the range [first, last] (inclusive) are selected.
  4. The original weights (from EnOptContext.realizations.weights) of the selected realizations are retained; all other realizations receive a weight of zero. Failed realizations (NaN constraint values) are effectively given the lowest rank and are excluded before selection.

Attributes:

Name Type Description
sort NonNegativeInt

The index of the constraint function to use for sorting.
first NonNegativeInt

The starting rank (0-based index) of realizations to select after sorting.
last NonNegativeInt

The ending rank (0-based index) of realizations to select after sorting.

ropt.realization_filter.default.CVaRObjectiveOptions

Bases: _ConfigBaseModel

Configuration settings for the cvar-objective realization filter.

This method calculates realization weights using the Conditional Value-at-Risk (CVaR) approach applied to a weighted sum of objective function values. It focuses on the "tail" of the distribution representing the worst-performing realizations.

How it works:

  1. A weighted sum is calculated for each realization using the objective values specified by the sort indices and the corresponding weights from the main EnOptContext. If only one objective index is provided in sort, no weighting is applied.
  2. Realizations are conceptually sorted based on this calculated value (ascending, assuming minimization).
  3. The method identifies the subset of realizations corresponding to the percentile worst outcomes (i.e., the highest weighted objective values).
  4. Weights are assigned to these worst-performing realizations based on the CVaR calculation. If the percentile boundary falls between two realizations, interpolation is used to assign partial weights. All other realizations receive a weight of zero.
  5. Failed realizations (NaN objective values) are effectively excluded from the CVaR calculation.

Attributes:

Name Type Description
sort tuple[NonNegativeInt]

List of objective function indices to use for the weighted sum.
percentile Annotated[float, Field(gt=0.0, le=1.0)]

The CVaR percentile (0.0 to 1.0) defining the portion of worst realizations to consider. Defaults to 0.5.

ropt.realization_filter.default.CVaRConstraintOptions

Bases: _ConfigBaseModel

Configuration settings for the cvar-constraint realization filter.

This method calculates realization weights using the Conditional Value-at-Risk (CVaR) approach applied to the values of a single constraint function. It focuses on the "tail" of the distribution representing the realizations that most severely violate or are furthest from satisfying the constraint.

How it works:

  1. The values of the constraint function specified by the sort index are retrieved for each realization. These values typically represent the constraint function evaluated minus its right-hand-side value (e.g., g(x) - rhs).
  2. Realizations are conceptually sorted based on how "badly" they perform with respect to the constraint type:
    • LE (<=) constraints: Realizations with the largest positive values (most violated) are considered the worst.
    • GE (>=) constraints: Realizations with the smallest negative values (most violated) are considered the worst.
    • EQ (==) constraints: Realizations with the largest absolute values (furthest from zero) are considered the worst.
  3. The method identifies the subset of realizations corresponding to the percentile worst outcomes based on the sorting defined above.
  4. Weights are assigned to these worst-performing realizations based on the CVaR calculation. If the percentile boundary falls between two realizations, interpolation is used to assign partial weights. All other realizations receive a weight of zero.
  5. Failed realizations (NaN constraint values) are effectively excluded from the CVaR calculation.

Attributes:

Name Type Description
sort NonNegativeInt

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

The CVaR percentile (0.0 to 1.0) defining the portion of worst realizations to consider. Defaults to 0.5.