R: Default scenario settings

defaultScenario {irace} | R Documentation

## Default scenario settings

### Description

Return scenario with default values.

### Usage

    defaultScenario(scenario = list())

### Arguments

`scenario` | (`list()`) Data structure containing irace settings. The data structure has to be the one returned by the function `defaultScenario` or `readScenario`.

### Value

A list indexed by the irace parameter names, containing the default values for each parameter, except for those already present in the scenario passed as argument. The scenario list contains the following elements:

- General options:

  `scenarioFile`

    Path of the file that describes the configuration scenario setup and other irace settings. (Default: `"./scenario.txt"`)

  `execDir`

    Directory where the programs will be run. (Default: `"./"`)

  `logFile`

    File to save tuning results as an R dataset, either absolute path or relative to execDir. (Default: `"./irace.Rdata"`)

  `debugLevel`

    Debug level of the output of `irace`. Set this to 0 to silence all debug messages. Higher values provide more verbose debug messages. (Default: `0`)

  `seed`

    Seed of the random number generator (by default, generate a random seed). (Default: `NA`)

  `repairConfiguration`

    User-defined R function that takes a configuration generated by irace and repairs it. (Default: `""`)

  `postselection`

    Percentage of the configuration budget used to perform a postselection race of the best configurations of each iteration after the execution of irace. (Default: `0`)

  `aclib`

    Enable/disable AClib mode. This option enables compatibility with GenericWrapper4AC as targetRunner script. (Default: `0`)

- Elitist `irace`:

  `elitist`

    Enable/disable elitist irace. (Default: `1`)

  `elitistNewInstances`

    Number of instances added to the execution list before previous instances in elitist irace. (Default: `1`)

  `elitistLimit`

    In elitist irace, maximum number per race of elimination tests that do not eliminate a configuration. Use 0 for no limit. (Default: `2`)

- Internal `irace` options:

  `nbIterations`

    Number of iterations. (Default: `0`)

  `nbExperimentsPerIteration`

    Number of runs of the target algorithm per iteration. (Default: `0`)

  `sampleInstances`

    Randomly sample the training instances or use them in the order given. (Default: `1`)

  `minNbSurvival`

    Minimum number of configurations needed to continue the execution of each race (iteration). (Default: `0`)

  `nbConfigurations`

    Number of configurations to be sampled and evaluated at each iteration. (Default: `0`)

  `mu`

    Parameter used to define the number of configurations sampled and evaluated at each iteration. (Default: `5`)

  `softRestart`

    Enable/disable the soft restart strategy that avoids premature convergence of the probabilistic model. (Default: `1`)

  `softRestartThreshold`

    Soft restart threshold value for numerical parameters. If `NA`, `NULL` or `""`, it is computed as `10^-digits`. (Default: `""`)

- Target algorithm parameters:

  `parameterFile`

    File that contains the description of the parameters of the target algorithm. (Default: `"./parameters.txt"`)

  `forbiddenExps`

    Vector of R logical expressions that cannot evaluate to `TRUE` for any evaluated configuration. (Default: `""`)

  `forbiddenFile`

    File that contains a list of logical expressions that cannot be `TRUE` for any evaluated configuration. If empty or `NULL`, do not use forbidden expressions. (Default: `""`)

  `digits`

    Maximum number of decimal places that are significant for numerical (real) parameters. (Default: `4`)

- Target algorithm execution:

  `targetRunner`

    Script called for each configuration that executes the target algorithm to be tuned. See templates. (Default: `"./target-runner"`)

  `targetRunnerRetries`

    Number of times to retry a call to `targetRunner` if the call failed. (Default: `0`)

  `targetRunnerData`

    Optional data passed to `targetRunner`. This is ignored by the default `targetRunner` function, but it may be used by custom `targetRunner` functions to pass persistent data around. (Default: `""`)

  `targetRunnerParallel`

    Optional R function to provide custom parallelization of `targetRunner`. (Default: `""`)

  `targetEvaluator`

    Optional script or R function that provides a numeric value for each configuration. See templates/target-evaluator.tmpl (Default: `""`)

  `deterministic`

    If the target algorithm is deterministic, configurations will be evaluated only once per instance. (Default: `0`)

  `parallel`

    Number of calls to `targetRunner` to execute in parallel. Values `0` or `1` mean no parallelization. (Default: `0`)

  `loadBalancing`

    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. (Default: `1`)

  `mpi`

    Enable/disable MPI. Use `Rmpi` to execute `targetRunner` in parallel (parameter `parallel` is the number of slaves). (Default: `0`)

  `batchmode`

    Specify how irace waits for jobs to finish when `targetRunner` submits jobs to a batch cluster: sge, pbs, torque or slurm. `targetRunner` must submit jobs to the cluster using, for example, `qsub`. (Default: `0`)

- Initial configurations:

  `initConfigurations`

    Data frame describing initial configurations (usually read from a file using `readConfigurations`). (Default: `""`)

  `configurationsFile`

    File that contains a table of initial configurations. If empty or `NULL`, all initial configurations are randomly generated. (Default: `""`)

- Training instances:

  `instances`

    Character vector of the instances to be used in the `targetRunner`. (Default: `""`)

  `trainInstancesDir`

    Directory where training instances are located; either absolute path or relative to current directory. If no `trainInstancesFiles` is provided, all the files in `trainInstancesDir` will be listed as instances. (Default: `"./Instances"`)

  `trainInstancesFile`

    File that contains a list of training instances and optionally additional parameters for them. If `trainInstancesDir` is provided, `irace` will search for the files in this folder. (Default: `""`)

- Tuning budget:

  `maxExperiments`

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

  `maxTime`

    Maximum total execution time in seconds for the executions of `targetRunner`. `targetRunner` must return two values: cost and time. (Default: `0`)

  `budgetEstimation`

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

- Statistical test:

  `testType`

    Statistical test used for elimination. Default test is always `F-test` unless `capping` is enabled, in which case the default test is `t-test`. Valid values are: F-test (Friedman test), t-test (pairwise t-tests with no correction), t-test-bonferroni (t-test with Bonferroni's correction for multiple comparisons), t-test-holm (t-test with Holm's correction for multiple comparisons). (Default: `"F-test"`)

  `firstTest`

    Number of instances evaluated before the first elimination test. It must be a multiple of `eachTest`. (Default: `5`)

  `eachTest`

    Number of instances evaluated between elimination tests. (Default: `1`)

  `confidence`

    Confidence level for the elimination test. (Default: `0.95`)

- Adaptive capping:

  `capping`

    Enable the use of adaptive capping, a technique designed for minimizing the computation time of configurations. This is only available when `elitist` is active. (Default: `0`)

  `cappingType`

    Measure used to obtain the execution bound from the performance of the elite configurations.

    - median: Median performance of the elite configurations.

    - mean: Mean performance of the elite configurations.

    - best: Best performance of the elite configurations.

    - worst: Worst performance of the elite configurations.

    (Default: `"median"`)

  `boundType`

    Method to calculate the mean performance of elite configurations.

    - candidate: Mean execution times across the executed instances and the current one.

    - instance: Execution time of the current instance.

    (Default: `"candidate"`)

  `boundMax`

    Maximum execution bound for `targetRunner`. It must be specified when capping is enabled. (Default: `0`)

  `boundDigits`

    Precision used for calculating the execution time. It must be specified when capping is enabled. (Default: `0`)

  `boundPar`

    Penalization constant for timed out executions (executions that reach `boundMax` execution time). (Default: `1`)

  `boundAsTimeout`

    Replace the configuration cost of bounded executions with `boundMax`. (Default: `1`)

- Recovery:

  `recoveryFile`

    Previously saved log file to recover the execution of `irace`, either absolute path or relative to the current directory. If empty or `NULL`, recovery is not performed. (Default: `""`)

- Testing:

  `testInstancesDir`

    Directory where testing instances are located, either absolute or relative to current directory. (Default: `""`)

  `testInstancesFile`

    File containing a list of test instances and optionally additional parameters for them. (Default: `""`)

  `testInstances`

    Character vector of the instances to be used in the `targetRunner` when executing the testing. (Default: `""`)

  `testNbElites`

    Number of elite configurations returned by irace that will be tested if test instances are provided. (Default: `1`)

  `testIterationElites`

    Enable/disable testing the elite configurations found at each iteration. (Default: `0`)

### Author(s)

Manuel López-Ibáñez and Jérémie Dubois-Lacoste

### See Also

`readScenario`

  for reading a configuration scenario from a file.

`printScenario`

  prints the given scenario.

`defaultScenario`

  returns the default scenario settings of irace.

`checkScenario`

  to check that the scenario is valid.

[Package irace version 3.4.1 Index]