Compute Steps

ropt.workflow.compute_steps.ComputeStep

Bases: ABC

Abstract base class for optimization compute steps.

This class defines the fundamental interface for all executable compute steps within an optimization workflow. Concrete implementations, which perform specific actions like running an optimizer or evaluating functions, must inherit from this base class.

event_handlers property

event_handlers: list[EventHandler]

Get the event handlers attached to this compute step.

Returns:

Type	Description
list[EventHandler]	A list of handlers.

__init__

__init__() -> None

Initialize the ComputeStep.

add_event_handler

add_event_handler(handler: EventHandler) -> None

Add an event handler.

Compute steps emit events to report on the calculations they perform. These events are processed by independently created event handlers. Use the add_event_handler method to attach these handlers to the compute step.

Parameters:

Name	Type	Description	Default
handler	EventHandler	The handler to add.	required

run abstractmethod

run(*args: Any, **kwargs: Any) -> Any

Execute the logic defined by this compute step.

This abstract method must be implemented by concrete ComputeStep subclasses to define the specific action the compute step performs within the optimization workflow.

The return value and type can vary depending on the specific implementation.

Parameters:

Name	Type	Description	Default
args	Any	Positional arguments.	()
kwargs	Any	Keyword arguments.	{}

Returns:

Type	Description
Any	The result of the execution, if any.

ropt.workflow.compute_steps.EnsembleEvaluator

Bases: ComputeStep

The default ensemble evaluator compute step for optimization workflows.

This compute step performs one or more ensemble evaluations based on the provided variables. It yields a tuple of FunctionResults objects, one for each input variable vector evaluated.

The compute step emits the following events:

• START_ENSEMBLE_EVALUATOR: Emitted before the evaluation process begins.
• START_EVALUATION: Emitted just before the underlying ensemble evaluation is called.
• FINISHED_EVALUATION: Emitted after the evaluation completes, carrying the generated FunctionResults in its data dictionary under the key "results". Event handlers typically listen for this event.
• FINISHED_ENSEMBLE_EVALUATOR: Emitted after the entire compute step, including result emission, is finished.

__init__

__init__(*, evaluator: Evaluator) -> None

Initialize a default evaluator.

Parameters:

Name	Type	Description	Default
evaluator	Evaluator	The evaluator object to run function evaluations.	required

run

run(
    context: EnOptContext,
    variables: ArrayLike,
    *,
    metadata: dict[str, Any] | None = None,
) -> ExitCode

Run the ensemble evaluator.

This method executes the core logic of the ensemble evaluator. It requires an optimizer context (EnOptContext) and optionally accepts specific variable vectors to evaluate.

If metadata is provided, it is attached to the Results objects emitted via the FINISHED_EVALUATION event.

Parameters:

Name	Type	Description	Default
context	EnOptContext	Optimizer context.	required
variables	ArrayLike	Variable vector(s) to evaluate.	required
metadata	dict[str, Any] | None	Optional dictionary to attach to emitted FunctionResults.	None

Returns:

Type	Description
ExitCode	An ExitCode indicating the outcome.

Raises:

Type	Description
ValueError	If the input variables have the wrong shape.

ropt.workflow.compute_steps.EnsembleOptimizer

Bases: ComputeStep

The default optimizer compute step.

This compute step executes an optimization algorithm based on a provided configuration (EnOptContext or a compatible dictionary). It iteratively performs function and potentially gradient evaluations, yielding a sequence of FunctionResults and GradientResults objects.

While initial variable values are typically specified in the configuration, they can be overridden by passing them directly to the run method.

The following events are emitted during execution:

• START_OPTIMIZER: Emitted just before the optimization process begins.
• START_EVALUATION: Emitted immediately before an ensemble evaluation (for functions or gradients) is requested from the underlying optimizer.
• FINISHED_EVALUATION: Emitted after an evaluation completes. This event carries the generated Results object(s) in its data dictionary under the key "results". Event handlers typically listen for this event to process or track optimization progress.
• FINISHED_OPTIMIZER: Emitted after the entire optimization process concludes (successfully, or due to termination conditions or errors).

__init__

__init__(*, evaluator: Evaluator) -> None

Initialize a default optimizer.

Parameters:

Name	Type	Description	Default
evaluator	Evaluator	The evaluator object to run function evaluations.	required

run

run(
    context: EnOptContext,
    variables: ArrayLike,
    *,
    metadata: dict[str, Any] | None = None,
) -> ExitCode

Run the compute step to perform an optimization.

This method executes the core logic of the optimizer compute step. It requires an optimizer context (EnOptContext) and optionally accepts specific initial variable vectors and metadata.

If metadata is provided, it is attached to the Results objects emitted via the FINISHED_EVALUATION event.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The optimizer context.	required
variables	ArrayLike	Optional initial variable vector(s) to start from.	required
metadata	dict[str, Any] | None	Optional dictionary to attach to emitted Results.	None

Returns:

Type	Description
ExitCode	An exit code indicating the outcome of the optimization.

Raises:

Type	Description
ValueError	If the input variables have the wrong shape.