class adaptive.runner.AsyncRunner(learner: LearnerType, goal: Optional[Callable[[LearnerType], bool]] = None, *, loss_goal: Optional[float] = None, npoints_goal: Optional[int] = None, end_time_goal: Optional[datetime] = None, duration_goal: Optional[Union[timedelta, int, float]] = None, executor: Optional[Union[ProcessPoolExecutor, ThreadPoolExecutor, SequentialExecutor, _ReusablePoolExecutor]] = None, ntasks: Optional[int] = None, log: bool = False, shutdown_executor: bool = False, ioloop=None, retries: int = 0, raise_if_retries_exceeded: bool = True)[source]#

Bases: BaseRunner

Run a learner asynchronously in an executor using asyncio.

  • learner (BaseLearner instance) –

  • goal (callable, optional) – The end condition for the calculation. This function must take the learner as its sole argument, and return True when we should stop requesting more points. If not provided, the runner will run forever (or stop when no more points can be added), or until runner.task.cancel() is called.

  • loss_goal (float, optional) – Convenience argument, use instead of goal. The end condition for the calculation. Stop when the loss is smaller than this value.

  • npoints_goal (int, optional) – Convenience argument, use instead of goal. The end condition for the calculation. Stop when the number of points is larger or equal than this value.

  • end_time_goal (datetime, optional) – Convenience argument, use instead of goal. The end condition for the calculation. Stop when the current time is larger or equal than this value.

  • duration_goal (timedelta or number, optional) – Convenience argument, use instead of goal. The end condition for the calculation. Stop when the current time is larger or equal than start_time + duration_goal. duration_goal can be a number indicating the number of seconds.

  • executor (concurrent.futures.Executor, distributed.Client,) –

    mpi4py.futures.MPIPoolExecutor, ipyparallel.Client or

    loky.get_reusable_executor, optional

    The executor in which to evaluate the function to be learned. If not provided, a new ProcessPoolExecutor on Linux, and a loky.get_reusable_executor on MacOS and Windows.

  • ntasks (int, optional) – The number of concurrent function evaluations. Defaults to the number of cores available in executor.

  • log (bool, default: False) – If True, record the method calls made to the learner by this runner.

  • shutdown_executor (bool, default: False) – If True, shutdown the executor when the runner has completed. If executor is not provided then the executor created internally by the runner is shut down, regardless of this parameter.

  • ioloop (asyncio.AbstractEventLoop, optional) – The ioloop in which to run the learning algorithm. If not provided, the default event loop is used.

  • retries (int, default: 0) – Maximum amount of retries of a certain point x in learner.function(x). After retries is reached for x the point is present in runner.failed.

  • raise_if_retries_exceeded (bool, default: True) – Raise the error after a point x failed retries.

  • allow_running_forever (bool, default: True) – If True, the runner will run forever if the goal is not provided.


The underlying task. May be cancelled in order to stop the runner.




The underlying learner. May be queried for its state.


BaseLearner instance


Record of the method calls made to the learner, in the format (method_name, *args).


list or None


List of (point, n_fails). When a point has failed runner.retries times it is removed but will be present in runner.tracebacks.


list of tuples


List of of (point, tb) for points that failed.


list of tuples


A list of tuples with (concurrent.futures.Future, point).


list of tuples

elapsed_time : callable

A method that returns the time elapsed since the runner was started.

overhead : callable

The overhead in percent of using Adaptive. This includes the overhead of the executor. Essentially, this is 100 * (1 - total_elapsed_function_time / self.elapsed_time()).


This runner can be used when an async function (defined with async def) has to be learned. In this case the function will be run directly on the event loop (and not in the executor).

block_until_done() None[source]#
cancel() None[source]#

Cancel the runner.

This is equivalent to calling runner.task.cancel().

elapsed_time() float[source]#

Return the total time elapsed since the runner was started.

live_info(*, update_interval: float = 0.1) None[source]#

Display live information about the runner.

Returns an interactive ipywidget that can be visualized in a Jupyter notebook.

live_info_terminal(*, update_interval: float = 0.5, overwrite_previous: bool = True) Task[source]#

Display live information about the runner in the terminal.

This function provides a live update of the runner’s status in the terminal. The update can either overwrite the previous status or be printed on a new line.

  • update_interval (float, optional) – The time interval (in seconds) at which the runner’s status is updated in the terminal. Default is 0.5 seconds.

  • overwrite_previous (bool, optional) – If True, each update will overwrite the previous status in the terminal. If False, each update will be printed on a new line. Default is True.


The asynchronous task responsible for updating the runner’s status in the terminal.

Return type:



>>> runner = AsyncRunner(...)
>>> runner.live_info_terminal(update_interval=1.0, overwrite_previous=False)


This function uses ANSI escape sequences to control the terminal’s cursor position. It might not work as expected on all terminal emulators.

live_plot(*, plotter: Callable[[LearnerType], holoviews.Element] | None = None, update_interval: float = 2.0, name: str | None = None, normalize: bool = True) holoviews.DynamicMap[source]#

Live plotting of the learner’s data.

  • runner (Runner) –

  • plotter (function) – A function that takes the learner as a argument and returns a holoviews object. By default learner.plot() will be called.

  • update_interval (int) – Number of second between the updates of the plot.

  • name (hasable) – Name for the live_plot task in adaptive.active_plotting_tasks. By default the name is None and if another task with the same name already exists that other live_plot is canceled.

  • normalize (bool) – Normalize (scale to fit) the frame upon each update.


dm – The plot that automatically updates every update_interval.

Return type:


start_periodic_saving(save_kwargs: Optional[dict[str, Any]] = None, interval: int = 30, method: Optional[Callable[[LearnerType], None]] = None)[source]#

Periodically save the learner’s data.

  • save_kwargs (dict) – Key-word arguments for**save_kwargs). Only used if method=None.

  • interval (int) – Number of seconds between saving the learner.

  • method (callable) – The method to use for saving the learner. If None, the default saves the learner using “pickle” which calls**save_kwargs). Otherwise provide a callable that takes the learner and saves the learner.


>>> runner = Runner(learner)
>>> runner.start_periodic_saving(
...     save_kwargs=dict(fname='data/test.pickle'),
...     interval=600)
status() str[source]#

Return the runner status as a string.

The possible statuses are: running, cancelled, failed, and finished.