[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / htmldoc / FourVectors.html

<html>
<head>
<title>Four-Vectors</title>
<link rel="stylesheet" type="text/css" href="pythia.css"/>
<link rel="shortcut icon" href="pythia32.gif"/>
</head>
<body>

<h2>Four-Vectors</h2>

The <code>Vec4</code> class gives a simple implementation of four-vectors. 
The member function names are based on the assumption that these 
represent four-momentum vectors. Thus one can get or set 
<i>p_x, p_y, p_z</i> and <i>e</i>, but not <i>x, y, z</i> 
or <i>t</i>. This is only a matter of naming, however; a 
<code>Vec4</code> can equally well be used to store a space-time
four-vector.
 
<p/>
The <code>Particle</code> object contains a <code>Vec4 p</code> that 
stores the particle four-momentum, and another <code>Vec4 vProd</code> 
for the production vertex. For the latter the input/output method 
names are adapted to the space-time character rather than the normal 
energy-momentum one. Thus a user would not normally access the 
<code>Vec4</code> classes directly, but only via the methods of the 
<code>Particle</code> class, 
see <a href="ParticleProperties.html" target="page">Particle Properties</a>.

<p/>
Nevertheless you are free to use the PYTHIA four-vectors, e.g. as 
part of some simple analysis code based directly on the PYTHIA output, 
say to define the four-vector sum of a set of particles. But note that
this class was never set up to allow complete generality, only  to
provide the operations that are of use inside PYTHIA. There is no
separate class for three-vectors, since such can easily be represented 
by four-vectors where the fourth component is not used.

<p/>
Four-vectors have the expected functionality: they can be created,
copied, added, multiplied, rotated, boosted, and manipulated in other 
ways. Operator overloading is implemented where reasonable. Properties 
can be read out, not only the components themselves but also for derived
quantities such as absolute momentum and direction angles.

<h3>Constructors and basic operators</h3>

A few methods are available to create or copy a four-vector:

<a name="method1"></a>
<p/><strong>Vec4::Vec4() &nbsp;</strong> <br/>
creates a four-vector with all components set to 0.
  

<a name="method2"></a>
<p/><strong>Vec4::Vec4(const Vec4& v) &nbsp;</strong> <br/>
creates a four-vector copy of the input four-vector.
  

<a name="method3"></a>
<p/><strong>Vec4& Vec4::operator=(const Vec4& v) &nbsp;</strong> <br/>
copies the input four-vector.
  

<a name="method4"></a>
<p/><strong>Vec4& Vec4::operator=(double value) &nbsp;</strong> <br/>
gives a  four-vector with all components set to <i>value</i>.
  

<h3>Member methods for input</h3>

The values stored in a four-vector can be modified in a few different
ways:

<a name="method5"></a>
<p/><strong>void Vec4::reset() &nbsp;</strong> <br/>
sets all components to 0.
  

<a name="method6"></a>
<p/><strong>void Vec4::p(double pxIn, double pyIn, double pzIn, double eIn) &nbsp;</strong> <br/>
sets all components to their input values.
  

<a name="method7"></a>
<p/><strong>void Vec4::p(Vec4 pIn) &nbsp;</strong> <br/>
sets all components equal to those of the input four-vector.
  

<a name="method8"></a>
<p/><strong>void Vec4::px(double pxIn) &nbsp;</strong> <br/>
  
<strong>void Vec4::py(double pyIn) &nbsp;</strong> <br/>
  
<strong>void Vec4::pz(double pzIn) &nbsp;</strong> <br/>
  
<strong>void Vec4::e(double eIn) &nbsp;</strong> <br/>
sets the respective component to the input value.
  

<h3>Member methods for output</h3>

A number of methods provides output of basic or derived quantities:

<a name="method9"></a>
<p/><strong>double Vec4::px() &nbsp;</strong> <br/>
  
<strong>double Vec4::py() &nbsp;</strong> <br/>
  
<strong>double Vec4::pz() &nbsp;</strong> <br/>
  
<strong>double Vec4::e() &nbsp;</strong> <br/>
gets the respective component.
  

<a name="method10"></a>
<p/><strong>double Vec4::mCalc() &nbsp;</strong> <br/>
  
<strong>double Vec4::m2Calc() &nbsp;</strong> <br/>
the (squared) mass, calculated from the four-vectors. 
If <i>m^2 &lt; 0</i> the mass is given with a minus sign, 
<i>-sqrt(-m^2)</i>.  Note the possible loss of precision 
in the calculation of <i>E^2 - p^2</i>; for particles the 
correct mass is stored separately to avoid such problems.
  

<a name="method11"></a>
<p/><strong>double Vec4::pT() &nbsp;</strong> <br/>
  
<strong>double Vec4::pT2() &nbsp;</strong> <br/>
the (squared) transverse momentum.
  

<a name="method12"></a>
<p/><strong>double Vec4::pAbs() &nbsp;</strong> <br/>
  
<strong>double Vec4::pAbs2() &nbsp;</strong> <br/>
the (squared) absolute momentum.
  

<a name="method13"></a>
<p/><strong>double Vec4::eT() &nbsp;</strong> <br/>
  
<strong>double Vec4::eT2() &nbsp;</strong> <br/>
the (squared) transverse energy, 
<i>eT = e * sin(theta) = e * pT / pAbs</i>.
  

<a name="method14"></a>
<p/><strong>double Vec4::theta() &nbsp;</strong> <br/>
the polar angle, in the range 0 through
<i>pi</i>.
  

<a name="method15"></a>
<p/><strong>double Vec4::phi() &nbsp;</strong> <br/>
the azimuthal angle, in the range <i>-pi</i> through <i>pi</i>.
  

<a name="method16"></a>
<p/><strong>double Vec4::thetaXZ() &nbsp;</strong> <br/>
the angle in the <i>xz</i> plane, in the range <i>-pi</i> through 
<i>pi</i>, with 0 along the <i>+z</i> axis.
  

<a name="method17"></a>
<p/><strong>double Vec4::pPos() &nbsp;</strong> <br/>
  
<strong>double Vec4::pNeg() &nbsp;</strong> <br/>
the combinations <i>E+-p_z</i>.  

<h3>Friend methods for output</h3>

There are also some <code>friend</code> methods that take one, two 
or three four-vectors as argument. Several of them only use the
three-vector part of the four-vector.

<a name="method18"></a>
<p/><strong>friend ostream& operator&lt;&lt;(ostream&, const Vec4& v) &nbsp;</strong> <br/>
writes out the values of the four components of a <code>Vec4</code> and,
within brackets, a fifth component being the invariant length of the 
four-vector, as provided by <code>mCalc()</code> above, and it all 
ended with a newline.
  

<a name="method19"></a>
<p/><strong>friend double m(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
  
<strong>friend double m2(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
the (squared) invariant mass.
  

<a name="method20"></a>
<p/><strong>friend double dot3(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
the three-product.
  

<a name="method21"></a>
<p/><strong>friend double cross3(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
the cross-product.
  

<a name="method22"></a>
<p/><strong>friend double theta(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
  
<strong>friend double costheta(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
the (cosine) of the opening angle between the vectors,
in the range 0 through <i>pi</i>.
  

<a name="method23"></a>
<p/><strong>friend double phi(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
  
<strong>friend double cosphi(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
the (cosine) of the azimuthal angle between the vectors around the
<i>z</i> axis, in the range 0 through <i>pi</i>.
  

<a name="method24"></a>
<p/><strong>friend double phi(const Vec4& v1, const Vec4& v2, const Vec4& v3) &nbsp;</strong> <br/>
  
<strong>friend double cosphi(const Vec4& v1, const Vec4& v2, const Vec4& v3) &nbsp;</strong> <br/>
the (cosine) of the azimuthal angle between the first two vectors 
around the direction of the third, in the range 0 through <i>pi</i>.
  

<h3>Operations with four-vectors</h3>

Of course one should be able to add, subtract and scale four-vectors, 
and more:

<a name="method25"></a>
<p/><strong>Vec4 Vec4::operator-() &nbsp;</strong> <br/>
return a vector with flipped sign for all components, while leaving
the original vector unchanged.
  

<a name="method26"></a>
<p/><strong>Vec4& Vec4::operator+=(const Vec4& v) &nbsp;</strong> <br/>
add a four-vector to an existing one.
  

<a name="method27"></a>
<p/><strong>Vec4& Vec4::operator-=(const Vec4& v) &nbsp;</strong> <br/>
subtract a four-vector from an existing one.
  

<a name="method28"></a>
<p/><strong>Vec4& Vec4::operator*=(double f) &nbsp;</strong> <br/>
multiply all four-vector components by a real number. 
  

<a name="method29"></a>
<p/><strong>Vec4& Vec4::operator/=(double f) &nbsp;</strong> <br/>
divide all four-vector components by a real number. 
  

<a name="method30"></a>
<p/><strong>friend Vec4 operator+(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
add two four-vectors.
  

<a name="method31"></a>
<p/><strong>friend Vec4 operator-(const Vec4& v1, const Vec4& v2) &nbsp;</strong> <br/>
subtract two four-vectors.
  

<a name="method32"></a>
<p/><strong>friend Vec4 operator*(double f, const Vec4& v) &nbsp;</strong> <br/>
  
<strong>friend Vec4 operator*(const Vec4& v, double f) &nbsp;</strong> <br/>
multiply a four-vector by a real number.
  

<a name="method33"></a>
<p/><strong>friend Vec4 operator/(const Vec4& v, double f) &nbsp;</strong> <br/>
divide a four-vector by a real number.
  

<a name="method34"></a>
<p/><strong>friend double operator*(const Vec4& v1, const Vec4 v2) &nbsp;</strong> <br/>
four-vector product.
  

<p/>
There are also a few related operations that are normal member methods:

<a name="method35"></a>
<p/><strong>void Vec4::rescale3(double f) &nbsp;</strong> <br/>
multiply the three-vector components by <i>f</i>, but keep the 
fourth component unchanged.
  

<a name="method36"></a>
<p/><strong>void Vec4::rescale4(double f) &nbsp;</strong> <br/>
multiply all four-vector components by <i>f</i>.
  

<a name="method37"></a>
<p/><strong>void Vec4::flip3() &nbsp;</strong> <br/>
flip the sign of the three-vector components, but keep the 
fourth component unchanged.
  

<a name="method38"></a>
<p/><strong>void Vec4::flip4() &nbsp;</strong> <br/>
flip the sign of all four-vector components.
  

<h3>Rotations and boosts</h3>

A common task is to rotate or boost four-vectors. In case only one
four-vector is affected the operation may be performed directly on it.
However, in case many particles are affected, the helper class
<code>RotBstMatrix</code> can be used to speed up operations.

<a name="method39"></a>
<p/><strong>void Vec4::rot(double theta, double phi) &nbsp;</strong> <br/>
rotate the three-momentum with the polar angle <i>theta</i>
and the azimuthal angle <i>phi</i>.
  

<a name="method40"></a>
<p/><strong>void Vec4::rotaxis(double phi, double nx, double ny, double nz) &nbsp;</strong> <br/>
rotate the three-momentum with the azimuthal angle <i>phi</i>
around the direction defined by the <i>(n_x, n_y, n_z)</i>
three-vector.
  

<a name="method41"></a>
<p/><strong>void Vec4::rotaxis(double phi, Vec4& n) &nbsp;</strong> <br/>
rotate the three-momentum with the azimuthal angle <i>phi</i>
around the direction defined by the three-vector part of <i>n</i>. 
  

<a name="method42"></a>
<p/><strong>void Vec4::bst(double betaX, double betaY, double betaZ) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (beta_x, beta_y, beta_z)</i>.
  

<a name="method43"></a>
<p/><strong>void Vec4::bst(double betaX, double betaY, double betaZ,double gamma) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (beta_x, beta_y, beta_z)</i>,
where the <i>gamma = 1/sqrt(1 - beta^2)</i> is also input to allow
better precision when <i>beta</i> is close to unity. 
  

<a name="method44"></a>
<p/><strong>void Vec4::bst(const Vec4& p) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (p_x/E, p_y/E, p_z/E)</i>.
  

<a name="method45"></a>
<p/><strong>void Vec4::bst(const Vec4& p, double m) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (p_x/E, p_y/E, p_z/E)</i>,
where the <i>gamma = E/m</i> is also calculated from input to allow
better precision when <i>beta</i> is close to unity. 
  

<a name="method46"></a>
<p/><strong>void Vec4::bstback(const Vec4& p) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (-p_x/E, -p_y/E, -p_z/E)</i>.
  

<a name="method47"></a>
<p/><strong>void Vec4::bstback(const Vec4& p, double m) &nbsp;</strong> <br/>
boost the four-momentum by <i>beta = (-p_x/E, -p_y/E, -p_z/E)</i>,
where the <i>gamma = E/m</i> is also calculated from input to allow
better precision when <i>beta</i> is close to unity. 
  

<a name="method48"></a>
<p/><strong>void Vec4::rotbst(const RotBstMatrix& M) &nbsp;</strong> <br/>
perform a combined rotation and boost; see below for a description
of the <code>RotBstMatrix</code>.
  

<p/>
For a longer sequence of rotations and boosts, and where several 
<code>Vec4</code> are to be rotated and boosted in the same way, 
a more efficient approach is to define a <code>RotBstMatrix</code>, 
which forms a separate auxiliary class. You can build up this 
4-by-4 matrix by successive calls to the methods of the class,
such that the matrix encodes the full sequence of operations.
The order in which you do these calls must agree with the imagined
order in which the rotations/boosts should be applied to a 
four-momentum, since in general the operations do not commute.

<a name="method49"></a>
<p/><strong>RotBstMatrix::RotBstMatrix() &nbsp;</strong> <br/>
creates a diagonal unit matrix, i.e. one that leaves a four-vector
unchanged.
  

<a name="method50"></a>
<p/><strong>RotBstMatrix::RotBstMatrix(const RotBstMatrix& Min) &nbsp;</strong> <br/>
creates a copy of the input matrix.
  

<a name="method51"></a>
<p/><strong>RotBstMatrix& RotBstMatrix::operator=(const RotBstMatrix4& Min) &nbsp;</strong> <br/>
copies the input matrix.
  

<a name="method52"></a>
<p/><strong>void RotBstMatrix::rot(double theta = 0., double phi = 0.) &nbsp;</strong> <br/>
rotate by this polar and azimuthal angle.
  

<a name="method53"></a>
<p/><strong>void RotBstMatrix::rot(const Vec4& p) &nbsp;</strong> <br/>
rotate so that a vector originally along the <i>+z</i> axis becomes 
parallel with <i>p</i>. More specifically, rotate by <i>-phi</i>, 
<i>theta</i> and <i>phi</i>, with angles defined by <i>p</i>.
  

<a name="method54"></a>
<p/><strong>void RotBstMatrix::bst(double betaX = 0., double betaY = 0., double betaZ = 0.) &nbsp;</strong> <br/>
boost by this <i>beta</i> vector.
  

<a name="method55"></a>
<p/><strong>void RotBstMatrix::bst(const Vec4&) &nbsp;</strong> <br/>
  
<strong>void RotBstMatrix::bstback(const Vec4&) &nbsp;</strong> <br/>
boost with a <i>beta = p/E</i> or <i>beta = -p/E</i>, respectively.
  

<a name="method56"></a>
<p/><strong>void RotBstMatrix::bst(const Vec4& p1, const Vec4& p2) &nbsp;</strong> <br/>
boost so that <i>p_1</i> is transformed to <i>p_2</i>. It is assumed 
that the two vectors obey <i>p_1^2 = p_2^2</i>.
  

<a name="method57"></a>
<p/><strong>void RotBstMatrix::toCMframe(const Vec4& p1, const Vec4& p2) &nbsp;</strong> <br/>
boost and rotate to the rest frame of <i>p_1</i> and <i>p_2</i>, 
with <i>p_1</i> along the <i>+z</i> axis.
  

<a name="method58"></a>
<p/><strong>void RotBstMatrix::fromCMframe(const Vec4& p1, const Vec4& p2) &nbsp;</strong> <br/>
rotate and boost from the rest frame of <i>p_1</i> and <i>p_2</i>, 
with <i>p_1</i> along the <i>+z</i> axis, to the actual frame of 
<i>p_1</i> and <i>p_2</i>, i.e. the inverse of the above.
  

<a name="method59"></a>
<p/><strong>void RotBstMatrix::rotbst(const RotBstMatrix& Min); &nbsp;</strong> <br/>
combine the current matrix with another one.
  

<a name="method60"></a>
<p/><strong>void RotBstMatrix::invert() &nbsp;</strong> <br/>
invert the matrix, which corresponds to an opposite sequence and sign 
of rotations and boosts.
  

<a name="method61"></a>
<p/><strong>void RotBstMatrix::reset() &nbsp;</strong> <br/>
reset to no rotation/boost; i.e. the default at creation.
  

<a name="method62"></a>
<p/><strong>double RotBstMatrix::deviation() &nbsp;</strong> <br/>
crude estimate how much a matrix deviates from the unit matrix:
the sum of the absolute values of all non-diagonal matrix elements 
plus the sum of the absolute deviation of the diagonal matrix 
elements from unity.
  

<a name="method63"></a>
<p/><strong>friend ostream& operator&lt;&lt;(ostream&, const RotBstMatrix& M) &nbsp;</strong> <br/>
writes out the values of the sixteen components of a 
<code>RotBstMatrix</code>, on four consecutive lines and
ended with a newline.
  

</body>
</html>

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