Basic Optimization Workflow

BasicOptimizer is a ready-made single-run driver for applications that embed ropt and already have their own batch-oriented evaluation infrastructure — for example dispatching a whole ensemble of runs to an external scheduler at once. It wraps an OptimizationStep and a ResultsHandler into a single class that takes a batch evaluator directly. For a Python script, prefer the simple API instead.

ropt.workflow._basic_optimizer

This module defines a basic optimization object.

ropt.workflow.BasicOptimizer

A simple interface for single optimization runs.

Wraps the workflow components into a run-once interface with built-in result tracking. Passing a configuration dictionary and an evaluator is enough to run an optimization and retrieve the best result. Internally it:

1. validates config into an EnOptContext;
2. wraps a plain EvaluationBatchCallback in a BatchEvaluator, or uses a supplied Evaluator as given;
3. creates an OptimizationStep and attaches a ResultsHandler to remember the best result;
4. runs the step, exposing the best FunctionResults via results.

Progress can be monitored by registering a callback with set_results_callback. For more control (multiple runs, custom event handlers, or parallel/async evaluation) use the workflow components directly.

Injecting event handlers into every run. Extra event handlers can be added to every BasicOptimizer run without changing any call site, for example to add logging, telemetry, or a custom results store. On start-up BasicOptimizer reads a JSON file at <prefix>/share/ropt/options.json, where <prefix> is the Python installation's data prefix (the value of sysconfig.get_paths()["data"]). Handlers are listed under basic_optimizer.event_handlers as module.ClassName strings:

{
    "basic_optimizer": {
        "event_handlers": ["mypackage.MyHandler"]
    }
}

Each referenced class must be importable from the active environment and must subclass EventHandler with no required constructor arguments; it is instantiated and attached to every run. Entries whose module cannot be imported are skipped, and a missing or malformed file is ignored.

__init__

__init__(
    config: dict[str, Any],
    evaluator: EvaluationBatchCallback | Evaluator,
    *,
    constraint_tolerance: float = 1e-10,
) -> None

Initialize a BasicOptimizer object.

Parameters:

Name	Type	Description	Default
config	dict[str, Any]	The configuration for the optimization.	required
evaluator	EvaluationBatchCallback | Evaluator	An EvaluationBatchCallback callable that evaluates a batch of variable vectors, or an Evaluator instance for advanced features such as caching, parallel, or HPC evaluation.	required
constraint_tolerance	float	The constraint violation tolerance; a constraint within this tolerance is considered satisfied. Violations are compared in the domain the optimizer works in, so a scale applies to them as well.	1e-10

results property

results: FunctionResults | None

The optimal result found during the optimization.

Returns:

Type	Description
FunctionResults | None	The optimal result, or None if none was found yet.

run

run(initial_values: ArrayLike) -> ExitCode

Run the optimization process.

Parameters:

Name	Type	Description	Default
initial_values	ArrayLike	The variable vector to start the optimization from.	required

Returns:

Type	Description
ExitCode	The exit code returned by the optimization workflow.

set_results_callback

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

Set a callback to report new results.

Invoked with a tuple[FunctionResults, ...] whenever new results become available:

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