Core Classes

ropt.core

The engines the workflow components are built on.

EnsembleEvaluator orchestrates the per-realization function calls of one evaluation, and EnsembleOptimizer drives the configured backend. Both are exposed for plugin authors and workflow developers; see Optimization Workflows for the layer above them.

ropt.core.EnsembleEvaluator

Construct functions and gradients from an ensemble of functions.

Uses the settings in an EnOptContext to turn the raw values from an evaluator callable, usually provided by an Evaluator, into function and gradient estimates.

__init__

__init__(
    context: EnOptContext,
    evaluator: EvaluationBatchCallback,
    metadata: dict[str, Any] | None = None,
) -> None

Initialize the EnsembleEvaluator.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The optimization context object.	required
evaluator	EvaluationBatchCallback	The callable for evaluating individual functions.	required
metadata	dict[str, Any] | None	Optional metadata to pass to the evaluator.	None

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.

Direct use of this class is generally discouraged. Use the high-level optimize API instead, or build a custom workflow from the optimization steps.

__init__

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

Initialize the EnsembleOptimizer.

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, invoked around each evaluation.	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 describing 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 evaluation results, or None before it starts.	None

ropt.core.OptimizerCallback

Bases: Protocol

Defines the call signature for the optimizer evaluation callback.

Optimizers use 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.

variables is a 1D array for a single vector, or a 2D array (one vector per row) for optimizers that evaluate a batch at once. return_functions and return_gradients select what the returned OptimizerCallbackResult computes.

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.

Bundles the objective and constraint values, and their gradients, returned by an OptimizerCallback evaluation. Both are None unless requested and successfully computed.

Non-linear constraints arrive normalized: each is split into values that are non-negative when the constraint is satisfied, so a backend compares them against zero and never needs a bound. A constraint with a finite lower and a finite upper bound contributes two values, an equality one, and a constraint with no finite bound none. Which of them are equalities is fixed for the run and available from nonlinear_equalities.

functions and gradients follow a fixed shape:

• Functions array: the objective followed by the constraint values. A vector variables gives a 1D array [objective, constraint1, ...]; a matrix variables gives a 2D array with one such row per input row.
• Gradients array: always 2D, with one row per objective and constraint value, and one column per variable:

  [
      [grad_obj_var1,         grad_obj_var2,         ...],
      [grad_constraint1_var1, grad_constraint1_var2, ...],
      ...
  ]
  

Attributes:

Name	Type	Description
functions	NDArray[float64] | None	Objective and constraint value(s).
gradients	NDArray[float64] | None	Gradient values.