taktwerk 0.6.0__tar.gz

taktwerk-0.6.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: taktwerk
+Version: 0.6.0
+Summary: Read taktwerk run records and campaigns into arrays and data frames, and start runs
+Keywords: simulation,co-simulation,fixed-step,records,campaign
+License-Expression: MIT OR Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: numpy>=2.2.6 ; extra == 'numpy'
+Requires-Dist: pandas>=2.3.3 ; extra == 'pandas'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://labinetix.github.io/taktwerk/
+Project-URL: Documentation, https://labinetix.github.io/taktwerk/python.html
+Provides-Extra: numpy
+Provides-Extra: pandas
+Description-Content-Type: text/markdown
+
+# taktwerk for Python
+
+Read the records of [taktwerk](https://labinetix.github.io/taktwerk/) runs and campaigns into
+lists, numpy arrays or pandas data frames, and start runs and campaigns through the `taktwerk`
+command. Offline only: nothing here touches a running engine's cycle.
+
+```sh
+pip install 'taktwerk[pandas]'      # or: uv add 'taktwerk[pandas]'
+```
+
+```python
+import taktwerk
+
+run = taktwerk.read_run("records/project/main")  # a run directory, or one run below it
+run["plant.level"], run.t_engine, run.stop, run.overrides
+run.to_pandas()  # indexed by engine time
+
+c = taktwerk.read_campaign("out/gains")  # a campaign's output directory
+c.to_pandas()  # one row per run: axes, values, status
+c.read("nominal-g03").to_pandas()
+
+taktwerk.run("project.toml", until_time=600, set={"ctrl.kp": 2.0}, seed=1)
+taktwerk.campaign("gains.toml")  # taktwerk campaign --write, then loaded
+```
+
+The reader needs only the standard library; `taktwerk[numpy]` and `taktwerk[pandas]` add the
+conversions. Starting runs needs the `taktwerk` command on `PATH` or in `$TAKTWERK`. Guide:
+[Python](https://labinetix.github.io/taktwerk/python.html).

taktwerk-0.6.0/README.md

@@ -0,0 +1,28 @@
+# taktwerk for Python
+
+Read the records of [taktwerk](https://labinetix.github.io/taktwerk/) runs and campaigns into
+lists, numpy arrays or pandas data frames, and start runs and campaigns through the `taktwerk`
+command. Offline only: nothing here touches a running engine's cycle.
+
+```sh
+pip install 'taktwerk[pandas]'      # or: uv add 'taktwerk[pandas]'
+```
+
+```python
+import taktwerk
+
+run = taktwerk.read_run("records/project/main")  # a run directory, or one run below it
+run["plant.level"], run.t_engine, run.stop, run.overrides
+run.to_pandas()  # indexed by engine time
+
+c = taktwerk.read_campaign("out/gains")  # a campaign's output directory
+c.to_pandas()  # one row per run: axes, values, status
+c.read("nominal-g03").to_pandas()
+
+taktwerk.run("project.toml", until_time=600, set={"ctrl.kp": 2.0}, seed=1)
+taktwerk.campaign("gains.toml")  # taktwerk campaign --write, then loaded
+```
+
+The reader needs only the standard library; `taktwerk[numpy]` and `taktwerk[pandas]` add the
+conversions. Starting runs needs the `taktwerk` command on `PATH` or in `$TAKTWERK`. Guide:
+[Python](https://labinetix.github.io/taktwerk/python.html).

taktwerk-0.6.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "taktwerk"
+version = "0.6.0"
+description = "Read taktwerk run records and campaigns into arrays and data frames, and start runs"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "simulation",
+    "co-simulation",
+    "fixed-step",
+    "records",
+    "campaign",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://labinetix.github.io/taktwerk/"
+Documentation = "https://labinetix.github.io/taktwerk/python.html"
+
+[project.optional-dependencies]
+numpy = ["numpy>=2.2.6"]
+pandas = ["pandas>=2.3.3"]
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.17.1",
+]

taktwerk-0.6.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "taktwerk"
+version = "0.6.0"
+description = "Read taktwerk run records and campaigns into arrays and data frames, and start runs"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["simulation", "co-simulation", "fixed-step", "records", "campaign"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://labinetix.github.io/taktwerk/"
+Documentation = "https://labinetix.github.io/taktwerk/python.html"
+
+[project.optional-dependencies]
+numpy = [
+    "numpy>=2.2.6",
+]
+pandas = [
+    "pandas>=2.3.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.17.1",
+]

taktwerk-0.6.0/src/taktwerk/__init__.py

@@ -0,0 +1,33 @@
+"""Read taktwerk run records and campaigns into arrays and data frames, and start runs.
+
+```python
+import taktwerk
+
+run = taktwerk.read_run("records/project/main")       # one run directory, or one below
+run["plant.y"], run.t_engine, run.events, run.overrides
+
+c = taktwerk.read_campaign("out/gains")               # a campaign's output
+c.to_pandas()                                          # one row per run, needs pandas
+c.read("nominal-g03").to_pandas()
+
+taktwerk.run("project.toml", until_time=600, set={"ctrl.kp": 2.0}, seed=1)
+taktwerk.campaign("gains.toml")                        # taktwerk campaign --write
+```
+"""
+
+from .campaign import Campaign, CampaignRun, read_campaign
+from .cli import campaign, plan, run
+from .records import Event, Run, find_runs, read_run
+
+__all__ = [
+    "Campaign",
+    "CampaignRun",
+    "Event",
+    "Run",
+    "campaign",
+    "find_runs",
+    "plan",
+    "read_campaign",
+    "read_run",
+    "run",
+]

taktwerk-0.6.0/src/taktwerk/campaign.py

@@ -0,0 +1,128 @@
+"""Read a campaign's output: campaign.json, each run's status.json, and its runs' records."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .records import Run, read_run
+
+
+@dataclass
+class CampaignRun:
+    """One planned run of a campaign and how it went."""
+
+    name: str
+    path: Path
+    seed: int
+    values: dict[str, Any]
+    case: str | None = None
+    grid: int | None = None
+    sample: int | None = None
+    replicate: int | None = None
+    spec_hash: str = ""
+    status: str = "pending"
+    stop: str | None = None
+    cycles: int | None = None
+    wall_s: float | None = None
+
+    @property
+    def ok(self) -> bool:
+        """Whether it ran to a limit or condition with the planned spec."""
+        return self.status == "ok"
+
+    def read(self, recorder: str | None = None) -> Run:
+        """Its records."""
+        return read_run(self.path, recorder)
+
+
+@dataclass
+class Campaign:
+    """A campaign's plan and the state of its runs."""
+
+    path: Path
+    manifest: dict[str, Any]
+    runs: list[CampaignRun]
+
+    def __len__(self) -> int:
+        return len(self.runs)
+
+    def __iter__(self) -> Iterator[CampaignRun]:
+        return iter(self.runs)
+
+    def __getitem__(self, name: str) -> CampaignRun:
+        for r in self.runs:
+            if r.name == name:
+                return r
+        raise KeyError(name)
+
+    @property
+    def keys(self) -> list[str]:
+        """Every key some run's axes set, in order of first appearance."""
+        keys: list[str] = []
+        for r in self.runs:
+            keys.extend(k for k in r.values if k not in keys)
+        return keys
+
+    def table(self) -> list[dict[str, Any]]:
+        """One row per run: name, axes, seed, status, stop, cycles, wall time, and the values."""
+        rows = []
+        for r in self.runs:
+            row: dict[str, Any] = {
+                "name": r.name,
+                "case": r.case,
+                "grid": r.grid,
+                "sample": r.sample,
+                "replicate": r.replicate,
+                "seed": r.seed,
+                "status": r.status,
+                "stop": r.stop,
+                "cycles": r.cycles,
+                "wall_s": r.wall_s,
+            }
+            for k in self.keys:
+                row[k] = r.values.get(k)
+            rows.append(row)
+        return rows
+
+    def to_pandas(self):
+        """`table()` as a DataFrame indexed by run name. Needs pandas."""
+        import pandas as pd
+
+        return pd.DataFrame(self.table()).set_index("name")
+
+    def read(self, name: str, recorder: str | None = None) -> Run:
+        """The records of run `name`."""
+        return self[name].read(recorder)
+
+
+def read_campaign(path: Path | str) -> Campaign:
+    """Load the campaign whose output directory is `path` (it holds campaign.json)."""
+    path = Path(path)
+    manifest = json.loads((path / "campaign.json").read_text())
+    runs = []
+    for e in manifest["runs"]:
+        run = CampaignRun(
+            name=e["name"],
+            path=path / "runs" / e["name"],
+            seed=e["seed"],
+            values=e.get("values", {}),
+            case=e.get("case"),
+            grid=e.get("grid"),
+            sample=e.get("sample"),
+            replicate=e.get("replicate"),
+            spec_hash=e["spec_hash"],
+        )
+        status_file = run.path / "status.json"
+        if status_file.is_file():
+            status = json.loads(status_file.read_text())
+            if status.get("spec_hash") == run.spec_hash:
+                run.status = status["status"]
+                run.stop = status.get("stop")
+                run.cycles = status.get("cycles")
+                run.wall_s = status.get("wall_s")
+        runs.append(run)
+    return Campaign(path=path, manifest=manifest, runs=runs)

taktwerk-0.6.0/src/taktwerk/cli.py

@@ -0,0 +1,142 @@
+"""Start runs and campaigns through the taktwerk command: a thin wrapper, nothing in-process."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+from .campaign import Campaign, read_campaign
+from .records import Run, find_runs, read_run
+
+
+def binary(path: str | None = None) -> str:
+    """The taktwerk command: `path`, else `$TAKTWERK`, else `taktwerk` on PATH."""
+    found = path or os.environ.get("TAKTWERK") or shutil.which("taktwerk")
+    if not found:
+        raise FileNotFoundError(
+            "no taktwerk command: install it, or set TAKTWERK to its path"
+        )
+    return found
+
+
+def toml_value(value: Any) -> str:
+    """`value` as a TOML literal for `--set`."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "nan"
+        if math.isinf(value):
+            return "inf" if value > 0 else "-inf"
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, Iterable):
+        return "[" + ", ".join(toml_value(v) for v in value) + "]"
+    raise TypeError(f"cannot pass {value!r} as a TOML value")
+
+
+def _execute(argv: list[str]) -> subprocess.CompletedProcess:
+    done = subprocess.run(argv, capture_output=True, text=True, check=False)
+    if done.returncode != 0:
+        tail = "\n".join(done.stderr.splitlines()[-20:])
+        raise RuntimeError(f"{' '.join(argv[:2])} failed ({done.returncode}):\n{tail}")
+    return done
+
+
+def run(
+    project: Path | str,
+    *,
+    speed: str | float = "max",
+    cycles: int | None = None,
+    until_time: float | None = None,
+    stop_when: Iterable[str] = (),
+    set: Mapping[str, Any] | None = None,
+    models: Mapping[str, Path | str] | None = None,
+    scenario: Path | str | None = None,
+    seed: int | None = None,
+    record_dir: Path | str | None = None,
+    connectors: bool = False,
+    command: str | None = None,
+) -> Run | None:
+    """Run `project` with `taktwerk run` and load its record: unpaced and without connectors
+    by default. Records go to `record_dir`, else a new temporary directory. Returns `None` when
+    the project has no file recorder."""
+    record_dir = (
+        Path(record_dir)
+        if record_dir
+        else Path(tempfile.mkdtemp(prefix="taktwerk-run-"))
+    )
+    argv = [
+        binary(command),
+        "run",
+        str(project),
+        "--speed",
+        str(speed),
+        "--record-dir",
+        str(record_dir),
+    ]
+    if not connectors:
+        argv.append("--no-connectors")
+    if cycles is not None:
+        argv += ["--cycles", str(cycles)]
+    if until_time is not None:
+        argv += ["--until-time", repr(float(until_time))]
+    for condition in stop_when:
+        argv += ["--stop-when", condition]
+    for key, value in (set or {}).items():
+        argv += ["--set", f"{key}={toml_value(value)}"]
+    for model, path in (models or {}).items():
+        argv += ["--model", f"{model}={path}"]
+    if scenario is not None:
+        argv += ["--scenario", str(scenario)]
+    if seed is not None:
+        argv += ["--seed", str(seed)]
+    before = frozenset(find_runs(record_dir))
+    _execute(argv)
+    new = [r for r in find_runs(record_dir) if r not in before]
+    if not new:
+        return None
+    return read_run(new[-1])
+
+
+def plan(file: Path | str, *, command: str | None = None) -> str:
+    """The plan of the campaign `file`, as `taktwerk campaign` prints it; nothing is run."""
+    return _execute([binary(command), "campaign", str(file)]).stdout
+
+
+def campaign(
+    file: Path | str,
+    *,
+    force: bool = False,
+    jobs: int | None = None,
+    command: str | None = None,
+) -> Campaign:
+    """Run the campaign `file` with `taktwerk campaign --write`, resuming where it stopped, and
+    load its output. Raises when a run is not ok."""
+    argv = [binary(command), "campaign", str(file), "--write"]
+    if force:
+        argv.append("--force")
+    if jobs is not None:
+        argv += ["--jobs", str(jobs)]
+    done = _execute(argv)
+    out = next(
+        (
+            line.split(None, 1)[1]
+            for line in done.stdout.splitlines()
+            if line.startswith("out ")
+        ),
+        None,
+    )
+    if out is None:
+        raise RuntimeError("taktwerk campaign printed no output directory")
+    return read_campaign(out.strip())

taktwerk-0.6.0/src/taktwerk/records.py

@@ -0,0 +1,187 @@
+"""Read one recorded run: run.json, the gzipped CSV parts and events.csv.
+
+Only the standard library is needed; numpy and pandas are imported when a conversion asks for
+them.
+"""
+
+from __future__ import annotations
+
+import csv
+import gzip
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, NamedTuple
+
+INT_TYPES = {"i64", "i32", "i16", "i8", "u64", "u32", "u16", "u8"}
+
+# Column type of run.json -> numpy dtype.
+NUMPY_TYPES = {
+    "f64": "float64",
+    "f32": "float32",
+    "i64": "int64",
+    "i32": "int32",
+    "i16": "int16",
+    "i8": "int8",
+    "u64": "uint64",
+    "u32": "uint32",
+    "u16": "uint16",
+    "u8": "uint8",
+    "bool": "bool",
+    "text": "object",
+}
+
+
+class Event(NamedTuple):
+    """One line of events.csv."""
+
+    cycle: int
+    t_engine: float
+    kind: str
+    source: str
+    detail: str
+
+
+def _converter(type_name: str):
+    """The function that turns a CSV field of a column of `type_name` into a Python value."""
+    if type_name in ("f64", "f32"):
+        return float
+    if type_name in INT_TYPES:
+        return int
+    if type_name == "bool":
+        return lambda s: s == "1"
+    return str
+
+
+@dataclass
+class Run:
+    """A recorded run: its manifest, its rows column by column, and its events."""
+
+    path: Path
+    manifest: dict[str, Any]
+    cycle: list[int] = field(default_factory=list)
+    t_engine: list[float] = field(default_factory=list)
+    data: dict[str, list[Any]] = field(default_factory=dict)
+    events: list[Event] = field(default_factory=list)
+
+    @property
+    def columns(self) -> list[str]:
+        """The recorded columns, in row order, without cycle and t_engine."""
+        return [c["name"] for c in self.manifest["columns"]]
+
+    @property
+    def invocation(self) -> dict[str, Any]:
+        """How the run was started: speed, stops, overrides, seeds, scenario; empty if unknown."""
+        return self.manifest.get("invocation") or {}
+
+    @property
+    def overrides(self) -> dict[str, Any]:
+        """Every override applied, key to value, in order."""
+        return {o["key"]: o["value"] for o in self.invocation.get("overrides", [])}
+
+    @property
+    def seed(self) -> int | None:
+        """The run seed, if it had one."""
+        return self.invocation.get("seed")
+
+    @property
+    def stop(self) -> str | None:
+        """Why the run ended, as its stop event says."""
+        stops = [e.detail for e in self.events if e.kind == "stop"]
+        return stops[-1] if stops else None
+
+    def __len__(self) -> int:
+        return len(self.cycle)
+
+    def __getitem__(self, name: str) -> list[Any]:
+        """A column by name: `plant.y`, `ctrl.u[0]`, or `cycle` and `t_engine`."""
+        if name == "cycle":
+            return self.cycle
+        if name == "t_engine":
+            return self.t_engine
+        return self.data[name]
+
+    def array(self, name: str) -> list[list[Any]]:
+        """An array signal recorded element by element: one list of its elements per row."""
+        cols = [c for c in self.columns if c.startswith(name + "[")]
+        if not cols:
+            raise KeyError(f"no columns of the array {name!r}")
+        return [list(row) for row in zip(*(self.data[c] for c in cols))]
+
+    def events_of(self, kind: str) -> list[Event]:
+        """The events of one kind: start, stop, tunable, scenario, stale, ..."""
+        return [e for e in self.events if e.kind == kind]
+
+    def to_numpy(self) -> dict[str, Any]:
+        """Every column as a numpy array, cycle and t_engine included. Needs numpy."""
+        import numpy as np
+
+        out = {"cycle": np.asarray(self.cycle, dtype="uint64")}
+        out["t_engine"] = np.asarray(self.t_engine, dtype="float64")
+        for c in self.manifest["columns"]:
+            values = self.data[c["name"]]
+            out[c["name"]] = np.asarray(
+                values, dtype=NUMPY_TYPES.get(c["type"], "float64")
+            )
+        return out
+
+    def to_pandas(self):
+        """The rows as a DataFrame indexed by t_engine, with a cycle column. Needs pandas."""
+        import pandas as pd
+
+        frame = pd.DataFrame(self.to_numpy())
+        return frame.set_index("t_engine")
+
+
+def find_runs(path: Path | str) -> list[Path]:
+    """Every run directory (one holding run.json) at or below `path`, sorted."""
+    path = Path(path)
+    if (path / "run.json").is_file():
+        return [path]
+    return sorted(p.parent for p in path.rglob("run.json"))
+
+
+def read_run(path: Path | str, recorder: str | None = None) -> Run:
+    """Load the run at `path`: a run directory, or a directory with exactly one run below it
+    (of `recorder`, when given)."""
+    runs = find_runs(path)
+    if recorder is not None:
+        runs = [
+            r
+            for r in runs
+            if json.loads((r / "run.json").read_text())["recorder"] == recorder
+        ]
+    if len(runs) != 1:
+        found = ", ".join(str(r) for r in runs) or "none"
+        raise ValueError(f"{path}: expected one run, found {len(runs)}: {found}")
+    run_dir = runs[0]
+    manifest = json.loads((run_dir / "run.json").read_text())
+    run = Run(path=run_dir, manifest=manifest)
+    columns = manifest["columns"]
+    convert = [_converter(c["type"]) for c in columns]
+    names = [c["name"] for c in columns]
+    for n in names:
+        run.data[n] = []
+    for part in sorted(run_dir.glob("part-*.csv.gz")):
+        with gzip.open(part, "rt", newline="") as f:
+            reader = csv.reader(f)
+            header = next(reader, None)
+            if header is None:
+                continue
+            if header[2:] != names:
+                raise ValueError(f"{part}: header does not match run.json's columns")
+            for row in reader:
+                run.cycle.append(int(row[0]))
+                run.t_engine.append(float(row[1]))
+                for n, conv, value in zip(names, convert, row[2:]):
+                    run.data[n].append(conv(value))
+    events = run_dir / "events.csv"
+    if events.is_file():
+        with events.open(newline="") as f:
+            reader = csv.reader(f)
+            next(reader, None)
+            for row in reader:
+                run.events.append(
+                    Event(int(row[0]), float(row[1]), row[2], row[3], row[4])
+                )
+    return run