


\subsection[General options]{General options}
\begin{description}
 \defparameter[h]{-{}-help}{help}{}%
Show the list of command-line options of \irace.

 \defparameter[v]{-{}-version}{version}{}%
Show the version of \irace.

 \defparameter[c]{-{}-check}{check}{}%
Check that the scenario and parameter definitions are correct and test the execution of the target algorithm. See \autoref{sec:execution}.

 \defparameter[i]{-{}-init}{init}{}%
Initialize the working directory with the template config files. This copies the files in \code{\$IRACE_HOME/templates} to the working directory without overwriting the files with the same names as those of the template files.

 \defparameter[s]{scenarioFile}{scenario}{./scenario.txt}%
File that contains the scenario setup and other irace options. All options listed in this section can be included in this file. See \IRACEHOME{/templates/} for an example. Relative file-system paths specified in the scenario file are relative to the scenario file itself.

 \defparameter{execDir}{exec-dir}{./}%
Directory where the target algorithm executions will be performed. The default execution directory is the current directory.
 \begin{xwarningbox}
 The execution directory must exist before executing \irace, it will not be created automatically.
\end{xwarningbox}

 \defparameter[l]{logFile}{log-file}{./irace.Rdata}%
  File to save tuning results as an \aR dataset. The provided path must be either an absolute path or relative to \parameter{execDir}. See \autoref{sec:output r} for details on the format of the \aR dataset.

 \defparameter{debugLevel}{debug-level}{0}%
Level of information to display in the text output of \irace. A value of 0 silences all debug messages. Higher values provide more verbose debug messages. Details about the text output of \irace are given in \autoref{sec:output text}.

 \defparameter{seed}{seed}{}%
Seed to initiallize the random number generator. The seed must be a positive integer. If the seed is \code{""} or \code{NULL}, a random seed will be generated.

 \defparameter{repairConfiguration}{}{}%
User-defined \aR function that takes a configuration generated by \irace and repairs it. See \autoref{sec:repairconf} for details.

 \defparameter{postselection}{postselection}{0}%
Percentage of the configuration budget used to perform a postselection race of the best configurations of each iteration after the execution of \irace. See \autoref{sec:postselection}.

 \defparameter{aclib}{aclib}{0}%
Enable/disable AClib mode. This option enables compatibility with \texttt{GenericWrapper4AC} (\url{https://github.com/automl/GenericWrapper4AC/}) as \parameter{targetRunner} script.

\end{description}

\subsection[Elitist irace]{Elitist \irace}
\begin{description}
 \defparameter[e]{elitist}{elitist}{1}%
Enable/disable elitist \irace.

 In the \textbf{elitist} version of \code{irace}~\citep{LopDubPerStuBir2016irace}, elite configurations are not discarded from the race until non-elite configurations have been executed on the same instances as the elite configurations.

 Each race begins by evaluating all configurations on a number of new instances. This number is defined by the option \parameter{elitistNewInstances}. After the new instances have been evaluated, configurations are evaluated on instances seen in the previous race.  Elite configurations already have results for most of these previous instances and, therefore, do not need to be re-evaluated. Finally, after configurations have been evaluated on all these instances, the race continues by evaluating additional new instances. 

 The statistical tests can be performed at any moment during the race according to the setting of the options \parameter{firstTest} and \parameter{eachTest}. The elitist rule forbids discarding elite configurations, even if the show poor performance, until the last of the previous instances is seen in the race. 

 The \textbf{non-elitist} version of \irace can discard elite configurations at any point of the race, instances are not re-used from one race to the next, and new instances are sampled for each race.

 \defparameter{elitistNewInstances}{elitist-new-instances}{1}%
 Number of new instances added to each race before evaluating instances from previous races (only for elitist \irace).
 \begin{xwarningbox}
 
 If \parameter{deterministic} is \code{TRUE} then the number of \parameter{elitistNewInstances} will be reduced or set to \code{0} once all instances have been evaluated.
\end{xwarningbox}

 \defparameter{elitistLimit}{elitist-limit}{2}%
  Maximum number of statistical tests performed without successful elimination after all instances from the previous race have been evaluated. If the limit is reached, the current race is stopped. Only valid for elitist \irace. Use \code{0} to disable the limit.

\end{description}

\subsection[Internal irace options]{Internal \irace options}
\begin{description}
 \defparameter{sampleInstances}{sample-instances}{1}%
Enable/disable the sampling of the training instances. If the option \parameter{sampleInstances} is disabled, the instances are used in the order provided in the \parameter{trainInstancesFile} or in the order they are read from the \parameter{trainInstancesDir} when\parameter{trainInstancesFile} is not provided. For more information about training instances see \autoref{sec:training}.

 \defparameter{softRestart}{soft-restart}{1}%
  Enable/disable the soft-restart strategy that avoids premature convergence of the probabilistic model. When a sampled configuration is \emph{similar} to its parent configuration, the probabilistic model of these configurations is soft restarted. The soft-restart mechanism is explained in the \irace paper~\citep{LopDubPerStuBir2016irace}. The similarity of categorical and ordinal parameters is given by the hamming distance, and the option \parameter{softRestartThreshold} defines the similarity of numerical parameters.

 \defparameter{softRestartThreshold}{soft-restart-threshold}{}%
Soft restart threshold value for numerical parameters. By default, it is computed as $10^{-digits}$, where \parameter{digits} corresponds to the \irace option explained in this section.

 \defparameter{nbIterations}{iterations}{0}%
Maximum number of iterations to be executed. Each iteration involves the generation of new configurations and the use of racing to select the best configurations. By default (with 0), \irace calculates a \emph{minimum} number of iterations as $\Niter = \lfloor 2 + \log_{2}\Nparam \rfloor$, where $\Nparam$ is the number of non-fixed parameters to be tuned. Setting this parameter may make \irace stop sooner than it should without using all the available budget. We recommend to use the default value.

 \defparameter{nbExperimentsPerIteration}{experiments-per-iteration}{0}%
Number of runs of the target algorithm per iteration. By default (when equal to 0), this value changes for each iteration and depends on the iteration index and the remaining budget. Further details are provided in the \irace paper~\citep{LopDubPerStuBir2016irace}.
We recommend to use the default value.

 \defparameter{minNbSurvival}{min-survival}{0}%
Minimum number of configurations needed to continue the execution of each race (iteration). If the number of configurations alive in the race is not larger than this value, the current iteration will stop and a new iteration will start, even if there is budget left to continue the current race. By default (when equal to 0), the value is calculated automatically as $\lfloor 2 + \log_{2}\Nparam \rfloor$, where $\Nparam$ is the number of non-fixed parameters to be tuned.

 \defparameter{nbConfigurations}{num-configurations}{0}%
  The number of configurations that will be raced at each iteration. By default (when equal to 0), this value changes for each iteration and depends on \parameter{nbExperimentsPerIteration}, the iteration index and \parameter{mu}. The precise details are given in the \irace paper~\citep{LopDubPerStuBir2016irace}.
We recommend to use the default value.

 \defparameter{mu}{mu}{5}%
  Parameter used to define the number of configurations to be sampled and evaluated at each iteration. The number of configurations will be calculated such that there is enough budget in each race to evaluate all configurations on at least $\mu + \min(5,j)$ training instances, where $j$ is the index of the current iteration. The value of $\mu$ will be adjusted to never be lower than the value of \parameter{firstTest}. We recommend to use the default value and, if needed, adjust \parameter{firstTest}and \parameter{eachTest}, instead.

\end{description}

\subsection[Target algorithm parameters]{Target algorithm parameters}
\begin{description}
 \defparameter[p]{parameterFile}{parameter-file}{./parameters.txt}%
File that contains the description of the parameters of the target algorithm. See \autoref{sec:target parameters}.

 \defparameter{forbiddenFile}{forbidden-file}{}%
File containing a list of logical expressions that cannot be true for any evaluated configuration. If empty or \code{NULL}, no forbidden configurations are considered. See \autoref{sec:forbidden} for more information.

 \defparameter{digits}{digits}{4}%
Maximum number of decimal places that are significant for numerical (real) parameters.

\end{description}

\subsection[Target algorithm execution]{Target algorithm execution}
\begin{description}
 \defparameter{targetRunner}{target-runner}{./target-runner}%
Executable or \aR function that evaluates a configuration of the target algorithm on a particular instance. See \autoref{sec:runner} for details.

 \defparameter{targetRunnerLauncher}{target-runner-launcher}{}%
Executable that will be used to launch the target runner, when \parameter{targetRunner} cannot be executed directly (.e.g, a Python script in Windows).

 \defparameter{targetRunnerLauncherArgs}{target-runner-args}{{targetRunner} {targetRunnerArgs}}%
Command-line arguments provided to \parameter{targetRunnerLauncher}. The substrings \code{\{targetRunner\}} and \code{\{targetRunnerArgs\}} will be replaced by the value of the option \parameter{targetRunner} and by the arguments usually passed when calling \parameter{targetRunner}, respectively. Example: \code{"-m \{targetRunner\} --args \{targetRunnerArgs\}"}.

 \defparameter{targetRunnerRetries}{target-runner-retries}{0}%
Number of times to retry a call to \parameter{targetRunner} if the call failed.

 \defparameter{targetRunnerData}{}{}%
Optional data passed to \parameter{targetRunner}. This is ignored by the default \parameter{targetRunner} function, but it may be used by custom \parameter{targetRunner} functions to pass persistent data around.

 \defparameter{targetRunnerParallel}{}{}%
 Optional \aR function to provide custom parallelization of \parameter{targetRunner}. See \autoref{sec:parallel} for more information.

 \defparameter{targetEvaluator}{target-evaluator}{}%
Optional script or \aR function that returns a numerical value for an experiment after all configurations have been executed on a given instance using \parameter{targetRunner}. See \autoref{sec:evaluator} for details.

 \defparameter{deterministic}{deterministic}{0}%
  Enable/disable deterministic target algorithm mode. If the target algorithm is deterministic, configurations will be evaluated only once per instance. See \autoref{sec:training} for more information.
\begin{xwarningbox}
 If the number of instances provided is less than the value specified for the option \parameter{firstTest}, no statistical test will be performed.
\end{xwarningbox}

 \defparameter{parallel}{parallel}{0}%
Number of calls of the \parameter{targetRunner} to execute in parallel. Values  0 or 1 mean no parallelization. For more information on parallelization, see \autoref{sec:parallel}.

 \defparameter{loadBalancing}{load-balancing}{1}%
  Enable/disable load-balancing when executing experiments in parallel. Load-balancing makes better use of computing resources, but increases communication overhead. If this overhead is large, disabling load-balancing may be faster. See \autoref{sec:parallel}.

 \defparameter{mpi}{mpi}{0}%
  Enable/disable use of \pkg{Rmpi} to execute the \parameter{targetRunner} in parallel using MPI protocol. When \parameter{mpi} is enabled, the option \parameter{parallel} is the number of slave nodes. See \autoref{sec:parallel}.

 \defparameter{batchmode}{batchmode}{0}%
  Specify how irace waits for jobs to finish when \parameter{targetRunner} submits jobs to a batch cluster: \code{sge}, \code{pbs}, \code{torque}, \code{slurm} or \code{htcondor} (\parameter{targetRunner} must submit jobs to the cluster using. for example, \code{qsub}). See \autoref{sec:parallel}.

\end{description}

\subsection[Initial configurations]{Initial configurations}
\begin{description}
 \defparameter{configurationsFile}{configurations-file}{}%
File containing a table of initial configurations. If empty or \code{NULL}, \irace will not use initial configurations. See \autoref{sec:initial}.
\begin{xwarningbox}
The provided configurations must not violate the constraints described in \parameter{parameterFile} and \parameter{forbiddenFile}.
\end{xwarningbox}

\end{description}

\subsection[Training instances]{Training instances}
\begin{description}
 \defparameter{trainInstancesDir}{train-instances-dir}{./Instances}%
Directory where training instances are located; either absolute path or relative to current directory. See \autoref{sec:training}.

 \defparameter{trainInstancesFile}{train-instances-file}{}%
File that contains a list of instances and optionally additional parameters for them. See \autoref{sec:training}.
\begin{xwarningbox}
The list of instances in \parameter{trainInstancesFile} is interpreted as file-system paths  relative to \parameter{trainInstancesDir}. When using an absolute path or instances that are not files, set \code{trainInstancesDir=""}.
\end{xwarningbox}

\end{description}

\subsection[Tuning budget]{Tuning budget}
\begin{description}
 \defparameter{maxExperiments}{max-experiments}{0}%
The maximum number of runs (invocations of \parameter{targetRunner}) that will be performed. It determines the maximum budget of experiments for the tuning. See \autoref{sec:budget}.

 \defparameter{maxTime}{max-time}{0}%
The maximum total time in seconds for the runs of \parameter{targetRunner} that will be  performed. The mean execution time  of each run is estimated in order to calculate the maximum number of experiments (see option \parameter{budgetEstimation}).
  When \parameter{maxTime} is positive, then \parameter{targetRunner} \textbf{must} return the execution time as its second output. See \autoref{sec:budget}.

 \defparameter{budgetEstimation}{budget-estimation}{0.02}%
Fraction (smaller than 1) of the budget used to estimate the mean execution time of a configuration. Only used when \parameter{maxTime} $> 0$. See \autoref{sec:budget}.

 \defparameter{minMeasurableTime}{min-measurable-time}{0.01}%
Minimum time unit that is still (significantly) measureable.

\end{description}

\subsection[Statistical test]{Statistical test}
\begin{description}
 \defparameter{testType}{test-type}{}%
Specifies the statistical test used for elimination:
\begin{itemize}
\item[] \code{F-test} (Friedman test)
\item[] \code{t-test} (pairwise t-tests with no correction)
\item[] \code{t-test-bonferroni} (t-test with Bonferroni's correction for multiple comparisons)
\item[] \code{t-test-holm} (t-test with Holm's correction for multiple comparisons).
\end{itemize}
 We recommend to not use corrections for multiple comparisons because the test typically becomes too strict and the search stagnates. 
See \autoref{sec:stat test} for details about choosing the statistical test most appropriate for your scenario.
\begin{xwarningbox}
 The default setting of \parameter{testType} is \code{F-test} unless the \parameter{capping} option is enabled in which case, the default setting is \code{t-test}.
\end{xwarningbox}

 \defparameter{firstTest}{first-test}{5}%
 Specifies how many instances are evaluated before the first elimination test.
\begin{xwarningbox}
The value of \parameter{firstTest} must be a multiple of \parameter{eachTest}.
\end{xwarningbox}

 \defparameter{eachTest}{each-test}{1}%
Specifies how many instances are evaluated between elimination tests.

 \defparameter{confidence}{confidence}{0.95}%
Confidence level for the elimination test.

\end{description}

\subsection[Adaptive capping]{Adaptive capping}
\begin{description}
 \defparameter{capping}{capping}{0}%
Enable the use of adaptive capping. This option is only available when \parameter{elitist} is active. When using this option, \irace provides an execution bound to each target algorithm execution (See \autoref{sec:runner}). For more details about this option See \autoref{sec:capping}.

 \defparameter{cappingType}{capping-type}{median}%
 Specifies the measure used to define the execution bound:
\begin{itemize}
\item[] \code{median} (the median of the performance of the elite configurations)
\item[] \code{mean} (the mean of the performance of the elite configurations)
\item[] \code{best} (the best performance of the elite configurations)
\item[] \code{worst} (the worst performance of the elite configurations).
\end{itemize}

 \defparameter{boundType}{bound-type}{candidate}%
Specifies how to calculate the performance of elite configurations for the execution bound:
\begin{itemize}
\item[] \code{candidate} (performance of candidates is aggregated across the instances already executed)
\item[] \code{instance} (performance of candidates on each instance).
\end{itemize}

 \defparameter{boundMax}{bound-max}{0}%
Maximum execution bound for \code{targetRunner}. It must be specified when capping is enabled.

 \defparameter{boundDigits}{bound-digits}{0}%
Precision used for calculating the execution time. It must be specified when capping is enabled.

 \defparameter{boundPar}{bound-par}{1}%
Penalty used for PARX. This value is used to penalize timed out executions, see \autoref{sec:capping}.

 \defparameter{boundAsTimeout}{bound-as-timeout}{1}%
Replace the configuration cost of bounded executions with \parameter{boundMax}. See \autoref{sec:capping}.

\end{description}

\subsection[Recovery]{Recovery}
\begin{description}
 \defparameter{recoveryFile}{recovery-file}{}%
Previously saved \irace log file that should be used to recover the execution of \irace; either absolute path or relative to the current directory. If empty or \code{NULL}, recovery is not performed. 
For more details about recovery, see \autoref{sec:recovery}.

\end{description}

\subsection[Testing]{Testing}
\begin{description}
 \defparameter{-{}-only-test}{only-test}{}%
Run the configurations contained in the file provided as argument on the test instances. See \autoref{sec:testing}.

 \defparameter{testInstancesDir}{test-instances-dir}{}%
Directory where testing instances are located, either absolute or relative to the current directory.

 \defparameter{testInstancesFile}{test-instances-file}{}%
File containing a list of test instances and, optionally, additional parameters for them.

 \defparameter{testNbElites}{test-num-elites}{1}%
  Number of elite configurations returned by irace that will be tested if test instances are provided. For more information about the testing, see \autoref{sec:testing}.

 \defparameter{testIterationElites}{test-iteration-elites}{0}%
Enable/disable testing the elite configurations found at each iteration.

\end{description}
