AbstractRunner(scenario[, required_arguments])

Interface class to handle the execution of SMAC configurations.


class smac.runner.abstract_runner.AbstractRunner(scenario, required_arguments=[])[source]

Bases: ABC

Interface class to handle the execution of SMAC configurations. This interface defines how to interact with the SMBO loop. The complexity of running a configuration as well as handling the results is abstracted to the SMBO via an AbstractRunner.

From SMBO perspective, launching a configuration follows a submit/collect scheme as follows:

  1. A run is launched via submit_run()

    • submit_run internally calls run_wrapper(), a method that contains common processing functions among different runners.

    • A class that implements AbstractRunner defines run() which is really the algorithm to translate a TrialInfo to a TrialValue, i.e. a configuration to an actual result.

  2. A completed run is collected via iter_results(), which iterates and consumes any finished runs, if any.

  3. This interface also offers the method wait() as a mechanism to make sure we have enough data in the next iteration to make a decision. For example, the intensifier might not be able to select the next challenger until more results are available.

  • scenario (Scenario) –

  • required_arguments (list[str]) – A list of required arguments, which are passed to the target function.

abstract count_available_workers()[source]

Returns the number of available workers.

Return type:


abstract is_running()[source]

Whether there are trials still running.

Generally, if the runner is serial, launching a trial instantly returns its result. On parallel runners, there might be pending configurations to complete.

Return type:


abstract iter_results()[source]

This method returns any finished configuration, and returns a list with the results of executing the configurations. This class keeps populating results to self._results_queue until a call to get_finished trials is done. In this case, the self._results_queue list is emptied and all trial values produced by running run are returned.


A list of TrialInfo/TrialValue tuples, all of which have been finished.

Return type:

Iterator[tuple[TrialInfo, TrialValue]]

property meta: dict[str, Any]

Returns the meta-data of the created object.

abstract run(config, instance=None, budget=None, seed=None)[source]

Runs the target function with a configuration on a single instance-budget-seed combination (aka trial).

  • config (Configuration) – Configuration to be passed to the target function.

  • instance (str | None, defaults to None) – The Problem instance.

  • budget (float | None, defaults to None) – A positive, real-valued number representing an arbitrary limit to the target function handled by the target function internally.

  • seed (int, defaults to None) –

Return type:

tuple[StatusType, float | list[float], float, dict]


  • status (StatusType) – Status of the trial.

  • cost (float | list[float]) – Resulting cost(s) of the trial.

  • runtime (float) – The time the target function took to run.

  • additional_info (dict) – All further additional trial information.

run_wrapper(trial_info, **dask_data_to_scatter)[source]

Wrapper around run() to execute and check the execution of a given config. This function encapsulates common handling/processing, so that run() implementation is simplified.

  • trial_info (RunInfo) – Object that contains enough information to execute a configuration run in isolation.

  • dask_data_to_scatter (dict[str, Any]) – When a user scatters data from their local process to the distributed network, this data is distributed in a round-robin fashion grouping by number of cores. Roughly speaking, we can keep this data in memory and then we do not have to (de-)serialize the data every time we would like to execute a target function with a big dataset. For example, when your target function has a big dataset shared across all the target function, this argument is very useful.

Return type:

tuple[TrialInfo, TrialValue]


  • info (TrialInfo) – An object containing the configuration launched.

  • value (TrialValue) – Contains information about the status/performance of config.

abstract submit_trial(trial_info)[source]

This function submits a configuration embedded in a TrialInfo object, and uses one of the workers to produce a result (such result will eventually be available on the self._results_queue FIFO).

This interface method will be called by SMBO, with the expectation that a function will be executed by a worker. What will be executed is dictated by trial_info, and how it will be executed is decided via the child class that implements a run method.

Because config submission can be a serial/parallel endeavor, it is expected to be implemented by a child class.


trial_info (TrialInfo) – An object containing the configuration launched.

Return type:


abstract wait()[source]

The SMBO/intensifier might need to wait for trials to finish before making a decision.

Return type: