MAGE-HEP: Monte Carlo Analysis and Graphical Environment for High-Energy Physics

Abstract: Monte Carlo event generators are central to high-energy physics analysis. However, 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. We present MAGE-HEP, short for Monte Carlo Analysis and Graphical Environment for High-Energy Physics, a Graphical User Interface (GUI) driven workflow environment for reproducible Monte Carlo-based analyses in high-energy physics. MAGE-HEP organizes analysis workflows through a project-study-run hierarchy. The project stores the workspace, the study stores the reusable analysis context, and each run represents a controlled execution of that context. The MAGE-HEP Node API provides the analysis-building layer for defining generator configurations, observables, selections, output rules, and generated C++/ROOT analysis code. A study context can be inspected, reused, or exported as a \texttt{.mcx} context bundle, while the project state can be exported as a portable \texttt{.mgp} bundle. The current beta implementation validates the core idea using a PYTHIA8 and ROOT workflow. It includes background execution, manifest-based run tracking, live ROOT inspection, and particle-table summaries for supported output layouts. This paper describes the architecture, workflow, and current beta implementation of MAGE-HEP.

• The paper introduces a hierarchical project-study-run structure that enhances reproducibility in Monte Carlo analysis in HEP.
• It employs a Node API and GUI interface to define context-driven analyses, generate C++/ROOT code, and facilitate parallel execution.
• The framework is validated on 10^10 events, demonstrating live diagnostic visualization and comprehensive output tracking.

MAGE-HEP: A Context-Driven Framework for Reproducible Monte Carlo Analysis in HEP

Introduction and Motivation

The rapidly evolving computational landscape of high-energy physics (HEP) presents acute challenges in the organization, reproducibility, and extensibility of Monte Carlo (MC) analysis workflows. MAGE-HEP ("Monte Carlo Analysis and Graphical Environment for High-Energy Physics") proposes a context-driven, GUI-oriented workflow layer atop established generators and analysis tools such as PYTHIA8 and ROOT. By introducing a coherent project-study-run hierarchy and an extensible Node API, MAGE-HEP aims to address persistent difficulties in structuring, sharing, and validating generator-level analyses, particularly as the scale and variety of MC studies expand.

Design Principles and Architecture

The conceptual foundation of MAGE-HEP is the explicit organization of analysis logic and execution metadata in a form that is discoverable, reusable, and portable. The project-study-run hierarchy structurally decouples workspace, analysis definition, and execution instance:

• Project: The top-level container for all associated studies and runs, encompassing workspace metadata and the portable .mgp bundle.
• Study: The repository for the reusable analysis context, including generator configuration, observables, output rules, and generated analysis code.
• Run: The record of a single, controlled execution of a study, tracking parameters, seed, outputs, logs, and provenance metadata.

This hierarchy supports robust reproducibility and manifest-based run tracking, and is visualized as a network of interrelated nodes, where generator sources, event- and particle-level calculations, selections, aggregation points, and output definitions are modularly composed.

Figure 1: The conceptual context graph in MAGE-HEP, demonstrating linkages between event sources, analysis nodes, cuts, data aggregation points, and ROOT output builders.

Key design goals include:

• User-centric GUI: Intuitive project and run management, live output inspection, and particle-table diagnostics.
• Workflow reproducibility: Exportable project bundles capturing all analysis logic and run metadata.
• Parallel execution: Sibling runs and parallelization via a mage-daemon background service, leveraging multi-core hardware.
• Canonical documentation: Comprehensive logging, manifest and status files, explicit code generation, and immutable run records.
• Extensibility: A Node API and context graph paradigm designed for future generator and output-backend integration.

MAGE-HEP Node API and Context Management

The Node API is central to MAGE-HEP's analysis-building paradigm. It provides an abstraction layer where users declaratively define generator setups, selection criteria, observables, and output mappings without the need for bespoke scripting. Critical aspects include:

• Context-based construction: Analyses are defined as context objects via a compositional API, fostering reusability and modularity.
• Explicit data flow: Observables, selections, and output definitions are chained through an internal graph that mirrors the logical analysis sequence.
• Code generation: Contexts are transpiled into C++/ROOT analysis code, which remains transparent to the user and executable independently, favoring both reproducibility and auditability.

Predefined recipes (e.g., $p_T$ spectra vs. multiplicity in specific $\eta$ intervals) are provided in a parameterized manner, with user-defined, flexible output rules specifying axes, splitting variables, and histogram types.

Implementation Overview and GUI Workflow

The MAGE-HEP architecture encompasses both backend and frontend elements. The Qt/C++ GUI abstracts the complexity of project and study setup, context import/export, and run control. All background run execution and job management are delegated to mage-daemon, decoupling UI responsiveness from computational workload.

The frontend supports:

• Project creation and initialization

  Figure 2: The GUI window for initializing a new MAGE-HEP project workspace.

• Study configuration, generator selection, and context access management

  Figure 3: Study setup in the GUI, including system, generator parameters, and context mode selection.

• Run launch, parameter override, and output policy selection

  Figure 4: Launch Run panel, exposing run-level parameter adjustments and output handling.

• Comprehensive run monitoring, status, and output file registry

  Figure 5: Run overview panel, showing run registry entries, progress, generated files, and real-time status.

• Live output visualization and diagnostics

  Figure 6: Integrated ROOT plotting for immediate inspection of output histograms.

  

  Figure 7: Tabular particle summary visualization in the GUI.

Reproducibility and Output Layer

MAGE-HEP's output architecture is rooted in the explicit mapping of context-specified "stores" to ROOT objects governed by user or recipe-defined save-rules. Metadata, code, status, and manifest files are co-located with generated outputs. The project bundle (.mgp) captures all logic and minimal lightweight files required for workflow reconstitution, facilitating interoperability with wider analysis preservation systems in the HEP community.

The current implementation restricts output to ROOT-based histograms (via TH1D/TH2D), but the save-rule abstraction and context graph design are positioned for future extension to formats like HepMC and YODA.

Numerical Results and Beta Validation

A validation example demonstrates the application of predefined particle $p_T$ spectra analysis across ${\sim10^{10}}$ PYTHIA8 events, utilizing 40 sibling cores. Outputs show:

• Correct multiplicity binning and particle identification
• Reproducibility confirmed by manifest cross-verification
• Live diagnostic and histogram inspection integrated in-GUI

Figure 8: Example identified-particle spectra output. Upper: event distribution in $N_{ch}$ bins; lower: transverse momentum distribution as a function of charged multiplicity in selected $\eta$ and PID bins.

Implications and Future Directions

The explicit context-driven paradigm and separation of project, study, and run instances have immediate implications for analysis reproducibility, collaborative workflow, and method validation in MC-heavy HEP studies. Extensions toward:

• Multi-generator and multi-output backend integration (e.g. HepMC, YODA, non-ROOT outputs)
• Direct support for ML dataset construction from MC outputs
• Broadened parameterization and user-definable save-rules
• Interfacing with external analysis preservation frameworks (e.g., REANA)

will further solidify MAGE-HEP as a bridge between experiment-specific scripting and scalable, reusable, future-proofed analysis pipelines. The modular Node API opens avenues for method sharing, context porting, integration of ML-assisted analysis tools, and improved workflow documentation across collaborative HEP efforts.

Conclusion

MAGE-HEP presents an authoritative solution to persistent challenges in reproducible and extensible MC analysis in high-energy physics. By encapsulating generator-level analysis logic and run metadata in a context-driven, GUI-supported, and code-generating workflow, it achieves a well-structured approach to sharing, iterating, and validating HEP analyses. While the current implementation is focused on PYTHIA8 and ROOT, the architecture is agnostic to generator and output backend, providing a fertile ground for expansion in both practical workflow management and methodological development. Public release and further feature development will strengthen its role in HEP computational methodology and analysis preservation.