Ensemble Optimizer

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 workflow containing the optimization steps.

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.

__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, an evaluator, and a plugin manager to function.

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

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

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

The optimizer plugins are used by the ensemble optimizer to implement the actual optimization process. The EnsembleOptimizer class provides the callback function to these plugins needed (see OptimizerCallback)

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

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