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.ccis the main example program;
- main144.cmndis a sample input command file;
- main144LinkDef.his used by Makefile to generate the 
  dictionary for only the used PYTHIA classes involved in the IO, for 
  the example; and
- main144.hdefines 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 
 
 
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 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");