{"id":15165885,"url":"https://github.com/mlopez-ibanez/irace","last_synced_at":"2025-04-13T05:04:42.381Z","repository":{"id":38838573,"uuid":"180209830","full_name":"MLopez-Ibanez/irace","owner":"MLopez-Ibanez","description":"Iterated Racing for Automatic Algorithm Configuration","archived":false,"fork":false,"pushed_at":"2025-02-17T18:23:01.000Z","size":28360,"stargazers_count":63,"open_issues_count":17,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-13T05:04:04.364Z","etag":null,"topics":["algorithm-configuration","hyperparameter-tuning","irace","optimization-algorithms","r","r-package"],"latest_commit_sha":null,"homepage":"https://mlopez-ibanez.github.io/irace/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MLopez-Ibanez.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-08T18:31:16.000Z","updated_at":"2025-02-17T18:04:32.000Z","dependencies_parsed_at":"2024-01-06T11:42:49.612Z","dependency_job_id":"fe5c775d-1f69-4624-b484-a5a02362db59","html_url":"https://github.com/MLopez-Ibanez/irace","commit_stats":{"total_commits":1972,"total_committers":13,"mean_commits":"151.69230769230768","dds":0.05476673427991885,"last_synced_commit":"1fdbba610a263a5dd2372a760d33164809e8495f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLopez-Ibanez%2Firace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLopez-Ibanez%2Firace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLopez-Ibanez%2Firace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLopez-Ibanez%2Firace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MLopez-Ibanez","download_url":"https://codeload.github.com/MLopez-Ibanez/irace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665748,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm-configuration","hyperparameter-tuning","irace","optimization-algorithms","r","r-package"],"created_at":"2024-09-27T04:05:42.955Z","updated_at":"2025-04-13T05:04:42.347Z","avatar_url":"https://github.com/MLopez-Ibanez.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"**irace**: Iterated Racing for Automatic Algorithm Configuration\n================================================================\n\n\u003c!-- badges: start --\u003e\n[![CRAN version](https://www.r-pkg.org/badges/version-last-release/irace)](https://cran.r-project.org/package=irace)\n[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/irace)](https://CRAN.R-project.org/package=irace)\n[![CRAN status](https://badges.cranchecks.info/worst/irace.svg)](https://cran.r-project.org/web/checks/check_results_irace.html)\n[![R build\nstatus](https://github.com/MLopez-Ibanez/irace/workflows/R-CMD-check/badge.svg)](https://github.com/MLopez-Ibanez/irace/actions) \n[![Codecov test coverage](https://codecov.io/gh/MLopez-Ibanez/irace/branch/master/graph/badge.svg)](https://app.codecov.io/gh/MLopez-Ibanez/irace?branch=master)\n[![r-universe version](https://mlopez-ibanez.r-universe.dev/badges/irace)](https://mlopez-ibanez.r-universe.dev/irace)\n[![r-universe build status](https://github.com/r-universe/mlopez-ibanez/actions/workflows/build.yml/badge.svg)](https://github.com/r-universe/mlopez-ibanez/actions/workflows/build.yml)\n\u003c!-- badges: end --\u003e\n\n[ [**Homepage**](https://mlopez-ibanez.github.io/irace/) ] [ [**User Guide (PDF)**](https://cran.r-project.org/package=irace/vignettes/irace-package.pdf) ]\n\n**Maintainers:** [Manuel López-Ibáñez](https://lopez-ibanez.eu/), Leslie Pérez Cáceres\n\n**Creators:** [Manuel López-Ibáñez](https://lopez-ibanez.eu/), Jérémie Dubois-Lacoste\n  \n**Contributors:** Jérémie Dubois-Lacoste, Thomas Stützle, Mauro Birattari, Eric\n  Yuan and Prasanna Balaprakash.\n\n**Contact:** \u003chttps://groups.google.com/d/forum/irace-package\u003e\n\n---------------------------------------\n\nIntroduction\n------------\n\nThe **irace** package implements the Iterated Race method, which is a\ngeneralization of the Iterated F-race method for the automatic configuration of\noptimization algorithms, that is, the tuning of their parameters by finding the\nmost appropriate settings given a set of instances of an optimization problem.\nIt builds upon the race package by Birattari and it is implemented in R.\n\nYou may also find the [**iraceplot**](https://auto-optimization.github.io/iraceplot/) package useful for analyzing the output of irace.\n\n**Keywords:** automatic configuration, offline tuning, parameter tuning, racing, F-race.\n\n**Relevant literature:**\n\n 1. M. López-Ibáñez, J. Dubois-Lacoste, L. Pérez Cáceres, T. Stützle, and\n    M. Birattari. [The irace package: Iterated Racing for Automatic Algorithm Configuration](http://dx.doi.org/10.1016/j.orp.2016.09.002).\n*Operations Research Perspectives*, 3:43–58, 2016.\u003cbr\u003e\n    [ [bibtex](https://iridia-ulb.github.io/references/index_bib.html#LopDubPerStuBir2016irace)\n    | doi: [10.1016/j.orp.2016.09.002](http://dx.doi.org/10.1016/j.orp.2016.09.002) ]\n\n 2. Leslie Perez Cáceres, Manuel López-Ibáñez, Holger Hoos, and Thomas Stützle. [An Experimental Study of Adaptive Capping in irace](https://doi.org/10.1007/978-3-319-69404-7_17). *Learning and Intelligent Optimization. LION 2017*. Lecture Notes in Computer Science, vol 10556. Springer, Cham.\u003cbr\u003e\n    [ [bibtex](https://iridia-ulb.github.io/references/index_bib.html#PerLopHooStu2017:lion)\n    | doi: [10.1007/978-3-319-69404-7_17](https://doi.org/10.1007/978-3-319-69404-7_17) ]\n\n 3. Thomas Stützle and Manuel López-Ibáñez. [Tutorial: Automated algorithm\n    configuration and design](https://doi.org/10.1145/3449726.3461404). GECCO\n    '21: Proceedings of the Genetic and Evolutionary Computation Conference\n    Companion, July 2021.\n    [doi:10.1145/3449726.3461404](https://doi.org/10.1145/3449726.3461404)\n\n\n### Requisites ###\n\n * R (\u003chttps://www.r-project.org\u003e) is required for running irace, but\n   you don't need to know the R language to use it.\n\n\n### User guide ###\n\nA complete [user guide](https://cran.r-project.org/package=irace/vignettes/irace-package.pdf)\ncomes with the package. You can access it online or, after installing the irace\npackage, invoking from the R console the following command:\n\n```R\n        vignette(\"irace-package\")\n```\n\nThe following is a quick-start guide. The user guide gives more detailed\ninstructions.\n\nQuick Start\n-----------\n\n1. Install R (with your favourite package manager, and see more details below).\n2. Install irace. This command works on Bash shell (Linux and MacOS) and Powershell (Windows) with R added to PATH (see detailed instructions below).\n```bash\n    Rscript -e \"install.packages('irace', repos='https://cloud.r-project.org')\"\n```\n\n3. Add irace to the `PATH` environment variable. This command works in Bash shell (Linux and MacOS). For Windows user, this step is unfortunately more involved, so please see more detailed instructions below.\n```bash\n    export PATH=\"$(Rscript -e \"cat(paste0(system.file(package='irace', 'bin', mustWork=TRUE), ':'))\" 2\u003e /dev/null)${PATH}\"\n```\nConsider adding this line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile` for it to persist between sessions. \n\n4. You can open the user guide with the following command. This command works on Bash shell (Linux and MacOS) and and Powershell (Windows) with R added to PATH (see detailed instructions below).\n```bash\n    Rscript -e \"vignette('irace-package')\"\n```\n\nInstalling R\n------------\n\nThe official instructions are available at\n\u003chttps://cran.r-project.org/doc/manuals/r-release/R-admin.html\u003e. We give below\na quick R installation guide that will work in most cases.\n\n### GNU/Linux ###\n\nYou should install R from your package manager. On a Debian/Ubuntu system, you will run in the Bash shell:\n```bash\n    sudo apt-get install r-base\n```\n\nOnce R is installed, you can launch R from the Terminal and from the R\nprompt install the irace package. See instructions below.\n\n\n### OS X ###\n\nYou can install R directly from a CRAN mirror (\u003chttps://cran.r-project.org/bin/macosx/\u003e).\n\nAlternatively, if you use homebrew, you can just run from the Terminal (Bash shell):\n```bash\n    brew install --cask r\n```\n\n(Using `brew install r` is not recommended because that will build R from source and you will not be able to use any CRAN binary, possibly resulting in annoying build failures). \n\nOnce R is installed, you can launch R from the Terminal (or from your\nApplications), and from the R prompt install the irace package. See\ninstructions below.\n\n### Windows ###\n\nYou can install R from a CRAN mirror\n(\u003chttps://cran.r-project.org/bin/windows/\u003e). Once R is installed, you can\nlaunch the R console and install the irace package from it. See instructions\nbelow.\n\nIn addition to using the R console, it might be very useful to add R to PATH so you can run R commands in CMD or Powershell. Usually, R is installed in `C:\\Program Files\\R\\R-4.1.3` (the version number depends on your installation).\n\nYou should add the following line [to PATH](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/) (if you want to use the 64-bit version)\n```\nC:\\Program Files\\R\\R-4.1.3\\bin\\x64\n```\n\nOr, if you are on a 32-bit version \n```\nC:\\Program Files\\R\\R-4.1.3\\bin\\i386\n```\n\nInstalling the irace package\n----------------------------\n\nThere are two methods for installing the\n[irace](https://mlopez-ibanez.github.io/irace/) R package on your computer:\n\n1. Install within R (automatic download). Run the following from the R console:\n```R\n        install.packages(\"irace\", repos = \"https://cloud.r-project.org\")\n```\n   and test the installation with:\n```R\n        library(irace)\n        irace_cmdline(\"--version\")\n        q()\n```\n\n2. Manually\n   [download the package from CRAN](https://cran.r-project.org/package=irace)\n   and invoke at the Bash shell, Terminal or Powershell:\n```bash\n        R CMD INSTALL \u003cpackage\u003e\n```\n   where `\u003cpackage\u003e` is one of the three versions available: `.tar.gz`\n   (Unix/BSD/GNU/Linux), `.tgz` (MacOS X), or `.zip` (Windows).\n\n\nIf the package fails to install because of insufficient permissions,\nyou need to force a *local installation* by typing in the Bash shell:\n```bash\n    mkdir ~/R\n    R CMD INSTALL --library=~/R irace.tar.gz\n    export R_LIBS=~/R:${R_LIBS}\n```\n\nOnce installed, test that it is working by typing in the R console (not in the bash shell):\n```R\n    library(irace)\n    irace_cmdline(\"--version\")\n    cat(system.file(package=\"irace\", \"bin\", mustWork=TRUE), \"\\n\")\n```\nThe last command gives you the installation folder of `irace`, for example, `/home/user/R/irace/bin`.\n\n### GNU/Linux and OS X ###\n\nSave the installation directory of `irace` to a variable, and add it to your\n`.bash_profile`, `.bashrc` or `.profile`:\n\n```bash\n    export IRACE_HOME=/home/user/R/irace/bin/ # Path given by system.file(package=\"irace\", \"bin\", mustWork=TRUE)\n    export PATH=${IRACE_HOME}:$PATH\n    # export R_LIBS=~/R:${R_LIBS} # Only if local installation was forced\n```\n\nAfter adding this and opening a new terminal, you should be able to\ninvoke `irace` as follows:\n\n```bash\n    irace --help\n```\n\n\n### Windows ###\n\nYou can find out where the irace binary is installed by running the following in Powershell or CMD:\n\n```Powershell\n    C:\\\u003e Rscript -e \"cat(gsub('/', '\\\\\\\\', system.file(package='irace', 'bin', 'x64', mustWork=TRUE)))\"\n```\n\nIt will output a path, such as `C:\\Program Files\\R\\R-4.1.3\\library\\irace\\bin\\x64` (replace `x64` with `i386` if you are on a 32-bit system), which can you [add to PATH](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). \n\nThen running the following should work:\n```Powershell \n    C:\\\u003e irace --help\n```\n\nYou can also launch irace by opening the R console and executing:\n\n```R\n    library(irace)\n    irace_cmdline(\"--help\")\n```\n\n### GitHub (Development version) ###\n\nIf you wish to try the development version, you can install it by executing the\nfollowing command within the R console:\n\n```R\n    install.packages('irace', repos = c('https://mlopez-ibanez.r-universe.dev', 'https://cloud.r-project.org'))\n```\n\n### Python ###\n\nYou can use the irace R package from Python using `rpy2`. There are actually two different implementations of this idea:  [iracepy](https://github.com/auto-optimization/iracepy) and [iracepy-tiny](https://github.com/Saethox/iracepy-tiny).\n\n### Rust ###\n\nYou can use `irace` from Rust by using [irace-rs](https://github.com/Saethox/irace-rs).\n\nUsage\n-----\n\n1. Create a directory for storing the tuning scenario setup (Bash shell):\n```bash\n        mkdir ./tuning\n        cd ./tuning\n```\n\n2. Initialize your tuning directory with template config files (Bash shell):\n```bash\n        $IRACE_HOME/bin/irace --init\n```\n\n3. Modify the generated files following the instructions found within each file. In particular,\n    * The scripts `target-runner` and `target-evaluator` (if you need it at all)\n      should be executable. The output of `target-runner` (or\n      `target-evaluator` if you use a separate evaluation step) is minimized by\n      default. If you wish to maximize it, just multiply the value by `-1`\n      within the script.\n    * In `scenario.txt`, uncomment and assign only the parameters for which\n      you need a value different than the default one. For example, you may need to set\n      `trainInstancesDir=\"./Instances/\"`.\n   \n    There are examples in `$IRACE_HOME/examples/`.\n\n4. Put the instances in `./tuning/Instances/`. In addition, you can\n   create a file that specifies which instances from that directory\n   should be run and which instance-specific parameters to use. See\n   `scenario.txt` and `instances-list.txt` for examples. The command\n   irace will not attempt to create the execution directory (`execDir`),\n   so it must exist before calling irace. The default `execDir` is the\n   current directory.\n\n5. Calling the command in the Bash shell:\n```bash\n        cd ./tuning/ \u0026\u0026 $IRACE_HOME/bin/irace\n```\n   performs one run of Iterated Race. See the output of `irace --help` for\n   additional irace parameters. Command-line parameters override the\n   scenario setup specified in the `scenario.txt` file.\n\n\n### Many tuning runs in parallel ###\n\nFor executing several repetitions of irace in parallel, call the\nprogram `parallel-irace` from the Bash shell:\n\n```bash\n    cd ./tuning/ \u0026\u0026 $IRACE_HOME/bin/parallel-irace N\n```\n\nwhere N is the number of repetitions. By default, the execution directory of\neach run of irace will be set to `./execdir-dd`, where `dd` is a number padded\nwith zeroes.\n\n**Be careful**, `parallel-irace` will create these directories from\nscratch, deleting them first if they already exist.\n\nCheck the help of `parallel-irace` by running it without parameters.\n\n\n### Parallelize one tuning ###\n\nA single run of irace can be done much faster by executing the calls\nto `targetRunner` (the runs of the algorithm being tuned) in\nparallel. See the [user guide](https://cran.r-project.org/package=irace/vignettes/irace-package.pdf) for the details.\n\nLicense\n-------\n\n**irace** is Copyright (C) 2010-2020 Manuel López-Ibáñez, Jérémie Dubois-Lacoste\nand Leslie Pérez-Cáceres.\n\nThis program is free software (software libre); you can redistribute it and/or\nmodify it under the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2 of the License, or (at your option)\nany later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the [GNU General Public License](https://cran.r-project.org/web/licenses/GPL-3) for more details.\n\n**IMPORTANT NOTE:** Please be aware that the fact that this program is released as\nFree Software does not excuse you from scientific propriety, which obligates\nyou to give appropriate credit! If you write a scientific paper describing\nresearch that made substantive use of this program, it is your obligation as a\nscientist to (a) mention the fashion in which this software was used in the\nMethods section; (b) mention the algorithm in the References section. The\nappropriate citation is:\n\n * Manuel López-Ibáñez, Jérémie Dubois-Lacoste, Leslie Pérez Cáceres, Thomas\n  Stützle, and Mauro Birattari.  [**The irace package: Iterated Racing for\n  Automatic Algorithm\n  Configuration.**](http://dx.doi.org/10.1016/j.orp.2016.09.002) _Operations\n  Research Perspectives_, 2016. doi: 10.1016/j.orp.2016.09.002\n\nThe **irace** package uses code under the GPL from the [race\npackage](https://CRAN.R-project.org/package=race) is Copyright (C) 2003 Mauro\nBirattari.\n\n\nBuilding an irace standalone container\n--------------------------------------\n\nThanks to [Singularity](https://sylabs.io/singularity/), you can build a\nstandalone container of `irace` using the file `irace.sindef` which is\navailable in the directory `inst/` in the source tarball and github repository\nor, after installing the irace R package, in the installation directory given\nby the R expression `system.file(package=\"irace\")`. After installing\nSingularityCE, the container may be build using:\n\n    sudo singularity build irace.sindef irace.sif\n    \nand run with:\n\n    singularity run irace.sif \u003carguments\u003e\n    \n\n\nFrequently Asked Questions\n--------------------------\n\nThe\n[user guide](https://cran.r-project.org/package=irace/vignettes/irace-package.pdf)\ncontains a list of frequently asked questions.\n\n\u003c!--\nLocal Variables:\nmode: markdown\nEnd:\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlopez-ibanez%2Firace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlopez-ibanez%2Firace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlopez-ibanez%2Firace/lists"}