Source-linked AI summary
MadAnalysis 5, a user-friendly framework for collider phenomenology
Eric Conte, Benjamin Fuks, Guillaume Serret
TL;DR
MadAnalysis 5 addresses the lack of a dedicated framework for validated and traceable phenomenological analyses at particle colliders. It provides a user-friendly C++-kernel framework with Python and expert C++ modes, supporting automated analysis outputs and flexible sophistication.
Problem
Phenomenological analyses often rely on home-made, non-public programs, creating validation, traceability, and interpretation problems.
Method
MadAnalysis 5 combines a multi-purpose C++ kernel with a straightforward Python interface and an expert mode for implementing analyses directly in C++ within SampleAnalyzer.
Results
MadAnalysis 5 enables efficient, user-friendly implementation and execution of phenomenological analyses, including automated cuts, histograms, cut-flow charts, and output files.
Takeaways & Limitations
The framework supports straightforward analyses for general users while allowing advanced users to implement more sophisticated analyses through C++ and Root.
Takeaways & Limitations
Event-file formats are not universally appropriate for every analysis sophistication level, and some reconstructed-event workflows require external conversion routines.
Abstract
from arXiv · showhide
We present MadAnalysis 5, a new framework for phenomenological investigations at particle colliders. Based on a C++ kernel, this program allows to efficiently perform, in a straightforward and user-friendly fashion, sophisticated physics analyses of event files such as those generated by a large class of Monte Carlo event generators. MadAnalysis 5 comes with two modes of running. The first one, easier to handle, uses the strengths of a powerful Python interface in order to implement physics analyses by means of a set of intuitive commands. The second one requires to implement the analyses in the C++ programming language, directly within the core of the analysis framework. This opens unlimited possibilities concerning the level of complexity which can be reached, being only limited by the programming skills and the originality of the user.
PROGRAM SUMMARY
MadAnalysis 5 is an open-source collider-analysis program implemented in Python and C++, with compatibility across supported platforms and software versions.
- MadAnalysis 5 is distributed under the GNU General Public License.
- The program uses Python 2.7, Root 5.27, and g++, while compatibility with newer versions is also ensured.The Python version must remain below 3.0.
- MadAnalysis 5 runs on all platforms providing the specified Python, Root, and g++ environments.
1. Introduction
Collider phenomenology needs accurate, increasingly sophisticated event simulation and analysis, but such work has often relied on fragmented private tools. MadAnalysis 5 addresses this by providing an efficient framework with both accessible and extensible analysis modes.
- Motivation: LHC phenomenology requires simulation of candidate signals and backgrounds despite the complexity of typical final states.The LHC and experiments such as ATLAS and CMS are probing the TeV scale and beyond-Standard-Model physics.
- Analysis workflow: Phenomenological analyses typically apply selection cuts to signal and background samples and produce histograms to extract information from backgrounds.Signal-over-background ratios can guide optimization of the selection cuts.
- Event simulation: Parton-shower and hadronization programs extend matrix-element event samples into more sophisticated hadron-level analyses.Pythia and Herwig provide strong-interaction modeling, while matching algorithms connect showers to hard-scattering matrix elements.
- Event simulation: Hadron-level events contain far more particles than partonic events, making event information harder to store and parse.Common event structures and formats such as StdHep and HepMC help organize these samples for detector simulation.
- Motivation: Home-made, non-public analysis programs can hinder validation, traceability, and interpretation of results.MadAnalysis 5 is introduced as a single open-source framework based on the SampleAnalyzer C++ kernel and Root.
- Contribution: MadAnalysis 5 combines an efficient Python interface with automated cuts, histograms, and cut-flow charts.Its expert mode permits direct C++ implementation within the kernel when embedded functionality is insufficient.
2. Overview of MadAnalysis 5
MadAnalysis 5 provides a unified workflow for defining, executing, and reporting collider analyses across multiple Monte Carlo event formats and analysis levels. Its Python interface supports routine tasks, while the C++ SampleAnalyzer architecture supports more sophisticated implementations.
- 2.1. MadAnalysis 5 in a nutshell: MadAnalysis 5 analyzes Monte Carlo samples through a C++ SampleAnalyzer kernel and a Python command-line interface.
- 2.1. MadAnalysis 5 in a nutshell: The framework reads LHE, StdHep, HepMC, and LHCO files containing parton-level, hadron-level, or reconstructed-level events.A single reader supports these event representations within one analysis framework.
- 2.1. MadAnalysis 5 in a nutshell: Users generate histograms of event-wide or particle-specific observables and compare samples through stacked or unity-normalized distributions.Stacked samples are automatically normalized to a user-specified integrated luminosity.
- 2.1. MadAnalysis 5 in a nutshell: Python commands apply selection cuts to event content, including missing transverse energy, lepton multiplicities, and hardest-particle properties.
- 2.1. MadAnalysis 5 in a nutshell: Signal and background tags enable automatic treatment of signal-over-background ratios and related user-specified observables with uncertainties.
- 2.2. Basic concepts: An analysis consists of selections, namely histograms and cuts, whose cut ordering affects intermediate histograms and efficiency tables.Histogram requests are commutative, whereas selection cuts are not.
- 2.2. Basic concepts: MadAnalysis 5 generates C++ jobs for efficient execution and collects histograms, efficiency tables, and optional signal-over-background tables into HTML or LaTeX reports.
- 2.3. Logical architecture of the program: The normal mode links the Python interface and C++ kernel, while expert users can bypass Python and implement analyses directly in SampleAnalyzer.The expert mode is intended for more sophisticated analyses and requires advanced programming skills.
3. First steps with MadAnalysis 5
MadAnalysis 5 guides users from loading Monte Carlo event samples to defining observables and selection cuts, then reports histogram and cut-efficiency results. A toy LHC analysis illustrates its command-driven workflow and dataset handling.
- Toy analysis: The example analyzes four 1000-event samples representing three Standard Model processes at the 7 TeV LHC.The samples are generated with MadGraph 5 at leading order using the CTEQ6 parton density fit.
- Starting the interface: MadAnalysis 5 can be launched without interactive compilation or configuration after installation, with dependency checks and automatic C++ library compilation handled by the program.The command interface is exposed through the ma5> prompt, while required Root files and a C++ compiler are checked at startup.
- Particle labels: Particle and multiparticle labels are loaded into the session, displayed through commands, and extendable at runtime with define.For example, the multiparticle label mu can represent both the muon and antimuon.
- Importing event samples: Imported files are merged into a unique defaultset event sample, which becomes the dataset on which the SampleAnalyzer kernel applies cuts.Wildcard characters allow several Monte Carlo files to be imported simultaneously.
- Selection cuts and histograms: The toy analysis plots missing transverse energy and final-state muon transverse momentum, with observables and histogram binning specified through plot.The merged dataset contains three top-antitop files and one diboson file; MET denotes missing transverse energy and PT denotes transverse momentum.
- Displaying results: Selection cuts produce efficiency tables and can report their effect on the signal-over-background ratio, although the toy example treats all events as signal by default.No sample was tagged as signal or background in this example, so that ratio feature is not relevant here.
4. Implementing analyses in an efficient and user-friendly way
MadAnalysis 5 supports analyses across parton-, hadron-, and reconstructed-level events through an interactive Python-inspired interface, scripts, or an expert C++ mode. Its commands organize datasets, selections, objects, and analysis execution while accommodating multiple event formats and UFO models.
- Running modes and event levels: MadAnalysis 5 analyzes partonic, hadronic, and reconstructed events, with level-specific launch modes available from the command line.LHE files can be used at all three levels, whereas StdHep/HepMC are limited to parton- and hadron-level events and LHCO to reconstructed-level analyses.
- Running modes and event levels: Scripts provide sequential, noninteractive execution of one or more command files and can terminate automatically after completion.Multiple files are concatenated in order, and the # character introduces ignored comments.
- Expert analyses and inputs: The framework offers an expert mode for highly sophisticated analyses, where implementation possibilities are unlimited but command-line startup options are ignored.Expert mode is launched with --expert, -e, or -E and supports analyses implemented directly within the framework’s core.
- Interactive analysis construction: The command interface uses a compact, Python-inspired action syntax with semicolon-separated commands, help, tab completion, shell access, and command history.The interface records the last 100 commands in .ma5history and supports case-sensitive commands at the ma5> prompt.
- Interactive analysis construction: Analysis objects represent particles, multiparticles, datasets, selection cuts, and session configuration, with properties accessed through object.option syntax.Object names must be unique across predefined actions, existing objects, and newly created objects.
- Expert analyses and inputs: MadAnalysis 5 automatically detects and loads complete UFO models, while imported Monte Carlo samples require the import command and compatible event formats.The available formats include LHE, StdHep, HepMC, and LHCO, but their suitability depends on the analysis level.
5. MadAnalysis 5 for expert users
MadAnalysis 5’s expert mode lets users implement analyses directly in C++ within SampleAnalyzer, overcoming the normal mode’s functional restrictions. Analyses are compiled and executed on dataset lists, producing user-defined output files.
- Expert mode: The expert mode removes the normal mode’s implemented-functionality restrictions by allowing users to design analyses directly in C++ within SampleAnalyzer.Its possibilities are limited by the user’s programming skills and originality; the framework provides event readers, data formats, reusable functions, automated compilation, and error management.
- Expert mode: Users can either extend an analysis generated in normal mode or design a new analysis from scratch.Generated working directories include SampleAnalyzer, lists, and root subdirectories for analysis files, dataset path lists, and output files.
- Analysis setup: Normal-mode analyses are implemented through three core C++ functions stored in user.cpp and user.h within SampleAnalyzer/Analysis.The analysis list is maintained in analysisList.cpp, and users modify the generated files after MadAnalysis 5 exits.
- Execution: SampleAnalyzer executes an analysis using dataset list files containing event-sample paths, with separate runs required for separate datasets.An analysis label selects which analysis runs when several analyses share one working directory.
- Output: The selected analysis generates output files according to the C++ implementation, while Finalize creates histograms, cut-flow charts, and a ROOT output file containing analysis results.Finalize also accepts summary information such as the total cross section and its uncertainty, averaged over the samples in a dataset.
6. Conclusions
The paper presents MadAnalysis 5 as a user-friendly framework for implementing collider phenomenology analyses across multiple event-simulation levels. Its normal Python mode simplifies standard analyses, while expert C++ mode supports more sophisticated investigations.
- Conclusions: MadAnalysis 5 is introduced as a user-friendly and efficient framework for implementing phenomenological analyses based on Monte Carlo event files.The paper explains how to implement and run analyses and provides detailed examples covering different program functionalities.
- Conclusions: The framework uses a multi-purpose C++ kernel, supports common event-file formats, and offers two running modes for different user needs and expertise.The supported analysis levels include parton-level, hadron-level, and reconstructed events.
- Conclusions: The normal mode uses a Python interface and intuitive commands to define datasets, histograms, and selection cuts without extensive implementation effort.The interface can generate relatively complex analyses through commands inspired by Python syntax.
- Conclusions: The expert mode lets advanced users implement analyses directly in C++ within SampleAnalyzer, overcoming the normal mode’s implemented-functionality limitations.Its analysis-level possibilities are limited by the user’s programming skills and imagination.
Appendix A.1. Requirements
MadAnalysis 5 requires Python, a C++ compiler, and ROOT, with additional dependencies enabling optional functionality. The documented validation environment constrains compiler support and requires matching Python and ROOT configurations.
- Python and ROOT: Python 2.6 or newer is required, but Python 3.x is unsupported.The Python version used to launch MadAnalysis 5 must match the version used to build ROOT’s Python library.
- Mandatory requirements: MadAnalysis 5 cannot run without Python, a C++ compiler with STL, and ROOT as mandatory external packages.Optional libraries add functionality, while their absence deactivates features without preventing event-file analyses.
- Compiler: The SampleAnalyzer kernel requires a C++ compiler, with validation performed using GNU gcc versions 4.3.x and 4.4.x.Other C++ compilers are theoretically compatible but currently require modifications to core files and are not supported.
- Python and ROOT: ROOT version 5.27 or newer is required, and its Python functionality must be available.The documentation gives ROOT configuration and inspection commands for enabling and checking Python support.
- Optional requirements: The optional zlib dependency enables analysis of zipped Monte Carlo event samples; without it, users must unzip files manually.The program otherwise remains usable for event-file analyses.
Appendix A.2. Downloading the program
MadAnalysis 5 is distributed as a downloadable tarball that can be unpacked in a MadGraph 5 directory or elsewhere. After unpacking, the program can be launched immediately.
- Downloading: The latest stable MadAnalysis 5 package is recommended and is distributed with the Python command-line interface, SampleAnalyzer, and an up-to-date manual.The package can be downloaded from the project website.
- Installation: The package requires no compilation or configuration after downloading and can be unpacked in a MadGraph 5 directory or any other location.The documented installation uses tar commands after changing to the target directory.
- MadGraph 5 integration: Installing MadAnalysis 5 as a MadGraph 5 dependency updates predefined particle and multiparticle labels from MadGraph 5 standards.This setup also permits analyses during event generation when MadGraph 5 pilots MadAnalysis 5.
- Launching: Once unpacked, MadAnalysis 5 can be launched immediately from a shell.The launch procedure follows the command-line usage described in the main program section.
Appendix A.3. Running MadAnalysis 5
MadAnalysis 5 verifies dependencies and compatibility at startup, then compiles its SampleAnalyzer core during the first session for reuse in later sessions.
- At startup, MadAnalysis 5 checks for gcc, Python, ROOT, and zlib, including compatibility with installed versions.
- If a dependency or compatibility problem prevents proper execution, MadAnalysis 5 prints a message and exits.
- During the first session, the SampleAnalyzer core is compiled as a static library in the lib directory.
- In subsequent sessions, the kernel is only recompiled.