Default Plan Plugins

ropt.plugins.plan.default

This module provides the default plugin implementations for steps and event handlers.

It defines DefaultPlanStepPlugin and DefaultEventHandlerPlugin, which serve as factories for the built-in plan components, enabling the creation of standard optimization plans out-of-the-box.

Supported Components:

Steps:
- ensemble_evaluator: Performs ensemble evaluations (DefaultEnsembleEvaluatorStep).
- optimizer: Runs an optimization algorithm using a configured optimizer plugin (DefaultOptimizerStep).
Handlers:
- tracker: Tracks the 'best' or 'last' valid result based on objective value and constraints (DefaultTrackerHandler).
- store: Accumulates all results from specified sources (DefaultStoreHandler).
- observer: Listens for events from specified sources, and calls a callback for each event (DefaultObserverHandler).
Evaluators:
- function_evaluator: Evaluator that forwards calculations to a given evaluation function. (DefaultFunctionEvaluator)
- caching_evaluator: Evaluator that uses caching to find results that were already evaluated before forwarding to another evaluator. (DefaultCachedEvaluator)

ropt.plugins.plan.default.DefaultPlanStepPlugin

Bases: PlanStepPlugin

The default plugin for creating built-in plan steps.

This plugin acts as a factory for the standard PlanStep implementations provided by ropt. It allows the PluginManager to instantiate these steps when requested by a Plan.

Supported Steps:

ensemble_evaluator: Creates a DefaultEnsembleEvaluatorStep instance, which performs ensemble evaluations.
optimizer: Creates a DefaultOptimizerStep instance, which runs an optimization algorithm using a configured optimizer plugin.

ropt.plugins.plan.default.DefaultEventHandlerPlugin

Bases: EventHandlerPlugin

The default plugin for creating built-in event handlers.

This plugin acts as a factory for the standard EventHandler implementations provided by ropt. It allows the PluginManager to instantiate these event handlers when requested by a Plan.

Supported Handlers:

tracker: Creates a DefaultTrackerHandler instance, which tracks either the 'best' or 'last' valid result based on objective value and constraints.
store: Creates a DefaultStoreHandler instance, which accumulates all results received from specified sources.
observer: Creates a DefaultObserverHandler instance, which calls a callback for each event received from specified sources.

ropt.plugins.plan.default.DefaultEvaluatorPlugin

Bases: EvaluatorPlugin

The default plugin for creating evaluators.

This plugin acts as a factory for the standard evaluator implementations provided by ropt. It allows the PluginManager to instantiate these steps when requested by a Plan.

Supported Evaluators:

function_evaluator: Creates a DefaultFunctionEvaluator instance, which uses function calls to calculated individual objectives and constraints.

ropt.plugins.plan.ensemble_evaluator.DefaultEnsembleEvaluatorStep

Bases: PlanStep

The default ensemble evaluator step for optimization plans.

This 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 step emits the following events:

START_ENSEMBLE_EVALUATOR_STEP: 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_STEP: Emitted after the entire step, including result emission, is finished.

run_step_from_plan

run_step_from_plan(
    config: EnOptConfig,
    variables: ArrayLike,
    *,
    transforms: OptModelTransforms | None = None,
    metadata: dict[str, Any] | None = None,
) -> ExitCode

Run the ensemble evaluator step to perform ensemble evaluations.

This method executes the core logic of the ensemble evaluator step. It requires an optimizer configuration (EnOptConfig) 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
`config`	`EnOptConfig`	Optimizer configuration.	required
`variables`	`ArrayLike`	Variable vector(s) to evaluate.	required
`transforms`	`OptModelTransforms \| None`	Optional transforms to apply to the variables, objectives, and constraints.	`None`
`metadata`	`dict[str, Any] \| None`	Optional dictionary to attach to emitted `FunctionResults`.	`None`

Returns:

Type	Description
`ExitCode`	An `ExitCode` indicating the outcome.

ropt.plugins.plan.optimizer.DefaultOptimizerStep

Bases: PlanStep

The default optimizer step for optimization plans.

This step executes an optimization algorithm based on a provided configuration (EnOptConfig 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 step emits the following events during its execution:

START_OPTIMIZER_STEP: 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_STEP: Emitted after the entire optimization process concludes (successfully, or due to termination conditions or errors).

This step also supports nested optimization. If a nested_optimization function is provided to the run method, the optimizer will execute a nested optimization at as part of each function evaluation. Each nested optimization run is done by creating a new plan. The provided function is then executed, passing the new plan and the variables. The nested_optimization function is expected to return a single FunctionResults object.

run_step_from_plan

run_step_from_plan(
    config: EnOptConfig,
    variables: ArrayLike,
    *,
    transforms: OptModelTransforms | None = None,
    nested_optimization: NestedOptimizationCallable
    | None = None,
    metadata: dict[str, Any] | None = None,
) -> ExitCode

Run the optimizer step to perform an optimization.

This method executes the core logic of the optimizer step. It requires an optimizer configuration (EnOptConfig) and optionally accepts specific initial variable vectors, and/or a nested optimization plan, and metadata.

If variables are not provided, the initial values specified in the config are used. If variables are provided, they override the config's initial values.

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

If a nested_optimization callable is provided, a fresh plan will be constructed, and the callable will be called passing that plan and the initial variables to use. The callable should return a a single FunctionResults object that should contain the results of the nested optimization.

Parameters:

Name	Type	Description	Default
`config`	`EnOptConfig`	Optimizer configuration.	required
`transforms`	`OptModelTransforms \| None`	Optional transforms to apply to the variables, objectives, and constraints.	`None`
`variables`	`ArrayLike`	Optional initial variable vector(s) to start from.	required
`nested_optimization`	`NestedOptimizationCallable \| None`	Optional callable to run a nested plan.	`None`
`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.

ropt.plugins.plan._tracker.DefaultTrackerHandler

Bases: EventHandler

The default event handler for tracking optimization results.

This event handler listens for FINISHED_EVALUATION events emitted by specified sources (plan steps). It processes the Results objects contained within these events and selects a single FunctionResults object to retain based on defined criteria.

The criteria for selection are:

what='best' (default): Tracks the result with the lowest weighted objective value encountered so far.
what='last': Tracks the most recently received valid result.

Optionally, results can be filtered based on constraint violations using the constraint_tolerance parameter. If provided, any result violating constraints beyond this tolerance is ignored.

The selected result (in the optimizer domain) is stored internally. The result accessible via dictionary access (handler["results"]) is the selected result, potentially transformed to the user domain.

ropt.plugins.plan._store.DefaultStoreHandler

Bases: EventHandler

The default event handler for storing optimization results.

This event handler listens for FINISHED_EVALUATION events emitted by specified sources (plan steps). It collects all Results objects contained within these events and stores them sequentially in memory.

The sources parameter filters which steps' results are collected. The accumulated results are stored as a tuple and can be accessed via dictionary access using the key "results" (e.g., handler["results"]). Each time new results are received from a valid source, they are appended to this tuple.

ropt.plugins.plan._observer.DefaultObserverHandler

Bases: EventHandler

The default event handler for observing events.

This event handler listens for events emitted by specified sources (plan steps) and forwards them to one or more callback functions.

The sources parameter filters which events are observed.

ropt.plugins.plan._function_evaluator.DefaultFunctionEvaluator

Bases: Evaluator

An evaluator that forwards calls to an evaluator function.

This class acts as an adapter, allowing a standard Python callable (which matches the signature of the eval method) to be used as an Evaluator within an optimization Plan.

It is initialized with an evaluator callable. When the eval method of this class is invoked by the plan, it simply delegates the call, along with all arguments, to the wrapped evaluator function.

This is useful for integrating existing evaluation logic that is not already structured as an Evaluator subclass into a ropt plan.

The clients parameter acts as a filter, determining which plan steps this evaluator should serve.

ropt.plugins.plan.cached_evaluator.DefaultCachedEvaluator

Bases: Evaluator

An evaluator that caches results to avoid redundant computations.

This evaluator attempts to retrieve previously computed function results from a cache before delegating to another evaluator. The cache is populated from FunctionResults objects stored by EventHandler instances specified as sources.

When an evaluation is requested, for each variable vector and its corresponding realization, this evaluator searches through the results attribute of its sources. If a FunctionResults object is found where the variables match the input (within a small tolerance) and the realization also matches, the cached objectives and constraints from that FunctionResults object are used.

If some, but not all, requested evaluations are found in the cache, this evaluator will mark the cached ones as inactive for the next evaluator in the chain and then call that evaluator to compute only the missing results. The final combined results (cached and newly computed) are then returned.

This is particularly useful in scenarios where the same variable sets might be evaluated multiple times, for example, in iterative optimization algorithms or when restarting optimizations.