ROOT usage

Standalone usage
Storing partial PYTHIA events in ROOT trees
PYTHIA as a plugin to ROOT

Many PYTHIA users wish to use ROOT to produce histograms, or even to run PYTHIA as a plugin to ROOT. This is possible. It is not a task supported by the PYTHIA team, however. All issues involving ROOT usage should be directed to the ROOT team, or to the local support team of your collaboration. Below some helpful hints have been collected. The text is based on contributions by Rene Brun, Andreas Morsch and Axel Naumann. Another example may be found in the VINCIA add-on program for parton showers, but this should also work for a PYTHIA standalone run.

Note that in all that follows, a Linux-type system with a Bash shell and GNU Make is assumed. In particular, for Mac OS X, the LD_LIBRARY_PATH should be replaced with DYLD_LIBRARY_PATH and the extension for shared libraries .so should be replaced with .dylib.

Standalone usage

One can perform the generation and analysis of events in a completely standalone fashion, and only use ROOT to process the completed events. Four example programs are provided in the examples directory, with details provided below. The examples assume that ROOT is installed, that you have run

 
    ./configure --with-root=root-installation-directory

where you have to specify which is the ROOT installation directory, and subsequently run make. More fine-grained options are available with configure, if need be.

Plotting with ROOT

The two examples examples/main141.cc and examples/main142.cc, provided by Dag Gillberg, produce simple graphical representations of events, in fig141.pdf and examples/fig142.pdf, respectively. The former shows parton and particle distributions in (y, phi) space, and the latter jet catchment areas in the same space.

Histogramming with ROOT

An example of histogramming with ROOT is provided in examples/main143.cc. It may be compiled and run just like the other example programs. After PYTHIA has run, a ROOT histogram of the charged multiplicity in the events will be shown. This is now stored in the hist.root file. If you can make this example work, the road should be open to do the same for all other histogramming needs. Specifically, you need to edit the examples/Makefile file to add the other programs to link as main143.cc currently does.

Storing partial PYTHIA events in ROOT trees

A common use case is to store partial track information including some overall event information to ROOT trees, relevant for a specific analysis. The resulting ROOT trees will then be what is often referred to as "n-tuples". The advantage of this over for example storing full events, is a significant reduction of disk space used, as well as the possibility to construct trees resembling those familiar from the experiments' central MC production. The examples/main144.cc example provides this - among other - functionality. As for the above example, it is split up in several files.

main144.cc is the main example program;
main144.cmnd is a sample input command file;
main144LinkDef.h is used by Makefile to generate the dictionary for only the used PYTHIA classes involved in the IO, for the example; and
main144.h defines a "track" and an "event" class where relevant event -and track information is defined.

Compiling the example

The main144 example is compatible with ROOT v.6 and above. One should have a working installation of ROOT, and then configure PYTHIA with:

 
    ./configure --with-root=root-installation-directory

One can then compile main144 with the usual:

 
    make main144

provided that all ROOT paths are set correctly by eg. running:

 
    source root-installation-directory/bin/thisroot.sh

Running the example

The main144 example can be run with several command line options. Running:

 
    ./main144 -h

will display a help text showing these options. To produce events, the user needs to supply a command file with option -c COMMAND-FILE.cmnd. The example command file main144.cmnd is a good starting point. The crucial command to output ROOT trees is to set Main:writeROOT = on. The ROOT file will be named pythia.root per default. This can be changed by appending -o ONAME on the command line.

Changing the event information

The header file main144.h defines a simple event class and track class, which in turn defines the information stored to the tree. If a user wants to change this, either by adding more track information or imposing cuts corresponding to detector acceptance (thus reducing the file size), this can be done directly in this header file. Both the track class and the event class has init functions returning a boolean value, and by returning false, the track/event is rejected. The main144 example must be recompiled after making any changes to the header file.

PYTHIA as a plugin to ROOT

In more ROOT-centric applications, PYTHIA can be run as a ROOT plug-in. This requires a version of ROOT that has been installed from source. The reason is that the interfaces depend on PYTHIA header files that are not distributed with ROOT. Installing ROOT is not more difficult than the PYTHIA installation, and some guidelines are provided below.

Installation

Define an environment variable for the path to your PYTHIA installation directory

 
    export PYTHIA8=path_to_PYTHIA8_installation

Before compiling ROOT, configure ROOT by running the configure command including the following options

 
    --enable-pythia8 
    --with-pythia8-incdir=$PYTHIA8/include/Pythia8 
    --with-pythia8-libdir=$PYTHIA8/lib

In case ROOT has already been compiled before, it will only recompile the PYTHIA module and build the library libEGPythia8.

Interfaces

When running PYTHIA as a plugin, the exact interface structure becomes very relevant. ROOT provides two simple interfaces (wrappers) for PYTHIA 8. The code for these interfaces are located in

 
    path_to_ROOT_source/montecarlo/pythia8

The two interfaces are

TPythia8 is an implementation of the TGenerator interface for PYTHIA 8.
It allows you to use PYTHIA within a ROOT macro or as a plug-in for a general-purpose particle generator based on this interface. The main methods of the interface are
- GenerateEvent() which triggers the generation of the next event, and
- ImportParticles(TClonesArray* particles) which copies the native PYTHIA stack into a TClonesArray of TParticles.
In addition, some methods that are directly related to corresponding PYTHIA methods are implemented
- ReadString(const char* string) → readString(...)
- ReadConfigFile(const char* string) → readFile(...)
- Initialize(int idAin, int idBin, double ecms) → init()
  Warning: this method will have to be updated for the 8.2 version!
- EventListing() → event.list()
- PrintStatistic() → stat()
  Warning: this method will have to be updated for the 8.2 version!
These methods provide already the basic PYTHIA functionality interactively from the ROOT command line. However, this does not mean that the usage of PYTHIA from within ROOT is restricted to these methods. In compiled code, one can always obtain a pointer to the Pythia instance e.g.
```
 
    TPythia8        *tp = new TPythia8(); 
    Pythia8::Pythia *p  = tp->Pythia8();
```
giving access to the full PYTHIA functionality. To access this functionality in the CINT interpreter see the "Advanced usage" section below.
TPythia8Decayer is an implementation of the TVirtualMCDecayer interface.
It allows you to use PYTHIA as a plug-in decayer for simulation frameworks based on the Virtual Monte Carlo (VMC) interface classes. The main methods of the interface are
- TPythia8Decayer::Init() for initialisation,
- TPythia8Decayer::Decay(Int_t pdg, TLorentzVector* p) to decay a particle with PDG code pdg and 4-momentum p, and
- ImportParticles(TClonesArray* particles) to retrieve the decay products as TParticles in the TClonesArray particles.

An example

A basic example for generating minimum-bias events with PYTHIA 8 inside a ROOT macro, and filling some histograms with the kinematics of the final-state particles is provided in either of the locations below

 
    /path_to_ROOT_source/tutorials/pythia/pythia8.C 
    /path_to_ROOT_installation/share/doc/root/tutorials/pythia/pythia8.C

Note that before executing this script

the environment variables PYTHIA8 and PYTHIA8DATA must be setup correctly e.g.

 
    export PYTHIA8=/path_to_PYTHIA_installation 
    export PYTHIA8DATA=$PYTHIA8/share/Pythia8/xmldoc

your LD_LIBRARY_PATH must contain the location of the PYTHIA 8 shared library, e.g.

 
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_to_PYTHIA8_installation/lib

The script can then be run with ROOT

 
    root pythia8.C

After execution, ROOT will display some histograms from the event generation.

Advanced usage

To access the full PYTHIA functionality from the CLING interpreter, a ROOT dictionary must be created. Currently that option has not been implemented as a standard option for PYTHIA 8.3, but it should be in the same spirit as what can be found in the 8.1 rootexamples directory. Also note that one dictionary is found in the examples/main142LinkDef.h file. This may then be loaded in ROOT giving full access to the full PYTHIA 8 functionality, e.g. in an interactive session

 
    gSystem->Load("path_to_PYTHIA8_installation/examples/pythiaDict"); 
    Pythia8::Pythia *p = new Pythia8::Pythia(); 
    p->readString("SoftQCD:nonDiffractive = on");