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

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.50
File Size Uploaded Provenance Actions
k4bench-0.0.50.tar.gz 1.3 MB With provenance Details for k4bench-0.0.50.tar.gz

Built distribution (wheel)

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

Total release size: 1.8 MB

Release files / k4bench-0.0.50.tar.gz

Download URL k4bench-0.0.50.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
b5b7c319b461b026e339d97addd85e911524168aa0f6fee82f0a3a3bec36025b
BLAKE2b-256 checksum
How to use checksums
c1dad1b902627ffc13dc423c8becf954cf1e0053b306f603de7815cf2b720da5
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 17, 2026.

Transparency log

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

Download URL k4bench-0.0.50-py3-none-any.whl
Size 454.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a11a90b5c96622c49a3baca9478543982bcff18ac7ee8599ed68a6391a6fca0
BLAKE2b-256 checksum
How to use checksums
67d7d6473cd4dcfe7df81230d22504baac554378b0ab8e51bee7fcfde3565269
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 17, 2026.

Transparency log

Security for k4bench 0.0.50

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.50.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 17, 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.50 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