Maintainers: Manuel López-Ibáñez, Leslie Pérez Cáceres
Creators: Manuel López-Ibáñez, Jérémie Dubois-Lacoste
Contributors: Jérémie Dubois-Lacoste, Thomas Stützle, Mauro Birattari, Eric Yuan and Prasanna Balaprakash.
The irace package implements the Iterated Race method, which is a generalization of the Iterated F-race method for the automatic configuration of optimization algorithms, that is, the tuning of their parameters by finding the most appropriate settings given a set of instances of an optimization problem. It builds upon the race package by Birattari and it is implemented in R.
Keywords: automatic configuration, offline tuning, parameter tuning, racing, F-race.
M. López-Ibáñez, J. Dubois-Lacoste, L. Pérez Cáceres, T. Stützle, and M. Birattari. The irace package: Iterated Racing for Automatic Algorithm Configuration. Operations Research Perspectives, 3:43–58, 2016.
[ bibtex | doi: 10.1016/j.orp.2016.09.002 ]
Manuel López-Ibáñez, Jérémie Dubois-Lacoste, Thomas Stützle, and Mauro Birattari. The irace package, Iterated Race for Automatic Algorithm Configuration. Technical Report TR/IRIDIA/2011-004, IRIDIA, Université libre de Bruxelles, Belgium, 2011.
[ bibtex | PDF ]
The official instructions are available at https://cran.r-project.org/doc/manuals/r-release/R-admin.html. We give below a quick R installation guide that will work in most cases.
You should install R from your package manager. On a Debian/Ubuntu system it will be something like:
Once R is installed, you can launch R from the Terminal and from the R prompt install the irace package. See instructions below.
You can install R directly from a CRAN mirror (https://cran.r-project.org/bin/macosx/).
Alternatively, if you use homebrew, you can just brew the R formula from the science tap (unfortunately it does not come already bottled so you need to have Xcode installed to compile it):
Once R is installed, you can launch R from the Terminal (or from your Applications), and from the R prompt install the irace package. See instructions below.
You can install R from a CRAN mirror (https://cran.r-project.org/bin/windows/). Once R is installed, you can launch the R console and install the irace package from it. See instructions below.
There are two methods for installing the irace R package on your computer:
select a mirror close to you, and test the installation with
<package> is one of the three versions available:
.tgz (MacOS X), or
If the package fails to install because of insufficient permissions, you need to force a local installation by doing:
Once installed, test that it is working by doing:
The last command tells you the installation directory of
Save the installation directory of
irace to a variable, and add it to your
After adding this and opening a new terminal, you should be able to invoke
irace as follows:
If the installation directory of
C:/R/irace/, you can invoke
irace by opening a terminal (launch the program
cmd.exe) and executing:
or if you are in a 32-bits system, executing:
You can also launch irace by opening the R console and executing:
For each template in your tuning directory, remove the
.tmpl suffix, and modify them following the instructions in each file. In particular,
target-evaluator(if you need it at all) should be executable. The output of
target-evaluatorif you use a separate evaluation step) is minimized by default. If you wish to maximize it, just multiply the value by
-1within the script.
scenario.txt, uncomment and assign only the parameters for which you need a value different than the default one.
There are examples in
Put the instances in
~/tuning/Instances/. In addition, you can create a file that specifies which instances from that directory should be run and which instance-specific parameters to use. See
instances-list.tmpl for examples. The command irace will not attempt to create the execution directory (
execDir), so it must exist before calling irace. The default
execDir is the current directory.
Calling the command:
For executing several repetitions of irace in parallel, call the program
where N is the number of repetitions. By default, the execution directory of each run of irace will be set to
dd is a number padded with zeroes.
parallel-irace will create these directories from scratch, deleting them first if they already exist.
Check the help of
parallel-irace by running it without parameters.
A single run of irace can be done much faster by executing the calls to
targetRunner (the runs of the algorithm being tuned) in parallel. See the user guide for the details.
irace is Copyright (C) 2010-2020 Manuel López-Ibáñez, Jérémie Dubois-Lacoste and Leslie Pérez-Cáceres.
This program is free software (software libre); you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
IMPORTANT NOTE: Please be aware that the fact that this program is released as Free Software does not excuse you from scientific propriety, which obligates you to give appropriate credit! If you write a scientific paper describing research that made substantive use of this program, it is your obligation as a scientist to (a) mention the fashion in which this software was used in the Methods section; (b) mention the algorithm in the References section. The appropriate citation is:
The irace package uses code under the GPL from the race package is Copyright (C) 2003 Mauro Birattari.
Thanks to Singularity, you can build a standalone container of
irace using the file
irace.sindef which is available in the directory
inst/ in the source tarball and github repository or, after installing the irace R package, in the installation directory given by the R expression
system.file(package="irace"). After installing SingularityCE, the container may be build using:
and run with:
The user guide contains a list of frequently asked questions.