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.

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 (EnOptConfig) 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 during plan execution.

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.

ropt.plugins.realization_filter.base.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.

During plan execution, the PluginManager identifies the appropriate realization filter plugin based on the configuration and uses its create class method to instantiate the actual RealizationFilter object that will calculate the realization weights.

create abstractmethod classmethod

create(
    enopt_config: EnOptConfig, filter_index: int
) -> 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 step requires realization weights calculated by this plugin.

Parameters:

Name	Type	Description	Default
enopt_config	EnOptConfig	The main EnOpt configuration object.	required
filter_index	int	Index into enopt_config.realization_filters for this filter.	required

Returns:

Type	Description
RealizationFilter	An initialized RealizationFilter object ready for use.

ropt.plugins.realization_filter.base.RealizationFilter

Bases: ABC

Abstract base class for realization filter classes.

__init__

__init__(
    enopt_config: EnOptConfig, filter_index: int
) -> None

Initialize the realization filter plugin.

Parameters:

Name	Type	Description	Default
enopt_config	EnOptConfig	The configuration of the optimizer.	required
filter_index	int	The index of the filter to use.	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 permissable.

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.