Campaign studies

A study runs one project many times: other gains, other plants, other noise, the same disturbance. A campaign file plans the runs; taktwerk campaign --write runs them, one process each, and resumes where it stopped.

taktwerk campaign study.toml            # the plan: every run with its values and seed
taktwerk campaign study.toml --write    # run what is not done

project = "sim.toml"
scenario = "disturbance.toml"
jobs = 4

[stop]
time_s = 7200.0

[[case]]
name = "nominal"
[[case]]
name = "fouled"
set = { "plant.ua" = 0.7 }

[grid]
"ctrl.kp" = [0.5, 1.0, 2.0]

[sample]
n = 20
"plant.tau" = { log_uniform = [50.0, 200.0] }

• Axes: named cases, a grid (every combination) and random samples (Latin hypercube by default), times replicates. Every key of the campaign file is an override as --set takes it.
• Common random numbers: run seeds derive from the campaign seed, the sample and the replicate, not the case or grid point, so compared variants see the same noise.
• Reproducible: every run’s effective scenario is its run.toml; taktwerk run --scenario run.toml reruns it alone. Each run’s record holds every override it got.
• Resume: a run is done when its status.json says ok and its spec hash (taktwerk version, project, packages, scenario) is the planned one; a rebuilt package runs again what uses it.
• Analysis: runs.csv and campaign.json list the runs; in Python taktwerk.read_campaign(out).to_pandas() is one row per run and r.read() a run’s record.

Walked through in the campaign tutorial; the details are in Campaigns. For larger studies the runs are independent processes without connectors, so a campaign’s output directory moves between machines as it is.