chore: update changelog for v0.3.16

Reviewed-on: #92

.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.3.13"
+current_version = "0.3.16"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"
@@ -8,7 +8,7 @@ regex = false
 allow_dirty = false
 commit = true
 tag = false
-message = "chore: bump version {current_version} -> {new_version} [skip ci]"
+message = "chore: bump version {current_version} -> {new_version}"
 pre_commit_hooks = ["uv lock", "git add uv.lock"]
 
 [[tool.bumpversion.files]]

.gitea/workflows/ci.yml

@@ -2,10 +2,9 @@ name: CI
 
 "on":
   push:
-    branches: ["**"]
+    branches: ["master"]
     tags: ["**"]
-  pull_request:
-    branches: [master]
+  pull_request: {}
 
 env:
   UV_CACHE_DIR: /uv-cache
@@ -156,7 +155,7 @@ jobs:
             uv run git-cliff --tag "$TAG" --unreleased --prepend CHANGELOG.md
             git add CHANGELOG.md
             if ! git diff --cached --quiet -- CHANGELOG.md; then
-              git commit -m "chore: update changelog for $TAG [skip ci]"
+              git commit -m "chore: update changelog for $TAG"
             else
               git restore --staged CHANGELOG.md
             fi
@@ -193,7 +192,7 @@ jobs:
             git config user.name "gitea-actions"
             git config user.email "actions@git.larsbogner.de"
             git add pyproject.toml uv.lock
-            git commit -m "chore: sync project version to tag ${GITHUB_REF_NAME} [skip ci]"
+            git commit -m "chore: sync project version to tag ${GITHUB_REF_NAME}"
             git push origin HEAD:master
             git push origin ":refs/tags/${GITHUB_REF_NAME}"
             git tag -f "${GITHUB_REF_NAME}" HEAD
@@ -201,3 +200,33 @@ jobs:
           else
             echo "Tag version matches project version ($CURRENT_VERSION)"
           fi
+
+  publish-package:
+    name: Publish package to Gitea package registry
+    needs: [ruff-check, ruff-format, type-check, test, sync-version-on-tag]
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: docker.gitea.com/runner-images:ubuntu-latest
+      volumes:
+        - /srv/act-runner-cache/uv:/uv-cache
+    steps:
+      # Check out by tag name (not the triggering SHA) since sync-version-on-tag
+      # may have force-moved the tag to a version-corrected commit.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: false
+      - run: |
+          echo "UV_CACHE_DIR=/uv-cache" >> "$GITHUB_ENV"
+          echo "UV_LINK_MODE=copy" >> "$GITHUB_ENV"
+      - run: uv build
+      # CI_TOKEN needs write:package scope (in addition to write:repository,
+      # used elsewhere) for this upload to authenticate.
+      - run: |
+          uv publish \
+            --publish-url "https://git.larsbogner.de/api/packages/lars/pypi" \
+            --username gitea-actions \
+            --password "${{ secrets.CI_TOKEN }}"

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.3.16] - 2026-08-31
+
+### Changed
+
+- Docs: record analysis_341dfb14 baseline rollout benchmark results
+
+- Feat: add eval-cost benchmark — Geant4 reference vs surrogate rollout timing
+
+## [0.3.15] - 2026-08-28
+
+### Changed
+
+- Perf: defer heavy imports in giant/dwarf CLIs until commands run
+
+## [0.3.14] - 2026-08-28
+
+### Changed
+
+- Ci: give automated commits visible checks, scope CI triggers, publish releases
+
+- Ci: fix pull_request trigger not registering
+
 ## [0.3.13] - 2026-08-28
 
 ### Added

CLAUDE.md

@@ -113,6 +113,8 @@ Secondary energies are a **stick-breaking partition of the `e_sec` budget** from
 
 **v0.3.0 — Stage-2 autoregressive redesign (implemented, released; on `master` since 2026-08-13):** motivated by the 2026-08-03 WGAN rollout benchmark, which failed specifically at the secondary-species level (zero photon secondaries, ~4M hallucinated `-14` muon antineutrinos). Stage 2 became autoregressive in descending-energy order with teacher forcing, and the particle-type representation went back to **categorical** (`particle_type.target = "onehot"`), reversing the 2026-07-17 continuous `(log-mass, charge)` target. The config break (`[conditioning]`/`[stage1_model]`/`[stage2_model]`/`[train]` replacing the flat `train.mode` + `[model]`) makes per-stage generators, stage-2-only training, and one-shot-vs-autoregressive comparison all expressible, and the `network.py` refactor into composable parts (encoder × trunk × objective) also makes routed WGAN work for the first time.
 
+**Baseline benchmark (done, 2026-08-26):** `configs/baseline.toml`'s first full rollout-vs-Geant4 validation (`analysis_341dfb14`, checkpoint `20260814_1743_s2-flow_h512_s2h512_bs36864_ep50/best.pt`, epoch 50/50). Confirms the v0.3.0 pivot fixed the species collapse — zero photon secondaries / hallucinated `-14` muon antineutrinos are both gone (γ at 95% of truth, no `-14` in the top species) — and rules out `conditioning.*.type = "physical"` as the cause, since this checkpoint pairs it with `flow`/no-router and still doesn't collapse. Bulk shower observables are close to Geant4 (total deposited energy +1.9%, containment depth-90%/95% both 0.986×), but steps/event now *over*-shoots by 1.32× (the opposite sign from every pre-v0.3.0 checkpoint), no hadronic/nuclear secondaries are produced at all, and event-to-event energy variance is ~16× too narrow. Writeup: `/home/lars/knowledge-base/experiments/giant-baseline-flow-ar-rollout-validation.md`.
+
 v0.2 configs and checkpoints are auto-migrated (`config.migrate_config`, `model._legacy._migrate_legacy_model_config`, both drawing on shared facts in `giant/_migration.py`). **v0.2 checkpoint-loading support has no expiry decided yet**: `/ceph` still holds pre-v0.3.0 checkpoints and analysis runs referencing them, so don't delete or substantially alter either migration function or `tests/legacy/network_v02_snapshot.py` (the frozen v0.2 snapshot they're tested against) without an explicit decision to do so first.
 
 **Faster-eval architectures — both implemented, neither validated.** Target is a ~10× native-Geant4 eval budget; no eval-latency number exists for any configuration yet, so that budget is unverified across the board.

cliff.toml

@@ -37,7 +37,7 @@ commit_preprocessors = [
 protect_breaking_commits = false
 commit_parsers = [
     { message = "^Merge ", skip = true },
-    { message = "\\[skip ci\\]", skip = true },
+    { message = "^chore: (bump version|update changelog|sync project version)", skip = true },
     { message = "^Add", group = "<!-- 0 -->Added" },
     { message = "^(Fix|Clamp|Clip)", group = "<!-- 1 -->Fixed" },
     { message = "^(Remove|Drop|Deprecate)", group = "<!-- 2 -->Removed" },

configs/baseline.toml

@@ -29,11 +29,21 @@
 #     capacity overfitting is not the binding constraint, and every recent
 #     run used 0.0.
 #
-# Known weak spots this baseline is expected to *exhibit* (they are the
-# reason for the comparisons, not a reason to retune this file): every model
-# on record under-produces steps per event by ~2x (rollout ~7e4 vs Geant4
-# ~1.4e5) and secondaries per event by 2-3.5x (~2-3e4 vs 7.2e4), and n_sec
-# head accuracy sits at 0.863-0.867 regardless of size or objective.
+# Known weak spots, now measured against this exact config rather than
+# extrapolated from the pre-v0.3 field (analysis_341dfb14, best.pt @ epoch
+# 50/50, full writeup: knowledge-base/experiments/
+# giant-baseline-flow-ar-rollout-validation.md). Unlike every pre-v0.3
+# checkpoint (which under-produced steps/event by 1.6-5x), this baseline
+# OVER-produces steps/event by 1.32x (1.86e5 vs Geant4 1.41e5) and
+# under-produces secondaries/event by 0.84x (5.97e4 vs 7.14e4) — the sign on
+# steps flipped with the v0.3 autoregressive pivot, so don't assume it still
+# undershoots. Secondary-species hallucination (zero photons, hallucinated
+# `-14` muon antineutrinos) that broke every prior checkpoint is gone; the
+# remaining species gap is a total absence of hadronic/nuclear secondaries
+# (protons, neutrons, ion recoils), not miscalibration of the ones produced.
+# Total deposited energy/event is +1.9% high but its event-to-event spread is
+# ~16x too narrow (31 MeV vs Geant4's 491 MeV). Per-step deposited energy is
+# the worst per-step marginal (KS 0.179 vs 0.004-0.071 for the others).
 
 [meta]
 # REQUIRED. Without it config.migrate_config reads this file as v0.2 and

giant/analysis/catalog.py

@@ -45,6 +45,7 @@ import numpy as np
 import polars as pl
 
 from giant.analysis.context import Context
+from giant.analysis.geant4_reference import GEANT4_REFERENCE, geant4_per_step_us
 from giant.analysis.grouping import (
     energy_bin_labels,
     event_energy_bins,
@@ -125,6 +126,7 @@ class Bundle:
                 phys=physical_steps(r_all, Side.rollout),
                 checkpoint=rs.checkpoint,
                 type_embedding_l1_dist=rs.type_embedding_l1_dist,
+                timing=rs.timing,
             )
         return cls(ctx=ctx, rollouts=sides, t_all=t_all, t_phys=physical_steps(t_all, Side.reference))
 
@@ -973,6 +975,80 @@ def _sec_cos_angle_finalize(parts: list[dict], ctx: Context) -> Reduced:
     )
 
 
+# ---------------------------------------------------------------------------
+# eval cost (not chunked — metadata-only, no row scan)
+# ---------------------------------------------------------------------------
+
+_EVAL_COST_LABELS = ["sampling / simulation", "parquet write / convert", "total"]
+_EVAL_COST_NOTE = (
+    "no rollout in this run carries a `timing` block — re-run `giant rollout` "
+    "(timing instrumentation added after this checkpoint's rollout run) to "
+    "populate this plot"
+)
+
+
+def _eval_cost_per_step(b: Bundle) -> Reduced:
+    """Per-rollout µs/physical-step vs the measured Geant4 reference.
+
+    ``timing`` (``giant.cli``'s ``rollout`` command) is metadata carried on
+    the rollout YAML, not derived from the row data, so this needs no chunked
+    scan — same shape as the router diagnostics above.
+    """
+    series: dict[str, list[float]] = {}
+    speedup: dict[str, float] = {}
+    for name, rs in b.rollouts.items():
+        t = rs.timing
+        if not t or t.get("us_per_step") is None:
+            continue
+        sample_us = t["us_per_step"]
+        write_us = t.get("write_us_per_step") or 0.0
+        series[name] = [sample_us, write_us, sample_us + write_us]
+
+    if not series:
+        return Reduced(
+            id="eval_cost_per_step",
+            family="cost",
+            kind="unavailable",
+            title="Eval cost per step: surrogate vs Geant4",
+            xlabel="n/a",
+            payload={"note": _EVAL_COST_NOTE},
+        )
+
+    g4 = geant4_per_step_us()
+    reference = [g4["sim_us_per_step"], g4["convert_us_per_step"], g4["total_us_per_step"]]
+    for name, vals in series.items():
+        speedup[name] = reference[-1] / vals[-1] if vals[-1] else float("inf")
+
+    return Reduced(
+        id="eval_cost_per_step",
+        family="cost",
+        kind="bar",
+        title="Eval cost per step: surrogate vs Geant4",
+        xlabel="phase",
+        payload={
+            "labels": _EVAL_COST_LABELS,
+            "series": series,
+            "reference": reference,
+            "ylabel": "µs per physical step",
+            "log_y": True,
+        },
+        meta={
+            "speedup_vs_geant4_total": speedup,
+            "geant4_provenance": GEANT4_REFERENCE["provenance"],
+            "caveat": (
+                "The Geant4 reference is measured single-threaded on one CPU core "
+                "(see giant.analysis.geant4_reference); a rollout's timing is "
+                "whatever device it actually ran on (see each series' device in "
+                "run_meta.json's plot_meta). This is a deployment-speedup ratio, "
+                "not a same-hardware or per-FLOP comparison."
+            ),
+        },
+    )
+
+
+_eval_cost_per_step_partial, _eval_cost_per_step_finalize = _unchunkable(_eval_cost_per_step)
+
+
 # ---------------------------------------------------------------------------
 # router diagnostics (not chunked — already bounded/subsampled)
 # ---------------------------------------------------------------------------
@@ -1160,6 +1236,13 @@ def build_catalog() -> list[PlotSpec]:
             compute_partial=_sec_cos_angle_partial,
             finalize=_sec_cos_angle_finalize,
         ),
+        PlotSpec(
+            "eval_cost_per_step",
+            "cost",
+            compute_partial=_eval_cost_per_step_partial,
+            finalize=_eval_cost_per_step_finalize,
+            chunkable=False,
+        ),
         PlotSpec(
             "router_gating",
             "model",

giant/analysis/condor.py

@@ -82,6 +82,7 @@ _PLOT_META_KEYS = (
     "rollout_seed",
     "n_rows",
     "termination_reason_counts",
+    "timing",
     "model_config",
     "training_epoch",
     "best_val_loss",
@@ -329,9 +330,9 @@ def compute_reduced(
 ) -> Path:
     """Core: run one (plot, chunk)'s partial reduction against explicit paths.
 
-    ``rollouts``: ``[{"name", "path", "checkpoint"?, "type_embedding_l1_dist"?},
-    ...]``, one per rollout series (insertion order preserved through to every
-    plot's ``Reduced.payload["series"]``).
+    ``rollouts``: ``[{"name", "path", "checkpoint"?, "type_embedding_l1_dist"?,
+    "timing"?}, ...]``, one per rollout series (insertion order preserved
+    through to every plot's ``Reduced.payload["series"]``).
 
     Writes a ``Partial`` JSON — the raw, not-yet-merged output of
     ``PlotSpec.compute_partial`` — never a finished ``Reduced``; ``merge_one``
@@ -352,6 +353,7 @@ def compute_reduced(
             source=r["path"],
             checkpoint=r.get("checkpoint"),
             type_embedding_l1_dist=r.get("type_embedding_l1_dist"),
+            timing=r.get("timing"),
         )
         for r in rollouts
     ]
@@ -377,6 +379,7 @@ def compute_one(spec_id: str, run_dir: str | Path, chunk_index: int = 0) -> Path
             "path": ro["path"],
             "checkpoint": ro["plot_meta"].get("checkpoint"),
             "type_embedding_l1_dist": ro["plot_meta"].get("type_embedding_l1_dist"),
+            "timing": ro["plot_meta"].get("timing"),
         }
         for ro in meta.rollouts
     ]

giant/analysis/geant4_reference.py

@@ -0,0 +1,76 @@
+"""Measured Geant4 (miniCaloSim) per-step eval cost — the reference line for
+``eval_cost_per_step`` in ``catalog.py``.
+
+Mirrors the precedent set by ``runtime_estimate.py``'s ``_COST_MODEL``: a
+constant table measured once on a specific machine and pasted in, with the
+methodology and provenance recorded in this docstring rather than derived at
+runtime (there is no live Geant4 install on the machines that run
+``giant analyze``, and re-measuring per invocation would be both slow and
+noisy — see the module docstring precedent).
+
+**Methodology** (``scratchpad/bench_geant4.py``, a one-off, not a `dwarf`
+subcommand): ``run_pbwo4`` (the default homogeneous-PbWO4 miniCaloSim
+executable, see ``~/Programming/minicalosim``) was timed at 3 beam energies
+(1/10/50 GeV) and **4 event counts each**, converting each run's ROOT output
+to Parquet with ``giant.tools.steps_to_parquet.convert_steps_to_parquet``
+immediately after. Event counts were scaled down as energy rose (100/400/
+1000/2000 at 1 GeV, 30/100/200/300 at 10 GeV, 10/25/45/60 at 50 GeV) to keep
+every run's row count under ~8.1M — a naive 50/200 pair at 50 GeV produces
+~27M steps and OOM'd the conversion step on a 14GB laptop. Per-energy linear
+fits (``t = intercept + slope * n``) separate Geant4's one-time init (physics
+tables, geometry construction) from its true marginal per-event cost — the
+slope, not a naive ``t / n_events`` from a single run, is what feeds
+``sim_us_per_step`` below. The per-step denominator is the produced
+``Steps``-tree/Parquet row count, matching the "physical step" unit
+``giant rollout``'s ``timing.n_physical_rows`` uses on the surrogate side.
+Both stages ran single-threaded (default Geant4 threading), pinned to one
+CPU core.
+
+``sim_us_per_step``/``convert_us_per_step``/``sim_ms_per_event`` below are
+the mean across the 3 energies. With 4 event-count points per energy (up
+from an initial 2-point pass, which had ~80% spread and nonsensical negative
+fitted intercepts at 10/50 GeV — an artifact of extrapolating a 2-point
+line), both quantities are now energy-flat as physically expected:
+``sim_us_per_step`` spread ~5%, ``convert_us_per_step`` spread ~13.5%. Treat
+these as reliable to about that precision.
+
+**Caveat — hardware asymmetry**: this reference is single-core CPU. A
+surrogate rollout's ``timing`` block will typically be measured on a batched
+GPU. The resulting ratio in ``eval_cost_per_step`` is a *deployment* speedup
+(what you'd actually see swapping Geant4 for the surrogate in a production
+pipeline), not a same-hardware or per-FLOP comparison — state this whenever
+quoting the number.
+
+**Staleness**: re-run ``scratchpad/bench_geant4.py`` (and update this file)
+if measured on different hardware, after a miniCaloSim/Geant4 version bump,
+or if this reference is more than a year or two stale.
+"""
+
+from __future__ import annotations
+
+GEANT4_REFERENCE: dict = {
+    "sim_us_per_step": 11.2903,
+    "convert_us_per_step": 11.1014,
+    "sim_ms_per_event": 609.6848,
+    "provenance": {
+        "cpu": "AMD Ryzen 7 PRO 4750U with Radeon Graphics",
+        "geant4_version": "11.4.1",
+        "minicalosim_sha": "ea917da",
+        "measured": "2026-08-31",
+        "energies_gev": [1.0, 10.0, 50.0],
+        "spread_pct_sim": 4.96,
+        "spread_pct_convert": 13.52,
+        "threads": 1,
+    },
+}
+
+
+def geant4_per_step_us() -> dict[str, float]:
+    """Sim / convert / total microseconds per physical step, from ``GEANT4_REFERENCE``."""
+    sim = GEANT4_REFERENCE["sim_us_per_step"]
+    convert = GEANT4_REFERENCE["convert_us_per_step"]
+    return {
+        "sim_us_per_step": sim,
+        "convert_us_per_step": convert,
+        "total_us_per_step": sim + convert,
+    }

giant/analysis/render.py

@@ -274,6 +274,8 @@ def _render_bar(r: Reduced, params: dict):
     ax.set_xticks(x)
     ax.set_xticklabels(labels, rotation=45, ha="right")
     ax.set_ylabel(r.payload.get("ylabel", "value"))
+    if r.payload.get("log_y"):
+        ax.set_yscale("log")
     ps.style_legend(ax, title="source")
     return fig
 

giant/analysis/runtime_estimate.py

@@ -96,6 +96,10 @@ _COST_MODEL: dict[str, tuple[float, float]] = {
     "sec_count_per_species": (0.0, 4.963e-07),
     "sec_energy": (0.0, 4.727e-07),
     "sec_cos_angle": (0.0, 2.749e-06),
+    # Metadata-only (YAML-carried `timing`, no row scan) — same shape as the
+    # router diagnostics' fixed cost, just cheaper since there's no live
+    # torch checkpoint to load.
+    "eval_cost_per_step": (0.0, 0.0),
 }
 
 

giant/analysis/sources.py

@@ -110,6 +110,7 @@ class RolloutSpec:
     source: str | Path | pl.LazyFrame
     checkpoint: str | None = None
     type_embedding_l1_dist: dict | None = None
+    timing: dict | None = None
 
 
 @dataclass
@@ -124,6 +125,10 @@ class RolloutSide:
     # only. Unlike checkpoint, this needs no live model: it's already a
     # finished histogram, just passed through.
     type_embedding_l1_dist: dict | None = None
+    # Wall-clock cost of this rollout run (giant.cli's rollout command),
+    # from the rollout YAML — eval_cost_per_step only. None on rollout runs
+    # that predate timing instrumentation.
+    timing: dict | None = None
 
 
 def _check_rollout_metadata(path: Path) -> None:

giant/cli.py

@@ -1,21 +1,19 @@
+from __future__ import annotations
+
 from collections import Counter
 from datetime import datetime, timezone
 from enum import Enum
 import math
 from pathlib import Path
 import re
-from typing import Optional
+from typing import TYPE_CHECKING, Optional, cast
 import uuid as uuid_mod
 
-import numpy as np
-import yaml
-import torch
 import typer
 from typing_extensions import Annotated
 
-import pyarrow as pa
-import pyarrow.parquet as pq
-from tqdm import tqdm
+if TYPE_CHECKING:
+    import numpy as np
 
 from giant import config as gconfig
 from giant.constants import (
@@ -25,30 +23,11 @@ from giant.constants import (
     PREDICT_SCHEMA_VERSION_KEY,
     ROLLOUT_COORD_VALUE,
 )
-from giant.data.loader import (
-    event_id_offset,
-    find_parquet_files,
-    iter_file_chunks,
-    iter_cond_chunks,
-)
-from giant.data.transforms import (
-    build_features,
-    build_cond_features,
-    energy_simplex_decode,
-    inv_local_frame_rotation,
-    inv_log_transform,
-    reconstruct_post_pos,
-)
-from giant.checkpoint_io import CheckpointCompatibilityError, load_for_inference
-from giant.geometry import GeometryOracle
+
+# giant.materials only pulls in numpy (no torch/pandas), and MATERIAL_PROPERTIES
+# is needed at decoration time below (a Typer option default), so it can't be
+# deferred into a command body like the rest of this module's heavy imports.
 from giant.materials import MATERIAL_PROPERTIES
-from giant.pipeline import run_train_job
-from giant.rollout import (
-    L1DistCollector,
-    decode_secondary_identity,
-    rollout as run_rollout,
-)
-from giant.sample import resolve_n_sec, sample_stage1, sample_stage2
 
 app = typer.Typer(no_args_is_help=True)
 
@@ -210,6 +189,8 @@ def _write_prediction_ref(
     comment: str | None = None,
 ) -> Path:
     """Write a YAML sidecar in the checkpoint directory and return its path."""
+    import yaml
+
     ref = {
         "prediction_id": pred_uuid,
         "output": str(out),
@@ -224,6 +205,45 @@ def _write_prediction_ref(
     return ref_path
 
 
+def _build_rollout_timing(
+    *,
+    setup_s: float,
+    rollout_s: float,
+    write_s: float,
+    n_rows: int,
+    termination_reason_counts: dict[str, int],
+    n_seed_events: int,
+    device: str,
+    torch_threads: int,
+) -> dict:
+    """Assemble ``giant rollout``'s ``timing`` sidecar block.
+
+    ``n_physical_rows`` excludes the synthetic termination rows (escape/
+    unknown-pdg/energy-cutoff/max-steps markers `giant.rollout` emits but
+    Geant4 never does) so ``us_per_step`` is comparable to
+    ``giant.analysis.geant4_reference``'s per-step Geant4 measurement — see
+    ``giant/analysis/catalog.py``'s ``eval_cost_per_step`` spec.
+    """
+    from giant.analysis.sources import SYNTHETIC_TERMINATION_REASONS
+
+    sample_s = rollout_s - write_s
+    n_synthetic_rows = sum(termination_reason_counts.get(reason, 0) for reason in SYNTHETIC_TERMINATION_REASONS)
+    n_physical_rows = n_rows - n_synthetic_rows
+    return {
+        "setup_s": setup_s,
+        "rollout_s": rollout_s,
+        "write_s": write_s,
+        "sample_s": sample_s,
+        "n_rows": n_rows,
+        "n_physical_rows": n_physical_rows,
+        "us_per_step": (sample_s / n_physical_rows * 1e6) if n_physical_rows else None,
+        "write_us_per_step": (write_s / n_physical_rows * 1e6) if n_physical_rows else None,
+        "ms_per_event": (rollout_s / n_seed_events * 1e3) if n_seed_events else None,
+        "device": device,
+        "torch_threads": torch_threads,
+    }
+
+
 @app.callback()
 def _main() -> None:
     """GIANT — Geant4 step-function surrogate."""
@@ -639,6 +659,10 @@ def train(
     ] = None,
 ) -> None:
     """Train the GIANT surrogate model."""
+    import torch
+
+    from giant.pipeline import run_train_job
+
     batch_size_auto = False
     batch_size_value: Optional[int] = None
     if batch_size is not None:
@@ -1048,6 +1072,25 @@ def predict(
     ] = None,
 ) -> None:
     """Run trained model on a parquet file and save predictions."""
+    import numpy as np
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+    import torch
+    from tqdm import tqdm
+
+    from giant.checkpoint_io import CheckpointCompatibilityError, load_for_inference
+    from giant.data.loader import event_id_offset, find_parquet_files, iter_cond_chunks, iter_file_chunks
+    from giant.data.transforms import (
+        build_cond_features,
+        build_features,
+        energy_simplex_decode,
+        inv_local_frame_rotation,
+        inv_log_transform,
+        reconstruct_post_pos,
+    )
+    from giant.rollout import decode_secondary_identity
+    from giant.sample import resolve_n_sec, sample_stage1, sample_stage2
+
     batch_size_auto = False
     batch_size_value: Optional[int] = None
     if batch_size.strip().lower() == "auto":
@@ -1343,6 +1386,10 @@ def _seed_from_data(files: list[Path], n_events: int | None) -> dict[str, np.nda
     the codebase's convention for the primary (a secondary always carries less
     energy than its parent). See giant/analysis/reduce.py:entry_axis.
     """
+    import numpy as np
+
+    from giant.data.loader import event_id_offset, iter_cond_chunks
+
     best_E: dict[int, float] = {}
     best: dict[int, tuple] = {}
     for file_idx, path in enumerate(files):
@@ -1447,6 +1494,21 @@ def rollout(
     ] = None,
 ) -> None:
     """Roll the surrogate forward into full showers (autoregressive)."""
+    import time
+
+    import numpy as np
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+    import torch
+    import yaml
+
+    from giant.checkpoint_io import CheckpointCompatibilityError, load_for_inference
+    from giant.data.loader import find_parquet_files
+    from giant.geometry import GeometryOracle
+    from giant.rollout import L1DistCollector, RolloutSummary, rollout as run_rollout
+
+    _t_setup_start = time.perf_counter()
+
     if seed is not None:
         torch.manual_seed(seed)
         np.random.seed(seed)
@@ -1492,9 +1554,11 @@ def rollout(
     # avg_tracks_per_event) — mirrors the row-group streaming `giant predict`
     # already does on its input side.
     writer: pq.ParquetWriter | None = None
+    _write_s = 0.0
 
     def _write_chunk(row: dict[str, np.ndarray]) -> None:
-        nonlocal writer
+        nonlocal writer, _write_s
+        _t0 = time.perf_counter()
         table = pa.table(row)
         if writer is None:
             table = table.replace_schema_metadata(
@@ -1505,11 +1569,14 @@ def rollout(
             )
             writer = pq.ParquetWriter(out, table.schema)
         writer.write_table(table)
+        _write_s += time.perf_counter() - _t0
 
     # Only meaningful under particle_type.target="embedding" — a
     # no-op collector otherwise, cheaper than branching the call itself.
     l1_dist_collector = L1DistCollector()
 
+    _setup_s = time.perf_counter() - _t_setup_start
+    _t_rollout_start = time.perf_counter()
     summary = run_rollout(
         model,
         sec_decoder,
@@ -1541,6 +1608,23 @@ def rollout(
     )
     if writer is not None:
         writer.close()
+    # on_chunk=_write_chunk is always passed above, so rollout() always
+    # returns the streaming-summary shape (RolloutSummary), never the
+    # materialized dict[str, np.ndarray] alternative its return type allows.
+    summary = cast(RolloutSummary, summary)
+    _rollout_s = time.perf_counter() - _t_rollout_start
+    timing = _build_rollout_timing(
+        setup_s=_setup_s,
+        rollout_s=_rollout_s,
+        write_s=_write_s,
+        n_rows=summary["n_rows"],
+        termination_reason_counts=summary["termination_reason_counts"],
+        n_seed_events=len(seeds["event_id"]),
+        device=str(_device),
+        torch_threads=torch.get_num_threads(),
+    )
+    _sample_s = timing["sample_s"]
+    n_physical_rows = timing["n_physical_rows"]
 
     l1_summary = l1_dist_collector.summary()
 
@@ -1563,6 +1647,10 @@ def rollout(
             "rollout_seed": seed,
             "n_rows": summary["n_rows"],
             "termination_reason_counts": summary["termination_reason_counts"],
+            # Wall-clock cost of this run, normalized per physical step (the
+            # comparable unit against giant.analysis.geant4_reference) — see
+            # eval_cost_per_step in giant/analysis/catalog.py.
+            "timing": timing,
             # Diagnostic — only present under
             # stage2_model.particle_type.target="embedding"; omitted (not
             # written as null) otherwise, so giant.analysis can tell "not
@@ -1586,6 +1674,11 @@ def rollout(
 
     typer.echo(f"wrote {summary['n_rows']:,} step rows → {out}")
     typer.echo(f"terminations: {summary['termination_reason_counts']}")
+    if timing["us_per_step"] is not None:
+        typer.echo(
+            f"timing: {_rollout_s:.1f}s total ({_sample_s:.1f}s sample + {_write_s:.1f}s write), "
+            f"{timing['us_per_step']:.1f} us/step over {n_physical_rows:,} physical steps"
+        )
     typer.echo(f"reference: {ref_path}")
 
 

giant/config.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import copy
 import difflib
 import hashlib
@@ -10,12 +12,12 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
-
-import numpy as np
-import torch
+from typing import TYPE_CHECKING
 
 from giant._migration import V02_FIXED_FACTS, V02_MODEL_KEY_TO_STAGES, reject_legacy_router_expert_sizing
-from giant.model.history import HISTORY_REGISTRY
+
+if TYPE_CHECKING:
+    import torch
 
 
 class Conditioning(str, Enum):
@@ -941,6 +943,8 @@ def git_hash() -> str:
 
 
 def auto_device() -> torch.device:
+    import torch
+
     if torch.cuda.is_available():
         return torch.device("cuda")
     if torch.backends.mps.is_available():
@@ -986,6 +990,8 @@ def estimate_batch_size(
     inference (e.g. `predict`), which uses a much lower per-sample memory
     calibration since there's no backward graph or optimizer state.
     """
+    import torch
+
     if device.type != "cuda":
         raise ValueError(f"--batch-size auto is only supported on cuda devices, got {device.type!r}")
     device_index = device.index if device.index is not None else torch.cuda.current_device()
@@ -1680,6 +1686,8 @@ def validate_config(cfg: dict, *, resume: bool = False) -> None:
                 "'energy_desc' (the only implemented ordering; see "
                 "AutoregressiveConfig.order's docstring)"
             )
+        from giant.model.history import HISTORY_REGISTRY
+
         history = _get_path(cfg, "stage2_model.autoregressive.history")
         if history not in HISTORY_REGISTRY:
             raise ValueError(
@@ -1881,6 +1889,9 @@ def resolve_default_out_dir(cfg: dict, base: Path = Path("checkpoints")) -> Path
 
 
 def seed_everything(seed: int) -> None:
+    import numpy as np
+    import torch
+
     random.seed(seed)
     np.random.seed(seed)
     torch.manual_seed(seed)
@@ -1934,6 +1945,8 @@ def build_run_meta(
     n_val_events: int,
     n_train_steps: int,
 ) -> dict:
+    import torch
+
     return {
         "config_version": CONFIG_VERSION,
         "git_hash": git_hash(),

giant/tools/dwarf.py

@@ -5,6 +5,8 @@ simulation-fanout tools into one Typer app so there's a single command name
 (and `--help`) to remember instead of five differently-hyphenated ones.
 """
 
+from __future__ import annotations
+
 import os
 from enum import Enum
 from pathlib import Path
@@ -14,20 +16,15 @@ import typer
 from typing_extensions import Annotated
 
 from giant.config import Conditioning
-from giant.tools.bump_dataset_version import (
-    run_bump_gen,
-    run_bump_schema,
-    run_create_manifest,
-    run_status,
-    run_update_manifest,
-)
-from giant.tools.create_root_files import run_make_root
-from giant.tools.geometry_oracle import run_build_geometry_oracle
-from giant.tools.hparam_scan import DATA_DEFAULT, SCAN_DIR_DEFAULT, run_hparam_scan
-from giant.tools.migrate_geant_steps import run_migration
-from giant.tools.steps_to_parquet import convert_steps_to_parquet
-from giant.tools.steps_to_parquet_parallel import run_parallel_job
-from giant.tools.warm_setup_cache import run_warm_setup_cache
+
+# DATA_DEFAULT/SCAN_DIR_DEFAULT are Typer option defaults (evaluated at
+# decoration time below), so that one name has to stay eager — the module
+# itself is stdlib-only, so it costs nothing. Every other giant.tools.*
+# import here is deferred into the one command body that uses it, since
+# several (steps_to_parquet: uproot/awkward/polars; warm_setup_cache:
+# giant.pipeline -> torch; geometry_oracle: pandas) are expensive and
+# `dwarf --help`/tab-completion shouldn't pay for all of them upfront.
+from giant.tools.hparam_scan import DATA_DEFAULT, SCAN_DIR_DEFAULT
 
 app = typer.Typer(no_args_is_help=True)
 
@@ -121,6 +118,9 @@ def convert(
     ] = None,
 ) -> None:
     """Convert ROOT Steps tree(s) to Parquet."""
+    from giant.tools.steps_to_parquet import convert_steps_to_parquet
+    from giant.tools.steps_to_parquet_parallel import run_parallel_job
+
     if jobs < 1:
         typer.echo("error: --jobs must be >= 1", err=True)
         raise typer.Exit(1)
@@ -183,6 +183,8 @@ def migrate(
     ] = False,
 ) -> None:
     """One-time migration into the versioned raw/processed/pools/derived layout."""
+    from giant.tools.migrate_geant_steps import run_migration
+
     run_migration(str(root), execute=execute, copy=copy)
 
 
@@ -207,6 +209,8 @@ def bump_gen(
     root: Annotated[Path, typer.Option("--root", help="Dataset root")] = _DATASET_ROOT_DEFAULT,
 ) -> None:
     """Cut a new raw generation."""
+    from giant.tools.bump_dataset_version import run_bump_gen
+
     run_bump_gen(
         kind=kind,
         reason=reason,
@@ -240,6 +244,8 @@ def bump_schema(
     root: Annotated[Path, typer.Option("--root", help="Dataset root")] = _DATASET_ROOT_DEFAULT,
 ) -> None:
     """Cut a new schema within a gen."""
+    from giant.tools.bump_dataset_version import run_bump_schema
+
     run_bump_schema(
         kind=kind,
         gen=gen,
@@ -257,6 +263,8 @@ def status(
     root: Annotated[Path, typer.Option("--root", help="Dataset root")] = _DATASET_ROOT_DEFAULT,
 ) -> None:
     """List existing gens/schemas per kind."""
+    from giant.tools.bump_dataset_version import run_status
+
     run_status(str(root))
 
 
@@ -281,6 +289,8 @@ def update_manifest(
     ] = False,
 ) -> None:
     """Repoint manifest(s) to a new gen and/or schema, verifying all target files exist."""
+    from giant.tools.bump_dataset_version import run_update_manifest
+
     run_update_manifest([str(m) for m in manifests], schema=schema, execute=execute, gen=gen)
 
 
@@ -311,6 +321,8 @@ def create_manifest(
     ] = False,
 ) -> None:
     """Create a new manifest from a list of parquet files."""
+    from giant.tools.bump_dataset_version import run_create_manifest
+
     run_create_manifest(
         [str(f) for f in files],
         execute=execute,
@@ -358,6 +370,8 @@ def make_root(
     ] = False,
 ) -> None:
     """Generate new ROOT shards via a minicalosim executable."""
+    from giant.tools.create_root_files import run_make_root
+
     _warn_if_exceeds_shared_quota(jobs, "--jobs")
     run_make_root(
         executable=executable,
@@ -423,6 +437,8 @@ def build_geometry_oracle(
     ] = 2000,
 ) -> None:
     """Fit a position -> (material, layer_id) oracle for `giant rollout`."""
+    from giant.tools.geometry_oracle import run_build_geometry_oracle
+
     run_build_geometry_oracle(
         data=data,
         out=out,
@@ -515,6 +531,8 @@ def warm_cache(
     such entry across every run) skips straight to training. See
     giant/data/setup_cache.py.
     """
+    from giant.tools.warm_setup_cache import run_warm_setup_cache
+
     flag_overrides = {
         "--val-fraction": val_fraction,
         "--seed": seed,
@@ -557,6 +575,8 @@ def hparam_scan(
     dry_run: Annotated[bool, typer.Option("--dry-run")] = False,
 ) -> None:
     """Grid-scan dropout x n_blocks x hidden_dim via sequential `giant train` runs."""
+    from giant.tools.hparam_scan import run_hparam_scan
+
     run_hparam_scan(data=data, scan_dir=scan_dir, seed=seed, dry_run=dry_run)
 
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "giant"
-version = "0.3.13"
+version = "0.3.16"
 description = "Geant4 step-function surrogate via conditional flow matching"
 readme = "README.md"
 requires-python = ">=3.12"

tests/test_catalog.py

@@ -261,3 +261,32 @@ def test_sec_count_per_step_by_species_zero_row_is_per_species(bundle):
     for j, _ in enumerate(cols):
         if j != g:
             assert ref[0][j] == 3 and sum(row[j] for row in ref[1:]) == 0
+
+
+# ---------------------------------------------------------------------------
+# eval_cost_per_step
+# ---------------------------------------------------------------------------
+
+
+def test_eval_cost_per_step_unavailable_without_timing(bundle: Bundle):
+    # `bundle`'s RolloutSpec carries no `timing` -> no rollout to compare.
+    spec = get_spec("eval_cost_per_step")
+    r = spec.finalize([spec.compute_partial(bundle)], bundle.ctx)
+    assert r.kind == "unavailable"
+    assert r.payload["note"]
+
+
+def test_eval_cost_per_step_bar_with_timing(ctx: Context):
+    spec = get_spec("eval_cost_per_step")
+    rs = RolloutSpec(
+        "rollout",
+        _rollout_frame(),
+        timing={"us_per_step": 12.5, "write_us_per_step": 2.5},
+    )
+    b = Bundle.open([rs], _reference_frame(), ctx)
+    r = spec.finalize([spec.compute_partial(b)], ctx)
+    assert r.kind == "bar"
+    assert r.payload["series"]["rollout"] == [12.5, 2.5, 15.0]
+    assert len(r.payload["reference"]) == 3
+    assert r.payload["log_y"] is True
+    assert "rollout" in r.meta["speedup_vs_geant4_total"]

tests/test_cli_rollout.py

@@ -8,11 +8,52 @@ from __future__ import annotations
 import torch
 from typer.testing import CliRunner
 
-from giant.cli import app
+from giant.cli import _build_rollout_timing, app
 
 runner = CliRunner()
 
 
+def test_build_rollout_timing_excludes_synthetic_rows_from_per_step_cost():
+    # 100 rows total, 30 of them synthetic termination markers (escape) ->
+    # us_per_step should be normalized over the 70 physical rows only, the
+    # same unit giant.analysis.geant4_reference measures Geant4 in.
+    timing = _build_rollout_timing(
+        setup_s=1.0,
+        rollout_s=10.0,
+        write_s=2.0,
+        n_rows=100,
+        termination_reason_counts={"escaped": 30, "natural_end": 70},
+        n_seed_events=5,
+        device="cpu",
+        torch_threads=4,
+    )
+    assert timing["n_rows"] == 100
+    assert timing["n_physical_rows"] == 70
+    assert timing["n_physical_rows"] < timing["n_rows"]
+    assert timing["sample_s"] == 8.0  # rollout_s - write_s
+    assert timing["us_per_step"] == 8.0 / 70 * 1e6
+    assert timing["write_us_per_step"] == 2.0 / 70 * 1e6
+    assert timing["ms_per_event"] == 10.0 / 5 * 1e3
+    assert timing["device"] == "cpu" and timing["torch_threads"] == 4
+
+
+def test_build_rollout_timing_handles_zero_physical_rows_and_events():
+    timing = _build_rollout_timing(
+        setup_s=1.0,
+        rollout_s=1.0,
+        write_s=0.0,
+        n_rows=5,
+        termination_reason_counts={"escaped": 5},
+        n_seed_events=0,
+        device="cpu",
+        torch_threads=1,
+    )
+    assert timing["n_physical_rows"] == 0
+    assert timing["us_per_step"] is None
+    assert timing["write_us_per_step"] is None
+    assert timing["ms_per_event"] is None
+
+
 def test_rollout_exits_1_on_checkpoint_missing_model_config(tmp_path):
     checkpoint = tmp_path / "bad.pt"
     torch.save({"sec_decoder": {}, "normalizer": {"sec_phys": {}}}, checkpoint)

tests/test_cli_train_overrides.py

@@ -20,7 +20,7 @@ def _invoke_and_capture_cfg(monkeypatch, tmp_path: Path, args: list[str]) -> dic
     def _fake_run_train_job(*, data, cfg, out_dir, **kwargs):
         captured["cfg"] = cfg
 
-    monkeypatch.setattr(cli, "run_train_job", _fake_run_train_job)
+    monkeypatch.setattr("giant.pipeline.run_train_job", _fake_run_train_job)
 
     result = runner.invoke(
         cli.app,
@@ -125,7 +125,7 @@ def test_stage2_init_from_and_freeze_flags_land_in_cfg_and_dont_touch_stage1(mon
 
 
 def test_batch_size_invalid_string_errors(monkeypatch, tmp_path):
-    monkeypatch.setattr(cli, "run_train_job", lambda *a, **kw: None)
+    monkeypatch.setattr("giant.pipeline.run_train_job", lambda *a, **kw: None)
     result = runner.invoke(
         cli.app,
         ["train", "dummy.parquet", "--out", str(tmp_path / "run"), "--batch-size", "not-a-number"],
@@ -140,7 +140,7 @@ def test_out_dir_resolution_prefers_explicit_out_over_resume(monkeypatch, tmp_pa
     def _fake_run_train_job(*, data, cfg, out_dir, **kwargs):
         captured["out_dir"] = out_dir
 
-    monkeypatch.setattr(cli, "run_train_job", _fake_run_train_job)
+    monkeypatch.setattr("giant.pipeline.run_train_job", _fake_run_train_job)
 
     resume_dir = tmp_path / "resumed_run"
     resume_dir.mkdir()
@@ -161,7 +161,7 @@ def test_out_dir_resolution_falls_back_to_resume_parent(monkeypatch, tmp_path):
     def _fake_run_train_job(*, data, cfg, out_dir, **kwargs):
         captured["out_dir"] = out_dir
 
-    monkeypatch.setattr(cli, "run_train_job", _fake_run_train_job)
+    monkeypatch.setattr("giant.pipeline.run_train_job", _fake_run_train_job)
 
     resume_dir = tmp_path / "resumed_run"
     resume_dir.mkdir()
@@ -178,7 +178,7 @@ def test_out_dir_resolution_defaults_when_neither_out_nor_resume_given(monkeypat
     def _fake_run_train_job(*, data, cfg, out_dir, **kwargs):
         captured["out_dir"] = out_dir
 
-    monkeypatch.setattr(cli, "run_train_job", _fake_run_train_job)
+    monkeypatch.setattr("giant.pipeline.run_train_job", _fake_run_train_job)
     monkeypatch.chdir(tmp_path)
 
     result = runner.invoke(cli.app, ["train", "dummy.parquet"])
@@ -192,7 +192,7 @@ def test_batch_size_auto_estimates_and_echoes(monkeypatch, tmp_path):
     def _fake_run_train_job(*, data, cfg, out_dir, num_workers, **kwargs):
         captured["batch_size"] = cfg["train"]["batch_size"]
 
-    monkeypatch.setattr(cli, "run_train_job", _fake_run_train_job)
+    monkeypatch.setattr("giant.pipeline.run_train_job", _fake_run_train_job)
     monkeypatch.setattr(cli.gconfig, "estimate_batch_size", lambda hidden_dim, n_blocks, device: 123)
 
     result = runner.invoke(

tests/test_condor.py

@@ -252,6 +252,22 @@ def test_compute_one_from_run_dir(tmp_path: Path):
     assert list(partial.data["r"]) == ["rollout"]
 
 
+def test_timing_survives_plot_meta_to_compute_one(tmp_path: Path):
+    yaml_path = _write_inputs(tmp_path)
+    d = yaml.safe_load(yaml_path.read_text())
+    d["timing"] = {"us_per_step": 7.0, "write_us_per_step": 1.0}
+    yaml_path.write_text(yaml.safe_dump(d))
+
+    run_dir = _prep([yaml_path])
+    meta = RunMeta.load(run_dir / "run_meta.json")
+    assert meta.rollouts[0]["plot_meta"]["timing"] == {"us_per_step": 7.0, "write_us_per_step": 1.0}
+
+    out = compute_one("eval_cost_per_step", run_dir)
+    reduced = Reduced(**Partial.load(out).data["reduced"])
+    assert reduced.kind == "bar"
+    assert reduced.payload["series"]["rollout"] == [7.0, 1.0, 8.0]
+
+
 def test_compute_reduced_explicit_paths(tmp_path: Path):
     run_dir = _prep([_write_inputs(tmp_path)])
     meta = RunMeta.load(run_dir / "run_meta.json")

tests/test_render.py

@@ -292,6 +292,20 @@ def test_render_one_of_each_kind(tmp_path: Path):
                 "ylabel": "frac",
             },
         ),
+        Reduced(
+            "cost",
+            "cost",
+            "bar",
+            "Cost",
+            "phase",
+            {
+                "labels": ["sample", "write", "total"],
+                "series": {"flow": [10.0, 1.0, 11.0]},
+                "reference": [5.0, 0.5, 5.5],
+                "ylabel": "us/step",
+                "log_y": True,
+            },
+        ),
         Reduced(
             "s",
             "species",

uv.lock

@@ -675,7 +675,7 @@ wheels = [
 
 [[package]]
 name = "giant"
-version = "0.3.13"
+version = "0.3.16"
 source = { editable = "." }
 dependencies = [
     { name = "numpy" },