Basic Optimizer

ropt.plan.BasicOptimizer

A class for executing single optimization runs.

The BasicOptimizer is designed to simplify the process of setting up and executing optimization workflows that consist primarily of a single optimization run. It offers a more streamlined approach compared to directly defining and managing a full Plan object, making it ideal for straightforward optimization tasks.

This class provides a user-friendly interface for common optimization operations, including:

Initiating a Single Optimization: Easily start an optimization process with a provided configuration and evaluator.
Observing Optimization Events: Register observer functions to monitor and react to various events that occur during the optimization, such as the start of an evaluation or the availability of new results.
Abort Conditions: Define a callback function that can be used to check for abort conditions during the optimization.
Result Reporting: Define a callback function that will be called whenever new results become available.
Accessing Results: After the optimization is complete, the optimal results, corresponding variables, and the optimization's exit code are readily accessible.
Customizable Steps and Handlers: While designed for single runs, it allows for the addition of custom plan steps and event handlers to the underlying Plan for more complex scenarios.

By encapsulating the core elements of an optimization run, the BasicOptimizer reduces the boilerplate code required for simple optimization tasks, allowing users to focus on defining the optimization problem and analyzing the results.

Customization

The optimization workflow executed by BasicOptimizer can be tailored in two main ways: by adding event handlers to the default workflow or by running an entirely different workflow. Customization can be configured using environment variables or a JSON configuration file.

The ROPT_HANDLERS environment variable may contain a comma-separated list of options that are each parsed to obtain event handlers or plan steps. In addition if a JSON configuration file is found at <sys.prefix>/share/ropt/options.json (where <sys.prefix> is the Python installation prefix), it will read it to find additional handlers to install.

Adding Custom Event Handlers (via ROPT_HANDLERS or JSON configuration)

This method allows for custom processing of events emitted by the default optimization workflow, without replacing the workflow itself. This is useful for tasks like custom logging or data processing.

Event handlers can be specified in two ways, and handlers from both sources will be combined:
- ROPT_HANDLERS Environment Variable: If ROPT_HANDLERS contains a comma-separated list of event handler names (and these names do not match the "Custom Step Execution" format described above), these handlers will be added to the default optimization workflow. Each name must correspond to a registered EventHandler.
- JSON Configuration File: If a JSON configuration file is found at <sys.prefix>/share/ropt/options.json (where <sys.prefix> is the Python installation prefix), BasicOptimizer will look for specific keys to load additional event handlers. If this JSON file contains a basic_optimizer key, and nested within it an event_handlers key, the value of event_handlers should be a list of strings. Each string in this list should be the name of a registered EventHandler. These handlers will be added to those found via ROPT_HANDLERS.
  
  Example shared/ropt/options.json: json { "basic_optimizer": { "event_handlers": [ "custom_logger", "extra/event_processor" ] } }
Note that if a custom optimization workflow is installed using the ROPT_SCRIPT environment variable (see below), these custom handlers will be ignored.
Custom Step Execution (via ROPT_SCRIPT)

If the ROPT_SCRIPT environment variable contains an option in the format step-name=script.py (where script.py may be any file), the named step will be executed instead of the standard optimization workflow, passing it the name of the script that defines the new optimization workflow.

The custom step (step-name) must adhere to the following:
- It must be a registered PlanStep.
- Its run method must accept: * An evaluator keyword argument, which will receive the evaluator function passed to BasicOptimizer.
  - A script keyword argument, which will receive the name of script passed via ROPT_SCRIPT.
- This method must return a callable that: * Accepts a Plan object as its only argument. * Returns an optimization ExitCode.
  
  This callable will then be executed by BasicOptimizer in place of its default workflow.
As a short-cut is possible to also define ROPT_SCRIPT with only the name of the script (i.e. ROPT_SCRIPT=script.py). In this case a step with the name run_plan is assumed to exists and will be used.

results `property`

results: FunctionResults | None

Return the optimal result found during the optimization.

This property provides access to the best FunctionResults object discovered during the optimization process. It encapsulates the objective function value, constraint values, and other relevant information about the optimal solution.

Returns:

Type	Description
`FunctionResults \| None`	The optimal result.

variables `property`

variables: NDArray[float64] | None

Return the optimal variables found during the optimization.

This property provides access to the variable values that correspond to the optimal FunctionResults object. These variables represent the solution that yielded the best objective function value found during the optimization process.

Returns:

Type	Description
`NDArray[float64] \| None`	The variables corresponding to the optimal result.

exit_code `property`

exit_code: ExitCode

Return the exit code of the optimization run.

This property provides access to the ExitCode that indicates the outcome of the optimization process. It can be used to determine whether the optimization completed successfully, was aborted, or encountered an error.

Returns:

Type	Description
`ExitCode`	The exit code of the optimization run.

init

__init__(
    enopt_config: dict[str, Any],
    evaluator: Callable[
        [NDArray[float64], EvaluatorContext],
        EvaluatorResult,
    ],
    *,
    transforms: OptModelTransforms | None = None,
    constraint_tolerance: float = 1e-10,
) -> None

Initialize a BasicOptimizer object.

This constructor sets up the necessary components for a single optimization run. It requires an optimization configuration, optional domain transforms, and an evaluator, which together define the optimization problem and how to evaluate potential solutions. If a constraint value is within the constraint_tolerance of zero, it is considered satisfied.

Parameters:

Name	Type	Description	Default
`enopt_config`	`dict[str, Any]`	The configuration for the optimization.	required
`evaluator`	`Callable[[NDArray[float64], EvaluatorContext], EvaluatorResult]`	The evaluator object.	required
`transforms`	`OptModelTransforms \| None`	The transforms to apply to the model.	`None`
`constraint_tolerance`	`float`	The constraint violation tolerance.	`1e-10`

run

run(initial_values: ArrayLike) -> Self

Run the optimization process.

This method initiates the optimization workflow defined by the BasicOptimizer object. It executes the underlying Plan, which manages the optimization steps, result handling, and event processing. After the optimization is complete, the optimal results, variables, and exit code can be accessed via the corresponding properties.

Returns:

Type	Description
`Self`	The `BasicOptimizer` instance, allowing for method chaining.

set_abort_callback

set_abort_callback(callback: Callable[[], bool]) -> Self

Set a callback to check for abort conditions.

The provided callback function will be invoked repeatedly during the optimization process. If the callback returns True, the optimization will be aborted, and the BasicOptimizer will exit with an ExitCode.USER_ABORT.

The callback function should have no arguments and return a boolean value.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[], bool]`	The callable to check for abort conditions.	required

Returns:

Type	Description
`Self`	The `BasicOptimizer` instance, allowing for method chaining.

set_results_callback

set_results_callback(callback: Callable[..., None]) -> Self

Set a callback to report new results.

The provided callback function will be invoked whenever new results become available during the optimization process. This allows for real-time monitoring and analysis of the optimization's progress.

The required signature of the callback function should be:

def callback(results: tuple[FunctionResults, ...]) -> None:
    ...

Parameters:

Name	Type	Description	Default
`callback`	`Callable[..., None]`	The callable that will be invoked to report new results.	required

Returns:

Type	Description
`Self`	The `BasicOptimizer` instance, allowing for method chaining.

Basic Optimizer

ropt.plan.BasicOptimizer

results property

variables property

exit_code property

__init__

run

set_abort_callback

set_results_callback

results `property`

variables `property`

exit_code `property`

init