PYTHIA8/pythia8145/examples/README

   1 ----------------------------------------------------------------------
   2
   3    BASIC INSTRUCTIONS FOR RUNNING TEST PROGRAMS
   4
   5 1) You are supposed to have already compiled PYTHIA 8, as described in
   6    the README file of the mother directory. For the moment we assume
   7    that you will NOT use the HepMC, LHAPDF, or FastJet libraries.
   8
   9 2) You are now ready to test run the first twentynine of the mainNN
  10    examples listed below. Type "gmake mainNN" to build an executable
  11    "mainNN.exe". Type "./mainNN.exe > output" to run this executable.
  12    Then study the output file. The existing files outNN are examples of
  13    possible outputs from several runs, so that you can compare.
  14
  15 3) If you want to run your own programs from this directory you can edit
  16    the "Makefile", adding the name of your main program to the already
  17    existing ones. Note that different cases exist, depending on which
  18    external libraries are to be linked.
  19
  20 4) Type "gmake clean" to clean up the examples directory (but not the
  21    output files).
  22
  23 ----------------------------------------------------------------------
  24
  25    ADVANCED INSTRUCTIONS FOR RUNNING TEST PROGRAMS
  26
  27 1) If you want to be able to run examples linked to HepMC you should
  28    already have set that up with the "./configure" command in the mother
  29    directory. If not, you can go back and do it now. This will create
  30    files "config.csh" and "config.sh" in the current directory.
  31
  32 2) If you are going to run examples linked with LHAPDF and/or FastJet,
  33    you should as a first step run the script "configure" in the current
  34    directory. You can use command-line arguments to set up the desired
  35    library links.
  36
  37    The possible options are:
  38      --help : prints a brief summary of the options described here.
  39      --enable-debug : turns on debugging flags and turns off optimization
  40      --enable-shared : use shared library (not yet implemented) (default no)
  41      --with-lhapdf=lhapdfpath : the path to your local copy of the LHAPDF
  42          library (must be version 5.3 or higher)
  43      --with-lhapdfversion=v : a simpler alternative to the above, valid
  44          if you are using the CERN AFS MCGenerators area; then you do not
  45          need to specify the full path but only the version, e.g. =5.3.0
  46          (must be version 5.3 or higher)
  47      --with-lhapdflibname=n : lhapdf library name line (default is -lLHAPDF)
  48      --with-lhapdfsets=path : path to the LHAPDF data files
  49          (default is lhapdfpath/../PDFsets, CERN AFS default is
  50          lhapdfpath/../../../share/PDFsets)
  51      --with-fastjet=path : path to FastJet (default = /usr/local)
  52      --with-fastjetversion=v : FastJet version
  53          (simplified alternative when using CERN AFS external, e.g. =2.3.3)
  54
  55    When "configure" is run it will create or append to the config.csh
  56    and config.sh files.
  57
  58 3) Before running the examples using external libraries for the first
  59    time, type "source config.csh" if you use the csh or tcsh shell, or
  60    "source config.sh" otherwise. (Use "echo $SHELL" if uncertain.)
  61    This will set or append the environment variables LD_LIBRARY_PATH,
  62    needed to find the HepMC libraries. (Eventually also LHAPDF and FastJet
  63    libraries, if shared ones are used. Default, if taken from CERN AFS
  64    MCGenerators, is archive.) It will also set the variable LHAPATH,
  65    needed to find the LHAPDF data files.
  66
  67 4) If you want to change to other LHAPDF or FastJet or versions, you
  68    have to rerun the script "configure" and again "source" one of the
  69    config.* files. In case of using shared libraries (these will  be taken
  70    if both shared and archive ones are on the same path) pay attention to
  71    the variable LD_LIBRARY_PATH: subsequent commands "source" will add new
  72    items to it, not substitute the old ones. As a result, the wrong
  73    version can still be loaded at runtime, which can cause relocation
  74    errors. A simple solution is to repeat the "configure" and "source"
  75    steps in a new window, i.e. in a new clean copy of the shell.
  76
  77 ----------------------------------------------------------------------
  78
  79    LIST OF TEST PROGRAMS
  80
  81 1) main01 - main20, main28 - main30, main71 only use the PYTHIA 8 library
  82 * main01.cc : brief example with charged multiplicity distribution
  83 * main02.cc : brief example with Z0 pT spectrum
  84 * main03.cc & main03.cmnd : simple single-particle analysis in jet events
  85 * main04.cc & main04.cmnd : simple tests of event properties
  86 * main05.cc : cone-jet analysis of LHC events
  87 * main06.cc & main06.cmnd : study elastic/diffractive events
  88 * main07.cc & main07.cmnd : study minimum-bias events
  89 * main08.cc & main08.cmnd  : combine results of subruns in separate pT bins
  90 * main09.cc : LEP events with sphericity/thrust/jetfinder analysis
  91 * main10.cc : implement UserHooks to interact with the generation process
  92 * main11.cc : set two hard interactions in the same event
  93 * main12.cc & ttbar.lhe : generate events from a Les Houches Event File
  94 * main13.cc & ttbar.lhe & ttbar2.lhe : several Les Houches Event Files & more
  95 * main14.cc : compare several cross sections with their PYTHIA 6.4 values.
  96 * main15.cc : redo B decays or hadronization several times for each event
  97 * main16.cc : user analysis class; command-line specification of input file
  98 * main17.cc : Pythia wrapper class; command-line specification of input file
  99 * main18.cc : event filter class to retain a subset of the particles
 100 * main19.cc : use two Pythia instances to combine signal and pileup events
 101 * main20.cc : write a Les Houches Event File with PYTHIA 8-generated events
 102 * main22.cc & main22.cmnd & sps1a.spc : SUSY using SLHA, internal cross sections
 103 * main28.cc : test program for large extra dimensions or unparticles
 104 * main29.cc : generic "energy blob" decay for cosmic-ray physics
 105 * main30.cc : Kaluza-Klein gamma/Z states in TeV-sized extra dimensions
 106 * main71.cc & powheg-hvq.lhe : interface to POWHEG events
 107 * main72.cc & main72.lhe : RPV-SUSY from LHEF with color junctions
 108
 109 2) main21 - main27 are examples how some external programs could be linked
 110 * main21.cc : external input of parton configurations for hadronization only
 111 * main23.cc : how to link an external decay handler
 112 * main24.cc : how to link an external random number generator
 113 * main25.cc : how to link an external process to use internally
 114 * main26.cc : how to link an external resonance and process to use internally
 115 * main27.cc : how to link an external momentum spread and vertex generator
 116
 117 3) main31 - main32 require linkage to the HepMC event record library
 118 * main31.cc & main31.cmnd : simple example output to HepMC
 119 * main32.cc & main32.cmnd : streamlined production of a HepMC event file
 120
 121 4) main41 - main43 require linkage to LHAPDF
 122 * main41.cc : test shape of PDF's
 123 * main42.cc : compare average multiplicity and pT for different PDF's
 124 * main43.cc : example of evolution with photon-in-proton: the MRST2004qed set
 125 * main44.cc : how to create your own PDF and link it in for usage
 126
 127 5) main51.cc requires linkage to Pythia 6.4, and is deprecated
 128
 129 6) main61 requires linkage to FastJet
 130 * main61.cc : rate of W + jets events using kT-clustering for jets
 131
 132 Note 1: main31 and main32 save HepMC-formatted events on hepmcoutNN.dat;
 133     these files become so big that they have not been included in the
 134     distribution.
 135 Note 2: There is no main00 program, but main00 is defined in the
 136     Makefile to link to PYTHIA 8, so this name can be used for
 137     simple first tests.
 138 Note 3: With ./runmains all the 30 first mainXX program will be run,
 139     plus main71, to get a thorough test of the installation.
 140     The runmains file can easily be edited to run the others as well,
 141     but then you should first link to the appropriate external libraries.
 142     The outref subdirectory contains the output of such a run, if you
 143     want to compare with what you obtain.
 144
 145 ----------------------------------------------------------------------