Function Evaluations

ropt.ensemble_evaluator.EnsembleEvaluator

Construct functions and gradients from an ensemble of functions.

The EnsembleEvaluator class is responsible for calculating functions and gradients from an ensemble of functions. It leverages the settings defined in an EnOptConfig configuration object to guide the calculations.

The core functionality relies on an evaluator callable, (usually provided by an Evaluator object), which is used to evaluate the individual functions within the ensemble. The evaluator provides the raw function values, which are then processed by the EnsembleEvaluator to produce the final function and gradient estimates.

init

__init__(
    config: EnOptConfig,
    transforms: OptModelTransforms | None,
    evaluator: Callable[
        [NDArray[float64], EvaluatorContext],
        EvaluatorResult,
    ],
    plugin_manager: PluginManager,
) -> None

Initialize the EnsembleEvaluator.

This method sets up the EnsembleEvaluator with the necessary configuration, evaluator, and plugins.

The config object contains all the settings required for the ensemble evaluation, such as the number of realizations, the function estimators, and the gradient settings. The transforms object defines the domain transforms that should be applied to variables, objectives and constraints. The evaluator callable is usually provide by a Evaluator object. The plugin_manager is used to load the realization filters, function estimators, and samplers.

Parameters:

Name	Type	Description	Default
`config`	`EnOptConfig`	The configuration object.	required
`transforms`	`OptModelTransforms \| None`	The domain transforms to apply.	required
`evaluator`	`Callable[[NDArray[float64], EvaluatorContext], EvaluatorResult]`	The callable for evaluating individual functions.	required
`plugin_manager`	`PluginManager`	A plugin manager to load required plugins.	required

calculate

calculate(
    variables: NDArray[float64],
    *,
    compute_functions: bool,
    compute_gradients: bool,
) -> tuple[Results, ...]

Evaluate the given variable vectors.

This method calculates functions, gradients, or both, based on the provided variable vectors and the specified flags.

The variables argument can be a single vector or a matrix where each row is a variable vector.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	The variable vectors to evaluate.	required
`compute_functions`	`bool`	Whether to calculate functions.	required
`compute_gradients`	`bool`	Whether to calculate gradients.	required

Returns:

Type	Description
`tuple[Results, ...]`	The results for function evaluations and/or gradient evaluations.

ropt.evaluator.EvaluatorContext `dataclass`

Capture additional details for the function evaluator.

Function evaluators (see Evaluator) primarily receive variable vectors to evaluate objective and constraint functions. However, they may also benefit from additional information to optimize their calculations. This EvaluatorContext object provides that supplementary information.

Specifically, it provides:

The configuration object for the current optimization step.
A boolean vector (active) indicating which variable rows require evaluation.
The realization index for each variable vector. This can be used to determine the correct function from an ensemble to use with each variable vector.
The perturbation index for each variable vector (if applicable). A value less than 0 indicates that the vector is not a perturbation.

Attributes:

Name	Type	Description
`config`	`EnOptConfig`	Configuration of the optimizer.
`active`	`NDArray[bool_]`	Indicates which variable rows require evaluation.
`realizations`	`NDArray[intc]`	Realization numbers for each requested evaluation.
`perturbations`	`NDArray[intc] \| None`	Perturbation numbers for each requested evaluation. A value less than 0 indicates that the vector is not a perturbation.

get_active_evaluations

get_active_evaluations(array: NDArray[T]) -> NDArray[T]

Filter an array based on the active property.

This is a utility method, which can be used if only the active property is used to exclude variable rows that are inactive, i.e. where none of the objects or constraints are needed.

This method filters a one- or two-dimensional array by retaining only those entries or rows that correspond to active. The activity of realizations is determined by the self.active boolean array (where True indicates active).

If self.active is None (indicating that all variable rows are to be considered active), no filtering is applied, and the original input is returned.

Parameters:

Name	Type	Description	Default
`array`	`NDArray[T]`	The array to filter.	required

Returns:

Type	Description
`NDArray[T]`	The filtered results.

insert_inactive_results

insert_inactive_results(
    array: NDArray[T], *, fill_value: float = 0.0
) -> NDArray[T]

Expand an array by inserting fill values for inactive variables.

This is a utility method, which can be used if only the active property is used to exclude variable rows that are fully inactive.

This method takes an array and expands it to its original dimensions by inserting a specified fill_value at positions corresponding to inactive rows. If the array is one-dimensional, zero entries are inserted, if it is two-dimensional rows of zero values are inserted.

If self.active is None (implying all rows were considered active or no filtering was applied), the input array is returned unchanged.

Parameters:

Name	Type	Description	Default
`array`	`NDArray[T]`	The array to expand.	required
`fill_value`	`float`	The value to insert for inactive entries.	`0.0`

Returns:

Type	Description
`NDArray[T]`	An expanded array matching the original number of variables.

ropt.evaluator.EvaluatorResult `dataclass`

Store the results of a function evaluation.

This class stores the results of evaluating objective and constraint functions for a set of variable vectors.

The objectives and constraints are stored as matrices. Each column in these matrices corresponds to a specific objective or constraint, and each row corresponds to a variable vector.

When the evaluator is asked to evaluate functions, some variable vectors may be marked as inactive. The results for these inactive vectors should be set to zero. All active variable vectors should be evaluated. If an evaluation fails for any reason, the corresponding values should be set to numpy.nan.

A batch_id can be set to identify this specific set of evaluation results.

The evaluation_info dictionary can store additional metadata for each evaluation. This information is not used internally by ropt and can have an arbitrary structure, to be interpreted by the application. This can be used, for example, to uniquely identify the results calculated for each variable vector, allowing them to be linked back to their corresponding input vectors.

Parameters:

Name	Type	Description	Default
`objectives`	`NDArray[float64]`	The calculated objective values.	required
`constraints`	`NDArray[float64] \| None`	Optional calculated constraint values.	`None`
`batch_id`	`int \| None`	Optional batch ID to identify this set of results.	`None`
`evaluation_info`	`dict[str, NDArray[Any]]`	Optional info for each evaluation.	`dict()`

Function Evaluations

ropt.ensemble_evaluator.EnsembleEvaluator

__init__

calculate

ropt.evaluator.EvaluatorContext dataclass

get_active_evaluations

insert_inactive_results

ropt.evaluator.EvaluatorResult dataclass

init

ropt.evaluator.EvaluatorContext `dataclass`

ropt.evaluator.EvaluatorResult `dataclass`