Python
The taktwerk package on PyPI reads run records and campaigns into Python, and starts runs and
campaigns through the taktwerk command. It never touches a running engine’s cycle: it reads
the files a recorder or a campaign wrote.
pip install 'taktwerk[pandas]' # or: uv add 'taktwerk[pandas]'
The reader needs only the standard library; the extras numpy and pandas add the conversions.
A run
import taktwerk
run = taktwerk.read_run("records/project/main")
read_run takes a run directory (one holding run.json), or a directory with exactly one run
below it; recorder= picks one of several.
| attribute or call | gives |
|---|---|
run["plant.level"] | a column as a list, typed by run.json: float, int, bool or str |
run.cycle, run.t_engine | the rows’ ticks and engine times |
run.columns | the recorded columns in order |
run.array("ctrl.u") | an array recorded element by element, one list per row |
run.events | events.csv as Event(cycle, t_engine, kind, source, detail) |
run.events_of("scenario") | the events of one kind |
run.stop | why the run ended |
run.manifest | run.json as a dict |
run.invocation, run.overrides, run.seed | how it was started |
run.to_numpy() | every column as an array; needs numpy |
run.to_pandas() | a data frame indexed by t_engine, with a cycle column; needs pandas |
A campaign
c = taktwerk.read_campaign("out/gains")
frame = c.to_pandas() # one row per run
for r in c:
if r.ok:
level = r.read()["plant.level"]
read_campaign takes a campaign’s output directory. Each CampaignRun has its
name, case, grid, sample, replicate, seed, values (what its axes set), and from
its status.json, when that matches the planned spec, status, stop, cycles and wall_s;
r.read() loads its records. c.table() gives the rows as dicts, c.to_pandas() as a data
frame indexed by run name with one column per value key.
Starting runs
run = taktwerk.run(
"project.toml",
until_time=600.0,
set={"ctrl.sp": [1.0], "ctrl.kp": 2.0},
scenario="disturbance.toml",
seed=1,
)
print(taktwerk.plan("gains.toml")) # the plan, nothing run
c = taktwerk.campaign("gains.toml") # taktwerk campaign --write, resuming; then loaded
run calls taktwerk run unpaced and without connectors (speed= and connectors= change
that), with the options of Simulation runs as keyword arguments: cycles,
until_time, stop_when, set, models, scenario, seed, record_dir. Values in set
are passed as TOML literals. Records go to record_dir, else a new temporary directory; the
new run is loaded and returned. A failed run raises with the end of its log. The command is
$TAKTWERK, else taktwerk on PATH.