CLHEP VERSION Reference Documentation
   
CLHEP Home Page     CLHEP Documentation     CLHEP Bug Reports

Vector/Vector/ThreeVector.h
Go to the documentation of this file.
1// -*- C++ -*-
2// CLASSDOC OFF
3// $Id: ThreeVector.h,v 1.4 2010/06/16 17:15:57 garren Exp $
4// ---------------------------------------------------------------------------
5// CLASSDOC ON
6//
7// This file is a part of the CLHEP - a Class Library for High Energy Physics.
8//
9// Hep3Vector is a general 3-vector class defining vectors in three
10// dimension using double components. Rotations of these vectors are
11// performed by multiplying with an object of the HepRotation class.
12//
13// .SS See Also
14// LorentzVector.h, Rotation.h, LorentzRotation.h
15//
16// .SS Authors
17// Leif Lonnblad and Anders Nilsson; Modified by Evgueni Tcherniaev;
18// ZOOM additions by Mark Fischler
19//
20
21#ifndef HEP_THREEVECTOR_H
22#define HEP_THREEVECTOR_H
23
24#ifdef GNUPRAGMA
25#pragma interface
26#endif
27
28#include <iostream>
29#include "CLHEP/Vector/defs.h"
30
31namespace CLHEP {
32
33class HepRotation;
34class HepEulerAngles;
35class HepAxisAngle;
36
41class Hep3Vector {
42
43public:
44
45// Basic properties and operations on 3-vectors:
46
47 enum { X=0, Y=1, Z=2, NUM_COORDINATES=3, SIZE=NUM_COORDINATES };
48 // Safe indexing of the coordinates when using with matrices, arrays, etc.
49 // (BaBar)
50
52 explicit Hep3Vector(double x);
53 Hep3Vector(double x, double y);
54 Hep3Vector(double x, double y, double z);
55 // The constructor.
56
57 inline Hep3Vector(const Hep3Vector &);
58 // The copy constructor.
59
60 inline ~Hep3Vector();
61 // The destructor. Not virtual - inheritance from this class is dangerous.
62
63 double operator () (int) const;
64 // Get components by index -- 0-based (Geant4)
65
66 inline double operator [] (int) const;
67 // Get components by index -- 0-based (Geant4)
68
69 double & operator () (int);
70 // Set components by index. 0-based.
71
72 inline double & operator [] (int);
73 // Set components by index. 0-based.
74
75 inline double x() const;
76 inline double y() const;
77 inline double z() const;
78 // The components in cartesian coordinate system. Same as getX() etc.
79
80 inline void setX(double);
81 inline void setY(double);
82 inline void setZ(double);
83 // Set the components in cartesian coordinate system.
84
85 inline void set( double x, double y, double z);
86 // Set all three components in cartesian coordinate system.
87
88 inline double phi() const;
89 // The azimuth angle.
90
91 inline double theta() const;
92 // The polar angle.
93
94 inline double cosTheta() const;
95 // Cosine of the polar angle.
96
97 inline double cos2Theta() const;
98 // Cosine squared of the polar angle - faster than cosTheta(). (ZOOM)
99
100 inline double mag2() const;
101 // The magnitude squared (r^2 in spherical coordinate system).
102
103 inline double mag() const;
104 // The magnitude (r in spherical coordinate system).
105
106 inline void setPhi(double);
107 // Set phi keeping mag and theta constant (BaBar).
108
109 inline void setTheta(double);
110 // Set theta keeping mag and phi constant (BaBar).
111
112 void setMag(double);
113 // Set magnitude keeping theta and phi constant (BaBar).
114
115 inline double perp2() const;
116 // The transverse component squared (rho^2 in cylindrical coordinate system).
117
118 inline double perp() const;
119 // The transverse component (rho in cylindrical coordinate system).
120
121 inline void setPerp(double);
122 // Set the transverse component keeping phi and z constant.
123
124 void setCylTheta(double);
125 // Set theta while keeping transvers component and phi fixed
126
127 inline double perp2(const Hep3Vector &) const;
128 // The transverse component w.r.t. given axis squared.
129
130 inline double perp(const Hep3Vector &) const;
131 // The transverse component w.r.t. given axis.
132
134 // Assignment.
135
136 inline bool operator == (const Hep3Vector &) const;
137 inline bool operator != (const Hep3Vector &) const;
138 // Comparisons (Geant4).
139
140 bool isNear (const Hep3Vector &, double epsilon=tolerance) const;
141 // Check for equality within RELATIVE tolerance (default 2.2E-14). (ZOOM)
142 // |v1 - v2|**2 <= epsilon**2 * |v1.dot(v2)|
143
144 double howNear(const Hep3Vector & v ) const;
145 // sqrt ( |v1-v2|**2 / v1.dot(v2) ) with a maximum of 1.
146 // If v1.dot(v2) is negative, will return 1.
147
148 double deltaR(const Hep3Vector & v) const;
149 // sqrt( pseudorapity_difference**2 + deltaPhi **2 )
150
152 // Addition.
153
155 // Subtraction.
156
157 inline Hep3Vector operator - () const;
158 // Unary minus.
159
160 inline Hep3Vector & operator *= (double);
161 // Scaling with real numbers.
162
164 // Division by (non-zero) real number.
165
166 inline Hep3Vector unit() const;
167 // Vector parallel to this, but of length 1.
168
169 inline Hep3Vector orthogonal() const;
170 // Vector orthogonal to this (Geant4).
171
172 inline double dot(const Hep3Vector &) const;
173 // double product.
174
175 inline Hep3Vector cross(const Hep3Vector &) const;
176 // Cross product.
177
178 double angle(const Hep3Vector &) const;
179 // The angle w.r.t. another 3-vector.
180
181 double pseudoRapidity() const;
182 // Returns the pseudo-rapidity, i.e. -ln(tan(theta/2))
183
184 void setEta ( double p );
185 // Set pseudo-rapidity, keeping magnitude and phi fixed. (ZOOM)
186
187 void setCylEta ( double p );
188 // Set pseudo-rapidity, keeping transverse component and phi fixed. (ZOOM)
189
191 // Rotates the Hep3Vector around the x-axis.
192
194 // Rotates the Hep3Vector around the y-axis.
195
197 // Rotates the Hep3Vector around the z-axis.
198
200 // Rotates reference frame from Uz to newUz (unit vector) (Geant4).
201
202 Hep3Vector & rotate(double, const Hep3Vector &);
203 // Rotates around the axis specified by another Hep3Vector.
204 // (Uses methods of HepRotation, forcing linking in of Rotation.cc.)
205
208 // Transformation with a Rotation matrix.
209
210
211// = = = = = = = = = = = = = = = = = = = = = = = =
212//
213// Esoteric properties and operations on 3-vectors:
214//
215// 1 - Set vectors in various coordinate systems
216// 2 - Synonyms for accessing coordinates and properties
217// 3 - Comparisions (dictionary, near-ness, and geometric)
218// 4 - Intrinsic properties
219// 5 - Properties releative to z axis and arbitrary directions
220// 6 - Polar and azimuthal angle decomposition and deltaPhi
221// 7 - Rotations
222//
223// = = = = = = = = = = = = = = = = = = = = = = = =
224
225// 1 - Set vectors in various coordinate systems
226
227 inline void setRThetaPhi (double r, double theta, double phi);
228 // Set in spherical coordinates: Angles are measured in RADIANS
229
230 inline void setREtaPhi ( double r, double eta, double phi );
231 // Set in spherical coordinates, but specify peudorapidiy to determine theta.
232
233 inline void setRhoPhiZ (double rho, double phi, double z);
234 // Set in cylindrical coordinates: Phi angle is measured in RADIANS
235
236 void setRhoPhiTheta ( double rho, double phi, double theta);
237 // Set in cylindrical coordinates, but specify theta to determine z.
238
239 void setRhoPhiEta ( double rho, double phi, double eta);
240 // Set in cylindrical coordinates, but specify pseudorapidity to determine z.
241
242// 2 - Synonyms for accessing coordinates and properties
243
244 inline double getX() const;
245 inline double getY() const;
246 inline double getZ() const;
247 // x(), y(), and z()
248
249 inline double getR () const;
250 inline double getTheta() const;
251 inline double getPhi () const;
252 // mag(), theta(), and phi()
253
254 inline double r () const;
255 // mag()
256
257 inline double rho () const;
258 inline double getRho () const;
259 // perp()
260
261 double eta () const;
262 double getEta () const;
263 // pseudoRapidity()
264
265 inline void setR ( double s );
266 // setMag()
267
268 inline void setRho ( double s );
269 // setPerp()
270
271// 3 - Comparisions (dictionary, near-ness, and geometric)
272
273 int compare (const Hep3Vector & v) const;
274 bool operator > (const Hep3Vector & v) const;
275 bool operator < (const Hep3Vector & v) const;
276 bool operator>= (const Hep3Vector & v) const;
277 bool operator<= (const Hep3Vector & v) const;
278 // dictionary ordering according to z, then y, then x component
279
280 inline double diff2 (const Hep3Vector & v) const;
281 // |v1-v2|**2
282
283 static double setTolerance (double tol);
284 static inline double getTolerance ();
285 // Set the tolerance used in isNear() for Hep3Vectors
286
287 bool isParallel (const Hep3Vector & v, double epsilon=tolerance) const;
288 // Are the vectors parallel, within the given tolerance?
289
290 bool isOrthogonal (const Hep3Vector & v, double epsilon=tolerance) const;
291 // Are the vectors orthogonal, within the given tolerance?
292
293 double howParallel (const Hep3Vector & v) const;
294 // | v1.cross(v2) / v1.dot(v2) |, to a maximum of 1.
295
296 double howOrthogonal (const Hep3Vector & v) const;
297 // | v1.dot(v2) / v1.cross(v2) |, to a maximum of 1.
298
299 enum { ToleranceTicks = 100 };
300
301// 4 - Intrinsic properties
302
303 double beta () const;
304 // relativistic beta (considering v as a velocity vector with c=1)
305 // Same as mag() but will object if >= 1
306
307 double gamma() const;
308 // relativistic gamma (considering v as a velocity vector with c=1)
309
310 double coLinearRapidity() const;
311 // inverse tanh (beta)
312
313// 5 - Properties relative to Z axis and to an arbitrary direction
314
315 // Note that the non-esoteric CLHEP provides
316 // theta(), cosTheta(), cos2Theta, and angle(const Hep3Vector&)
317
318 inline double angle() const;
319 // angle against the Z axis -- synonym for theta()
320
321 inline double theta(const Hep3Vector & v2) const;
322 // synonym for angle(v2)
323
324 double cosTheta (const Hep3Vector & v2) const;
325 double cos2Theta(const Hep3Vector & v2) const;
326 // cos and cos^2 of the angle between two vectors
327
328 inline Hep3Vector project () const;
329 Hep3Vector project (const Hep3Vector & v2) const;
330 // projection of a vector along a direction.
331
332 inline Hep3Vector perpPart() const;
333 inline Hep3Vector perpPart (const Hep3Vector & v2) const;
334 // vector minus its projection along a direction.
335
336 double rapidity () const;
337 // inverse tanh(v.z())
338
339 double rapidity (const Hep3Vector & v2) const;
340 // rapidity with respect to specified direction:
341 // inverse tanh (v.dot(u)) where u is a unit in the direction of v2
342
343 double eta(const Hep3Vector & v2) const;
344 // - ln tan of the angle beween the vector and the ref direction.
345
346// 6 - Polar and azimuthal angle decomposition and deltaPhi
347
348 // Decomposition of an angle within reference defined by a direction:
349
350 double polarAngle (const Hep3Vector & v2) const;
351 // The reference direction is Z: the polarAngle is abs(v.theta()-v2.theta()).
352
353 double deltaPhi (const Hep3Vector & v2) const;
354 // v.phi()-v2.phi(), brought into the range (-PI,PI]
355
356 double azimAngle (const Hep3Vector & v2) const;
357 // The reference direction is Z: the azimAngle is the same as deltaPhi
358
359 double polarAngle (const Hep3Vector & v2,
360 const Hep3Vector & ref) const;
361 // For arbitrary reference direction,
362 // polarAngle is abs(v.angle(ref) - v2.angle(ref)).
363
364 double azimAngle (const Hep3Vector & v2,
365 const Hep3Vector & ref) const;
366 // To compute azimangle, project v and v2 into the plane normal to
367 // the reference direction. Then in that plane take the angle going
368 // clockwise around the direction from projection of v to that of v2.
369
370// 7 - Rotations
371
372// These mehtods **DO NOT** use anything in the HepRotation class.
373// Thus, use of v.rotate(axis,delta) does not force linking in Rotation.cc.
374
375 Hep3Vector & rotate (const Hep3Vector & axis, double delta);
376 // Synonym for rotate (delta, axis)
377
379 // HepAxisAngle is a struct holding an axis direction and an angle.
380
383 double theta,
384 double psi);
385 // Rotate via Euler Angles. Our Euler Angles conventions are
386 // those of Goldstein Classical Mechanics page 107.
387
388protected:
389 void setSpherical (double r, double theta, double phi);
390 void setCylindrical (double r, double phi, double z);
391 double negativeInfinity() const;
392
393protected:
394
395 double dx;
396 double dy;
397 double dz;
398 // The components.
399
400 static double tolerance;
401 // default tolerance criterion for isNear() to return true.
402}; // Hep3Vector
403
404// Global Methods
405
406Hep3Vector rotationXOf (const Hep3Vector & vec, double delta);
407Hep3Vector rotationYOf (const Hep3Vector & vec, double delta);
408Hep3Vector rotationZOf (const Hep3Vector & vec, double delta);
409
410Hep3Vector rotationOf (const Hep3Vector & vec,
411 const Hep3Vector & axis, double delta);
412Hep3Vector rotationOf (const Hep3Vector & vec, const HepAxisAngle & ax);
413
414Hep3Vector rotationOf (const Hep3Vector & vec,
415 double phi, double theta, double psi);
416Hep3Vector rotationOf (const Hep3Vector & vec, const HepEulerAngles & e);
417// Return a new vector based on a rotation of the supplied vector
418
419std::ostream & operator << (std::ostream &, const Hep3Vector &);
420// Output to a stream.
421
422std::istream & operator >> (std::istream &, Hep3Vector &);
423// Input from a stream.
424
425extern const Hep3Vector HepXHat, HepYHat, HepZHat;
426
429
430Hep3Vector operator / (const Hep3Vector &, double a);
431// Division of 3-vectors by non-zero real number
432
433inline Hep3Vector operator + (const Hep3Vector &, const Hep3Vector &);
434// Addition of 3-vectors.
435
436inline Hep3Vector operator - (const Hep3Vector &, const Hep3Vector &);
437// Subtraction of 3-vectors.
438
439inline double operator * (const Hep3Vector &, const Hep3Vector &);
440// double product of 3-vectors.
441
442inline Hep3Vector operator * (const Hep3Vector &, double a);
443inline Hep3Vector operator * (double a, const Hep3Vector &);
444// Scaling of 3-vectors with a real number
445
446} // namespace CLHEP
447
448#include "CLHEP/Vector/ThreeVector.icc"
449
450#ifdef ENABLE_BACKWARDS_COMPATIBILITY
451// backwards compatibility will be enabled ONLY in CLHEP 1.9
452using namespace CLHEP;
453#endif
454
455#endif /* HEP_THREEVECTOR_H */
Hep3Vector & operator-=(const Hep3Vector &)
Hep3Vector & rotateY(double)
double beta() const
double cosTheta(const Hep3Vector &v2) const
Hep3Vector & rotate(const HepAxisAngle &ax)
double z() const
void setEta(double p)
double azimAngle(const Hep3Vector &v2) const
Hep3Vector & rotateX(double)
double rapidity(const Hep3Vector &v2) const
Hep3Vector unit() const
double eta() const
double phi() const
Hep3Vector orthogonal() const
Hep3Vector & rotate(const HepEulerAngles &e)
Hep3Vector & rotate(double phi, double theta, double psi)
void setPerp(double)
void setRhoPhiEta(double rho, double phi, double eta)
bool operator>=(const Hep3Vector &v) const
double getZ() const
Hep3Vector(const Hep3Vector &)
double cos2Theta() const
double operator()(int) const
double theta() const
double x() const
void setY(double)
double mag2() const
double getR() const
Hep3Vector & rotateZ(double)
double diff2(const Hep3Vector &v) const
Hep3Vector & operator/=(double)
double y() const
double polarAngle(const Hep3Vector &v2, const Hep3Vector &ref) const
double getTheta() const
void setCylEta(double p)
void setRhoPhiZ(double rho, double phi, double z)
void setSpherical(double r, double theta, double phi)
Hep3Vector cross(const Hep3Vector &) const
double operator[](int) const
void setRThetaPhi(double r, double theta, double phi)
double angle(const Hep3Vector &) const
Hep3Vector & operator=(const Hep3Vector &)
void setR(double s)
double howNear(const Hep3Vector &v) const
double dot(const Hep3Vector &) const
Hep3Vector perpPart(const Hep3Vector &v2) const
double perp2() const
void setTheta(double)
Hep3Vector & rotate(const Hep3Vector &axis, double delta)
Hep3Vector project(const Hep3Vector &v2) const
void setZ(double)
double perp(const Hep3Vector &) const
bool operator>(const Hep3Vector &v) const
bool isOrthogonal(const Hep3Vector &v, double epsilon=tolerance) const
double negativeInfinity() const
Hep3Vector perpPart() const
static double getTolerance()
bool operator!=(const Hep3Vector &) const
double mag() const
Hep3Vector(double x, double y, double z)
Hep3Vector & operator*=(double)
bool isNear(const Hep3Vector &, double epsilon=tolerance) const
double pseudoRapidity() const
Hep3Vector & transform(const HepRotation &)
double getEta() const
bool operator<=(const Hep3Vector &v) const
double rapidity() const
double getRho() const
double deltaPhi(const Hep3Vector &v2) const
double theta(const Hep3Vector &v2) const
void setCylindrical(double r, double phi, double z)
double eta(const Hep3Vector &v2) const
void set(double x, double y, double z)
double coLinearRapidity() const
int compare(const Hep3Vector &v) const
void setMag(double)
double getX() const
double howParallel(const Hep3Vector &v) const
double cos2Theta(const Hep3Vector &v2) const
double getPhi() const
static double setTolerance(double tol)
double howOrthogonal(const Hep3Vector &v) const
double azimAngle(const Hep3Vector &v2, const Hep3Vector &ref) const
double angle() const
Hep3Vector operator-() const
bool operator==(const Hep3Vector &) const
double deltaR(const Hep3Vector &v) const
void setX(double)
void setREtaPhi(double r, double eta, double phi)
void setRhoPhiTheta(double rho, double phi, double theta)
Hep3Vector & rotateUz(const Hep3Vector &)
double cosTheta() const
Hep3Vector & rotate(double, const Hep3Vector &)
void setPhi(double)
double gamma() const
double perp() const
void setCylTheta(double)
bool operator<(const Hep3Vector &v) const
double polarAngle(const Hep3Vector &v2) const
void setRho(double s)
Hep3Vector(double x, double y)
Hep3Vector & operator+=(const Hep3Vector &)
Hep3Vector(double x)
bool isParallel(const Hep3Vector &v, double epsilon=tolerance) const
Hep3Vector project() const
double rho() const
double getY() const
double perp2(const Hep3Vector &) const
double r() const
HepLorentzVector rotationYOf(const HepLorentzVector &vec, double delta)
Hep3Vector operator-(const Hep3Vector &, const Hep3Vector &)
Hep3Vector operator+(const Hep3Vector &, const Hep3Vector &)
HepLorentzVector rotationXOf(const HepLorentzVector &vec, double delta)
HepLorentzRotation operator*(const HepRotation &r, const HepLorentzRotation &lt)
HepLorentzVector rotationZOf(const HepLorentzVector &vec, double delta)
HepLorentzVector rotationOf(const HepLorentzVector &vec, const Hep3Vector &axis, double delta)
const Hep3Vector HepXHat
std::ostream & operator<<(std::ostream &os, const HepAxisAngle &aa)
Definition AxisAngle.cc:86
std::istream & operator>>(std::istream &is, HepAxisAngle &aa)
Definition AxisAngle.cc:96
HepLorentzVector operator/(const HepLorentzVector &, double a)