K4GeneratorsConfig: Monte Carlo Benchmarking Tool

• K4GeneratorsConfig is a Python-based configuration package that standardizes Monte Carlo event-generator studies for future e+e- colliders.
• It employs a generator-independent YAML input to automatically translate physics parameters into specific run cards and scripts.
• The tool ensures consistency and reproducibility across generator comparisons and integrates seamlessly with the Key4hep software stack.

K4GeneratorsConfig, presented in the literature as k4GeneratorsConfig, is a Python-based configuration and benchmarking package for Monte Carlo event-generator studies for future $e^+e^-$ colliders. Its defining feature is a generator-independent YAML input that specifies the intended physics content—such as beam energy, final states, ISR settings, polarization, beamstrahlung, cuts, model parameters, and analysis requests—and is then translated automatically into generator-specific run cards, scripts, and auxiliary files. The package is designed to make comparisons between generators consistent, reproducible, and less error-prone, and it is available both standalone and integrated into the Key4hep software stack, including support for conversion to EDM4hep (Price et al., 24 Sep 2025).

1. Motivation and intended scope

The package was developed in the context of next-generation electron–positron colliders, including circular or linear machines such as FCC, CEPC, ILC/LCF, and CLIC, where realistic event simulation is part of a broader software chain used to evaluate detector concepts and benchmark physics performance. In that setting, Monte Carlo generators are central to the simulation of Standard Model processes, but practical generator comparisons are often compromised by inconsistent setups, hand-written cards, software-version drift, and subtle mismatches in electroweak inputs, cuts, beam configurations, or technical defaults (Price et al., 24 Sep 2025).

The problem addressed by K4GeneratorsConfig is therefore not generic event generation in isolation, but the technical comparison of generators in domains where agreement is expected. The paper is explicit that the framework is intended for cases in which several generators can simulate the same Standard Model process at the same nominal perturbative accuracy and where one wishes to determine whether observed differences are physical or merely technical. This also clarifies a frequent misconception: the package is not presented as a framework for comparing the full physics sophistication of different codes. Rather, it is a diagnostic infrastructure for enforcing equivalent assumptions and exposing implementation or configuration mismatches.

Within that scope, the package targets several recurrent failure modes: inconsistent generator setups across tools even when “the same process” is intended; poor reproducibility, especially when software-stack versions or nightlies change; incorrect translation of common physics inputs into generator-specific options; human error in hand-maintained cards and scripts; and difficulty in identifying whether generator differences arise from real physics or from technical configuration mismatches.

2. Generator-independent configuration model

The central configuration object is a YAML input file. The main keys listed in the paper are Generators, Model, SqrtS, Events, RandomSeed, OutDir, OutputFormat, EventMode, NLO, EWParamDevThreshold, PolarisationDensity, PolarisationFraction, Beamstrahlung, Processes, ParticleData, Selectors, and Analysis. All keys are case-insensitive and are internally converted to lowercase (Price et al., 24 Sep 2025).

This YAML model is the package’s “single source of truth” for physics configuration. Each process is assigned a user-defined ProcessName, and a process entry includes at least a final-state specification, for example PDG IDs under Final. A process may also override global settings such as RandomSeed or ISRMode. The paper notes that one YAML file can therefore describe multiple processes and multiple energies, which is important for batch-style technical scans.

A representative example given in the paper is:

$m_\textrm{W}$8

This example illustrates the intended usage pattern: universal physics inputs are declared once, while generator-specific artifacts are derived automatically. The paper also defines allowed values for OutputFormat as edm4hep, hepmc3, or lhe, and for EventMode as weighted or unweighted.

3. Software architecture and translation layer

The implementation is mainly in Python, with a C++ component for conversion into the Key4hep event data model. The architecture uses dynamic loading and an object-oriented structure with shallow inheritance. The core modules identified in the paper are the Parameters module, which manages a global set of Standard Model and derived parameters; the Process module, which interprets beam particles, final states, labels, and process metadata; the Generators module, which dispatches to generator-specific translation code and builds datacards and execution scripts; GeneratorBase, which provides shared backend behavior; and the optional GeneratorProcDB and ProcDBBase, which carry generator- and process-specific standard options (Price et al., 24 Sep 2025).

The package’s modularity is driven by Python importlib. The framework expects a generator-specific module/class name match, so adding a new generator requires implementing the corresponding module and class without modifying the steering module itself. This is the core extensibility mechanism.

The translation layer operates as follows. First, the Process module resolves initial and final state particles and creates a process label based on unsigned PDG IDs. Second, the Generators module dynamically loads each requested backend. Third, for every combination of generator, process, and center-of-mass energy, a dedicated output directory is created,

$\texttt{OutDir/Generator/ProcessName[\_ecms]},$

with the energy in MeV appended if multiple energies are requested. Fourth, the backend builds the run card in memory, applies generator-specific formatting and option syntax, and writes the datacard, a shell script to run the generator in the Key4hep environment, and optionally an auxiliary file for generator-specific cut structures.

The paper distinguishes two backend styles. For Madgraph, Pythia, Whizard, and Babayaga, datacards are generated on the fly. For KKMCee, a template file is loaded and only predefined settings are changed via string replacement. This distinction is operationally important because it constrains how much dynamic configuration can be injected into different backends.

The package also defines explicit precedence rules. YamlInput overrides GeneratorProcDB process defaults. For particle properties, ParameterSets override GeneratorProcDB, and YamlInput overrides ParameterSets. In addition, there is a generator-specific escape hatch of the form

$\texttt{Generator:Key:Value},$

which takes priority over common keys but may create untested or inconsistent configurations.

4. Physics parameterization and formal inputs

A major design feature is the treatment of electroweak parameters. The package adopts $G_F$, $m_\textrm{W}$, and $m_\textrm{Z}$ as its main electroweak input scheme because many generators support it directly. The paper notes that others, such as KKMCee and Pythia, require the electroweak mixing angle instead. Rather than translating schemes on the fly with additional radiative-correction assumptions, the package extends its parameter set to include derived parameters as well (Price et al., 24 Sep 2025).

The supported parameters include $G_F$; $m_\textrm{W}$, $m_\textrm{Z}$, $m_\textrm{H}$, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$0, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$1; widths $\texttt{OutDir/Generator/ProcessName[\_ecms]},$2, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$3, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$4, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$5; $\texttt{OutDir/Generator/ProcessName[\_ecms]},$6; $\texttt{OutDir/Generator/ProcessName[\_ecms]},$7, $\texttt{OutDir/Generator/ProcessName[\_ecms]},$8, and LO variants; $\texttt{OutDir/Generator/ProcessName[\_ecms]},$9, $\texttt{Generator:Key:Value},$0, $\texttt{Generator:Key:Value},$1; $\texttt{Generator:Key:Value},$2; and the Yukawas $\texttt{Generator:Key:Value},$3 and $\texttt{Generator:Key:Value},$4. The paper gives the relations

$\texttt{Generator:Key:Value},$5

and

$\texttt{Generator:Key:Value},$6

A leading-order consistency cross-check is implemented using tree-level relations among $\texttt{Generator:Key:Value},$7, $\texttt{Generator:Key:Value},$8, $\texttt{Generator:Key:Value},$9, $G_F$0, $G_F$1, $G_F$2, and $G_F$3. If any relative deviation exceeds EWParamDevThreshold, a warning is emitted; the default threshold is $G_F$4, i.e. one per mille.

For beam configuration, the package supports beamstrahlung via Beamstrahlung, with the paper mentioning use of CIRCE for some collider setups and generator-specific implementations for others. It also supports longitudinal beam polarization through PolarisationDensity, defined as a list of two integers indicating polarization states of the incoming beams, and PolarisationFraction, defined as the average polarization values for the two beams. The current implementation is limited to longitudinal polarization, reflecting the common subset supported by multiple generators.

Processes are specified through initial-state $G_F$5 beams and final-state PDG IDs. The common representation is therefore based on final-state identity, ISR choice, and optional cuts, rather than generator-specific process syntax. Supported cuts are expressed via Selectors and include PT, ET, Energy, Rapidity, Eta, Theta, Mass, Angle, DeltaEta, DeltaRapidity, DeltaPhi, DeltaR, and Flavour. For composite variables such as invariant mass or angular differences, two PDG IDs must be provided.

5. Supported generators, execution model, and reproducibility infrastructure

The paper explicitly mentions support for Sherpa, Whizard, Madgraph, KKMCee / KKMC, Pythia, and Babayaga. The package is designed so that additional generators can be supported by implementing a backend module/class. Supported output formats are edm4hep (the default), hepmc3, and lhe. Within Key4hep, generated events can be converted to EDM4hep, enabling standardized downstream analysis (Price et al., 24 Sep 2025).

Two analysis routes are integrated. Rivet is used for supported event formats such as HepMC. A Key4hep/ROOT-based truth analysis produces predefined distributions and summaries. The package generates shell scripts assuming execution in the Key4hep environment with access to cvmfs, although the paper states that these scripts can be modified for local installations.

The package installs shell setup scripts that define the executable alias k4GeneratorsConfig. The required positional argument is the YAML input path. The command-line options listed in the paper are --nevts, --seed, --ecms, --ecmsFiles, --parameterTag, --parameterTagFile, --key4hepVersion, and --key4hepUseNightlies. These allow runtime overrides of event count, random seed, energy scan points, parameter set choice, and exact software-stack version. The ability to request a Key4hep release by date or to use dated nightlies is described as an explicit reproducibility feature.

Reproducibility is also embedded in the software-engineering workflow. The package is tested with GitHub Actions in a CI pipeline using a Key4hep software stack. The tests validate runcard generation, translation of physics input into generator-specific formats, reproducibility and consistency across generators, and compatibility across platforms. This makes benchmarking not only a user-facing workflow but also part of automated validation infrastructure.

6. Benchmarking methodology, empirical findings, and limitations

The benchmarking procedure generates equivalent samples from multiple generators and compares both inclusive and differential quantities. For every requested process, generator, and $G_F$6, the package creates a dedicated directory with the necessary datacard and execution script. Batch processing follows naturally because a single YAML file may contain multiple generators, multiple processes, multiple energies, and optional analyses to run automatically afterward. The principal observables are cross sections, extracted from output files or metadata and compared as functions of $G_F$7, and differential distributions produced via Rivet or Key4hep truth analysis (Price et al., 24 Sep 2025).

The paper gives specific examples of differential observables: invariant mass of final-state lepton pairs, polar-angle distributions, $G_F$8 of final-state particles in the lab frame, and, for all two-particle combinations, invariant mass, transverse momentum, and longitudinal momentum. The Key4hep summary overlays all generators with fixed colors and symbols and also shows deviation from the average. For histogram-level comparisons, each bin is compared to the average over generators, with agreement assessed using statistical uncertainties and a $G_F$9 measure.

The reported validation results are concrete. For LO $m_\textrm{W}$0 production as a function of $m_\textrm{W}$1, Madgraph, Sherpa, and Whizard are in excellent agreement, better than one per mille, while Madgraph and Whizard agree at the level of a tenth of a per mille. Pythia is off at about the percent level in that comparison. The paper attributes this to the fact that Pythia requires an input value for the effective electroweak mixing angle, and that the translation from the package’s chosen electroweak scheme is not suitable for a true LO comparison because Pythia expects a $m_\textrm{W}$2 that includes radiative corrections. The paper therefore concludes that a true leading-order benchmark should not include Pythia in that specific comparison.

For the $m_\textrm{W}$3-boson polar-angle distribution at $m_\textrm{W}$4, the paper reports that all generators are compatible with the average within statistical error and that the corresponding $m_\textrm{W}$5 values are similar and below $m_\textrm{W}$6. Beyond agreement studies, the framework also had clear diagnostic value: it helped identify incomplete configuration of a generator inside Key4hep found via platform-dependent CI behavior, generators failing to write cross sections, a rounding issue causing rejection of events over a range of $m_\textrm{W}$7, and ISR/boost inconsistencies causing event rejection at the shower/hadronization stage.

The paper is equally explicit about limitations. The common YAML interface necessarily covers only the shared feature set among generators. Generator-specific overrides may be required for uncommon options, but these can bypass validation and produce untested setups. Polarization support is currently limited to longitudinal polarization. Some generators, notably KKMCee, rely on template-based configuration rather than full dynamic option insertion. Electroweak scheme translation is not universally exact, especially for generators that expect effective parameters including radiative effects. The package is described as an alpha release, even though it is already integrated with Key4hep.

The stated future directions are to extend automated tests in the Key4hep CI pipeline, include more state-of-the-art generator predictions, broaden the process coverage of the validation suite, compare different versions of the same generator to localize regressions, and continue strengthening reproducibility across software releases and nightlies. This suggests a long-term role as an independent, framework-level validation layer complementing the validation efforts of individual generator authors.