k4bench 0.0.13__tar.gz

k4bench-0.0.13/.codespellrc

@@ -0,0 +1,7 @@
+[codespell]
+builtin = clear,rare,en-GB_to_en-US,names,informal,code
+check-filenames =
+check-hidden =
+skip = */.git,*/build,*/prefix,*tests/data,*/.vscode,*/playground,*/py-venv,CODE_OF_CONDUCT.md
+quiet-level = 2
+ignore-words-list = jupyter

k4bench-0.0.13/.devcontainer/devcontainer.json

@@ -0,0 +1,37 @@
+// Devcontainer for local development
+// See https://github.com/key4hep/key4hep-images/ for available images
+// Requires the host have
+// a) CernVM-FS installed (see https://cvmfs.readthedocs.io/en/stable/cpt-quickstart.html for instructions)
+// b) The necessary repositories mounted on the host machine; sudo mount -t cvmfs sw.hsf.org /cvmfs/sw.hsf.org
+{
+  "name": "Key4HEP Dev",
+  "image": "ghcr.io/key4hep/key4hep-images/alma9-cvmfs:latest",
+
+  // Make sure CVMFS is mounted on the host (and bind-mounted):
+  "mounts": [
+    "source=/cvmfs,target=/cvmfs,type=bind"
+  ],
+
+  // "postCreateCommand" runs once after the container is created.
+  // Here, we append the source line to ~/.bashrc so new terminals pick it up.
+  "postCreateCommand": [
+    "bash",
+    "-c",
+    "echo 'source setup.sh' >> ~/.bashrc"
+  ],
+  // Install and activate vs code extensions for environment
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-toolsai.jupyter",
+        "ms-vscode.cpptools",
+        "llvm-vs-code-extensions.vscode-clangd",
+        "ms-vscode.cmake-tools",
+        "ibm.output-colorizer",
+        "charliermarsh.ruff",
+        "eamodio.gitlens"
+      ]
+    }
+  }
+}

k4bench-0.0.13/.github/actionlint.yaml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - fcc-ironic

k4bench-0.0.13/.github/benchmarks/ALLEGRO_o1_v02.yml

@@ -0,0 +1,48 @@
+# k4Bench nightly benchmark config — ALLEGRO o1 v02
+#
+# The nightly workflow expands every file in .github/benchmarks/ into a matrix
+# of (detector × sample) jobs and uploads each result to EOS under:
+#   {detector}/{platform}/key4hep-{release}/{sample}/{date}/
+# To add a new detector, drop a new <detector>.yml file in this directory.
+# To add a new sample, append an entry to samples: below.
+#
+# ── Top-level keys (apply to every sample in this file) ────────────────────
+#   xml           required   detector geometry, $K4GEO-relative or absolute path
+#   verbose       optional   stream ddsim output to stdout      (default: false)
+#   sweep         optional   baseline + one run per subdetector dropped
+#   include_only  optional   keep only these subdetectors       (list, single run)
+#   exclude_only  optional   drop these subdetectors            (list, single run)
+#   ddsim_args    optional   ddsim flags applied to every sample
+#   steering_file optional   ddsim --steeringFile path; $VAR refs (e.g. $FCCCONFIG)
+#                            are expanded inside the runner. Steering files for FCC
+#                            detectors live in https://github.com/HEP-FCC/FCC-config
+#                            and are installed under $FCCCONFIG by Key4hep, e.g.
+#                            $FCCCONFIG/FullSim/IDEA/IDEA_o1_v03/SteeringFile_IDEA_o1_v03.py
+#   samples       required   list of sample entries — see below
+#
+# ── Per-sample keys (under samples:) ───────────────────────────────────────
+#   name          required   slug — becomes the EOS sample directory + job label
+#   n_events      required   positive integer
+#   ddsim_args    optional   appended to top-level ddsim_args (not replaced)
+#   input_files   optional   HepMC path(s); mutually exclusive with --enableGun
+#   steering_file optional   overrides the top-level steering_file for this sample
+#
+# Sample-level keys override top-level, except ddsim_args (which concatenates).
+# sweep / include_only / exclude_only are mutually exclusive.
+
+xml: FCCee/ALLEGRO/compact/ALLEGRO_o1_v02/ALLEGRO_o1_v02.xml
+verbose: false
+sweep: true
+
+samples:
+  - name: single_e-_10GeV
+    n_events: 500
+    ddsim_args: >-
+      --enableGun
+      --gun.particle e-
+      --gun.distribution uniform
+      --gun.energy 10*GeV
+
+  - name: p8_ee_Zbb_ecm91
+    n_events: 100
+    input_files: root://eospublic.cern.ch//eos/experiment/fcc/ee/generation/hepmc/p8_ee_Zbb_ecm91/events_noVtxSmear.hepmc

k4bench-0.0.13/.github/benchmarks/ALLEGRO_o1_v03.yml

@@ -0,0 +1,48 @@
+# k4Bench nightly benchmark config — ALLEGRO o1 v03
+#
+# The nightly workflow expands every file in .github/benchmarks/ into a matrix
+# of (detector × sample) jobs and uploads each result to EOS under:
+#   {detector}/{platform}/key4hep-{release}/{sample}/{date}/
+# To add a new detector, drop a new <detector>.yml file in this directory.
+# To add a new sample, append an entry to samples: below.
+#
+# ── Top-level keys (apply to every sample in this file) ────────────────────
+#   xml           required   detector geometry, $K4GEO-relative or absolute path
+#   verbose       optional   stream ddsim output to stdout      (default: false)
+#   sweep         optional   baseline + one run per subdetector dropped
+#   include_only  optional   keep only these subdetectors       (list, single run)
+#   exclude_only  optional   drop these subdetectors            (list, single run)
+#   ddsim_args    optional   ddsim flags applied to every sample
+#   steering_file optional   ddsim --steeringFile path; $VAR refs (e.g. $FCCCONFIG)
+#                            are expanded inside the runner. Steering files for FCC
+#                            detectors live in https://github.com/HEP-FCC/FCC-config
+#                            and are installed under $FCCCONFIG by Key4hep, e.g.
+#                            $FCCCONFIG/FullSim/IDEA/IDEA_o1_v03/SteeringFile_IDEA_o1_v03.py
+#   samples       required   list of sample entries — see below
+#
+# ── Per-sample keys (under samples:) ───────────────────────────────────────
+#   name          required   slug — becomes the EOS sample directory + job label
+#   n_events      required   positive integer
+#   ddsim_args    optional   appended to top-level ddsim_args (not replaced)
+#   input_files   optional   HepMC path(s); mutually exclusive with --enableGun
+#   steering_file optional   overrides the top-level steering_file for this sample
+#
+# Sample-level keys override top-level, except ddsim_args (which concatenates).
+# sweep / include_only / exclude_only are mutually exclusive.
+
+xml: FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03.xml
+verbose: false
+sweep: true
+
+samples:
+  - name: single_e-_10GeV
+    n_events: 500
+    ddsim_args: >-
+      --enableGun
+      --gun.particle e-
+      --gun.distribution uniform
+      --gun.energy 10*GeV
+
+  - name: p8_ee_Zbb_ecm91
+    n_events: 100
+    input_files: root://eospublic.cern.ch//eos/experiment/fcc/ee/generation/hepmc/p8_ee_Zbb_ecm91/events_noVtxSmear.hepmc

k4bench-0.0.13/.github/benchmarks/ALLEGRO_o2_v01.yml

@@ -0,0 +1,48 @@
+# k4Bench nightly benchmark config — ALLEGRO o2 v01
+#
+# The nightly workflow expands every file in .github/benchmarks/ into a matrix
+# of (detector × sample) jobs and uploads each result to EOS under:
+#   {detector}/{platform}/key4hep-{release}/{sample}/{date}/
+# To add a new detector, drop a new <detector>.yml file in this directory.
+# To add a new sample, append an entry to samples: below.
+#
+# ── Top-level keys (apply to every sample in this file) ────────────────────
+#   xml           required   detector geometry, $K4GEO-relative or absolute path
+#   verbose       optional   stream ddsim output to stdout      (default: false)
+#   sweep         optional   baseline + one run per subdetector dropped
+#   include_only  optional   keep only these subdetectors       (list, single run)
+#   exclude_only  optional   drop these subdetectors            (list, single run)
+#   ddsim_args    optional   ddsim flags applied to every sample
+#   steering_file optional   ddsim --steeringFile path; $VAR refs (e.g. $FCCCONFIG)
+#                            are expanded inside the runner. Steering files for FCC
+#                            detectors live in https://github.com/HEP-FCC/FCC-config
+#                            and are installed under $FCCCONFIG by Key4hep, e.g.
+#                            $FCCCONFIG/FullSim/IDEA/IDEA_o1_v03/SteeringFile_IDEA_o1_v03.py
+#   samples       required   list of sample entries — see below
+#
+# ── Per-sample keys (under samples:) ───────────────────────────────────────
+#   name          required   slug — becomes the EOS sample directory + job label
+#   n_events      required   positive integer
+#   ddsim_args    optional   appended to top-level ddsim_args (not replaced)
+#   input_files   optional   HepMC path(s); mutually exclusive with --enableGun
+#   steering_file optional   overrides the top-level steering_file for this sample
+#
+# Sample-level keys override top-level, except ddsim_args (which concatenates).
+# sweep / include_only / exclude_only are mutually exclusive.
+
+xml: FCCee/ALLEGRO/compact/ALLEGRO_o2_v01/ALLEGRO_o2_v01.xml
+verbose: false
+sweep: true
+
+samples:
+  - name: single_e-_10GeV
+    n_events: 500
+    ddsim_args: >-
+      --enableGun
+      --gun.particle e-
+      --gun.distribution uniform
+      --gun.energy 10*GeV
+
+  - name: p8_ee_Zbb_ecm91
+    n_events: 100
+    input_files: root://eospublic.cern.ch//eos/experiment/fcc/ee/generation/hepmc/p8_ee_Zbb_ecm91/events_noVtxSmear.hepmc

k4bench-0.0.13/.github/benchmarks/IDEA_o1_v03.yml

@@ -0,0 +1,50 @@
+# k4Bench nightly benchmark config — IDEA o1 v03
+#
+# The nightly workflow expands every file in .github/benchmarks/ into a matrix
+# of (detector × sample) jobs and uploads each result to EOS under:
+#   {detector}/{platform}/key4hep-{release}/{sample}/{date}/
+# To add a new detector, drop a new <detector>.yml file in this directory.
+# To add a new sample, append an entry to samples: below.
+#
+# ── Top-level keys (apply to every sample in this file) ────────────────────
+#   xml           required   detector geometry, $K4GEO-relative or absolute path
+#   verbose       optional   stream ddsim output to stdout      (default: false)
+#   sweep         optional   baseline + one run per subdetector dropped
+#   include_only  optional   keep only these subdetectors       (list, single run)
+#   exclude_only  optional   drop these subdetectors            (list, single run)
+#   ddsim_args    optional   ddsim flags applied to every sample
+#   steering_file optional   ddsim --steeringFile path; $VAR refs (e.g. $FCCCONFIG)
+#                            are expanded inside the runner. Steering files for FCC
+#                            detectors live in https://github.com/HEP-FCC/FCC-config
+#                            and are installed under $FCCCONFIG by Key4hep, e.g.
+#                            $FCCCONFIG/FullSim/IDEA/IDEA_o1_v03/SteeringFile_IDEA_o1_v03.py
+#   samples       required   list of sample entries — see below
+#
+# ── Per-sample keys (under samples:) ───────────────────────────────────────
+#   name          required   slug — becomes the EOS sample directory + job label
+#   n_events      required   positive integer
+#   ddsim_args    optional   appended to top-level ddsim_args (not replaced)
+#   input_files   optional   HepMC path(s); mutually exclusive with --enableGun
+#   steering_file optional   overrides the top-level steering_file for this sample
+#
+# Sample-level keys override top-level, except ddsim_args (which concatenates).
+# sweep / include_only / exclude_only are mutually exclusive.
+
+xml: FCCee/IDEA/compact/IDEA_o1_v03/IDEA_o1_v03.xml
+steering_file: $FCCCONFIG/FullSim/IDEA/IDEA_o1_v03/SteeringFile_IDEA_o1_v03.py
+
+verbose: false
+sweep: false
+
+samples:
+  - name: single_e-_10GeV
+    n_events: 100
+    ddsim_args: >-
+      --enableGun
+      --gun.particle e-
+      --gun.distribution uniform
+      --gun.energy 10*GeV
+
+  - name: p8_ee_Zbb_ecm91
+    n_events: 100
+    input_files: root://eospublic.cern.ch//eos/experiment/fcc/ee/generation/hepmc/p8_ee_Zbb_ecm91/events_noVtxSmear.hepmc

k4bench-0.0.13/.github/benchmarks/IDEA_o2_v01.yml

@@ -0,0 +1,50 @@
+# k4Bench nightly benchmark config — IDEA o2 v01
+#
+# The nightly workflow expands every file in .github/benchmarks/ into a matrix
+# of (detector × sample) jobs and uploads each result to EOS under:
+#   {detector}/{platform}/key4hep-{release}/{sample}/{date}/
+# To add a new detector, drop a new <detector>.yml file in this directory.
+# To add a new sample, append an entry to samples: below.
+#
+# ── Top-level keys (apply to every sample in this file) ────────────────────
+#   xml           required   detector geometry, $K4GEO-relative or absolute path
+#   verbose       optional   stream ddsim output to stdout      (default: false)
+#   sweep         optional   baseline + one run per subdetector dropped
+#   include_only  optional   keep only these subdetectors       (list, single run)
+#   exclude_only  optional   drop these subdetectors            (list, single run)
+#   ddsim_args    optional   ddsim flags applied to every sample
+#   steering_file optional   ddsim --steeringFile path; $VAR refs (e.g. $FCCCONFIG)
+#                            are expanded inside the runner. Steering files for FCC
+#                            detectors live in https://github.com/HEP-FCC/FCC-config
+#                            and are installed under $FCCCONFIG by Key4hep, e.g.
+#                            $FCCCONFIG/FullSim/IDEA/IDEA_o2_v01/SteeringFile_IDEA_o2_v01.py
+#   samples       required   list of sample entries — see below
+#
+# ── Per-sample keys (under samples:) ───────────────────────────────────────
+#   name          required   slug — becomes the EOS sample directory + job label
+#   n_events      required   positive integer
+#   ddsim_args    optional   appended to top-level ddsim_args (not replaced)
+#   input_files   optional   HepMC path(s); mutually exclusive with --enableGun
+#   steering_file optional   overrides the top-level steering_file for this sample
+#
+# Sample-level keys override top-level, except ddsim_args (which concatenates).
+# sweep / include_only / exclude_only are mutually exclusive.
+
+xml: FCCee/IDEA/compact/IDEA_o2_v01/IDEA_o2_v01.xml
+steering_file: $FCCCONFIG/FullSim/IDEA/IDEA_o2_v01/SteeringFile_IDEA_o2_v01.py
+
+verbose: false
+sweep: false
+
+samples:
+  - name: single_e-_10GeV
+    n_events: 100
+    ddsim_args: >-
+      --enableGun
+      --gun.particle e-
+      --gun.distribution uniform
+      --gun.energy 10*GeV
+
+  - name: p8_ee_Zbb_ecm91
+    n_events: 100
+    input_files: root://eospublic.cern.ch//eos/experiment/fcc/ee/generation/hepmc/p8_ee_Zbb_ecm91/events_noVtxSmear.hepmc

k4bench-0.0.13/.github/scripts/list_benchmarks.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Expand .github/benchmarks/*.yml into benchmark jobs and print them as JSON
+on stdout. Two output shapes:
+
+  default  — flat list, one record per (detector, sample)
+  --grouped — list of {detector, samples: [...]} so the nightly workflow can
+              fan out one reusable-workflow call per detector and nest the
+              sample matrix beneath it in the Actions UI
+
+Each sample record is a fully-merged config consumed downstream as plain env
+vars — no YAML parsing happens after this script runs.
+
+Top-level keys in a benchmark file are detector-wide defaults; keys inside a
+samples[] entry override them for that sample only. The single exception is
+ddsim_args: top-level and sample-level strings are concatenated (top first),
+which lets shared ddsim flags live at the detector level. Lists are joined
+to space-separated strings so they round-trip through env vars unchanged.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import sys
+from pathlib import Path
+
+import yaml
+
+BENCH_DIR = Path(".github/benchmarks")
+CONFIG_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+SAMPLE_RE = re.compile(r"^[A-Za-z0-9_.+-]+$")
+
+SCALAR_KEYS = ("xml", "n_events", "ddsim_args", "verbose", "sweep", "steering_file")
+LIST_KEYS   = ("input_files", "include_only", "exclude_only")
+
+
+def _scalar(v) -> str:
+    if v is None:           return ""
+    if isinstance(v, bool): return str(v).lower()
+    return str(v).strip()
+
+
+def _list(v) -> str:
+    if v is None:           return ""
+    if isinstance(v, list): return " ".join(str(x) for x in v)
+    return str(v).strip()
+
+
+def _die(msg: str) -> None:
+    print(f"ERROR: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def expand(path: Path) -> list[dict]:
+    config = path.stem
+    if not CONFIG_RE.match(config):
+        _die(f"invalid config name {config!r} (from {path})")
+
+    cfg = yaml.safe_load(path.read_text()) or {}
+    if not isinstance(cfg, dict):
+        _die(f"top-level YAML must be a mapping in {path}")
+    samples = cfg.get("samples") or []
+    if not isinstance(samples, list):
+        _die(f"'samples' must be a list in {path}")
+    if not samples:
+        _die(f"no samples defined in {path}")
+
+    records = []
+    for s in samples:
+        if not isinstance(s, dict):
+            _die(f"sample entries in {path} must be mappings, got {type(s).__name__}")
+        name = s.get("name")
+        if not name:
+            _die(f"sample entry in {path} is missing 'name'")
+        if not SAMPLE_RE.match(name):
+            _die(f"invalid sample name {name!r} in {path}")
+
+        def merge(k):
+            # ddsim_args concatenates (top + sample); everything else overrides.
+            if k == "ddsim_args":
+                parts = [v for v in (cfg.get(k), s.get(k)) if v]
+                return " ".join(str(p).strip() for p in parts) if parts else None
+            return s[k] if k in s else cfg.get(k)
+
+        rec = {"config": config, "sample": name}
+        for k in SCALAR_KEYS: rec[k] = _scalar(merge(k))
+        for k in LIST_KEYS:   rec[k] = _list(merge(k))
+
+        loc = f"{path}::{name}"
+        if not rec["n_events"].isdigit() or int(rec["n_events"]) <= 0:
+            _die(f"n_events must be a positive integer ({loc})")
+        if rec["input_files"] and "--enableGun" in shlex.split(rec["ddsim_args"]):
+            _die(f"input_files and '--enableGun' in ddsim_args are mutually exclusive ({loc})")
+        modes = (rec["sweep"] == "true") + bool(rec["include_only"]) + bool(rec["exclude_only"])
+        if modes > 1:
+            _die(f"sweep / include_only / exclude_only are mutually exclusive ({loc})")
+
+        records.append(rec)
+    return records
+
+
+def _group_by_detector(items: list[dict]) -> list[dict]:
+    grouped: dict[str, list[dict]] = {}
+    for item in items:
+        grouped.setdefault(item["config"], []).append(item)
+    return [{"detector": d, "samples": s} for d, s in grouped.items()]
+
+
+def main() -> None:
+    grouped = "--grouped" in sys.argv[1:]
+    paths = sorted(BENCH_DIR.glob("*.yml"))
+    if not paths:
+        _die(f"no benchmark configs found in {BENCH_DIR}/")
+    items = [r for p in paths for r in expand(p)]
+    print(json.dumps(_group_by_detector(items) if grouped else items))
+
+
+if __name__ == "__main__":
+    main()

k4bench-0.0.13/.github/scripts/machine_info.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Collect machine info around a benchmark run.
+
+  machine_info.py start    <output_dir>   # snapshot before the benchmark
+  machine_info.py finalize <output_dir>   # snapshot after, merged with start
+
+The start step writes <output_dir>/_machine_info_start.json with static
+fields (CPU model, RAM total, OS, kernel) and "_start" baselines for the
+dynamic fields (load, free memory, swap, CPU frequency, thermal throttle
+counter). The finalize step reads that file, adds matching "_end" fields,
+computes thermal_throttle_events as the delta over the run, writes
+<output_dir>/machine_info.json, and removes the intermediate start file.
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import platform
+import sys
+from pathlib import Path
+
+START_FILE = "_machine_info_start.json"
+FINAL_FILE = "machine_info.json"
+
+
+def _read(path: str, default: str = "") -> str:
+    try:
+        with open(path) as f:
+            return f.read()
+    except OSError:
+        return default
+
+
+def _parse_meminfo() -> dict[str, int]:
+    out: dict[str, int] = {}
+    for line in _read("/proc/meminfo").splitlines():
+        p = line.split()
+        if len(p) >= 2:
+            try:
+                out[p[0].rstrip(":")] = int(p[1])
+            except ValueError:
+                pass
+    return out
+
+
+def _loadavg() -> list[str]:
+    return _read("/proc/loadavg").split()
+
+
+def _cpu_freq_mhz() -> float | None:
+    raw = _read("/sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq").strip()
+    if not raw:
+        return None
+    try:
+        return round(int(raw) / 1000, 1)
+    except ValueError:
+        return None
+
+
+def _throttle_paths() -> list[str]:
+    return glob.glob("/sys/devices/system/cpu/cpu*/thermal_throttle/core_throttle_count")
+
+
+def _sum_throttle(paths: list[str]) -> int | None:
+    if not paths:
+        return None
+    total = 0
+    for p in paths:
+        raw = _read(p).strip()
+        try:
+            total += int(raw)
+        except ValueError:
+            pass
+    return total
+
+
+def _kib_to_gib(kib: int) -> float:
+    return round(kib / 1024**2, 2)
+
+
+def collect_start() -> dict:
+    cpuinfo = _read("/proc/cpuinfo")
+    cpu_model = next(
+        (line.split(":", 1)[1].strip() for line in cpuinfo.splitlines() if "model name" in line),
+        "unknown",
+    )
+    # Tolerate any whitespace between the field name and the colon.
+    cpu_logical = sum(1 for line in cpuinfo.splitlines() if line.startswith("processor"))
+
+    # Count unique (physical_id, core_id) pairs — more accurate than socket count
+    # alone. Falls back to logical count if these fields are absent (VMs, containers).
+    pairs: set = set()
+    current: dict = {}
+
+    def _flush(block: dict) -> None:
+        if "processor" in block:
+            pairs.add((
+                block.get("physical id", "0"),
+                block.get("core id", block.get("processor", "0")),
+            ))
+
+    for line in cpuinfo.splitlines():
+        if not line.strip():
+            _flush(current)
+            current = {}
+        elif ":" in line:
+            k, _, v = line.partition(":")
+            current[k.strip()] = v.strip()
+    _flush(current)  # capture the final block when no trailing blank line
+    cpu_physical = len(pairs) if pairs else cpu_logical
+    cpu_flags = next(
+        (line.split(":", 1)[1].strip().split() for line in cpuinfo.splitlines() if line.startswith("flags")),
+        [],
+    )
+
+    mem = _parse_meminfo()
+    loadavg = _loadavg()
+    swap_used_kib = mem.get("SwapTotal", 0) - mem.get("SwapFree", mem.get("SwapTotal", 0))
+
+    os_name = next(
+        (line.split("=", 1)[1].strip('"') for line in _read("/etc/os-release").splitlines()
+         if line.startswith("PRETTY_NAME=")),
+        "unknown",
+    )
+
+    return {
+        "cpu_model":                    cpu_model,
+        "cpu_physical_cores":           cpu_physical,
+        "cpu_logical_cores":            cpu_logical,
+        "cpu_flags":                    cpu_flags,
+        "ram_total_gb":                 _kib_to_gib(mem.get("MemTotal", 0)),
+        "ram_available_gb_start":       _kib_to_gib(mem.get("MemAvailable", 0)),
+        "swap_total_gb":                _kib_to_gib(mem.get("SwapTotal", 0)),
+        "swap_used_gb_start":           _kib_to_gib(swap_used_kib),
+        "load_avg_1m_start":            float(loadavg[0]) if len(loadavg) > 0 else None,
+        "load_avg_5m_start":            float(loadavg[1]) if len(loadavg) > 1 else None,
+        "cpu_governor":                 _read("/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor").strip() or None,
+        "cpu_freq_mhz_start":           _cpu_freq_mhz(),
+        "thermal_throttle_count_start": _sum_throttle(_throttle_paths()),
+        "kernel":                       platform.release(),
+        "os":                           os_name,
+        "hostname":                     os.uname().nodename,
+        "in_container":                 os.path.exists("/.dockerenv"),
+    }
+
+
+def finalize(machine_info: dict) -> dict:
+    mem = _parse_meminfo()
+    loadavg = _loadavg()
+    swap_used_kib = mem.get("SwapTotal", 0) - mem.get("SwapFree", mem.get("SwapTotal", 0))
+
+    machine_info["ram_available_gb_end"] = _kib_to_gib(mem.get("MemAvailable", 0))
+    machine_info["swap_used_gb_end"]     = _kib_to_gib(swap_used_kib)
+    machine_info["load_avg_1m_end"]      = float(loadavg[0]) if len(loadavg) > 0 else None
+    machine_info["load_avg_5m_end"]      = float(loadavg[1]) if len(loadavg) > 1 else None
+    machine_info["cpu_freq_mhz_end"]     = _cpu_freq_mhz()
+
+    paths = _throttle_paths()
+    end   = _sum_throttle(paths)
+    start = machine_info.get("thermal_throttle_count_start")
+    machine_info["thermal_throttle_events"] = (
+        max(0, end - start) if (paths and start is not None and end is not None) else None
+    )
+    return machine_info
+
+
+def cmd_start(out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    info = collect_start()
+    (out_dir / START_FILE).write_text(json.dumps(info, indent=2))
+    print(f"cpu_model        : {info['cpu_model']}")
+    print(f"cpu_logical_cores: {info['cpu_logical_cores']}")
+    print(f"ram_total_gb     : {info['ram_total_gb']:.2f} GB")
+    print(f"ram_available    : {info['ram_available_gb_start']:.2f} GB")
+    print(f"load_avg_1m      : {info['load_avg_1m_start']}")
+
+
+def cmd_finalize(out_dir: Path) -> None:
+    start_path = out_dir / START_FILE
+    if start_path.exists():
+        info = json.loads(start_path.read_text())
+        start_path.unlink()
+    else:
+        print(f"WARNING: {start_path} not found — machine info start snapshot missing", flush=True)
+        info = {}
+    info = finalize(info)
+    (out_dir / FINAL_FILE).write_text(json.dumps(info, indent=2))
+    print(f"Written: {out_dir / FINAL_FILE}")
+
+
+def main() -> None:
+    if len(sys.argv) != 3 or sys.argv[1] not in ("start", "finalize"):
+        sys.exit(f"usage: {sys.argv[0]} (start|finalize) <output_dir>")
+    cmd = sys.argv[1]
+    out_dir = Path(sys.argv[2])
+    (cmd_start if cmd == "start" else cmd_finalize)(out_dir)
+
+
+if __name__ == "__main__":
+    main()