Skip to content

Realization Filter Plugins

ropt.plugins.realization_filter

Provides plugin functionality for adding realization filters.

Realization filters are used by the optimization process to determine how the results from a set of realizations should be weighted when evaluating the overall objective and constraint functions. This module allows for the extension of ropt with custom realization filtering strategies.

Built-in Realization Filter Plugins:

The default DefaultRealizationFilter class provides several filtering methods, including sorting by objective/constraint values and Conditional Value-at-Risk (CVaR) based weighting.

Core Concepts:

  • Plugin Interface: Realization filter plugins must inherit from the RealizationFilterPlugin base class. This class acts as a factory, defining a create method to instantiate filter objects.
  • Filter Implementation: The actual filtering logic resides in classes that inherit from the RealizationFilter abstract base class. These classes are initialized with the optimization configuration (EnOptContext) and the index of the specific filter configuration to use (filter_index). The core functionality is provided by the get_realization_weights method, which calculates and returns weights for each realization based on their objective and constraint values.
  • Discovery: The PluginManager discovers available RealizationFilterPlugin implementations (typically via entry points) and uses them to create RealizationFilter instances as needed.

RealizationFilterPlugin

Bases: Plugin

Abstract Base Class for Realization Filter Plugins (Factories).

This class defines the interface for plugins responsible for creating RealizationFilter instances. These plugins act as factories for specific realization filtering strategies.

create abstractmethod classmethod 

create(
    filter_config: RealizationFilterConfig,
) -> RealizationFilter

Factory method to create a concrete RealizationFilter instance.

This abstract class method serves as a factory for creating concrete RealizationFilter objects. Plugin implementations must override this method to return an instance of their specific RealizationFilter subclass.

The PluginManager calls this method when an optimization requires realization weights calculated by this plugin.

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The configuration object for this realization filter.

 required

Returns:

Type Description
RealizationFilter

An initialized RealizationFilter object ready for use.

ropt.plugins.realization_filter.RealizationFilterPlugin

Bases: Plugin

Abstract Base Class for Realization Filter Plugins (Factories).

This class defines the interface for plugins responsible for creating RealizationFilter instances. These plugins act as factories for specific realization filtering strategies.

create abstractmethod classmethod 

create(
    filter_config: RealizationFilterConfig,
) -> RealizationFilter

Factory method to create a concrete RealizationFilter instance.

This abstract class method serves as a factory for creating concrete RealizationFilter objects. Plugin implementations must override this method to return an instance of their specific RealizationFilter subclass.

The PluginManager calls this method when an optimization requires realization weights calculated by this plugin.

Parameters:

Name Type Description Default
filter_config RealizationFilterConfig

The configuration object for this realization filter.

 required

Returns:

Type Description
RealizationFilter

An initialized RealizationFilter object ready for use.

ropt.realization_filter.RealizationFilter

Bases: ABC

Abstract base class for realization filter classes.

init abstractmethod 

init(context: EnOptContext) -> None

Initialize the realization filter.

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]

Return the updated weights of the realizations.

This method is called by the optimizer with the current values of the objectives and constraints. Based on these values it must decide how much weight each realization should be given, and return those as a vector.

The objectives and the constraints are passed as matrices, where the columns contain the values of the objectives or constraints. The index along the row axis corresponds to the number of the realization.

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]

The objectives of all realizations.

 required
constraints NDArray[float64] | None

The constraints for all realizations.

 required

Returns:

Type Description
NDArray[float64]

A vector of weights of the realizations.

ropt.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 EnOptContext.

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.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.