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

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.45
File Size Uploaded Provenance Actions
k4bench-0.0.45.tar.gz 1.1 MB With provenance Details for k4bench-0.0.45.tar.gz

Built distribution (wheel)

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

Total release size: 1.5 MB

Release files / k4bench-0.0.45.tar.gz

Download URL k4bench-0.0.45.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
95ec510bcc62970dd83f820a2904b03063caa5fc15ca568a8c943c56e63f4def
BLAKE2b-256 checksum
How to use checksums
fbf3533446f44aeda08638f381b76e057b6c11d0cd86af6c4ebfa77ccc103bd5
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 5, 2026.

Transparency log

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

Download URL k4bench-0.0.45-py3-none-any.whl
Size 403.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5da1f4c4d816681ff83634246d479a2505f46be931f4311b7b9caf7e7422ba01
BLAKE2b-256 checksum
How to use checksums
84389a094838cfcd1ce5d958156ca4d197fcd677cb6ca1a2bcabb0fef723a158
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 5, 2026.

Transparency log

Security for k4bench 0.0.45

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.45.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 5, 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.45 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