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