CLHEP/Vector/ThreeVector.h

0001 // -*- C++ -*-
0002 // CLASSDOC OFF
0003 // ---------------------------------------------------------------------------
0004 // CLASSDOC ON
0005 //
0006 // This file is a part of the CLHEP - a Class Library for High Energy Physics.
0007 //
0008 // Hep3Vector is a general 3-vector class defining vectors in three
0009 // dimension using double components. Rotations of these vectors are
0010 // performed by multiplying with an object of the HepRotation class.
0011 //
0012 // .SS See Also
0013 // LorentzVector.h, Rotation.h, LorentzRotation.h
0014 //
0015 // .SS Authors
0016 // Leif Lonnblad and Anders Nilsson; Modified by Evgueni Tcherniaev;
0017 // ZOOM additions by Mark Fischler
0018 //
0019
0020 #ifndef HEP_THREEVECTOR_H
0021 #define HEP_THREEVECTOR_H
0022
0023 #include <iostream>
0024 #include "CLHEP/Vector/defs.h"
0025
0026 namespace CLHEP {
0027
0028 class HepRotation;
0029 class HepEulerAngles;
0030 class HepAxisAngle;
0031
0032 /**
0033  * @author
0034  * @ingroup vector
0035  */
0036 class Hep3Vector {
0037
0038 public:
0039
0040 // Basic properties and operations on 3-vectors:
0041
0042   enum { X=0, Y=1, Z=2, NUM_COORDINATES=3, SIZE=NUM_COORDINATES };
0043   // Safe indexing of the coordinates when using with matrices, arrays, etc.
0044   // (BaBar)
0045
0046   Hep3Vector();
0047   explicit Hep3Vector(double x);
0048   Hep3Vector(double x, double y);
0049   Hep3Vector(double x, double y, double z);
0050   // The constructor.
0051
0052   inline Hep3Vector(const Hep3Vector &);
0053   inline Hep3Vector(Hep3Vector &&) = default;
0054   // The copy and move constructors.
0055
0056   inline ~Hep3Vector();
0057   // The destructor.  Not virtual - inheritance from this class is dangerous.
0058
0059   inline double operator () (int) const;
0060   // Get components by index -- 0-based (Geant4)
0061
0062   inline double operator [] (int) const;
0063   // Get components by index -- 0-based (Geant4)
0064
0065   inline double & operator () (int);
0066   // Set components by index.  0-based.
0067
0068   inline double & operator [] (int);
0069   // Set components by index.  0-based.
0070
0071   inline double x() const;
0072   inline double y() const;
0073   inline double z() const;
0074   // The components in cartesian coordinate system.  Same as getX() etc.
0075
0076   inline void setX(double);
0077   inline void setY(double);
0078   inline void setZ(double);
0079   // Set the components in cartesian coordinate system.
0080
0081   inline void set( double x, double y, double z);
0082   // Set all three components in cartesian coordinate system.
0083
0084   inline double phi() const;
0085   // The azimuth angle.
0086
0087   inline double theta() const;
0088   // The polar angle.
0089
0090   inline double cosTheta() const;
0091   // Cosine of the polar angle.
0092
0093   inline double cos2Theta() const;
0094   // Cosine squared of the polar angle - faster than cosTheta(). (ZOOM)
0095
0096   inline double mag2() const;
0097   // The magnitude squared (r^2 in spherical coordinate system).
0098
0099   inline double mag() const;
0100   // The magnitude (r in spherical coordinate system).
0101
0102   inline void setPhi(double);
0103   // Set phi keeping mag and theta constant (BaBar).
0104
0105   inline void setTheta(double);
0106   // Set theta keeping mag and phi constant (BaBar).
0107
0108          void setMag(double);
0109   // Set magnitude keeping theta and phi constant (BaBar).
0110
0111   inline double perp2() const;
0112   // The transverse component squared (rho^2 in cylindrical coordinate system).
0113
0114   inline double perp() const;
0115   // The transverse component (rho in cylindrical coordinate system).
0116
0117   inline void setPerp(double);
0118   // Set the transverse component keeping phi and z constant.
0119
0120   void setCylTheta(double);
0121   // Set theta while keeping transvers component and phi fixed
0122
0123   inline double perp2(const Hep3Vector &) const;
0124   // The transverse component w.r.t. given axis squared.
0125
0126   inline double perp(const Hep3Vector &) const;
0127   // The transverse component w.r.t. given axis.
0128
0129   inline Hep3Vector & operator = (const Hep3Vector &);
0130   inline Hep3Vector & operator = (Hep3Vector &&) = default;
0131   // The copy and move assignment operators.
0132
0133   inline bool operator == (const Hep3Vector &) const;
0134   inline bool operator != (const Hep3Vector &) const;
0135   // Comparisons (Geant4).
0136
0137   bool isNear (const Hep3Vector &, double epsilon=tolerance) const;
0138   // Check for equality within RELATIVE tolerance (default 2.2E-14). (ZOOM)
0139   // |v1 - v2|**2 <= epsilon**2 * |v1.dot(v2)|
0140
0141   double howNear(const Hep3Vector & v ) const;
0142   // sqrt ( |v1-v2|**2 / v1.dot(v2) ) with a maximum of 1.
0143   // If v1.dot(v2) is negative, will return 1.
0144
0145   double deltaR(const Hep3Vector & v) const;
0146   // sqrt( pseudorapity_difference**2 + deltaPhi **2 )
0147
0148   inline Hep3Vector & operator += (const Hep3Vector &);
0149   // Addition.
0150
0151   inline Hep3Vector & operator -= (const Hep3Vector &);
0152   // Subtraction.
0153
0154   inline Hep3Vector operator - () const;
0155   // Unary minus.
0156
0157   inline Hep3Vector & operator *= (double);
0158   // Scaling with real numbers.
0159
0160          Hep3Vector & operator /= (double);
0161   // Division by (non-zero) real number.
0162
0163   inline Hep3Vector unit() const;
0164   // Vector parallel to this, but of length 1.
0165
0166   inline Hep3Vector orthogonal() const;
0167   // Vector orthogonal to this (Geant4).
0168
0169   inline double dot(const Hep3Vector &) const;
0170   // double product.
0171
0172   inline Hep3Vector cross(const Hep3Vector &) const;
0173   // Cross product.
0174
0175   double angle(const Hep3Vector &) const;
0176   // The angle w.r.t. another 3-vector.
0177
0178   double pseudoRapidity() const;
0179   // Returns the pseudo-rapidity, i.e. -ln(tan(theta/2))
0180
0181   void setEta  ( double p );
0182   // Set pseudo-rapidity, keeping magnitude and phi fixed.  (ZOOM)
0183
0184   void setCylEta  ( double p );
0185   // Set pseudo-rapidity, keeping transverse component and phi fixed.  (ZOOM)
0186
0187   Hep3Vector & rotateX(double);
0188   // Rotates the Hep3Vector around the x-axis.
0189
0190   Hep3Vector & rotateY(double);
0191   // Rotates the Hep3Vector around the y-axis.
0192
0193   Hep3Vector & rotateZ(double);
0194   // Rotates the Hep3Vector around the z-axis.
0195
0196   Hep3Vector & rotateUz(const Hep3Vector&);
0197   // Rotates reference frame from Uz to newUz (unit vector) (Geant4).
0198
0199     Hep3Vector & rotate(double, const Hep3Vector &);
0200   // Rotates around the axis specified by another Hep3Vector.
0201   // (Uses methods of HepRotation, forcing linking in of Rotation.cc.)
0202
0203   Hep3Vector & operator *= (const HepRotation &);
0204   Hep3Vector & transform(const HepRotation &);
0205   // Transformation with a Rotation matrix.
0206
0207 // = = = = = = = = = = = = = = = = = = = = = = = =
0208 //
0209 // Esoteric properties and operations on 3-vectors:
0210 //
0211 // 1 - Set vectors in various coordinate systems
0212 // 2 - Synonyms for accessing coordinates and properties
0213 // 3 - Comparisions (dictionary, near-ness, and geometric)
0214 // 4 - Intrinsic properties
0215 // 5 - Properties releative to z axis and arbitrary directions
0216 // 6 - Polar and azimuthal angle decomposition and deltaPhi
0217 // 7 - Rotations
0218 //
0219 // = = = = = = = = = = = = = = = = = = = = = = = =
0220
0221 // 1 - Set vectors in various coordinate systems
0222
0223   inline void setRThetaPhi  (double r, double theta, double phi);
0224   // Set in spherical coordinates:  Angles are measured in RADIANS
0225
0226   inline void setREtaPhi  ( double r, double eta,  double phi );
0227   // Set in spherical coordinates, but specify peudorapidiy to determine theta.
0228
0229   inline void setRhoPhiZ   (double rho, double phi, double z);
0230   // Set in cylindrical coordinates:  Phi angle is measured in RADIANS
0231
0232   void setRhoPhiTheta ( double rho, double phi, double theta);
0233   // Set in cylindrical coordinates, but specify theta to determine z.
0234
0235   void setRhoPhiEta ( double rho, double phi, double eta);
0236   // Set in cylindrical coordinates, but specify pseudorapidity to determine z.
0237
0238 // 2 - Synonyms for accessing coordinates and properties
0239
0240   inline double getX() const;
0241   inline double getY() const;
0242   inline double getZ() const;
0243   // x(), y(), and z()
0244
0245   inline double getR    () const;
0246   inline double getTheta() const;
0247   inline double getPhi  () const;
0248   // mag(), theta(), and phi()
0249
0250   inline double r       () const;
0251   // mag()
0252
0253   inline double rho     () const;
0254   inline double getRho  () const;
0255   // perp()
0256
0257   double eta     () const;
0258   double getEta  () const;
0259   // pseudoRapidity()
0260
0261   inline void setR ( double s );
0262   // setMag()
0263
0264   inline void setRho ( double s );
0265   // setPerp()
0266
0267 // 3 - Comparisions (dictionary, near-ness, and geometric)
0268
0269   int compare (const Hep3Vector & v) const;
0270   bool operator > (const Hep3Vector & v) const;
0271   bool operator < (const Hep3Vector & v) const;
0272   bool operator>= (const Hep3Vector & v) const;
0273   bool operator<= (const Hep3Vector & v) const;
0274   // dictionary ordering according to z, then y, then x component
0275
0276   inline double diff2 (const Hep3Vector & v) const;
0277   // |v1-v2|**2
0278
0279   static double setTolerance (double tol);
0280   static inline double getTolerance ();
0281   // Set the tolerance used in isNear() for Hep3Vectors
0282
0283   bool isParallel (const Hep3Vector & v, double epsilon=tolerance) const;
0284   // Are the vectors parallel, within the given tolerance?
0285
0286   bool isOrthogonal (const Hep3Vector & v, double epsilon=tolerance) const;
0287   // Are the vectors orthogonal, within the given tolerance?
0288
0289   double howParallel   (const Hep3Vector & v) const;
0290   // | v1.cross(v2) / v1.dot(v2) |, to a maximum of 1.
0291
0292   double howOrthogonal (const Hep3Vector & v) const;
0293   // | v1.dot(v2) / v1.cross(v2) |, to a maximum of 1.
0294
0295   static const int ToleranceTicks = 100;
0296
0297 // 4 - Intrinsic properties
0298
0299   double beta    () const;
0300   // relativistic beta (considering v as a velocity vector with c=1)
0301   // Same as mag() but will object if >= 1
0302
0303   double gamma() const;
0304   // relativistic gamma (considering v as a velocity vector with c=1)
0305
0306   double coLinearRapidity() const;
0307   // inverse tanh (beta)
0308
0309 // 5 - Properties relative to Z axis and to an arbitrary direction
0310
0311       // Note that the non-esoteric CLHEP provides
0312       // theta(), cosTheta(), cos2Theta, and angle(const Hep3Vector&)
0313
0314   inline double angle() const;
0315   // angle against the Z axis -- synonym for theta()
0316
0317   inline double theta(const Hep3Vector & v2) const;
0318   // synonym for angle(v2)
0319
0320   double cosTheta (const Hep3Vector & v2) const;
0321   double cos2Theta(const Hep3Vector & v2) const;
0322   // cos and cos^2 of the angle between two vectors
0323
0324   inline Hep3Vector project () const;
0325          Hep3Vector project (const Hep3Vector & v2) const;
0326   // projection of a vector along a direction.
0327
0328   inline Hep3Vector perpPart() const;
0329   inline Hep3Vector perpPart (const Hep3Vector & v2) const;
0330   // vector minus its projection along a direction.
0331
0332   double rapidity () const;
0333   // inverse tanh(v.z())
0334
0335   double rapidity (const Hep3Vector & v2) const;
0336   // rapidity with respect to specified direction:
0337   // inverse tanh (v.dot(u)) where u is a unit in the direction of v2
0338
0339   double eta(const Hep3Vector & v2) const;
0340   // - ln tan of the angle beween the vector and the ref direction.
0341
0342 // 6 - Polar and azimuthal angle decomposition and deltaPhi
0343
0344   // Decomposition of an angle within reference defined by a direction:
0345
0346   double polarAngle (const Hep3Vector & v2) const;
0347   // The reference direction is Z: the polarAngle is abs(v.theta()-v2.theta()).
0348
0349   double deltaPhi (const Hep3Vector & v2) const;
0350   // v.phi()-v2.phi(), brought into the range (-PI,PI]
0351
0352   double azimAngle  (const Hep3Vector & v2) const;
0353   // The reference direction is Z: the azimAngle is the same as deltaPhi
0354
0355   double polarAngle (const Hep3Vector & v2,
0356                     const Hep3Vector & ref) const;
0357   // For arbitrary reference direction,
0358   //    polarAngle is abs(v.angle(ref) - v2.angle(ref)).
0359
0360   double azimAngle  (const Hep3Vector & v2,
0361                     const Hep3Vector & ref) const;
0362   // To compute azimangle, project v and v2 into the plane normal to
0363   // the reference direction.  Then in that plane take the angle going
0364   // clockwise around the direction from projection of v to that of v2.
0365
0366 // 7 - Rotations
0367
0368 // These mehtods **DO NOT** use anything in the HepRotation class.
0369 // Thus, use of v.rotate(axis,delta) does not force linking in Rotation.cc.
0370
0371   Hep3Vector & rotate  (const Hep3Vector & axis, double delta);
0372   // Synonym for rotate (delta, axis)
0373
0374   Hep3Vector & rotate  (const HepAxisAngle & ax);
0375   // HepAxisAngle is a struct holding an axis direction and an angle.
0376
0377   Hep3Vector & rotate (const HepEulerAngles & e);
0378   Hep3Vector & rotate (double phi,
0379                         double theta,
0380                         double psi);
0381   // Rotate via Euler Angles. Our Euler Angles conventions are
0382   // those of Goldstein Classical Mechanics page 107.
0383
0384 protected:
0385   void setSpherical (double r, double theta, double phi);
0386   void setCylindrical (double r, double phi, double z);
0387   double negativeInfinity() const;
0388
0389 protected:
0390
0391   double data[3];
0392   // The components.
0393
0394   static double tolerance;
0395   // default tolerance criterion for isNear() to return true.
0396 };  // Hep3Vector
0397
0398 // Global Methods
0399
0400 Hep3Vector rotationXOf (const Hep3Vector & vec, double delta);
0401 Hep3Vector rotationYOf (const Hep3Vector & vec, double delta);
0402 Hep3Vector rotationZOf (const Hep3Vector & vec, double delta);
0403
0404 Hep3Vector rotationOf (const Hep3Vector & vec,
0405                 const Hep3Vector & axis, double delta);
0406 Hep3Vector rotationOf (const Hep3Vector & vec, const HepAxisAngle & ax);
0407
0408 Hep3Vector rotationOf (const Hep3Vector & vec,
0409                 double phi, double theta, double psi);
0410 Hep3Vector rotationOf (const Hep3Vector & vec, const HepEulerAngles & e);
0411 // Return a new vector based on a rotation of the supplied vector
0412
0413 std::ostream & operator << (std::ostream &, const Hep3Vector &);
0414 // Output to a stream.
0415
0416 std::istream & operator >> (std::istream &, Hep3Vector &);
0417 // Input from a stream.
0418
0419 extern const Hep3Vector HepXHat, HepYHat, HepZHat;
0420
0421 typedef Hep3Vector HepThreeVectorD;
0422 typedef Hep3Vector HepThreeVectorF;
0423
0424 Hep3Vector operator / (const Hep3Vector &, double a);
0425 // Division of 3-vectors by non-zero real number
0426
0427 inline Hep3Vector operator + (const Hep3Vector &, const Hep3Vector &);
0428 // Addition of 3-vectors.
0429
0430 inline Hep3Vector operator - (const Hep3Vector &, const Hep3Vector &);
0431 // Subtraction of 3-vectors.
0432
0433 inline double operator * (const Hep3Vector &, const Hep3Vector &);
0434 // double product of 3-vectors.
0435
0436 inline Hep3Vector operator * (const Hep3Vector &, double a);
0437 inline Hep3Vector operator * (double a, const Hep3Vector &);
0438 // Scaling of 3-vectors with a real number
0439
0440 }  // namespace CLHEP
0441
0442 #include "CLHEP/Vector/ThreeVector.icc"
0443
0444 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
0445 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
0446 using namespace CLHEP;
0447 #endif
0448
0449 #endif /* HEP_THREEVECTOR_H */