PYTHIA8/pythia8170/xmldoc/AdvancedUsage.xml

   1 <chapter name="Advanced Usage">
   2
   3 <h2>Advanced Usage</h2>
   4
   5 On this page we collect information on a number of classes that
   6 the normal user would not encounter. There are cases where the
   7 information is essential, however, for instance to
   8 <aloc href="ImplementNewShowers">implement your own showers</aloc>.
   9
  10 <h3>The subsystems</h3>
  11
  12 One aspect that complicates administration is that an event
  13 can contain several subsystems, each consisting of one MPI and its
  14 associated ISR and FSR. To first approximation these systems are
  15 assumed to evolve independently, but to second they are connected by
  16 the interleaved evolution, and potentially by rescattering effects.
  17 The partons of a given subsystem therefore do not have to be stored
  18 consecutively.
  19
  20 <p/>
  21 The <code>PartonSystems</code> class is primarily used to keep track
  22 of the current positions of all partons belonging to each system,
  23 represented by the index <code>iPos</code> for a parton stored in the
  24 event-record slot <code>event[iPos]</code>. With "all" we mean the
  25 currently defined two incoming partons, or none for a resonance decay,
  26 and the current set of outgoing partons, but with all ISR and FSR
  27 intermediate-state partons omitted. That is, it stores all partons
  28 that could be subject to some action in the next step of the
  29 combined MPI/ISR/FSR/BR description. As a special case, an outgoing
  30 parton is stored even if it undergoes a rescattering, and thus no
  31 longer belongs to the final state proper.
  32
  33 <p/>
  34 The <code>partonSystems</code> instance of <code>PartonSystems</code>
  35 class is a public member of the <code>Pythia</code> top-level class,
  36 but is also available as a pointer <code>partonSystemsPtr</code> in
  37 various <code>PartonLevel</code> classes, e.g. inside the current
  38 instances of the <code>TimeShower</code> and <code>SpaceShower</code>
  39 classes.
  40
  41 <p/>
  42 A number of <code>PartonSystems</code> methods can be used to set or
  43 get information on the subsystems:
  44 <ul>
  45 <li><code>clear()</code> resets all the contents in preparation for the
  46 next event.
  47 <li><code>addSys()</code> add a new (initially empty) subsystem to the
  48 current list and return its index <code>iSys</code> in the list,
  49 where index 0 is the hardest subcollision and so on.
  50 <li><code>sizeSys()</code> the number of separate subsystems.</li>
  51 <li><code>setInA(iSys, iPos), setInB(iSys, iPos)</code> store position
  52 <code>iPos</code> of the incoming parton from beam A or beam B to the
  53 <code>iSys</code>'th subcollision. These values are 0 initially, and
  54 should so remain if there are no beams, such as in resonance decays.
  55 </li>
  56 <li><code>addOut(iSys, iPos)</code> store position <code>iPos</code>
  57 of a new outgoing parton in the <code>iSys</code>'th subcollision,
  58 by appending it at the end of the current vector, with beginning in
  59 slot 0.</li>
  60 <li><code>setOut(iSys, iMem, iPos)</code> store position <code>iPos</code>
  61 in the <code>iMem</code>'th slot in the vector of outgoing partons in the
  62 <code>iSys</code>'th subcollision. Here <code>iMem</code> must be in
  63 the range already constructed by <code>addOut</code> calls. </li>
  64 <li><code>replace(iSys, iPosOld, iPosNew)</code> replace the existing
  65 incoming or outgoing parton position <code>iPosOld</code> by
  66 <code>iPosNew</code> in the <code>iSys</code>'th subcollision.</li>
  67 <li><code>setSHat(iSys, sHat)</code> set the invariant squared mass
  68 <code>sHat</code> of the <code>iSys</code>'th subcollision.</li>
  69 <li><code>hasInAB(iSys)</code> true if an incoming parton has been set
  70 for beam A or beam B (and hence should have been set for both) in the
  71 <code>iSys</code>'th subcollision, else false.</li>
  72 <li><code>getInA(iSys), getInB(iSys)</code> the position <code>iPos</code>
  73 of the incoming parton from beam A or beam B to the <code>iSys</code>'th
  74 subcollision.</li>
  75 <li><code>sizeOut(iSys)</code> the number of outgoing partons
  76 in the <code>iSys</code>'th subcollision.</li>
  77 <li><code>getOut(iSys, iMem)</code> the position <code>iPos</code>
  78 of an outgoing parton in the <code>iSys</code>'th subcollision,
  79 with the <code>iMem</code> range limited by <code>sizeOut(iSys)</code>.
  80 These partons are not guaranteed to appear in any particular order. </li>
  81 <li><code>sizeAll(iSys)</code> the total number of incoming and outgoing
  82 partons in the <code>iSys</code>'th subcollision.</li>
  83 <li><code>getAll(iSys, iMem)</code> the position <code>iPos</code>
  84 of an incoming or outgoing parton in the <code>iSys</code>'th subcollision.
  85 In case there are beams it gives same as <code>getInA(iSys) </code> and
  86 <code> getInB(iSys)</code> for indices 0 and 1, and thereafter agrees with
  87 <code>getOut(iSys, iMem)</code> offset two positions. If there are no
  88 beams it is identical with <code>getOut(iSys, iMem)</code>.</li>
  89 <li><code>getSHat(iSys)</code> the invariant squared mass
  90 <code>sHat</code> of the <code>iSys</code>'th subcollision.</li>
  91 <li><code>list()</code> print a listing of all the system information,
  92 except for the <code>sHat</code> values.</li>
  93 </ul>
  94
  95 <p/>
  96 New systems are created from the hard process and by the MPI, not from
  97 any of the other components. Both FSR and ISR modify the position
  98 of partons, however. Since an FSR or ISR branching typically implies
  99 a new state with one more parton than before, an outgoing parton must
 100 be added to the system. Furthermore, in a branching, several existing
 101 partons may also be moved to new slots, including the incoming beam ones.
 102 In a FSR <ei>1 -> 2</ei> branching it is irrelevant which parton position
 103 you let overwrite the existing slot and which is added to the end of
 104 the system.
 105
 106 <p/>
 107 The system information must be kept up-to-date. Both the MPI, ISR, FSR and
 108 BR descriptions make extensive use of the existing information. As an
 109 example, the introduction of primordial <ei>kT</ei> in the beam remnants
 110 will fail if the information on which final-state partons belong to which
 111 system is out-of-date. The introduction of rescattering as part of the
 112 MPI framework adds further complications, where an outgoing parton of one
 113 subsystem may be the incoming one of another system. This part of the code
 114 is still under development.
 115
 116 <p/>
 117 Currently the system information is kept throughout the continued
 118 history of the event. Specifically, resonance decays create new systems,
 119 appended to the existing ones. This could be useful during the
 120 hadronization stage, to collect the partons that belong to a resonace
 121 with preserved mass when a small string collapses to one particle,
 122 but is not yet used for that.
 123
 124 <h3>The beams</h3>
 125
 126 The different subsystems are tied together by them sharing the same
 127 initial beam particles, and thereby being restricted by energy-momentum
 128 and flavour conservation issues. The information stored in the two
 129 beam particles, here called <code>beamA</code> and <code>beamB</code>,
 130 is therefore as crucial to keep correct as the above subsystem list.
 131
 132 <p/>
 133 Both beam objects are of the <code>BeamParticle</code> class.
 134 Each such object contains a vector with the partons extracted from it.
 135 The number of such partons, <code>beamX.size()</code> (X = A or B),
 136 of course is the same as the above number of subsystems in the event
 137 record. (The two diverge at the BR step, where further beam remnants
 138 are added to the beams without corresponding to new subsystems.)
 139 The individual partons are accessed by an overloaded indexing
 140 operator to a vector of <code>ResolvedParton</code> objects. The
 141 <code>iPos()</code> property corresponds to the <code>iPos</code>
 142 one above, i.e. providing the position in the main event record of
 143 a parton. In particular,
 144 <code>beamA[iSys].iPos() = partonSystemsPtr->getInA(iSys)</code> and
 145 <code>beamB[iSys].iPos() = partonSystemsPtr->getInB(iSys)</code>.
 146 Whereas thus the indices of the two incoming partons to a subsystem
 147 are stored in two places, the ones of the outgoing partons only
 148 appear in the system part of the <code>PartonSystems</code> class.
 149
 150 <p/>
 151 Just as the subsystems in <code>PartonSystems</code> must be updated,
 152 so must the information in the two <code>BeamParticle</code>'s, e.g.
 153 with methods<code>beamX[iSys].iPos( iPosIn)</code> when an incoming
 154 parton is replaced by a new one in line <code>iPosIn</code>. Furthermore
 155 the new parton identity should be set by <code>beamX[iSys].id( idIn)</code>
 156 and the new <ei>x</ei> energy-momentum fraction by
 157 <code>beamX[iSys].x( xIn)</code>. The three can be combined in one go
 158 by <code>beamX[iSys].update( iPosIn, idIn, xIn)</code>.
 159
 160 <p/>
 161 To be specific, it is assumed that, at each step, the two incoming
 162 partons are moving along the <ei>+-z</ei> axis and are massless.
 163 Since the event is constructed in the c.m. frame of the incoming
 164 beams this implies that <ei>x = 2 E / E_cm</ei>.
 165 If the <ei>x</ei> values are not defined accordingly or not kept
 166 up-to-date the BR treatment will not conserve energy-momentum.
 167
 168 <p/>
 169 In return, the <code>BeamParticle</code> objects give access to some
 170 useful methods. The <code>beamX.xf( id, x, Q2)</code> returns the
 171 standard PDF weight <ei>x f_id(x, Q^2)</ei>. More intererstingly,
 172 <code>beamX.xfISR( iSys, id, x, Q2)</code> returns the modified weight
 173 required when several subsystems have to share the energy and flavours.
 174 Thus <code>iSys</code> is added as an extra argument, and the momentum
 175 already assigned to the other subsystems is not available for evolution,
 176 i.e. the maximal <ei>x</ei> is correspondingly smaller than unity.
 177 Also flavour issues are handled in a similar spirit.
 178
 179 <p/>
 180 An additional complication is that a parton can be either valence or
 181 sea, and in the latter case the BR treatment also distinguishes
 182 companion quarks, i.e. quark-antiquark pairs that are assumed to
 183 come from the same original <ei>g -> q qbar</ei> branching, whether
 184 perturbative or not. This can be queried either with the
 185 <code>beamX[iSys].companion()</code> method, for detailed information,
 186 or with the <code>beamX[iSys].isValence()</code>,
 187 <code>beamX[iSys].isUnmatched()</code> and
 188 <code>beamX[iSys].isCompanion()</code> metods for yes/no answers
 189 whether a parton is valence, unmatched sea or matched sea.
 190 This choice should affect the ISR evolution; e.g., a valence quark
 191 cannot be constructed back to come from a gluon.
 192
 193 <p/>
 194 To keep this info up-to-date, the <code>beamX.pickValSeaComp()</code>
 195 method should be called whenever a parton of a new flavour has been
 196 picked in the ISR backwards evolution, but not if the flavour has not
 197 been changed, since then one should not be allowed to switch back and
 198 forth between the same quark being considered as valence or as sea.
 199 Since the <code>pickValSeaComp()</code> method makes use of the
 200 current parton-density values, it should be preceded by a call
 201 to <code>beamX.xfISR( iSys, id, x, Q2)</code>, where the values in
 202 the call are the now finally accepted ones for the newly-found mother.
 203 (Such a call is likely to have been made before, during the evolution,
 204 but is not likely to be the most recent one, i.e. still in memory, and
 205 therefore had better be redone.)
 206
 207 </chapter>
 208
 209 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->