PYTHIA8/pythia8170/xmldoc/ROOTusage.xml

   1 <chapter name="ROOT usage">
   2
   3 <h2>ROOT usage</h2>
   4
   5 Many PYTHIA users wish to use <a href="http://root.cern.ch/">ROOT</a>
   6 to produce histograms, or even to run PYTHIA as a plugin to ROOT.
   7 This is possible. It is not a task supported by the PYTHIA team,
   8 however. All issues involving ROOT usage should be directed to the
   9 ROOT team, or to the local support team of your collaboration.
  10 Below some helpful hints have been collected. The text is based on
  11 contributions by Rene Brun, Andreas Morsch and Axel Naumann.
  12 Another example may be found in the
  13 <a href="http://home.fnal.gov/~skands/vincia/">VINCIA</a>
  14 add-on program for parton showers, but this should also work for
  15 a PYTHIA standalone run.
  16 <br/><br/>
  17 Note that in all that follows, a Linux-type system with a Bash shell
  18 and GNU Make is assumed. In particular, for Mac OS X, the
  19 <code>LD_LIBRARY_PATH</code> should be replaced with
  20 <code>DYLD_LIBRARY_PATH</code> and the extension for shared libraries
  21 <code>.so</code> should be replaced with <code>.dylib</code>.
  22
  23 <br/><br/><hr/>
  24 <h3>Standalone usage</h3>
  25
  26 One can perform the generation and analysis of events in a completely
  27 standalone fashion, and only use ROOT to process the completed events.
  28 Some example programs are provided in the <code>rootexamples</code>
  29 directory, with details provided below and in the <code>README</code>
  30 file.
  31
  32 The examples assume that you have already compiled the PYTHIA library,
  33 ROOT is installed, and that all paths have been setup correctly (e.g.
  34 PATH and LD_LIBRARY_PATH). If these paths are not already set, ROOT
  35 typically comes with a shell script to set these paths, which can be
  36 run with
  37 <pre>
  38     source /path_to_ROOT_installation/bin/thisroot.sh
  39 </pre>
  40
  41 <h4>Histogramming with ROOT</h4>
  42
  43 An example of histogramming with ROOT is provided in
  44 <code>rootexamples/hist.cc</code>. It may be compiled and run
  45 with the following commands
  46 <pre>
  47     make hist
  48     ./hist.exe
  49 </pre>
  50 After PYTHIA has run, a ROOT histogram of the charged multiplicity in
  51 the events will be shown. This is now stored in the
  52 <code>hist.root</code> file.
  53
  54 <h4>Storing PYTHIA events in ROOT trees</h4>
  55
  56 Instead of only generating histograms, it is possible to store entire
  57 PYTHIA events in ROOT trees. The <code>tree</code> example in the
  58 <code>rootexamples</code> subdirectory provides an example of this and
  59 is comprised of the following files
  60 <ul>
  61   <li><code>tree.cc</code> is the main example program showing how
  62   PYTHIA events can be stored in ROOT trees.</li>
  63   <li><code>pythiaLinkdef.h</code> is used by Makefile to generate the
  64   dictionary for all PYTHIA classes involved in the IO, as needed for
  65   the example.</li>
  66   <li><code>pythiaROOT.h</code> is a small include declaring the
  67   <code>Pythia8</code> namespace as default.</li>
  68 </ul>
  69
  70 <br/>
  71 The example may be compiled and run with
  72 <pre>
  73     make tree
  74     ./tree.exe
  75 </pre>
  76 After the example has run, the <code>pytree.root</code> file will now
  77 be present containing the PYTHIA events. Note that files can become
  78 quite large when many events are generated.
  79
  80 <br/><br/><hr/>
  81 <h3>PYTHIA as a plugin to ROOT</h3>
  82
  83 In more ROOT-centric applications, PYTHIA can be run as a ROOT plug-in.
  84 This requires a version of ROOT that has been
  85 <a href="http://root.cern.ch/drupal/content/installing-root-source">
  86 installed from source</a>. The reason is that the interfaces depend on
  87 PYTHIA header files that are not distributed with ROOT. Installing ROOT
  88 is not more difficult than the PYTHIA installation, and some
  89 guidelines are provided below.
  90
  91 <h4>Installation</h4>
  92
  93 To be run as a plugin, PYTHIA must be compiled as a shared library.
  94 This is achieved by running the PYTHIA <code>configure</code> script
  95 with the <code>--enable-shared</code> option before <code>make</code>
  96 is run.<br/><br/>
  97
  98 Define an environment variable for the path to your
  99 PYTHIA installation directory
 100 <pre>
 101     export PYTHIA8=path_to_PYTHIA8_installation
 102 </pre>
 103 Before compiling ROOT,
 104 <a href="http://root.cern.ch/drupal/content/installing-root-source">
 105 configure ROOT</a> by running the <code>configure</code> command
 106 including the following options
 107 <pre>
 108     --enable-pythia8
 109     --with-pythia8-incdir=$PYTHIA8/include
 110     --with-pythia8-libdir=$PYTHIA8/lib
 111 </pre>
 112 In case ROOT has already been compiled before, it will only recompile
 113 the PYTHIA module and build the library <code>libEGPythia8</code>.
 114
 115 <h4>Interfaces</h4>
 116
 117 When running PYTHIA as a plugin, the exact interface structure becomes
 118 very relevant. ROOT provides two simple interfaces (wrappers) for
 119 PYTHIA 8. The code for these interfaces are located in
 120 <pre>
 121     path_to_ROOT_source/montecarlo/pythia8
 122 </pre>
 123 <br/>
 124 The two interfaces are
 125 <ul>
 126   <li><a href="http://root.cern.ch/root/html/TPythia8.html">
 127   <code>TPythia8</code></a> is an implementation of the
 128   <a href="http://root.cern.ch/root/html/TGenerator.html">
 129   <code>TGenerator</code></a> interface for PYTHIA 8.<br/>
 130   It allows you to use PYTHIA within a ROOT macro or as a plug-in
 131   for a general-purpose particle generator based on this interface. The
 132   main methods of the interface are
 133   <ul>
 134     <li><code>GenerateEvent()</code> which triggers the
 135     generation of the next event, and </li>
 136     <li><code>ImportParticles(TClonesArray* particles)</code>
 137     which copies the native PYTHIA stack into a
 138     <a href="http://root.cern.ch/root/html/TClonesArray.html">
 139     <code>TClonesArray</code></a> of
 140     <a href="http://root.cern.ch/root/html/TParticle.html">
 141     <code>TParticles</code></a>.
 142   </ul>
 143
 144   In addition, some methods that are directly related to corresponding
 145   PYTHIA methods are implemented
 146   <ul>
 147     <li><code>ReadString(const char* string)</code> ->
 148     <code>readString(...)</code></li>
 149     <li><code>ReadConfigFile(const char* string)</code> ->
 150     <code>readFile(...)</code></li>
 151     <li><code>Initialize(int idAin, int idBin, double ecms)</code> ->
 152     <code>init(...)</code></li>
 153     <li><code>EventListing()</code> ->
 154     <code>event.list()</code></li>
 155     <li><code>PrintStatistic()</code> ->
 156     <code>statistics()</code></li>
 157   </ul>
 158
 159   These methods provide already the basic PYTHIA functionality
 160   interactively from the ROOT command line. However, this does not mean
 161   that the usage of PYTHIA from within ROOT is restricted to these methods.
 162   In compiled code, one can always obtain a pointer to the
 163   <code>Pythia</code> instance e.g.
 164   <pre>
 165     TPythia8        *tp = new TPythia8();
 166     Pythia8::Pythia *p  = tp->Pythia8();</pre>
 167   giving access to the full PYTHIA functionality. To access this
 168   functionality in the CINT interpreter see the "Advanced usage"
 169   section below.</li>
 170
 171   <li><a href="http://root.cern.ch/root/html/TPythia8Decayer.html">
 172   <code>TPythia8Decayer</code></a> is an implementation of the
 173   <a href="http://root.cern.ch/root/html/TVirtualMCDecayer.html">
 174   <code>TVirtualMCDecayer</code></a> interface.<br/>
 175   It allows you to use PYTHIA as a plug-in decayer for simulation
 176   frameworks based on the Virtual Monte Carlo
 177   (<a href="http://root.cern.ch/drupal/content/vmc">VMC</a>) interface
 178   classes. The main methods of the interface are
 179   <ul>
 180     <li><code>TPythia8Decayer::Init()</code> for initialisation,</li>
 181     <li><code>TPythia8Decayer::Decay(Int_t pdg, TLorentzVector* p)</code>
 182     to decay a particle with PDG code <code>pdg</code> and
 183     <a href="http://root.cern.ch/root/html/TLorentzVector.html">
 184     4-momentum</a> <code>p</code>, and </li>
 185     <li><code>ImportParticles(TClonesArray* particles)</code>
 186     to retrieve the decay products as
 187     <a href="http://root.cern.ch/root/html/TParticle.html">
 188     <code>TParticles</code></a> in the
 189     <code><a href="http://root.cern.ch/root/html/TClonesArray.html">
 190     TClonesArray</a> particles</code>.</li>
 191   </ul></li>
 192 </ul>
 193
 194 <h4>An example</h4>
 195
 196 A <a href="http://root.cern.ch/root/html/tutorials/pythia/pythia8.C.html">
 197 basic example</a> for generating minimum-bias events with PYTHIA 8 inside
 198 a ROOT macro, and filling some histograms with the kinematics of the
 199 final-state particles is provided in either of the locations below
 200 <pre>
 201     /path_to_ROOT_source/tutorials/pythia/pythia8.C
 202     /path_to_ROOT_installation/share/doc/root/tutorials/pythia/pythia8.C
 203 </pre>
 204 <br/>
 205 Note that before executing this script
 206 <ul>
 207   <li>the environment variables <code>PYTHIA8</code> and
 208   <code>PYTHIA8DATA</code> must be setup correctly e.g.
 209   <pre>
 210     export PYTHIA8=/path_to_PYTHIA_installation
 211     export PYTHIA8DATA=$PYTHIA8/xmldoc
 212   <pre></li>
 213   <li>your LD_LIBRARY_PATH must contain the location of the
 214   PYTHIA 8 shared library, e.g.
 215   <pre>
 216     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_to_PYTHIA8_installation/lib
 217   </pre>
 218   </li>
 219 </ul>
 220 The script can then be run with ROOT
 221 <pre>
 222     root pythia8.C
 223 </pre>
 224 After execution, ROOT will display some histograms from the event
 225 generation.
 226
 227 <h4>Advanced usage</h4>
 228
 229 To access the full PYTHIA functionality from the CINT interpreter,
 230 a ROOT dictionary must be created. An example of creating this
 231 dictionary is contained in the <code>rootexamples</code> directory.
 232 The <code>pythiaDict.so</code> library may be created by running
 233 <pre>
 234     make dict
 235 </pre>
 236
 237 This may then be loaded in ROOT giving full access to the full PYTHIA 8
 238 functionality, e.g. in an interactive session
 239 <pre>
 240     gSystem->Load("path_to_PYTHIA8_installation/rootexamples/pythiaDict");
 241     Pythia8::Pythia *p = new Pythia8::Pythia();
 242     p->readString("SoftQCD:minBias = on");
 243 </pre>
 244
 245 </chapter>
 246
 247 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->