Default Realization Filter Plugin

ropt.plugins.realization_filter.default.DefaultRealizationFilter

Bases: RealizationFilter

The default implementation for realization filtering strategies.

This class provides several methods for calculating realization weights based on objective or constraint values. The specific method and its parameters are configured via the RealizationFilterConfig in the main EnOptConfig.

Supported Methods:

sort-objective: Sorts realizations based on a weighted sum of specified objective function values. It then assigns zero weights to realizations outside of a defined index range (first to last) in the sorted list. Requires options defined by SortObjectiveOptions.
sort-constraint: Sorts realizations based on the value of a single specified constraint function. It assigns zero weights to realizations outside of a defined index range (first to last) in the sorted list. Requires options defined by SortConstraintOptions.
cvar-objective: Calculates realization weights using the Conditional Value-at-Risk (CVaR) method applied to a weighted sum of specified objective function values. Weights are assigned based on a specified percentile of the worst-performing realizations (highest objective values for minimization). Interpolation is used if the percentile boundary falls between realizations. Requires options defined by CVaRObjectiveOptions.
cvar-constraint: Calculates realization weights using the CVaR method applied to the value of a single specified constraint function. Weights are assigned based on a specified percentile of the worst-performing realizations (definition of "worst" depends on the constraint type: LE, GE, or EQ). Interpolation is used if the percentile boundary falls between realizations. Requires options defined by CVaRConstraintOptions.

ropt.plugins.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:

A weighted sum is calculated for each realization using the objective values specified by the sort indices and the corresponding weights from the main EnOptConfig. If only one objective index is provided in sort, no weighting is applied.
Realizations are sorted based on this calculated value (ascending).
Realizations whose rank falls within the range [first, last] (inclusive) are selected.
The original weights (from EnOptConfig.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.plugins.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:

The values of the constraint function specified by the sort index are retrieved for each realization.
Realizations are sorted based on these constraint values (ascending).
Realizations whose rank falls within the range [first, last] (inclusive) are selected.
The original weights (from EnOptConfig.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.plugins.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:

A weighted sum is calculated for each realization using the objective values specified by the sort indices and the corresponding weights from the main EnOptConfig. If only one objective index is provided in sort, no weighting is applied.
Realizations are conceptually sorted based on this calculated value (ascending, assuming minimization).
The method identifies the subset of realizations corresponding to the percentile worst outcomes (i.e., the highest weighted objective values).
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.
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.plugins.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:

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).
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.
The method identifies the subset of realizations corresponding to the percentile worst outcomes based on the sorting defined above.
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.
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.