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