Detector-agnostic performance benchmarking for Key4hep simulations
👉 Open the live dashboard · 📖 Read the docs
k4Bench measures where the time and memory go in DD4hep / Geant4 detector
simulations run through ddsim in the Key4hep stack.
Point it at any DD4hep compact geometry and it will tell you how long a simulation takes, how much memory it needs, and — crucially — which subdetector is responsible. It does this without you editing a single XML file or recompiling anything.
What it does
- ⚡ Geometry sweeps — automatically run a baseline, then re-run with each subdetector removed (or only a chosen subset kept) to measure each detector's cost. The original geometry is never touched.
- ⏱️ Per-event & per-detector timing — C++ Geant4 timing plugins record per-event wall time, RSS memory, and per-subdetector stepping time.
- 📊 Analysis & dashboard — load results into pandas, plot them with the bundled helpers, or browse historical trends across Key4hep releases on the live dashboard.
- 🔭 Detector-agnostic — works on any DD4hep compact XML. FCC-ee detectors (ALLEGRO, IDEA, ILD_FCCee, CLD) and DD4hep's own SiD example are the worked examples and nightly-CI targets, not a limit.
Quick start
The recommended install is from source, so the C++ timing plugins are built and you get the full set of metrics:
# 1. Clone the repository
git clone https://github.com/key4hep/k4Bench.git
cd k4Bench
# 2. Source setup.sh to source Key4hep, make a CVMFS-aware venv, install deps,
# build the timing plugins, and install pre-commit hooks.
source setup.sh
# 3. Install the k4bench command (editable)
pip install --no-build-isolation -e .
# 4. Benchmark a geometry (single particle-gun run)
k4bench --xml $K4GEO/FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03.xml \
--events 100 \
--ddsim-args="--enableGun --gun.particle e- --gun.distribution uniform"
Want to know each subdetector's cost? Add --sweep:
k4bench --xml ALLEGRO_o1_v03.xml --sweep \
--ddsim-args="--enableGun --gun.particle e- --gun.distribution uniform"
Results print as a summary table and are written as CSV (plus per-event /
per-region JSON) under logs/<geometry>/.
Also on PyPI:
pip install k4bench --no-deps(inside Key4hep) gives you run-level metrics, but not the C++ timing plugins — so per-event and per-detector timing are unavailable. Installing from source is recommended.
Analyse and plot the results
The bundled analysis helpers load a run directory into pandas and produce ready-made Plotly figures:
from k4bench.analysis import load_results, plot_run_overview
df = load_results("logs/ALLEGRO_o1_v03") # one row per run
plot_run_overview("logs/ALLEGRO_o1_v03").show() # bar charts across runs
Documentation
Full documentation — installation, every CLI option, the sweep modes, the timing plugins, the architecture, and the dashboard — lives at:
📖 https://key4hep.github.io/k4Bench/
| I want to… | Start here |
|---|---|
| Install and run my first benchmark | Getting started |
| Understand sweep modes & options | User guide |
| Understand how it works | Architecture |
License
Distributed under the terms of the LICENSE in this repository.
1 maintainer
Metadata
1 maintainer
Release files for k4bench 0.0.31
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| k4bench-0.0.31.tar.gz | 751.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| k4bench-0.0.31-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / k4bench-0.0.31.tar.gz
| Download URL | k4bench-0.0.31.tar.gz |
|---|---|
| Size | 751.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a81c346fe0a931dd24feb21cfe4de237a2da5fc1d004a369d94df7cb36c77a1
|
|
BLAKE2b-256 checksum How to use checksums |
80298cff46b2cdd91dd61744b9baf086519c7173e2568fc9f6037b131086849f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.
Transparency logRelease files / k4bench-0.0.31-py3-none-any.whl
| Download URL | k4bench-0.0.31-py3-none-any.whl |
|---|---|
| Size | 278.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e1dd1f72b7d313214cff23369d180a3709d22508f9c543a0db6bd20f25e47de
|
|
BLAKE2b-256 checksum How to use checksums |
8b004a1916af12c5ff9f837e686bdb9daaac80b0490f5349516ffbcdd2281e27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.
Transparency log
