Update to pythi8.170
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / xmldoc / BeamParameters.xml
1 <chapter name="Beam Parameters">
2
3 <h2>Beam Parameters</h2>
4
5 The settings on this page relate to the beam identities and energies, 
6 to a beam momentum spread and to a beam interaction spot. 
7 As always, momenta and energies are to be given in units of GeV,
8 and of space and time in mm. 
9
10 <h3>Incoming beams</h3>
11
12 There are two ways to set the identities and energies of the two incoming 
13 beam particles. One is to use the <code>init()</code> method with no 
14 arguments. Then the settings variables below will be read and used. The 
15 alternative is to call <code><aloc href="ProgramFlow">init(...)</aloc></code> 
16 with arguments that provide this information. Then you need not use the 
17 variables below (although it would still be possible). Note that, if nothing 
18 is done, you will default to LHC at 14 TeV.
19
20 <p/>
21 Currently the beam particles must be either a hadron pair or a lepton
22 pair. In the former category <ei>p p</ei> and <ei>pbar p</ei> 
23 combinations dominate, but it is also possible to combine with 
24 <ei>pi^+</ei>, <ei>pi^-</ei> and <ei>pi^0</ei>. In the latter 
25 <ei>e^+ e^-</ei> and <ei>mu^+ mu^-</ei> would be the most useful 
26 combinations, but also others should work if combined with an 
27 appropriate hard process.
28
29 <modeopen name="Beams:idA" default="2212">
30 The PDG <code>id</code> code for the first incoming particle.
31 Allowed codes include 
32 <br/><ei>2212 = p</ei>, <ei>-2212 = pbar</ei>, 
33 <br/><ei>211 = pi^+</ei>, <ei>-211 = pi^-</ei>, <ei>111 = pi^0</ei>,  
34 <br/><ei>990 = Pomeron</ei> (used in diffractive machinery;
35 here mainly for debug purposes),
36 <br/><ei>11 = e^-</ei>, <ei>-11 = e^+</ei>, 
37 <br/><ei>13 = mu^-</ei>, <ei>-13 = mu^+</ei>, 
38 <br/>and a few more leptons/neutrinos in a few combinations.
39 </modeopen>
40
41 <modeopen name="Beams:idB" default="2212">
42 The PDG <code>id</code> code for the second incoming particle.
43 </modeopen>
44  
45 <modepick name="Beams:frameType" default="1" min="1" max="5">
46 Choice of frame for the two colliding particles. For options
47 1 - 3 the beam identities are specified above, while they are
48 obtained by the Les Houches information for options 4 and 5.
49 <option value="1">the beams are colliding in their CM frame, 
50 and therefore only the CM energy needs to be provided, see 
51 <code>Beams:eCM</code> below.
52 </option>
53 <option value="2">the beams are back-to-back, but with different energies,
54 see <code>Beams:eA</code> and <code>Beams:eB</code> below.
55 This option could also be used for fixed-target configurations.
56 </option>
57 <option value="3">the beams are not back-to-back, and therefore the
58 three-momentum of each incoming particle needs to be specified, see
59 <code>Beams:pxA</code> through <code>Beams:pzB</code> below.
60 </option> 
61 <option value="4">the beam and event information is stored in a 
62 <aloc href="LesHouchesAccord">Les Houches Event File</aloc>, 
63 see <code>Beams:LHEF</code> below.
64 </option> 
65 <option value="5">the beam and event information is obtained by a
66 pointer to an <code><aloc href="LesHouchesAccord">LHAup</aloc></code> 
67 class instance.  
68 </option> 
69 </modepick>
70
71 <parm name="Beams:eCM" default="14000." min="10.">
72 Collision CM energy, to be set if <code>Beams:frameType</code> = 1. 
73 </parm>
74
75 <parm name="Beams:eA" default="7000." min="0.">
76 The energy of the first incoming particle, moving in the 
77 <ei>+z </ei>direction, to be set if <code>Beams:frameType</code> = 2. 
78 If the particle energy is smaller than its mass
79 it is assumed to be at rest. 
80 </parm>
81
82 <parm name="Beams:eB" default="7000." min="0."> 
83 The energy of the second incoming particle, moving in the 
84 <ei>-z</ei> direction, to be set if <code>Beams:frameType</code> = 2. 
85 If the particle energy is smaller than its mass
86 it is assumed to be at rest.
87 </parm>
88
89 <parm name="Beams:pxA" default="0.">
90 The <ei>p_x</ei> component of the first incoming particle, 
91 to be set if <code>Beams:frameType</code> = 3. 
92 </parm>
93
94 <parm name="Beams:pyA" default="0.">
95 The <ei>p_y</ei> component of the first incoming particle, 
96 to be set if <code>Beams:frameType</code> = 3. 
97 </parm>
98
99 <parm name="Beams:pzA" default="7000.">
100 The <ei>p_z</ei> component of the first incoming particle, 
101 to be set if <code>Beams:frameType</code> = 3. 
102 </parm>
103
104 <parm name="Beams:pxB" default="0.">
105 The <ei>p_x</ei> component of the second incoming particle, 
106 to be set if <code>Beams:frameType</code> = 3. 
107 </parm>
108
109 <parm name="Beams:pyB" default="0.">
110 The <ei>p_y</ei> component of the second incoming particle, 
111 to be set if <code>Beams:frameType</code> = 3. 
112 </parm>
113
114 <parm name="Beams:pzB" default="-7000.">
115 The <ei>p_z</ei> component of the second incoming particle, 
116 to be set if <code>Beams:frameType</code> = 3. 
117 </parm>
118
119 <word name="Beams:LHEF" default="void">
120 The name of a Les Houches Event File,
121 to be set if <code>Beams:frameType</code> = 4. 
122 </word>
123
124 <word name="Beams:LHEFheader" default="void">
125 As some information in a Les Houches Event File init block is only known
126 at the end of generation, some programs choose to output this as a
127 separate file. If <code>Beams:LHEFheader</code> is given, information up
128 till the end of the init block is read from this file, with
129 the events themselves read as usual from the file given in
130 <code>Beams:LHEF</code>.
131 </word>
132
133 <flag name="Beams:newLHEFsameInit" default="off">
134 Allow to begin reading events from a new LHEF or or a new 
135 <code>LHAup</code> instance without a completely new initialization. 
136 Only useful when <code>Beams:frameType</code> = 4 or 5.
137 </flag>
138
139 <flag name="Beams:readLHEFheaders" default="on">
140 Read in LHEF header blocks and store them in the
141 <aloc href="EventInformation">Info</aloc> class. See also
142 <aloc href="LesHouchesAccord">LHAupLHEF</aloc> for more information.
143 </flag>
144
145 <mode name="Beams:nSkipLHEFatInit" default="0">
146 Skip the first <ei>nSkip</ei> events of the input stream 
147 (cf. the <code>LHAup::skipEvent(nSkip)</code> method).
148 Only used when <code>Beams:frameType</code> = 4 or 5.
149 </flag>
150
151 <h3>Beam momentum spread</h3>
152
153 This framework currently is intended for a modest beam spread, such as
154 experienced at hadron colliders. Thus it can be safely assumed that the 
155 physics does not change over the CM energy range probed, so that the 
156 parameters of the physics initialization at the nominal energy can be
157 used as is. Currently it can <b>not</b> be used for the more extensive
158 energy spread expected at linear <ei>e^+ e^-</ei> colliders. Also,
159 any attempt to combine it with external Les Houches input of 
160 parton-level events is at own risk. 
161      
162 <p/>
163 On this page you can set the momentum spread according to a simple 
164 Gaussian distribution. If you instead want a more sophisticated 
165 parametrization, you can write and link your own 
166 <code><aloc href="BeamShape">BeamShape</aloc></code> class.
167
168 <flag name="Beams:allowMomentumSpread" default="off">
169 Allow the beam momenta to be smeared around their initialization
170 nominal values. 
171 </flag>
172
173 <parm name="Beams:sigmaPxA" default="0." min="0.">
174 The width of a Gaussian distribution of the <ei>p_x</ei> spread of the
175 first incoming particle.
176 </parm>
177
178 <parm name="Beams:sigmaPyA" default="0." min="0.">
179 The width of a Gaussian distribution of the <ei>p_y</ei> spread of the
180 first incoming particle.
181 </parm>
182
183 <parm name="Beams:sigmaPzA" default="0." min="0.">
184 The width of a Gaussian distribution of the <ei>p_z</ei> spread of the
185 first incoming particle.
186 </parm>
187
188 <parm name="Beams:maxDevA" default="5." min="0.">
189 The triply Gaussian distribution <ei>(p_x, p_y, p_z)</ei> is restricted to 
190 a maximal total deviation from the nominal values <ei>(p_x0, p_y0, p_z0)</ei>
191 for the first incoming particle, like
192 <eq>
193 (p_x - p_x0)^2/sigma_px^2 + (p_y - p_y0)^2/sigma_py^2 +
194 (p_z - p_z0)^2/sigma_pz^2 < maxDev^2
195 </eq>
196 (Note the absence of a factor 2 in the denominator, unlike the Gaussians 
197 used to pick <ei>(p_x, p_y, p_z)</ei>.) 
198 </parm>
199
200 <parm name="Beams:sigmaPxB" default="0." min="0.">
201 The width of a Gaussian distribution of the <ei>p_x</ei> spread of the
202 second incoming particle.
203 </parm>
204
205 <parm name="Beams:sigmaPyB" default="0." min="0.">
206 The width of a Gaussian distribution of the <ei>p_y</ei> spread of the
207 second incoming particle.
208 </parm>
209
210 <parm name="Beams:sigmaPzB" default="0." min="0.">
211 The width of a Gaussian distribution of the <ei>p_z</ei> spread of the
212 second incoming particle.
213 </parm>
214
215 <parm name="Beams:maxDevB" default="5." min="0.">
216 The triply Gaussian distribution <ei>(p_x, p_y, p_z)</ei> is restricted to 
217 a maximal total deviation from the nominal values <ei>(p_x0, p_y0, p_z0)</ei>, 
218 for the second incoming particle, like
219 <eq>
220 (p_x - p_x0)^2/sigma_px^2 + (p_y - p_y0)^2/sigma_py^2 +
221 (p_z - p_z0)^2/sigma_pz^2 < maxDev^2
222 </eq>
223 (Note the absence of a factor 2 in the denominator, unlike the Gaussians 
224 used to pick <ei>(p_x, p_y, p_z)</ei>.) 
225 </parm>
226
227 <h3>Beam interaction vertex</h3>
228
229 On this page you can set the spread of the interaction vertex according to 
230 a simple Gaussian distribution. If you instead want a more sophisticated 
231 parametrization, you can write and link your own 
232 <code><aloc href="BeamShape">BeamShape</aloc></code> class.
233
234 <flag name="Beams:allowVertexSpread" default="off">
235 Allow the interaction vertex of the two colliding beams to be smeared.
236 If off, then the vertex is set to be the origin.
237 </flag>
238
239 <parm name="Beams:sigmaVertexX" default="0." min="0.">
240 The width of a Gaussian distribution of the <ei>x</ei> location of the
241 interaction vertex. 
242 </parm>
243
244 <parm name="Beams:sigmaVertexY" default="0." min="0.">
245 The width of a Gaussian distribution of the <ei>y</ei> location of the
246 interaction vertex. 
247 </parm>
248
249 <parm name="Beams:sigmaVertexZ" default="0." min="0.">
250 The width of a Gaussian distribution of the <ei>z</ei> location of the
251 interaction vertex. 
252 </parm>
253
254 <parm name="Beams:maxDevVertex" default="5." min="0.">
255 The triply Gaussian distribution of interaction vertex position 
256 <ei>(x, y, z)</ei> is restricted to a maximal total deviation from the 
257 origin, like
258 <eq>
259 x^2/sigma_x^2 + y^2/sigma_y^2 + z^2/sigma_z^2 < maxDevVertex^2
260 </eq>
261 (Note the absence of a factor 2 in the denominator, unlike the Gaussians 
262 used to pick <ei>(x, y, z)</ei>.) 
263 </parm>
264
265 <parm name="Beams:sigmaTime" default="0." min="0.">
266 The width of a Gaussian distribution of the collision time (in units of
267 mm/c). Note that, if the above space parametrization is viewed as the
268 effect of two incoming beams along the <ei>+-z</ei> axis, with each beam
269 having a Gaussian spread, then the spread of the time would also become 
270 a Gaussian with the same width as the <ei>z</ei> one (times the 
271 velocity of the beams, which we expect is close to unity). For flexibility
272 we have not enforced any such relation, however. 
273 </parm>
274
275 <parm name="Beams:maxDevTime" default="5." min="0.">
276 The collision time is restricted to be in the range 
277 <ei>|t| &lt; sigma_t * maxDevTime</ei>. 
278 </parm>
279
280 <p/>
281 The distributions above are all centered at the origin. It is also 
282 possible to shift the above distributions to be centered around another
283 nominal position. You must have <code>Beams:allowVertexSpread = on</code>
284 to use this possibility.
285
286 <parm name="Beams:offsetVertexX" default="0.">
287 The <ei>x</ei> location of the interaction vertex is centered at this value. 
288 </parm>
289
290 <parm name="Beams:offsetVertexY" default="0.">
291 The <ei>y</ei> location of the interaction vertex is centered at this value. 
292 </parm>
293
294 <parm name="Beams:offsetVertexZ" default="0.">
295 The <ei>z</ei> location of the interaction vertex is centered at this value. 
296 </parm>
297
298 <parm name="Beams:offsetTime" default="0.">
299 The time <ei>t</ei> of the interaction vertex is centered at this value. 
300 </parm>
301
302 </chapter>
303
304 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->