`k4bench.benchmark.ddsim`¶

k4bench.benchmark.ddsim ¶

Benchmark ddsim across geometry configurations.

This module is the top-level orchestrator. It wires together:

:mod:k4bench.geometry.scanner — discover subdetector names
:mod:k4bench.geometry.patcher — produce patched XML files
:mod:k4bench.runner.executor — time each ddsim run
:mod:k4bench.results.model — collect results

All runs are sequential. Parallel execution would skew wall-time and RSS metrics because competing processes share CPU, cache, and memory

Sweep modes

FULL Baseline (full geometry) + one run per subdetector with that detector removed. INCLUDE_ONLY Single run with only the named detectors active (all others removed). No baseline. EXCLUDE_ONLY Single run with the named detectors removed (all others active). No additional baseline. Empty detector_names falls back to a full-geometry run.

SweepMode ¶

Bases: Enum

Selects which benchmark strategy :func:run_sweep executes.

BenchmarkConfig `dataclass` ¶

BenchmarkConfig(xml_path: Path, n_events: int, output_file: Path, log_dir: Path, mode: SweepMode = FULL, detector_names: list[str] = list(), setup_script: Path | None = None, extra_args: list[str] = list(), verbose: bool = False)

All parameters needed to run a benchmark sweep.

Parameters:

Name	Type	Description	Default
`xml_path`	`Path`	Top-level compact XML for the primary geometry.	required
`n_events`	`int`	Number of events to simulate per run.	required
`output_file`	`Path`	Temporary EDM4hep ROOT file written by ddsim. Reused across runs (overwritten each time); only its size at run-end matters.	required
`log_dir`	`Path`	Directory where per-run `.log` files are written.	required
`mode`	`SweepMode`	Which benchmark strategy to execute; see :class:`SweepMode`.	`FULL`
`detector_names`	`list[str]`	For `INCLUDE_ONLY` — simulate with only these detectors active. For `EXCLUDE_ONLY` — simulate with all detectors except these. Ignored for `FULL` mode.	`list()`
`setup_script`	`Path \| None`	Optional shell script sourced before each ddsim invocation.	`None`
`extra_args`	`list[str]`	Additional ddsim arguments passed verbatim to every run (e.g. `["--runType=batch", "--enableGun", "--gun.particle", "e-"]`).	`list()`
`verbose`	`bool`	If True, print ddsim stdout in real time instead of buffering until run-end.	`False`

run_sweep ¶

run_sweep(config: BenchmarkConfig) -> list[RunResult]

Execute a benchmark sweep and return all results.

Dispatches to the appropriate strategy based on config.mode. Failed ddsim runs are marked with a non-zero return code and included in the results; the sweep always continues to completion.

Parameters:

Name	Type	Description	Default
`config`	`BenchmarkConfig`	All parameters for the sweep; see :class:`BenchmarkConfig`.	required

Returns:

Type	Description
`list[RunResult]`	Results in execution order.

Source code in k4bench/benchmark/ddsim.py

def run_sweep(config: BenchmarkConfig) -> list[RunResult]:
    """Execute a benchmark sweep and return all results.

    Dispatches to the appropriate strategy based on ``config.mode``.
    Failed ddsim runs are marked with a non-zero return code and
    included in the results; the sweep always continues to completion.

    Parameters
    ----------
    config:
        All parameters for the sweep; see :class:`BenchmarkConfig`.

    Returns
    -------
    list[RunResult]
        Results in execution order.
    """
    config.log_dir.mkdir(parents=True, exist_ok=True)

    if config.mode == SweepMode.BASELINE:
        return _run_baseline(config)
    elif config.mode == SweepMode.INCLUDE_ONLY:
        return _run_include_only_sweep(config)
    elif config.mode == SweepMode.EXCLUDE_ONLY:
        return _run_exclude_only_sweep(config)
    else:
        return _run_removal_sweep(config)

k4bench.benchmark.ddsim¶