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.48

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.48
File Size Uploaded Provenance Actions
k4bench-0.0.48.tar.gz 1.2 MB With provenance Details for k4bench-0.0.48.tar.gz

Built distribution (wheel)

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

Total release size: 1.6 MB

Release files / k4bench-0.0.48.tar.gz

Download URL k4bench-0.0.48.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
2956f5fa8d8c68002cc11b6bc1a099fdd61b94bc0348d57bf922df8d6f94537b
BLAKE2b-256 checksum
How to use checksums
5100aed3be332f413a606a022d7900a342a035bc9fd78f802e693e1a969afe2a
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.48-py3-none-any.whl

Download URL k4bench-0.0.48-py3-none-any.whl
Size 424.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3b0711399f71cd2f5f4c95e249726a353b6f0d9ae21d1ad4f54a49ae7a939459
BLAKE2b-256 checksum
How to use checksums
7c5c3d37a7e94ee2ffb2147e8229a5e85a753f94aa3b069a822e857f72eb5296
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.48

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.48.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.48 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