PYTHIA8/pythia8170/htmldoc/ROOTusage.html

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