Ensemble Optimization

ropt.optimization.EnsembleOptimizer

Optimizer 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__(
    enopt_config: EnOptConfig,
    transforms: OptModelTransforms | None,
    ensemble_evaluator: EnsembleEvaluator,
    signal_evaluation: SignalEvaluationCallback
    | None = None,
    nested_optimizer: NestedOptimizerCallback | None = None,
) -> None

Initialize the EnsembleOptimizer.

This class orchestrates ensemble-based optimizations. It requires an optimization configuration, an evaluator, and a plugin manager to function.

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

1. An EnOptConfig object: This contains all configuration settings for the optimization.
2. A OptModelTransforms object: This handles the transforms to apply to the variables, objectives and constraints.
3. An EnsembleEvaluator object: This object is responsible for evaluating functions.
4. A PluginManager object: This object provides access to optimizer plugins.

Additionally, two optional callbacks can be provided to extend the functionality:

1. A SignalEvaluationCallback: This callback is invoked before and after each function evaluation.
2. A NestedOptimizerCallback: This callback is invoked at each function evaluation to run a nested optimization.

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
enopt_config	EnOptConfig	The ensemble optimization configuration.	required
transforms	OptModelTransforms | None	The transforms to apply to the model.	required
ensemble_evaluator	EnsembleEvaluator	The evaluator for function evaluations.	required
signal_evaluation	SignalEvaluationCallback | None	Optional callback to signal evaluations.	None
nested_optimizer	NestedOptimizerCallback | None	Optional callback for nested optimizations.	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.optimization.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.optimization.NestedOptimizerCallback

Bases: Protocol

Protocol for functions that start a nested optimization.

__call__

__call__(
    variables: NDArray[float64],
) -> tuple[FunctionResults | None, bool]

Callback protocol for executing a nested optimization.

This function is invoked by the ensemble optimizer during each function evaluation to initiate a nested optimization process. It receives the current variables as input and is expected to perform a nested optimization using these variables as a starting point. The function should return a tuple containing the result of the nested optimization and a boolean indicating whether the nested optimization was aborted by the user. The result of the nested optimization should be a FunctionResults object, or None if no result is available.

Parameters:

Name	Type	Description	Default
variables	NDArray[float64]	The variables to use as the starting point.	required

Returns:

Type	Description
tuple[FunctionResults | None, bool]	The result and a boolean indicating if the user aborted.

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