Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Scenario file

A scenario file is a test of a project: overrides, swapped model packages, stop limits, a seed and timed events, given to taktwerk run --scenario <file> and used by every campaign run. Unknown keys are errors. What the events do while a run runs is in Scenario events.

seed = 3

[set]
"ctrl.sp" = [1.0]

[models]
plant = "../packages/plant-v2"

[stop]
time_s = 900.0
when = ["plant.level > 2.5"]

[[event]]
at_s = 300.0
add = "plant.q_dist"
value = 0.2

Top level

keytypemeaning
seedintegerthe run seed, as --seed; --seed wins
settableoverrides, key → TOML value, as --set takes them (Overrides); applied before those of the command line
modelstablemodel id → package or FMU path, relative to this file, as --model; applied before --model
stoptablestop limits and conditions, below
eventarray of tablestimed events, below

[stop]

keytypemeaning
cyclesintegeras --cycles: stop after this many ticks; --cycles wins
time_sfloatas --until-time: stop before the first tick at or after this engine time; --until-time wins
whenlist of stringsas --stop-when; these and the command line’s all apply

[[event]]

Each event has a time, exactly one action and the values that action takes.

keytypemeaning
at_sfloatengine time, seconds: the event applies at the first tick at or after it
cycleintegeror the tick it applies at
actionvaluesdoes
set = "<target>"valuesets a tunable or external input; a number sets every element (or name[i] one), an array the whole signal
add = "<target>"valueadds value: a step
ramp = "<target>"to, over_smoves linearly from the value at the event to to, one step per tick, reaching it over_s seconds later
fault = "<signal>"one fault below, optional for_schanges what the signal’s readers see, for for_s seconds or until cleared or the end of the run
clear = "<signal>"ends the fault on the signal
faultreaders see
hold = truethe value the signal had when the fault started
value = <x>x (nan allowed: a lost reading)
offset = <x>the value plus x: a bias
scale = <x>the value times x: a gain error
noise_sd = <x>the value plus normal noise of standard deviation x
drop = truean external input no longer written: its last value; with an age limit it goes stale like a lost connection

A target is a tunable or an external input, a fault’s signal an output or an external input, whole or one element name[i]. Events are checked against the plan at start: an unknown signal, a target of the wrong kind, a missing or misplaced value fails the run before the first tick. Events of one tick apply in file order, before the models step.

In a run

  • The file’s set applies before --set, its models before --model; --seed, --cycles and --until-time win over the file’s; stop conditions add up.
  • run.json’s invocation keeps the file whole: path, hash and text (run.json).
  • A campaign merges its common scenario, its own [set], [stop] and events, a case’s scenario and the axes’ values into one scenario per run, run.toml (Campaign file).