Collecting Results

For an overview of the ways to access optimization output, see Getting Output.

Using a result callback

Pass a function as result_callback to receive results as evaluations finish. optimize, evaluate, and evaluate_batch accept this parameter. For example, append each function result to a list:

from ropt import optimize

reported = []
result = optimize(config, x0, objective, result_callback=reported.append)

The callback receives one FunctionResults at a time. For optimize, set report_gradients=True to also receive GradientResults; in that case, the callback must handle both result types.

The callback does not replace or change the value returned by optimize, which remains the OptimizationResult. Returning True from the callback asks optimize to stop gracefully. Results later in the same batch are not passed to the callback. The return value is ignored by evaluate and evaluate_batch.

Each optimization calls its callback independently. If several optimizations run concurrently with the same callback, they can call it at the same time. Use a separate callback for each optimization, make shared state thread-safe, or use a handler when collecting results across concurrent optimizations.

Using handlers

An optimize call returns only its single best result. A handler lets you see every result an optimization produces: it is an object that observes the optimization and processes its results as they arrive.

Pass handlers with the handlers argument. Each receives the full result objects, FunctionResults and GradientResults, rather than the summary optimize returns; see Working with Results.

For instance, the HistoryHandler collects all results:

from ropt import HistoryHandler, optimize

history = HistoryHandler()
result = optimize(config, x0, objective, handlers=[history])
print(len(history.results))   # every evaluation from this optimization

Unlike a result callback, a handler can be reused across several sequential calls to optimize, accumulating results from all of them.

Built-in handlers

ropt ships a few ready-to-use handlers, all imported from ropt:

• HistoryHandler — keeps every result, as used above.
• ResultsHandler — keeps only one result: the best seen so far (default), or the most recent.
• DataFrameHandler — collects results into a pandas or polars table.

See Result handlers for the full list, and for what a handler shared between concurrent optimizations guarantees.