Campaign file
A campaign file plans a set of runs of one project for taktwerk campaign. Unknown keys are
errors; paths are relative to the campaign file. How the runs are formed, seeded, run and
resumed is in Campaigns.
Top level
| key | type | default | meaning |
|---|---|---|---|
project | string | required | the project file every run runs |
out | string | the file’s stem, beside it | the output directory |
jobs | integer | 1 | runs at a time, ≥ 1; --jobs overrides |
speed | string | "max" | --speed of every run: "max" or a factor |
seed | integer | 0 | the campaign’s seed; every run’s seed derives from it |
scenario | string | none | a scenario file every run starts from |
set | table | {} | overrides of every run, as a scenario’s [set] |
stop | table | {} | stops of every run, as a scenario’s [stop] |
event | array of tables | [] | events of every run, as a scenario’s [[event]] |
case | array of tables | [] | the list axis, below |
grid | table | {} | the grid axis: key → list of values; every combination |
sample | table | none | the random axis, below |
replicates | integer | 1 | repeats of every run with another seed, ≥ 1 |
Every run needs a stop limit, cycles or time_s, from the campaign, its scenario or its
case’s.
[[case]]
| key | type | meaning |
|---|---|---|
name | string | required, unique; ASCII letters, digits, - and _ |
scenario | string | a scenario file merged over the common one |
set | table | overrides of this case |
[grid]
Each key is an override key (as --set takes it) with a non-empty list of values. A grid key
seed sets the run seed instead.
[sample]
| key | type | default | meaning |
|---|---|---|---|
n | integer | required | draws, ≥ 1 |
method | string | "lhs" | "lhs" (Latin hypercube) or "uniform" (independent draws) |
| any other key | table | an override key and its distribution, below; at least one |
| distribution | parameters |
|---|---|
{ uniform = [a, b] } | finite a ≤ b |
{ log_uniform = [a, b] } | 0 < a ≤ b; exp of uniform on [ln a, ln b] |
{ normal = [mean, sd] } | finite mean, sd ≥ 0 |
{ choice = [v1, v2, …] } | at least one value, each equally likely |
A sample key seed sets the run seed instead.
Merge order
Per run: the common scenario, then the campaign’s set, stop and events, then the case’s
scenario and set, then the grid point’s and the sample’s values. Later values win; stop
conditions and events add up. The result is the run’s run.toml, a scenario file that
taktwerk run --scenario reruns alone.