MAGE-HEP: Reproducible Monte Carlo Analysis

• MAGE-HEP is a GUI-driven workflow environment designed for reproducible, structured generator-level analyses in high-energy physics.
• It uses a three-level project-study-run hierarchy to separate configuration, execution, and output for enhanced reproducibility.
• Its Node API translates handwritten scripts into portable C++/ROOT code, streamlining analysis and ensuring code inspectability.

Searching arXiv for the specified paper and closely related HEP workflow context. MAGE-HEP, short for Monte Carlo Analysis and Graphical Environment for High-Energy Physics, is a GUI-driven workflow environment for reproducible Monte Carlo-based analyses in high-energy physics. It is designed as a workflow and context layer on top of established tools such as PYTHIA8, ROOT, Rivet, HepMC, and preservation platforms, rather than as a replacement for them. Its central contribution is to turn a generator-level analysis from an ad hoc collection of handwritten scripts into a structured, inspectable, and portable object organized through a project-study-run hierarchy, with a Node API for defining generator configurations, observables, selections, stores, and output rules, and with exportable .mcx and .mgp bundles for reuse and portability (Gupta et al., 18 May 2026).

1. Conceptual scope and problem setting

Monte Carlo event generators are central to high-energy physics analysis, but workflows based on handwritten scripts can be difficult to reuse, modify, and reproduce when multiple Monte Carlo models, tune variations, run variations, and output formats are involved. MAGE-HEP targets this specific failure mode of generator-level analysis practice: users often mix generator settings, event loops, particle cuts, histogram definitions, output naming, random seeds, and job management in one-off files, which may suffice for an initial study but become difficult to modify or repeat across controlled variations (Gupta et al., 18 May 2026).

The framework addresses this by making the analysis definition itself a reusable object and by separating reusable study logic from concrete executions. This suggests that the principal abstraction in MAGE-HEP is not the output ROOT file alone, but the full analysis context: generator configuration, analysis recipe, observable definitions, selections, output mapping, generated code, and version metadata. A plausible implication is that the framework treats workflow provenance as a first-class analysis artifact rather than as ancillary documentation.

The paper explicitly positions MAGE-HEP as a generator-level environment. Its current beta implementation validates the architecture on a PYTHIA8 + ROOT workflow, where PYTHIA8 provides event generation and ROOT provides histogramming, output files, and GUI-side plot inspection. The generated code is ordinary C++/ROOT analysis code, so the framework does not lock users into the GUI runtime after code generation (Gupta et al., 18 May 2026).

2. Project-study-run architecture

At the conceptual center of MAGE-HEP is a three-level hierarchy consisting of project, study, and run. This hierarchy is the paper’s main architectural idea.

Level	Role	Typical contents
Project	Whole workspace	studies, runs, metadata, exportable project state
Study	Reusable analysis context	generator config, observables, selections, output rules, generated source files, tool versions
Run	Controlled execution of a study	seed, event count, selected parameters, status, logs, output paths, generated files

A project stores the workspace, contains one or more studies and their runs, and carries workspace metadata and exportable project state. A study stores the reusable analysis definition: generator configuration, analysis recipe, observable definitions, output rules, mutable parameters, generated source files, and tool-version metadata. A run inherits the study context and applies only run-level overrides such as random seed, event count, selected parameters, binning, or particle species (Gupta et al., 18 May 2026).

This separation is intended to solve a reproducibility problem. Rather than rewriting the analysis for every variation, one defines it once at study level and launches controlled variations as runs, each with its own manifest, status, logs, output paths, and generated files. The paper gives a representative project layout: at project level, project_manifest.json and a compressed portable bundle <ProjectName>.mgp; under studies/<study_id>/, files such as study_manifest.json, context.mcx, analysis.cc, analysis.h, pythia.cmnd, observables.json, and root_layout.json; under runs/<run_id>/, files such as run_manifest.json, run.cc, status.json, run.log, and ROOT output such as [spectra](https://www.emergentmind.com/topics/spectra-6815ea26-e478-4301-bbaa-6afdedfa981b).root (Gupta et al., 18 May 2026).

The significance of that layout is explicit: the ROOT file is not the only record of the analysis. Code, configuration, metadata, and execution state are all treated as first-class parts of the workflow. This suggests a preservation model in which executable provenance is reconstructed from manifests and generated sources rather than inferred retrospectively from final histograms.

3. Node API and internal context graph

The analysis-building layer is the MAGE-HEP Node API. It provides a structured alternative to writing a monolithic script and allows users to specify external-tool requirements, generator configurations, reusable modules, observables, selections, internal stores, and ROOT output rules (Gupta et al., 18 May 2026).

The paper’s representative study definition begins with:

$|\eta| < 0.8 .$6

Toolchain requirements are then declared through:

$|\eta| < 0.8 .$7

The paper emphasizes that .AutoDetect() captures tool versions in the context, supporting rebuildability and provenance. Generator configuration is specified through a Pythia8 block, for example with collision system, center-of-mass energy, event count, .cmnd file, and explicit settings such as {"Tune:pp", 14} and {"SoftQCD:inelastic", true} (Gupta et al., 18 May 2026).

Analysis logic is defined through .Analyze(...). In the paper’s Recipes::UserHistogram example, the observable is the particle azimuthal angle $\phi$, evaluated at Stage::Particle, with selections Select::Final(), Select::Charged(), and the cut

$|\eta| < 0.8 .$

The corresponding string expression is:

$|\eta| < 0.8 .$8

The paper distinguishes observables from selections. Here the observable is $\phi$, while the selections are “final,” “charged,” and the pseudorapidity cut. The notation .eta() is parsed into the particle object’s eta() in generated code. The analysis output is stored in an internal named store, phiData, described as a data socket: an intermediate analysis object linking the computation stage to the output-writing stage (Gupta et al., 18 May 2026).

The Node API is compiled into an internal context graph. The paper’s conceptual pipeline diagram contains nodes for the event source, currently PYTHIA8; a run node bridging study logic to execution; event-level nodes for quantities such as multiplicity or centrality; particle-level nodes for observables such as $p_T$, $\eta$, $y$, and $\phi$; cut/property blocks; data sockets; and a ROOT builder. The graph is designed for reuse: multiple analyses can branch from the same context, and previously exported contexts can be imported into new studies. A more compact predefined recipe, Recipes::PidPtVsNch, demonstrates this expansion mechanism for identified-particle spectra into event and particle logic, sparse stores for spectra, and ROOT-writing rules, with output described as a collection of two-dimensional histograms in $p_T$ versus global charged multiplicity, split by PID and $\eta$ bin (Gupta et al., 18 May 2026).

4. Generated code, save-rules, and portable bundles

The generated-code step is explicit and inspectable. The paper’s example uses:

$|\eta| < 0.8 .$9

.Generate(...) invokes the MAGE-HEP transpiler, described as a source-to-source translation layer, producing ordinary C++ analysis code such as analysis.cc together with metadata including context summaries, parameter values, semantic-flow information, and ROOT layout descriptions. The framework’s stated design goal is transparency: users can inspect, copy, compile, and run the generated code independently of the GUI (Gupta et al., 18 May 2026).

Output construction is handled by the ROOT builder and the save-rule system. A save-rule specifies which store is written, which variables become histogram axes, which variables split the output into multiple objects, the ROOT object type, and the naming pattern. The representative rule in the paper is:

$\phi$0

This means that a single internal store can materialize as many ROOT histograms. In this example, the histogram axes are $p_T$ and global charged-multiplicity bin, while separate histograms are produced for each PID and $|\eta| < 0.8 .$0-bin combination. In the beta implementation, save-rules are intentionally limited to two predefined classes: one for TH1D via Recipes::UserHistogram, and one recipe-specific TH2D rule via Recipes::PidPtVsNch. Fully general user-defined save-rules are stated as future work (Gupta et al., 18 May 2026).

MAGE-HEP defines two distinct portable bundles. A .mcx file is the reusable study context package containing analysis definitions, modules, parameters, stores, output rules, version metadata, and related context information. A .mgp file is the portable project package, storing project metadata, analysis flows, run states, parameters, generated source files, output layout descriptions, parallel execution settings, and tool versions in a fixed layout. Large ROOT files are currently excluded from .mgp so that the project bundle remains lightweight (Gupta et al., 18 May 2026).

Context reuse is an explicit architectural feature. A study can import a previously exported .mcx through .Reuse("flow_context_pp.mcx");, which the paper states carries over module definitions, parameters, store names, output rules, source-level information, and version metadata. This makes the analysis logic portable across systems, for example from a proton-proton study to a heavy-ion context, without manually copying scripts.

5. Execution workflow, GUI, and backend daemon

The workflow is formalized in the paper through an execution sequence: create or open a project; define or import a study context; generate study-level analysis.cc; select run-level parameters exposed by the study; for each run, create a run directory; write run_manifest.json; generate or configure run.cc; submit the run to the backend daemon; update status.json and logs during execution; register outputs on completion; update plots and particle tables in the GUI; and finally export project state as a lightweight .mgp bundle (Gupta et al., 18 May 2026).

The GUI is the primary user-facing interface. It is responsible for project creation, study creation or import, run launching, inspection of generated files, progress monitoring, and output viewing. The Create Project window initializes a workspace that can later be exported as .mgp. The Add Study workflow lets users describe the study, choose access mode, select collision system, generator, and configuration, and either build a new context from a definition file or load an existing .mcx. The access modes are listed as Public, Private, and Key-gated, with the last marked as planned for future versions (Gupta et al., 18 May 2026).

Once a study exists, the Add Run interface exposes run-level parameters. Users can launch one run or multiple parallel siblings, meaning sibling run instances that share the study context but execute as controlled variations. Output policy is controlled through a merge option: each run can keep a separate ROOT output, or outputs from sibling runs can be merged into a single ROOT file.

Long-running execution is delegated to mage-daemon, not executed directly by the GUI. The daemon receives run requests, launches generated drivers in detached terminals, tracks the process, updates status files, writes logs, and reports progress to the interface. The implementation uses separate tmux sessions for each run, enabling independent background execution, logging, and multi-run concurrency over available CPU cores. Because each run has its own status.json and run.log, project state survives GUI restarts (Gupta et al., 18 May 2026).

The GUI also includes live ROOT inspection and particle-table summaries. Since save-rules explicitly record what variables are written and how, the interface can display supported ROOT histograms directly. Both features are implemented with lazy loading so that large ROOT files are opened only as needed, reducing memory overhead. The authors characterize these as beta-stage visual validation tools rather than a full final visualization system.

6. Validation status, limitations, and development trajectory

The current release is explicitly described as a beta implementation validated on a PYTHIA8 + ROOT workflow. The validation is architecture-oriented rather than a broad backend or physics-performance benchmark. The paper’s demonstration uses the predefined identified-particle spectra recipe and runs the generated context for approximately

$|\eta| < 0.8 .$1

across 40 sibling cores, with outputs merged into a single ROOT file. The example output includes the event distribution in global charged-multiplicity bins and the $|\eta| < 0.8 .$2-versus-$|\eta| < 0.8 .$3 distributions for a selected particle and $|\eta| < 0.8 .$4 bin, with the upper panel shown for

$|\eta| < 0.8 .$5

The stated purpose is to validate that the Node API definition is correctly translated into C++/ROOT analysis files and that the generated code produces the expected ROOT objects and GUI-visible plots (Gupta et al., 18 May 2026).

Several limitations are stated explicitly. The current version is restricted to PYTHIA8 as the validated generator backend, ROOT-based output only, selected predefined output layouts (TH1D, TH2D), a limited set of predefined analysis recipes, and a GUI focused on project-study-run management and basic visual diagnostics rather than a complete analysis workbench. It does not yet offer fully general save-rule authoring, broad cross-generator support, HepMC/YODA export, real-data import, MC-to-data comparison, tuning workflows, or integrated ML tools (Gupta et al., 18 May 2026).

The planned extensions are correspondingly broad: additional generator backends, HepMC-based event records, broader ROOT and YODA layouts, REANA integration for preservation and execution, real-data import, MC/data comparison, tuning workflows, and ML-assisted tools. The GUI roadmap includes “ML Lab” and “Plot Lab”. The first would build ML datasets directly from ROOT files using context-aware requirements; the second would derive further plots directly from saved outputs without extra user analysis code. These plans indicate that the current implementation is intended as a proof of the workflow architecture rather than a finished general-purpose HEP analysis platform.

A common misconception would be to read MAGE-HEP as a replacement for generator frameworks or preservation systems. The paper states the opposite: it is a workflow and context layer on top of them. Another misconception would be to treat the generated ROOT file as the full persistent artifact of the analysis. MAGE-HEP’s model is broader: study context, generated code, manifests, run states, and version metadata are all preserved as part of the analysis record. In that sense, its distinguishing feature is not a new physics algorithm but a structured reproducibility model for Monte Carlo analysis (Gupta et al., 18 May 2026).