Options and file formats

In the optimization-process of SMAC, there are several ways to configure the options:

  • Commandline-options, with which SMAC is called directly (not needed if SMAC is used within Python).

  • Scenario-options, that are specified via a Scenario-object. Either directly in the Python-code or by using a scenario-file.

  • A Parameter Configuration Space (PCS), that provides the legal ranges of parameters to optimize, their types (e.g. int or float) and their default values.

  • Instance- and feature-files, that list the instances and features to optimize upon.

SMAC Options

The basic command line options are described in Basic Usage. The options are separated into three groups, Main Options, SMAC Options and Scenario Options. See the Main and SMAC Options below. Find the Scenario Options in the next section.

Main Options:


number of hydra iterations. Only active if mode is set to Hydra Default: 3.


set to validate incumbents on. valX => validation set of size training_set * 0.X Default: train.


number of configurations to keep per psmac/hydra iteration. Default: 1.


Configuration mode. Default: SMAC4AC.


number of optimizers to run in parallel per psmac/hydra iteration. Default: 1.


Validate all psmac configurations.


path to a python module containing a class RandomConfigurationChooserImpl`implementing the interface of `RandomConfigurationChooser


Path to directory with SMAC-files.


Scenario file in AClib format.


Random Seed. Default: 1.


Verbosity level. Default: 20.

SMAC Options:


If true, SMAC will abort if the first run of the target algorithm crashes. Default: True.


Number of challengers returned by acquisition function optimization. Also influences the number of randomly sampled configurations to optimized the acquisition function Default: 5000.


Race new incumbents always against default configuration.


number of hydra iterations. Only active if mode is set to Hydra Default: 3.


For parallel SMAC, multiple output-directories are used.


Slack factor of adpative capping (factor * adpative cutoff). Only active if obj is runtime. If set to very large number it practically deactivates adaptive capping. Default: 1.2.


Minimal number of challengers to be considered in each intensification run (> 1). Set to 1 and in combination with very small intensification-percentage. it will deactivate randomly sampled configurations (and hence, extrapolation of random forest will be an issue.) Default: 2.


The fraction of time to be used on intensification (versus choice of next Configurations). Default: 0.5.


If true, SMAC will use pynisher to limit time and memory for the target algorithm. Allows SMAC to use all resources available. Applicable only to func TAEs. Set to ‘True’ by default. (Use with caution!) Default: True.


Maximum number of calls per configuration. Default: 2000.


Minimum number of calls per configuration. Default: 1.


Specifies the output-directory for all emerging files, such as logging and results. Default: smac3-output_2021-07-27_15:54:31_919661.


probablity to run a random configuration instead of configuration optimized on the acquisition function Default: 0.5.


path to a python module containing a class`RandomConfigurationChooserImpl` implementingthe interface of RandomConfigurationChooser


Use bootstraping in random forest. Default: True.


Maximum depth of each tree in the random forest. Default: 20.


Minimum required number of samples in each leaf of a tree in the random forest. Default: 3.


Minimum number of samples to split for building a tree in the random forest. Default: 3.


Number of trees in the random forest (> 1). Default: 10.


Ratio of sampled features in each split ([0.,1.]). Default: 0.8333333333333334.


Whether to run SMAC in parallel mode.


Maximum number of local search steps in one iteration during the optimization of the acquisition function.


Maximum number of steps on plateaus during the optimization of the acquisition function. Default: 10.


Transform all observed cost values via log-transformations or inverse scaling. The subfix “s” indicates that SMAC scales the y-values accordingly to apply the transformation. Default: NONE.


Instead of measuring SMAC’s wallclock time, only consider time reported by the target algorithm (ta).


The scenario-object (smac.scenario.scenario.Scenario) is used to configure SMAC and can be constructed either by providing an actual scenario-object (see SVM-example), or by specifing the options in a scenario file (see SPEAR example).

The format of the scenario file is one option per line:


For boolean options “1” or “true” both evaluate to True. The following assumes that the scenario is created via a scenario-file. If it is generated within custom code, you might not need algo or paramfile.

Scenario Options:


Maximum amount of CPU-time used for optimization. Default: inf.


Race new incumbents always against default configuration.


Defines the cost-value for crashed runs on scenarios with quality as run-obj. Default: 2147483647.0.


Maximum runtime, after which the target algorithm is cancelled. Required if *run_obj* is runtime.


If true, SMAC assumes that the target function or algorithm is deterministic (the same static seed of 0 is always passed to the function/algorithm). If false, different random seeds are passed to the target function/algorithm.


Specifies the path to the execution-directory. Default: ..


Specifies the file with the instance-features.


DEFAULT is the default from the PCS. Default: DEFAULT.


Maximum available memory the target algorithm can occupy before being cancelled in MB.


PARX, where X is an integer defining the penalty imposed on timeouts (i.e. runtimes that exceed the cutoff-time). Default: par10.


Specifies the path to the PCS-file.


Defines what metric to optimize. When optimizing runtime, cutoff_time is required as well.


If true, runhistory and stats are saved immediately on changes. Otherwise, runhistory and states are only saved once after the optimization process has finished.


Specifies the target algorithm call that SMAC will optimize. Interpreted as a bash-command.


Maximum number of algorithm-calls during optimization. Default: inf.


Specifies the file with the test-instances.


Specifies the file with the training-instances.


Maximum amount of wallclock-time used for optimization. Default: inf.

These options are also available as command line switches: Prepend two “-” and replace each “_” by “-“, e.g. “wallclock_limit” becomes “–wallclock-limit”. The options on the command line overwrite the values given in the scenario file.

Parameter Configuration Space (PCS)

The Parameter Configuration Space (PCS) defines the legal ranges of the parameters to be optimized and their default values. In the examples-folder you can find several examples for PCS-files. Generally, the format is:

To define parameters and their ranges, the following format is supported:

parameter_name categorical {value_1, ..., value_N} [default value]
parameter_name ordinal {value_1, ..., value_N} [default value]
parameter_name integer [min_value, max_value] [default value]
parameter_name integer [min_value, max_value] [default value] log
parameter_name real [min_value, max_value] [default value]
parameter_name real [min_value, max_value] [default value] log

The trailing “log” indicates that SMAC should sample from the defined ranges on a log scale.

Furthermore, conditional dependencies can be expressed. That is useful if a parameter activates sub-parameters. For example, only if a certain heuristic is used, the heuristic’s parameter are active and otherwise SMAC can ignore these.

# Conditionals:
child_name | condition [&&,||] condition ...

# Condition Operators:
# parent_x [<, >] parent_x_value (if parameter type is ordinal, integer or real)
# parent_x [==,!=] parent_x_value (if parameter type is categorical, ordinal or integer)
# parent_x in {parent_x_value1, parent_x_value2,...}

Forbidden constraints allow for specifications of forbidden combinations of parameter values. Please note that SMAC uses a simple rejection sampling strategy. Therefore, SMAC cannot handle efficiently highly constrained spaces.

# Forbiddens:
{parameter_name_1=value_1, ..., parameter_name_N=value_N}

Instances and Features

To specify instances and features, simply provide text-files in the following format and provide the paths to the instances in the scenario.

Instance-files are text-files with one instance per line. If you want to use training- and test-sets, separate files are expected.

Feature-files are files following the comma-separated-value-format, as can also be seen in the SPEAR-example:


name of feature 1

name of feature 2

name of instance 1

value of feature 1

value of feature 2