---
title: 'MAGE-HEP: Reproducible Monte Carlo Analysis'
url: https://www.emergentmind.com/topics/mage-hep
type: topic
---

# MAGE-HEP: Reproducible Monte Carlo Analysis

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 [2605.17871].

## 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 [2605.17871].

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 [2605.17871].

## 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 [2605.17871].

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.root` [2605.17871].

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 [2605.17871].

The paper’s representative study definition begins with:

```cpp
Study pp("flow_context_pp");
```

Toolchain requirements are then declared through:

```cpp
pp.Toolchain()
  .Require("ROOT")
  .Require("PYTHIA8")
  .AutoDetect();
```

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}` [2605.17871].

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:

```cpp
"abs(.eta()) < etaMax"
```

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 [2605.17871].

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 [2605.17871].

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

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

```cpp
pp.Generate("generated/flow_context_pp");
pp.Export("flow_context_pp.mcx");
```

`.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 [2605.17871].

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:

```text
Store: ptData
Axes:  pt, globalNchBin
Split: pid, etaBin
Type:  TH2D
Name:  h2_pt_globalNch_pid{pid}_etaBin{etaBin}
```

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\)-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 [2605.17871].

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 [2605.17871].

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 [2605.17871].

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 [2605.17871].

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 [2605.17871].

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
\[
10^{10}\ \text{events}
\]
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 \(p_T\)-versus-\(N_{\rm ch}\) distributions for a selected particle and \(\eta\) bin, with the upper panel shown for
\[
1.1 < |\eta| < 1.2 .
\]
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 [2605.17871].

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** [2605.17871].

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 [2605.17871].

Source: https://www.emergentmind.com/topics/mage-hep