################################################################################ # # Copyright (C) 2012-2018 Eric Conte, Benjamin Fuks # The MadAnalysis development team, email: <ma5team@iphc.cnrs.fr> # # This file is part of MadAnalysis 5. # Official website: <https://launchpad.net/madanalysis5> # # MadAnalysis 5 is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # MadAnalysis 5 is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with MadAnalysis 5. If not, see <http://www.gnu.org/licenses/> # ################################################################################ W E L C O M E to M A D A N A L Y S I S 5 ,----,. ____ ,' ,' | ,' , `. ,---, ,' .' | ,-+-,.' _ | ' .' \ ,----.' . ,-+-. ; , || / ; '. | | .' ,--.'|' | ;|: : \ : : |--, | | ,', | ':: | /\ \ : | ;.' \ | | / | | ||| : ' ;. : | | | ' | : | : |,| | ;/ \ \`----'.'\ ; ; . | ; |--' ' : | \ \ ,' __ \ . | | : | | , | | ' '--' / /\/ / : | : ' |/ | : : / ,,/ ',- . ; | |`-' | | ,' \ ''\ ; | ;/ `--'' \ \ .' '---' `--`-,-' 1. What is MadAnalysis 5 ? 2. Requirements 3. Downloading and installing the MadAnalysis 5 package 4. Description of the package 5. Very first steps with MadAnalysis 5 6. Troubleshootings and bug reports 7. Our famous last words ################################################################################ 1. WHAT IS MADANALYSIS 5 ? ################################################################################ MadAnalysis 5 is 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. The first running mode of the program, 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 running modes 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 that can be reached, the latter being only limited by the programming skills and the originality of the user. More details can be found on the MadAnalysis 5 website: https://launchpad.net/madanalysis5 ################################################################################ 2. REQUIREMENTS ################################################################################ MadAnalysis 5 requires several external libraries in order to properly run: - Python 2.6 or a more recent version (but not the 3.X series) that can be downloaded from the website http://www.python.org/ In order to check the installed version of Python on a system, it is sufficient to issue in a shell python --version - The GNU GCC compiler. MadAnalysis 5 has been validated with the versions 4.3.X and 4.4.X. The GCC compiler can be downloaded from the website: http://gcc.gnu.org/ - ROOT v5.27 or a more recent version that can be downloaded from the website http://root.cern.ch/ To check the version number of ROOT installed on a system, it is sufficient to type in a shell release root-config --version Moreover, the Python libraries generated by ROOT must be present. To install them, it is necessary to first install the Linux package 'Python-devel' on the system. Next, before generating the ROOT makefile, the ROOT configuration script has to be run as ./configure --with-python Let us note that the Python release employed when starting MadAnalysis 5 has to be the same that has been used for the compilation of ROOT. To benefit from all options coming with the MadAnalysis 5 program, the following (optional) libraries have to be installed on the system: - Zlib headers and libraries that can be downloaded from the website http://zlib.net/ - The FastJet package version 3.0, or a more recent version, that can be downloaded from http://fastjet.fr/ This package can also be installed by typing 'install fastjet' in MadAnalysis 5. - latex and pdflatex compilers ################################################################################ 3. DOWNLOADING AND INSTALLING THE MADANALYSIS 5 PACKAGE ################################################################################ The latest stable version of the MadAnalysis 5 package can be downloaded as a tarball from the website https://launchpad.net/madanalysis5 The tarball can subsequently be unpacked by issuing in a shell tar -xvf ma5_xxxx.tgz where 'xxxx' stands for a version number. Alternatively, MadAnalysis 5 can also be obtained via the Bazaar versioning system by issuing in a shell bzr branch lp:madanalysis5 ################################################################################ 4. DESCRIPTION OF THE PACKAGE ################################################################################ The directory structure of the MadAnalysis 5 package can be summarized as follows: + bin | This directory contains the executable file 'ma5'. + madanalysis | This directory contains all the source files of | MadAnalysis 5. + configuration | This directory contains functions related to the | configuration of the dependencie such as FastJet. + core | This directory contains the core of the Python | interface. + dataset | This directory contains the functions related to the | handling of Monte Carlo event files in MadAnalysis | 5. + enumeration | This directory contains the definition of the | keywords used by within the Python source files. + input | This directory contains the lists of (multi)particles | to be loaded at the start-up of MadAnalysis 5. + IOinterface | This directory contains routines related to | input/output flows. + interpreter | This directory contains all the commands available | within the Python interface of MadAnalysis 5. + job | This directory contains the routines necessary for | the creation and execution of C++ jobs. + layout | This directory contains all the functions necessary | for handling the layout of the figures and reports | produced by MadAnalysis 5. + multiparticle | This directory contains the functions related to the | handling of multiparticle and particle collections. + observable | This directory contains the list of observables | supported within MadAnalysis 5. + selection | This directory contains the routines necessary for | producing histograms and applying event selection | cuts. + tools | This directory contains the packages that are used | by MadAnalysis 5. + SampleAnalyzer | This directory contains the C++ kernel of | MadAnalysis, dubbed SampleAnalyzer (see below). + Glue | This directory contains the glues allowing to use | showering programs (not supported yet). (+) samples | This optional directory is dedicated to event sample | storage. The main file of the package is also the only one which is supposed to be run on a system: bin/ma5 In addition, several text files are dedicated to specific information: - README: this file, - COPYING: the description of the software license, - version.txt: general information about the installed release, - madanalysis/UpdateNotes.txt: the update notes. The C++ kernel of MadAnalysis is stored in the directory tools/SampleAnalyzer This directory has the following structure: + tools + SampleAnalyzer + Analyzer | This directory contains the skeleton for the | analysis class as well as for the merging plots. + Core | This directory contains the main routines. + Counter | This directory contains routines related to | histogram and cut referencing. + DataFormat | This directory contains the implementation of the | employed data format for handling event samples | and the related information. + Filter | This directory contains routines for applying event | filtering (to be developped in the future). + JetClustering | This directory contains routines dedicated to jet | clustering algorithms. + Lib | This directory store the SampleAnalyzer library, | once compiled. + Plot | This directory contains all the methods related to | histogram generation. + Reader | This directory contains the definition of classes | dedicated to the reading of the event files. + Service | This directory contains services (logger, physics | tools, ...) + Writer | This directory contains the definition of classes | dedicated to the writing of event files and | result files. + newAnalyzer.py | This script allows to create a blank analysis. + newFilter.py | This script allows to create a blank filter. The Glue directory contains routines dedicated to future developments and are thus neither supporter, nor documented. The associated Doxygen documentation can be found on the MadAnalysis 5 wiki: http://madanalysis.irmp.ucl.ac.be/wiki/doxygen ################################################################################ 5. VERY FIRST STEPS WITH MADANALYSIS 5 ################################################################################ To start MadAnalysis 5, it is enough to type in a shell bin/ma5 In a first step, the program checks all the dependencies and provide warning and/or error messages if necessary. Next, the SampleAnalyzer C++ kernel library is generated. This is performed once and for all at the first run of MadAnalysis 5. Let us however note that if the system configuration changes, this is detected by MadAnalysis 5 and the library is regenerated. If everything is going as smoothly as it should, a Python command line interface with a 'ma5>' prompt appears. To learn how to use MadAnalysis 5 and to get an overview of its functionalities, we refer in particular to Section 3 of the manual that can be found on the webpage http://arxiv.org/abs/1206.1599 ################################################################################ 6. TROUBLESHOOTINGS AND BUG REPORTS ################################################################################ Any public release of MadAnalysis 5 has been automatically and intensely validated. However, especially due to the variety of possible system configurations and the large number of functionalities included in the program, it is not impossible that some bugs are found. In this case, is is strongly suggested to create a report on our website https://launchpad.net/madanalysis5 In this way, you also participate to the improvement of MadAnalysis 5 and the authors thank you for this. ################################################################################ 7. OUR FAMOUS LAST WORDS ################################################################################ The development team of MadAnalysis 5 hopes that the package will meet the expectations of the users and help particle physicists in their phenomenological investigations. Feedback, comments and advises are welcome and can be sent by e-mail: ma5team@iphc.cnrs.fr That's all folks!