Skip to main content

k4Bench — detector-agnostic performance benchmarking for Key4hep

Detector-agnostic performance benchmarking for Key4hep simulations
👉 Open the live dashboard  ·  📖 Read the docs


Release Build status codecov DOI


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.

Metadata

Release files for k4bench 0.0.47

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for k4bench 0.0.47
File Size Uploaded Provenance Actions
k4bench-0.0.47.tar.gz 1.1 MB With provenance Details for k4bench-0.0.47.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for k4bench 0.0.47
File Interpreter ABI Platform Actions
k4bench-0.0.47-py3-none-any.whl Python 3 none any Details for k4bench-0.0.47-py3-none-any.whl

Total release size: 1.6 MB

Release files / k4bench-0.0.47.tar.gz

Download URL k4bench-0.0.47.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
d1a8103dc0bffe1d68765319fd43e8ddaa8300409514058bdc708f27cae2f9b7
BLAKE2b-256 checksum
How to use checksums
d105df8647197dfe470f3198df9384e18fae8183d2dc18a9a1e39aaaf649b2af
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 Oct 10, 2026.

Transparency log

Release files / k4bench-0.0.47-py3-none-any.whl

Download URL k4bench-0.0.47-py3-none-any.whl
Size 421.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ef6e3a5a25d1bac85368e18912073f35c261f9f5c59cc2bf0aafc978fd25948a
BLAKE2b-256 checksum
How to use checksums
c5b6cf0746d85c8dbd052b936baaae7c5f6e05e6f50d6ca6cc809a4a950f0da8
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 Oct 10, 2026.

Transparency log

Security for k4bench 0.0.47

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for k4bench-0.0.47.tar.gz

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 Oct 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.47 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page