PYTHIA8/pythia8170/xmldoc/FourVectors.xml

   1 <chapter name="Four-Vectors">
   2
   3 <h2>Four-Vectors</h2>
   4
   5 The <code>Vec4</code> class gives a simple implementation of four-vectors.
   6 The member function names are based on the assumption that these
   7 represent four-momentum vectors. Thus one can get or set
   8 <ei>p_x, p_y, p_z</ei> and <ei>e</ei>, but not <ei>x, y, z</ei>
   9 or <ei>t</ei>. This is only a matter of naming, however; a
  10 <code>Vec4</code> can equally well be used to store a space-time
  11 four-vector.
  12
  13 <p/>
  14 The <code>Particle</code> object contains a <code>Vec4 p</code> that
  15 stores the particle four-momentum, and another <code>Vec4 vProd</code>
  16 for the production vertex. For the latter the input/output method
  17 names are adapted to the space-time character rather than the normal
  18 energy-momentum one. Thus a user would not normally access the
  19 <code>Vec4</code> classes directly, but only via the methods of the
  20 <code>Particle</code> class,
  21 see <aloc href="ParticleProperties">Particle Properties</aloc>.
  22
  23 <p/>
  24 Nevertheless you are free to use the PYTHIA four-vectors, e.g. as
  25 part of some simple analysis code based directly on the PYTHIA output,
  26 say to define the four-vector sum of a set of particles. But note that
  27 this class was never set up to allow complete generality, only  to
  28 provide the operations that are of use inside PYTHIA. There is no
  29 separate class for three-vectors, since such can easily be represented
  30 by four-vectors where the fourth component is not used.
  31
  32 <p/>
  33 Four-vectors have the expected functionality: they can be created,
  34 copied, added, multiplied, rotated, boosted, and manipulated in other
  35 ways. Operator overloading is implemented where reasonable. Properties
  36 can be read out, not only the components themselves but also for derived
  37 quantities such as absolute momentum and direction angles.
  38
  39 <h3>Constructors and basic operators</h3>
  40
  41 A few methods are available to create or copy a four-vector:
  42
  43 <method name="Vec4::Vec4()">
  44 creates a four-vector with all components set to 0.
  45 </method>
  46
  47 <method name="Vec4::Vec4(const Vec4& v)">
  48 creates a four-vector copy of the input four-vector.
  49 </method>
  50
  51 <method name="Vec4& Vec4::operator=(const Vec4& v)">
  52 copies the input four-vector.
  53 </method>
  54
  55 <method name="Vec4& Vec4::operator=(double value)">
  56 gives a  four-vector with all components set to <ei>value</ei>.
  57 </method>
  58
  59 <h3>Member methods for input</h3>
  60
  61 The values stored in a four-vector can be modified in a few different
  62 ways:
  63
  64 <method name="void Vec4::reset()">
  65 sets all components to 0.
  66 </method>
  67
  68 <method name="void Vec4::p(double pxIn, double pyIn, double pzIn,
  69 double eIn)">
  70 sets all components to their input values.
  71 </method>
  72
  73 <method name="void Vec4::p(Vec4 pIn)">
  74 sets all components equal to those of the input four-vector.
  75 </method>
  76
  77 <method name="void Vec4::px(double pxIn)">
  78 </method>
  79 <methodmore name="void Vec4::py(double pyIn)">
  80 </methodmore>
  81 <methodmore name="void Vec4::pz(double pzIn)">
  82 </methodmore>
  83 <methodmore name="void Vec4::e(double eIn)">
  84 sets the respective component to the input value.
  85 </methodmore>
  86
  87 <h3>Member methods for output</h3>
  88
  89 A number of methods provides output of basic or derived quantities:
  90
  91 <method name="double Vec4::px()">
  92 </method>
  93 <methodmore name="double Vec4::py()">
  94 </methodmore>
  95 <methodmore name="double Vec4::pz()">
  96 </methodmore>
  97 <methodmore name="double Vec4::e()">
  98 gets the respective component.
  99 </methodmore>
 100
 101 <method name="double Vec4::mCalc()">
 102 </method>
 103 <methodmore name="double Vec4::m2Calc()">
 104 the (squared) mass, calculated from the four-vectors.
 105 If <ei>m^2 &lt; 0</ei> the mass is given with a minus sign,
 106 <ei>-sqrt(-m^2)</ei>.  Note the possible loss of precision
 107 in the calculation of <ei>E^2 - p^2</ei>; for particles the
 108 correct mass is stored separately to avoid such problems.
 109 </methodmore>
 110
 111 <method name="double Vec4::pT()">
 112 </method>
 113 <methodmore name="double Vec4::pT2()">
 114 the (squared) transverse momentum.
 115 </methodmore>
 116
 117 <method name="double Vec4::pAbs()">
 118 </method>
 119 <methodmore name="double Vec4::pAbs2()">
 120 the (squared) absolute momentum.
 121 </methodmore>
 122
 123 <method name="double Vec4::eT()">
 124 </method>
 125 <methodmore name="double Vec4::eT2()">
 126 the (squared) transverse energy,
 127 <ei>eT = e * sin(theta) = e * pT / pAbs</ei>.
 128 </methodmore>
 129
 130 <method name="double Vec4::theta()">
 131 the polar angle, in the range 0 through
 132 <ei>pi</ei>.
 133 </method>
 134
 135 <method name="double Vec4::phi()">
 136 the azimuthal angle, in the range <ei>-pi</ei> through <ei>pi</ei>.
 137 </method>
 138
 139 <method name="double Vec4::thetaXZ()">
 140 the angle in the <ei>xz</ei> plane, in the range <ei>-pi</ei> through
 141 <ei>pi</ei>, with 0 along the <ei>+z</ei> axis.
 142 </method>
 143
 144 <method name="double Vec4::pPos()">
 145 </method>
 146 <methodmore name="double Vec4::pNeg()">
 147 the combinations <ei>E+-p_z</ei>.</methodmore>
 148
 149 <h3>Friend methods for output</h3>
 150
 151 There are also some <code>friend</code> methods that take one, two
 152 or three four-vectors as argument. Several of them only use the
 153 three-vector part of the four-vector.
 154
 155 <method name="friend ostream& operator&lt;&lt;(ostream&, const Vec4& v)">
 156 writes out the values of the four components of a <code>Vec4</code> and,
 157 within brackets, a fifth component being the invariant length of the
 158 four-vector, as provided by <code>mCalc()</code> above, and it all
 159 ended with a newline.
 160 </method>
 161
 162 <method name="friend double m(const Vec4& v1, const Vec4& v2)">
 163 </method>
 164 <methodmore name="friend double m2(const Vec4& v1, const Vec4& v2)">
 165 the (squared) invariant mass.
 166 </methodmore>
 167
 168 <method name="friend double dot3(const Vec4& v1, const Vec4& v2)">
 169 the three-product.
 170 </method>
 171
 172 <method name="friend double cross3(const Vec4& v1, const Vec4& v2)">
 173 the cross-product.
 174 </method>
 175
 176 <method name="friend double theta(const Vec4& v1, const Vec4& v2)">
 177 </method>
 178 <methodmore name="friend double costheta(const Vec4& v1, const Vec4& v2)">
 179 the (cosine) of the opening angle between the vectors,
 180 in the range 0 through <ei>pi</ei>.
 181 </methodmore>
 182
 183 <method name="friend double phi(const Vec4& v1, const Vec4& v2)">
 184 </method>
 185 <methodmore name="friend double cosphi(const Vec4& v1, const Vec4& v2)">
 186 the (cosine) of the azimuthal angle between the vectors around the
 187 <ei>z</ei> axis, in the range 0 through <ei>pi</ei>.
 188 </methodmore>
 189
 190 <method name="friend double phi(const Vec4& v1, const Vec4& v2,
 191 const Vec4& v3)">
 192 </method>
 193 <methodmore name="friend double cosphi(const Vec4& v1, const Vec4& v2,
 194 const Vec4& v3)">
 195 the (cosine) of the azimuthal angle between the first two vectors
 196 around the direction of the third, in the range 0 through <ei>pi</ei>.
 197 </methodmore>
 198
 199 <h3>Operations with four-vectors</h3>
 200
 201 Of course one should be able to add, subtract and scale four-vectors,
 202 and more:
 203
 204 <method name="Vec4 Vec4::operator-()">
 205 return a vector with flipped sign for all components, while leaving
 206 the original vector unchanged.
 207 </method>
 208
 209 <method name="Vec4& Vec4::operator+=(const Vec4& v)">
 210 add a four-vector to an existing one.
 211 </method>
 212
 213 <method name="Vec4& Vec4::operator-=(const Vec4& v)">
 214 subtract a four-vector from an existing one.
 215 </method>
 216
 217 <method name="Vec4& Vec4::operator*=(double f)">
 218 multiply all four-vector components by a real number.
 219 </method>
 220
 221 <method name="Vec4& Vec4::operator/=(double f)">
 222 divide all four-vector components by a real number.
 223 </method>
 224
 225 <method name="friend Vec4 operator+(const Vec4& v1, const Vec4& v2)">
 226 add two four-vectors.
 227 </method>
 228
 229 <method name="friend Vec4 operator-(const Vec4& v1, const Vec4& v2)">
 230 subtract two four-vectors.
 231 </method>
 232
 233 <method name="friend Vec4 operator*(double f, const Vec4& v)">
 234 </method>
 235 <methodmore name="friend Vec4 operator*(const Vec4& v, double f)">
 236 multiply a four-vector by a real number.
 237 </methodmore>
 238
 239 <method name="friend Vec4 operator/(const Vec4& v, double f)">
 240 divide a four-vector by a real number.
 241 </method>
 242
 243 <method name="friend double operator*(const Vec4& v1, const Vec4 v2)">
 244 four-vector product.
 245 </method>
 246
 247 <p/>
 248 There are also a few related operations that are normal member methods:
 249
 250 <method name="void Vec4::rescale3(double f)">
 251 multiply the three-vector components by <ei>f</ei>, but keep the
 252 fourth component unchanged.
 253 </method>
 254
 255 <method name="void Vec4::rescale4(double f)">
 256 multiply all four-vector components by <ei>f</ei>.
 257 </method>
 258
 259 <method name="void Vec4::flip3()">
 260 flip the sign of the three-vector components, but keep the
 261 fourth component unchanged.
 262 </method>
 263
 264 <method name="void Vec4::flip4()">
 265 flip the sign of all four-vector components.
 266 </method>
 267
 268 <h3>Rotations and boosts</h3>
 269
 270 A common task is to rotate or boost four-vectors. In case only one
 271 four-vector is affected the operation may be performed directly on it.
 272 However, in case many particles are affected, the helper class
 273 <code>RotBstMatrix</code> can be used to speed up operations.
 274
 275 <method name="void Vec4::rot(double theta, double phi)">
 276 rotate the three-momentum with the polar angle <ei>theta</ei>
 277 and the azimuthal angle <ei>phi</ei>.
 278 </method>
 279
 280 <method name="void Vec4::rotaxis(double phi, double nx, double ny,
 281 double nz)">
 282 rotate the three-momentum with the azimuthal angle <ei>phi</ei>
 283 around the direction defined by the <ei>(n_x, n_y, n_z)</ei>
 284 three-vector.
 285 </method>
 286
 287 <method name="void Vec4::rotaxis(double phi, Vec4& n)">
 288 rotate the three-momentum with the azimuthal angle <ei>phi</ei>
 289 around the direction defined by the three-vector part of <ei>n</ei>.
 290 </method>
 291
 292 <method name="void Vec4::bst(double betaX, double betaY, double betaZ)">
 293 boost the four-momentum by <ei>beta = (beta_x, beta_y, beta_z)</ei>.
 294 </method>
 295
 296 <method name="void Vec4::bst(double betaX, double betaY, double betaZ,
 297 double gamma)">
 298 boost the four-momentum by <ei>beta = (beta_x, beta_y, beta_z)</ei>,
 299 where the <ei>gamma = 1/sqrt(1 - beta^2)</ei> is also input to allow
 300 better precision when <ei>beta</ei> is close to unity.
 301 </method>
 302
 303 <method name="void Vec4::bst(const Vec4& p)">
 304 boost the four-momentum by <ei>beta = (p_x/E, p_y/E, p_z/E)</ei>.
 305 </method>
 306
 307 <method name="void Vec4::bst(const Vec4& p, double m)">
 308 boost the four-momentum by <ei>beta = (p_x/E, p_y/E, p_z/E)</ei>,
 309 where the <ei>gamma = E/m</ei> is also calculated from input to allow
 310 better precision when <ei>beta</ei> is close to unity.
 311 </method>
 312
 313 <method name="void Vec4::bstback(const Vec4& p)">
 314 boost the four-momentum by <ei>beta = (-p_x/E, -p_y/E, -p_z/E)</ei>.
 315 </method>
 316
 317 <method name="void Vec4::bstback(const Vec4& p, double m)">
 318 boost the four-momentum by <ei>beta = (-p_x/E, -p_y/E, -p_z/E)</ei>,
 319 where the <ei>gamma = E/m</ei> is also calculated from input to allow
 320 better precision when <ei>beta</ei> is close to unity.
 321 </method>
 322
 323 <method name="void Vec4::rotbst(const RotBstMatrix& M)">
 324 perform a combined rotation and boost; see below for a description
 325 of the <code>RotBstMatrix</code>.
 326 </method>
 327
 328 <p/>
 329 For a longer sequence of rotations and boosts, and where several
 330 <code>Vec4</code> are to be rotated and boosted in the same way,
 331 a more efficient approach is to define a <code>RotBstMatrix</code>,
 332 which forms a separate auxiliary class. You can build up this
 333 4-by-4 matrix by successive calls to the methods of the class,
 334 such that the matrix encodes the full sequence of operations.
 335 The order in which you do these calls must agree with the imagined
 336 order in which the rotations/boosts should be applied to a
 337 four-momentum, since in general the operations do not commute.
 338
 339 <method name="RotBstMatrix::RotBstMatrix()">
 340 creates a diagonal unit matrix, i.e. one that leaves a four-vector
 341 unchanged.
 342 </method>
 343
 344 <method name="RotBstMatrix::RotBstMatrix(const RotBstMatrix& Min)">
 345 creates a copy of the input matrix.
 346 </method>
 347
 348 <method name="RotBstMatrix& RotBstMatrix::operator=(const RotBstMatrix4& Min)">
 349 copies the input matrix.
 350 </method>
 351
 352 <method name="void RotBstMatrix::rot(double theta = 0., double phi = 0.)">
 353 rotate by this polar and azimuthal angle.
 354 </method>
 355
 356 <method name="void RotBstMatrix::rot(const Vec4& p)">
 357 rotate so that a vector originally along the <ei>+z</ei> axis becomes
 358 parallel with <ei>p</ei>. More specifically, rotate by <ei>-phi</ei>,
 359 <ei>theta</ei> and <ei>phi</ei>, with angles defined by <ei>p</ei>.
 360 </method>
 361
 362 <method name="void RotBstMatrix::bst(double betaX = 0., double betaY = 0.,
 363 double betaZ = 0.)">
 364 boost by this <ei>beta</ei> vector.
 365 </method>
 366
 367 <method name="void RotBstMatrix::bst(const Vec4&)">
 368 </method>
 369 <methodmore name="void RotBstMatrix::bstback(const Vec4&)">
 370 boost with a <ei>beta = p/E</ei> or <ei>beta = -p/E</ei>, respectively.
 371 </methodmore>
 372
 373 <method name="void RotBstMatrix::bst(const Vec4& p1, const Vec4& p2)">
 374 boost so that <ei>p_1</ei> is transformed to <ei>p_2</ei>. It is assumed
 375 that the two vectors obey <ei>p_1^2 = p_2^2</ei>.
 376 </method>
 377
 378 <method name="void RotBstMatrix::toCMframe(const Vec4& p1, const Vec4& p2)">
 379 boost and rotate to the rest frame of <ei>p_1</ei> and <ei>p_2</ei>,
 380 with <ei>p_1</ei> along the <ei>+z</ei> axis.
 381 </method>
 382
 383 <method name="void RotBstMatrix::fromCMframe(const Vec4& p1, const Vec4& p2)">
 384 rotate and boost from the rest frame of <ei>p_1</ei> and <ei>p_2</ei>,
 385 with <ei>p_1</ei> along the <ei>+z</ei> axis, to the actual frame of
 386 <ei>p_1</ei> and <ei>p_2</ei>, i.e. the inverse of the above.
 387 </method>
 388
 389 <method name="void RotBstMatrix::rotbst(const RotBstMatrix& Min);">
 390 combine the current matrix with another one.
 391 </method>
 392
 393 <method name="void RotBstMatrix::invert()">
 394 invert the matrix, which corresponds to an opposite sequence and sign
 395 of rotations and boosts.
 396 </method>
 397
 398 <method name="void RotBstMatrix::reset()">
 399 reset to no rotation/boost; i.e. the default at creation.
 400 </method>
 401
 402 <method name="double RotBstMatrix::deviation()">
 403 crude estimate how much a matrix deviates from the unit matrix:
 404 the sum of the absolute values of all non-diagonal matrix elements
 405 plus the sum of the absolute deviation of the diagonal matrix
 406 elements from unity.
 407 </method>
 408
 409 <method name="friend ostream& operator&lt;&lt;(ostream&,
 410 const RotBstMatrix& M)">
 411 writes out the values of the sixteen components of a
 412 <code>RotBstMatrix</code>, on four consecutive lines and
 413 ended with a newline.
 414 </method>
 415
 416 </chapter>
 417
 418 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->