mlr_optimizers_irace: Iterated Racing

In bbotk: Black-Box Optimization Toolkit

Iterated Racing

Description

OptimizerBatchIrace class that implements iterated racing. Calls irace::irace() from package irace.

Parameters

instances

list()
A list of instances where the configurations executed on.

targetRunnerParallel

⁠function()⁠
A function that executes the objective function with a specific parameter configuration and instance. A default function is provided, see section "Target Runner and Instances".

For the meaning of all other parameters, see irace::defaultScenario().

Internal Termination Parameters

The algorithm can terminated with TerminatorEvals. Other Terminators do not work with OptimizerBatchIrace. Additionally, the following internal termination parameters can be used:

maxExperiments

integer(1)
Maximum number of runs (invocations of targetRunner) that will be performed. It determines the maximum budget of experiments for the tuning. Default is 0.

minExperiments

integer(1)
Minimum number of runs (invocations of targetRunner) that will be performed. It determines the minimum budget of experiments for the tuning. The actual budget depends on the number of parameters and minSurvival. Default is NA.

maxTime

integer(1)
Maximum total execution time for the executions of targetRunner. targetRunner must return two values: cost and time. This value and the one returned by targetRunner must use the same units (seconds, minutes, iterations, evaluations, ...). Default is 0.

budgetEstimation

numeric(1)
Fraction (smaller than 1) of the budget used to estimate the mean computation time of a configuration. Only used when maxTime > 0 Default is 0.05.

minMeasurableTime

numeric(1)
Minimum time unit that is still (significantly) measureable. Default is 0.01.

Initial parameter values

• digits:

  • Adjusted default: 15.

  • This represents double parameters with a higher precision and avoids rounding errors.

Target Runner and Instances

The irace package uses a targetRunner script or R function to evaluate a configuration on a particular instance. Usually it is not necessary to specify a targetRunner function when using OptimizerBatchIrace. A default function is used that forwards several configurations and instances to the user defined objective function. As usually, the user defined function has a xs, xss or xdt parameter depending on the used Objective class. For irace, the function needs an additional instances parameter.

fun = function(xs, instances) {
 # function to evaluate configuration in `xs` on instance `instances`
}

Archive

The Archive holds the following additional columns:

• "race" (integer(1))
  Race iteration.

• "step" (integer(1))
  Step number of race.

• "instance" (integer(1))
  Identifies instances across races and steps.

• "configuration" (integer(1))
  Identifies configurations across races and steps.

Result

The optimization result (instance$result) is the best performing elite of the final race. The reported performance is the average performance estimated on all used instances.

Dictionary

This Optimizer can be instantiated via the dictionary mlr_optimizers or with the associated sugar function opt():

mlr_optimizers$get("irace")
opt("irace")

Progress Bars

⁠$optimize()⁠ supports progress bars via the package progressr combined with a Terminator. Simply wrap the function in progressr::with_progress() to enable them. We recommend to use package progress as backend; enable with progressr::handlers("progress").

Super classes

bbotk::Optimizer -> bbotk::OptimizerBatch -> OptimizerBatchIrace

Methods

Public methods

• OptimizerBatchIrace$new()

• OptimizerBatchIrace$clone()

Inherited methods

• bbotk::Optimizer$format()
• bbotk::Optimizer$help()
• bbotk::Optimizer$print()
• bbotk::OptimizerBatch$optimize()

---

Method new()

Creates a new instance of this R6 class.

Usage

OptimizerBatchIrace$new()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

OptimizerBatchIrace$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Source

Lopez-Ibanez M, Dubois-Lacoste J, Caceres LP, Birattari M, Stuetzle T (2016). “The irace package: Iterated racing for automatic algorithm configuration.” Operations Research Perspectives, 3, 43–58. \Sexpr[results=rd]{tools:::Rd_expr_doi("https://doi.org/10.1016/j.orp.2016.09.002")}.

Examples

# example only runs if irace is available
if (mlr3misc::require_namespaces("irace", quietly = TRUE)) {
# runtime of the example is too long

library(data.table)

# set domain
domain = ps(
  x1 = p_dbl(-5, 10),
  x2 = p_dbl(0, 15)
)

# set codomain
codomain = ps(y = p_dbl(tags = "minimize"))

# branin function with noise
# the noise generates different instances of the branin function
# the noise values are passed via the `instances` parameter
fun = function(xdt, instances) {
  ys = branin(xdt[["x1"]], xdt[["x2"]], noise = as.numeric(instances))
  data.table(y = ys)
}

# define objective with instances as a constant
objective = ObjectiveRFunDt$new(
 fun = fun,
 domain = domain,
 codomain = codomain,
 constants = ps(instances = p_uty()))

instance = oi(
  objective = objective,
  terminator = trm("evals", n_evals = 96))

# create instances of branin function
instances = rnorm(10, mean = 0, sd = 0.1)

# load optimizer and set branin instances
optimizer = opt("irace", instances = instances)

# trigger optimization
optimizer$optimize(instance)

# all evaluated configurations
instance$archive

# best performing configuration
instance$result

}

bbotk documentation built on Nov. 5, 2025, 6:23 p.m.