Skip to content

oliviermattelaer/madanalysis5

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

31 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

################################################################################
#  
#  Copyright (C) 2012 Eric Conte, Benjamin Fuks, Guillaume Serret
#  The MadAnalysis development team, email: <ma5team@iphc.cnrs.fr>
#  
#  This file is part of MadAnalysis 5.
#  Official website: <http://madanalysis.irmp.ucl.ac.be>
#  
#  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:
  http://madanalysis.irmp.ucl.ac.be/ 


################################################################################
                             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/


################################################################################
            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
  http://madanalysis.irmp.ucl.ac.be 
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 by SVN (SubVersion) by issuing
in a shell
  svn checkout https://cp3.irmp.ucl.ac.be/sources/madanalysis/branches/madanalysis-current


################################################################################
                         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.
      +   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.
      +   SampleAnalyzer | This directory contains the C++ kernel of
                         |   MadAnalysis, dubbed SampleAnalyzer (see below).
      +   selection      | This directory contains the routines necessary for
                         |   producing histograms and applying event selection
                         |   cuts.
  (+) samples            | This optional directory is dedicated to event sample
                         |   storage. 
  (+) lib                | If not present, this directory is created by
                         |   MadAnalysis to store the SampleAnalyzer library. 

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.ma5: 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
  madanalysis/SampleAnalyzer
This directory has the following structure: 
   + madanalysis         
     + SampleAnalyzer
       + Analysis         | This directory contains examples of predefined
                          |   analyses.
       + Core             | This directory contains the main routines.
       + DataFormat       | This directory contains the implementation of the
                          |   employed data format for handling event samples
                          |   and the related information.
       + Reader           | This directory contains the definition of classes
                          |   dedicated to the reading of the event files. 
       + Services         | This directory contains services (logger, physics
                          |   tools, ...)
     + newAnalysis.py     | This Python script allows to create a blank analysis
                          |   (see the manual).

The associated Doxygen documentation can be found on the MadAnalysis 5 website
  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 ticket on our website
  http://madanalysis.irmp.ucl.ac.be/newticket

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!



About

A package for event file analysis and recasting of LHC results

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 56.6%
  • C++ 33.3%
  • Tcl 7.9%
  • Fortran 1.7%
  • TeX 0.3%
  • C 0.2%