Core Classes

ropt.core.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 EnOptContext context 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__(
    context: EnOptContext, evaluator: EvaluatorCallback
) -> None

Initialize the EnsembleEvaluator.

This method sets up the EnsembleEvaluator with the necessary optimization context object and evaluator callable.

The context object contains all the settings required for the ensemble evaluation, such as the number of realizations, the function estimators, and the gradient settings. The evaluator callable is usually provide by a Evaluator object.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The optimization context object.	required
`evaluator`	`EvaluatorCallback`	The callable for evaluating individual functions.	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.

This method returns a tuple of Results objects, which can be the result of function evaluations (FunctionResults), gradient evaluations (GradientResults), or both, depending on the specified flags.

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

Backend for ensemble-based optimizations.

The EnsembleOptimizer class provides the core functionality for running ensemble-based optimizations. Direct use of this class is generally discouraged. Instead, use the BasicOptimizer class or build a custom workflow containing the optimization steps.

init

__init__(
    context: EnOptContext,
    ensemble_evaluator: EnsembleEvaluator,
    signal_evaluation: SignalEvaluationCallback
    | None = None,
) -> None

Initialize the EnsembleOptimizer.

This class orchestrates ensemble-based optimizations. It requires an optimization context object and an evaluator to function.

The EnsembleOptimizer needs the following to define a single optimization run:

An EnOptContext object: This contains all necessary information for the optimization.
An EnsembleEvaluator object: This object is responsible for evaluating functions.

Additionally, an optional callback can be provided that is invoked before and after each function evaluation.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The ensemble optimization context.	required
`ensemble_evaluator`	`EnsembleEvaluator`	The evaluator for function evaluations.	required
`signal_evaluation`	`SignalEvaluationCallback \| None`	Optional callback to signal evaluations.	`None`

is_parallel `property`

is_parallel: bool

Determine if the optimization supports parallel evaluations.

The underlying optimization algorithm may request function evaluations via a callback. Parallel optimization, in this context, means that the algorithm may request multiple function evaluations in a single callback.

Returns:

Type	Description
`bool`	`True` if the optimization supports parallel evaluations, `False`
`bool`	otherwise.

start

start(variables: NDArray[float64]) -> ExitCode

Start the optimization process.

This method initiates the optimization process using the provided initial variables. The optimization will continue until a stopping criterion is met or an error occurs.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	The initial variables for the optimization.	required

Returns:

Type	Description
`ExitCode`	An `ExitCode` indicating the reason for termination.

ropt.core.SignalEvaluationCallback

Bases: Protocol

Protocol for a callback to signal the start and end of an evaluation.

This callback is invoked before and after each evaluation, allowing for custom handling or tracking of evaluation events.

call

__call__(
    results: tuple[Results, ...] | None = None,
) -> None

Callback protocol for signaling the start and end of evaluations.

This callback is invoked by the ensemble optimizer before and after each evaluation. Before the evaluation starts, the callback is called with results set to None. After the evaluation completes, the callback is called again, this time with results containing the output of the evaluation.

Parameters:

Name	Type	Description	Default
`results`	`tuple[Results, ...] \| None`	The results produced by the evaluation, or `None` if the evaluation has not yet started.	`None`

ropt.core.OptimizerCallback

Bases: Protocol

Defines the call signature for the optimizer evaluation callback.

Optimizers uses this callback to request function and gradient evaluations from the ropt core during the optimization process.

call

__call__(
    variables: NDArray[float64],
    /,
    *,
    return_functions: bool,
    return_gradients: bool,
) -> OptimizerCallbackResult

Request function and/or gradient evaluations from the ropt core.

This method is called by the optimizer implementation to obtain objective function values, constraint values, and their gradients for one or more sets of variable values. In addition other update information, such as non-linear constraint bounds may be returned.

The variables argument can be a 1D array (single vector) or a 2D array (matrix where each row is a variable vector). Parallel or batch-based optimizers might provide a matrix, while others typically provide a single vector.

The return_functions and return_gradients flags control what is computed and returned in a OptimizerCallbackResult structure.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	A 1D or 2D array of variable values to evaluate.	required
`return_functions`	`bool`	If `True`, compute and return function/constraint values.	required
`return_gradients`	`bool`	If `True`, compute and return gradient values.	required

Returns:

Type	Description
`OptimizerCallbackResult`	A data structure with the results.

ropt.core.OptimizerCallbackResult `dataclass`

Holds the results from an optimizer callback evaluation.

This dataclass is used to structure the output of the OptimizerCallback. It bundles the objective function values, gradient values, and any updated non-linear constraint bounds that result from an evaluation request.

The functions attribute will contain a NumPy array of the objective function value(s) if they were requested and successfully computed, otherwise it will be None. Similarly, the gradients attribute will hold a NumPy array of gradient values if requested and computed, and None otherwise.

The nonlinear_constraint_bounds attribute is a tuple containing two NumPy arrays: the first for lower bounds and the second for upper bounds of any non-linear constraints. This will be None if there are no non-linear constraints or if their bounds were not updated during the callback.

The functions and gradients fields must be structured as follows:

Functions Array: This array contains the objective and non-linear constraint values. If variables was a vector, it's a 1D array:
```
[objective, constraint1, constraint2, ...]
```
If variables was a matrix, it's a 2D array where each row corresponds to a row in the input variables, with the same structure:
```
[
    [obj_row1, con1_row1, ...],
    [obj_row2, con2_row2, ...],
    ...
]
```
Gradients Array: This array contains the gradients of the objective and non-linear constraints. It's always a 2D array where rows correspond to the objective/constraints and columns correspond to the variables:
```
[
    [grad_obj_var1,  grad_obj_var2,  ...],
    [grad_con1_var1, grad_con1_var2, ...],
    ...
]
```

Attributes:

Name	Type	Description
`functions`	`NDArray[float64] \| None`	Objective function value(s).
`gradients`	`NDArray[float64] \| None`	Gradient values.
`nonlinear_constraint_bounds`	`tuple[NDArray[float64], NDArray[float64]] \| None`	Updated non-linear constraint lower and upper bounds.

Core Classes

ropt.core.EnsembleEvaluator

__init__

calculate

ropt.core.EnsembleOptimizer

__init__

is_parallel property

start

ropt.core.SignalEvaluationCallback

__call__

ropt.core.OptimizerCallback

__call__

ropt.core.OptimizerCallbackResult dataclass

init

init

is_parallel `property`

call

call

ropt.core.OptimizerCallbackResult `dataclass`