Core Classes

The ropt.core package contains the low-level engines used by the workflow components: an ensemble evaluator that orchestrates per-realization function calls, an ensemble optimizer that drives the chosen backend, and the callback protocols connecting them. Most users will not interact with these classes directly; they are exposed for plugin authors and advanced workflow developers.

See Optimization Workflows for the higher-level framework that wraps these engines.

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.

The EnsembleOptimizer class provides the core functionality for running ensemble-based optimizations. Direct use of this class is generally discouraged. Instead, use the high-level optimize API 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:

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

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