CLHEP/Vector/ThreeVector.h

00001 // -*- C++ -*-
00002 // CLASSDOC OFF
00003 // $Id: ThreeVector.h,v 1.27 2003/10/10 19:25:54 mf Exp $
00004 // ---------------------------------------------------------------------------
00005 // CLASSDOC ON
00006 //
00007 // This file is a part of the CLHEP - a Class Library for High Energy Physics.
00008 //
00009 // Hep3Vector is a general 3-vector class defining vectors in three
00010 // dimension using double components. Rotations of these vectors are
00011 // performed by multiplying with an object of the HepRotation class.
00012 //
00013 // .SS See Also
00014 // LorentzVector.h, Rotation.h, LorentzRotation.h 
00015 //
00016 // .SS Authors
00017 // Leif Lonnblad and Anders Nilsson; Modified by Evgueni Tcherniaev;
00018 // ZOOM additions by Mark Fischler
00019 //
00020 
00021 #ifndef HEP_THREEVECTOR_H
00022 #define HEP_THREEVECTOR_H
00023 
00024 #ifdef GNUPRAGMA
00025 #pragma interface
00026 #endif
00027 
00028 #include "CLHEP/config/CLHEP.h"
00029 #include "CLHEP/config/iostream.h"
00030 
00031 #ifdef HEP_NO_INLINE_IN_DECLARATION
00032 #define inline
00033 #endif
00034 
00035 class HepRotation;
00036 class HepEulerAngles;
00037 class HepAxisAngle;
00038 
00043 class Hep3Vector {
00044 
00045 public:
00046 
00047 // Basic properties and operations on 3-vectors:  
00048 
00049   enum { X=0, Y=1, Z=2, NUM_COORDINATES=3, SIZE=NUM_COORDINATES };
00050   // Safe indexing of the coordinates when using with matrices, arrays, etc.
00051   // (BaBar)
00052 
00053   inline Hep3Vector(double x = 0.0, double y = 0.0, double z = 0.0);
00054   // The constructor.  
00055 
00056   inline Hep3Vector(const Hep3Vector &);
00057   // The copy constructor.
00058 
00059   inline ~Hep3Vector();
00060   // The destructor.  Not virtual - inheritance from this class is dangerous.
00061 
00062   double operator () (int) const;
00063   // Get components by index -- 0-based (Geant4) 
00064 
00065   inline double operator [] (int) const;
00066   // Get components by index -- 0-based (Geant4) 
00067 
00068   double & operator () (int);
00069   // Set components by index.  0-based.
00070 
00071   inline double & operator [] (int);
00072   // Set components by index.  0-based.
00073 
00074   inline double x() const;
00075   inline double y() const;
00076   inline double z() const;
00077   // The components in cartesian coordinate system.  Same as getX() etc.
00078 
00079   inline void setX(double);
00080   inline void setY(double);
00081   inline void setZ(double);
00082   // Set the components in cartesian coordinate system.
00083 
00084   inline void set( double x, double y, double z); 
00085   // Set all three components in cartesian coordinate system.
00086 
00087   inline double phi() const;
00088   // The azimuth angle.
00089 
00090   inline double theta() const;
00091   // The polar angle.
00092 
00093   inline double cosTheta() const;
00094   // Cosine of the polar angle.
00095 
00096   inline double cos2Theta() const;
00097   // Cosine squared of the polar angle - faster than cosTheta(). (ZOOM)
00098 
00099   inline double mag2() const;
00100   // The magnitude squared (r^2 in spherical coordinate system).
00101 
00102   inline double mag() const;
00103   // The magnitude (r in spherical coordinate system).
00104 
00105   inline void setPhi(double);
00106   // Set phi keeping mag and theta constant (BaBar).
00107 
00108   inline void setTheta(double);
00109   // Set theta keeping mag and phi constant (BaBar).
00110 
00111          void setMag(double);
00112   // Set magnitude keeping theta and phi constant (BaBar).
00113 
00114   inline double perp2() const;
00115   // The transverse component squared (rho^2 in cylindrical coordinate system).
00116 
00117   inline double perp() const;
00118   // The transverse component (rho in cylindrical coordinate system).
00119 
00120   inline void setPerp(double);
00121   // Set the transverse component keeping phi and z constant.
00122 
00123   void setCylTheta(double);
00124   // Set theta while keeping transvers component and phi fixed 
00125 
00126   inline double perp2(const Hep3Vector &) const;
00127   // The transverse component w.r.t. given axis squared.
00128 
00129   inline double perp(const Hep3Vector &) const;
00130   // The transverse component w.r.t. given axis.
00131 
00132   inline Hep3Vector & operator = (const Hep3Vector &);
00133   // Assignment.
00134 
00135   inline bool operator == (const Hep3Vector &) const;
00136   inline bool operator != (const Hep3Vector &) const;
00137   // Comparisons (Geant4). 
00138 
00139   bool isNear (const Hep3Vector &, double epsilon=tolerance) const;
00140   // Check for equality within RELATIVE tolerance (default 2.2E-14). (ZOOM)
00141   // |v1 - v2|**2 <= epsilon**2 * |v1.dot(v2)| 
00142 
00143   double howNear(const Hep3Vector & v ) const;
00144   // sqrt ( |v1-v2|**2 / v1.dot(v2) ) with a maximum of 1.
00145   // If v1.dot(v2) is negative, will return 1.
00146 
00147   double deltaR(const Hep3Vector & v) const;
00148   // sqrt( pseudorapity_difference**2 + deltaPhi **2 )
00149 
00150   inline Hep3Vector & operator += (const Hep3Vector &);
00151   // Addition.
00152 
00153   inline Hep3Vector & operator -= (const Hep3Vector &);
00154   // Subtraction.
00155 
00156   inline Hep3Vector operator - () const;
00157   // Unary minus.
00158 
00159   inline Hep3Vector & operator *= (double);
00160   // Scaling with real numbers.
00161 
00162          Hep3Vector & operator /= (double);
00163   // Division by (non-zero) real number.
00164 
00165   inline Hep3Vector unit() const;
00166   // Vector parallel to this, but of length 1.
00167 
00168   inline Hep3Vector orthogonal() const;
00169   // Vector orthogonal to this (Geant4).
00170 
00171   inline double dot(const Hep3Vector &) const;
00172   // double product.
00173 
00174   inline Hep3Vector cross(const Hep3Vector &) const;
00175   // Cross product.
00176 
00177   double angle(const Hep3Vector &) const;
00178   // The angle w.r.t. another 3-vector.
00179 
00180   double pseudoRapidity() const;
00181   // Returns the pseudo-rapidity, i.e. -ln(tan(theta/2))
00182 
00183   void setEta  ( double p );
00184   // Set pseudo-rapidity, keeping magnitude and phi fixed.  (ZOOM)
00185 
00186   void setCylEta  ( double p );
00187   // Set pseudo-rapidity, keeping transverse component and phi fixed.  (ZOOM)
00188 
00189   Hep3Vector & rotateX(double);
00190   // Rotates the Hep3Vector around the x-axis.
00191 
00192   Hep3Vector & rotateY(double);
00193   // Rotates the Hep3Vector around the y-axis.
00194 
00195   Hep3Vector & rotateZ(double);
00196   // Rotates the Hep3Vector around the z-axis.
00197 
00198   Hep3Vector & rotateUz(const Hep3Vector&);
00199   // Rotates reference frame from Uz to newUz (unit vector) (Geant4).
00200 
00201     Hep3Vector & rotate(double, const Hep3Vector &);
00202   // Rotates around the axis specified by another Hep3Vector.
00203   // (Uses methods of HepRotation, forcing linking in of Rotation.cc.)
00204 
00205   Hep3Vector & operator *= (const HepRotation &);
00206   Hep3Vector & transform(const HepRotation &);
00207   // Transformation with a Rotation matrix.
00208 
00209 
00210 // = = = = = = = = = = = = = = = = = = = = = = = =
00211 //
00212 // Esoteric properties and operations on 3-vectors:  
00213 //
00214 // 1 - Set vectors in various coordinate systems
00215 // 2 - Synonyms for accessing coordinates and properties
00216 // 3 - Comparisions (dictionary, near-ness, and geometric)
00217 // 4 - Intrinsic properties 
00218 // 5 - Properties releative to z axis and arbitrary directions
00219 // 6 - Polar and azimuthal angle decomposition and deltaPhi
00220 // 7 - Rotations 
00221 //
00222 // = = = = = = = = = = = = = = = = = = = = = = = =
00223 
00224 // 1 - Set vectors in various coordinate systems
00225 
00226   inline void setRThetaPhi  (double r, double theta, double phi);
00227   // Set in spherical coordinates:  Angles are measured in RADIANS
00228 
00229   inline void setREtaPhi  ( double r, double eta,  double phi );
00230   // Set in spherical coordinates, but specify peudorapidiy to determine theta.
00231 
00232   inline void setRhoPhiZ   (double rho, double phi, double z);
00233   // Set in cylindrical coordinates:  Phi angle is measured in RADIANS
00234 
00235   void setRhoPhiTheta ( double rho, double phi, double theta);
00236   // Set in cylindrical coordinates, but specify theta to determine z.
00237 
00238   void setRhoPhiEta ( double rho, double phi, double eta);
00239   // Set in cylindrical coordinates, but specify pseudorapidity to determine z.
00240 
00241 // 2 - Synonyms for accessing coordinates and properties
00242 
00243   inline double getX() const; 
00244   inline double getY() const;
00245   inline double getZ() const; 
00246   // x(), y(), and z()
00247 
00248   inline double getR    () const;
00249   inline double getTheta() const;
00250   inline double getPhi  () const;
00251   // mag(), theta(), and phi()
00252 
00253   inline double r       () const;
00254   // mag()
00255 
00256   inline double rho     () const;
00257   inline double getRho  () const;
00258   // perp()
00259 
00260   double eta     () const;
00261   double getEta  () const;
00262   // pseudoRapidity() 
00263 
00264   inline void setR ( double s );
00265   // setMag()
00266 
00267   inline void setRho ( double s );
00268   // setPerp()
00269 
00270 // 3 - Comparisions (dictionary, near-ness, and geometric)
00271 
00272   int compare (const Hep3Vector & v) const;
00273   bool operator > (const Hep3Vector & v) const;
00274   bool operator < (const Hep3Vector & v) const;
00275   bool operator>= (const Hep3Vector & v) const;
00276   bool operator<= (const Hep3Vector & v) const;
00277   // dictionary ordering according to z, then y, then x component
00278 
00279   inline double diff2 (const Hep3Vector & v) const;
00280   // |v1-v2|**2
00281 
00282   static double setTolerance (double tol);
00283   static inline double getTolerance ();
00284   // Set the tolerance used in isNear() for Hep3Vectors 
00285 
00286   bool isParallel (const Hep3Vector & v, double epsilon=tolerance) const;
00287   // Are the vectors parallel, within the given tolerance?
00288 
00289   bool isOrthogonal (const Hep3Vector & v, double epsilon=tolerance) const;
00290   // Are the vectors orthogonal, within the given tolerance?
00291 
00292   double howParallel   (const Hep3Vector & v) const;
00293   // | v1.cross(v2) / v1.dot(v2) |, to a maximum of 1.
00294 
00295   double howOrthogonal (const Hep3Vector & v) const;
00296   // | v1.dot(v2) / v1.cross(v2) |, to a maximum of 1.
00297 
00298   enum { ToleranceTicks = 100 };
00299 
00300 // 4 - Intrinsic properties 
00301 
00302   double beta    () const;
00303   // relativistic beta (considering v as a velocity vector with c=1)
00304   // Same as mag() but will object if >= 1
00305 
00306   double gamma() const;
00307   // relativistic gamma (considering v as a velocity vector with c=1)
00308 
00309   double coLinearRapidity() const;
00310   // inverse tanh (beta)
00311 
00312 // 5 - Properties relative to Z axis and to an arbitrary direction
00313 
00314           // Note that the non-esoteric CLHEP provides 
00315           // theta(), cosTheta(), cos2Theta, and angle(const Hep3Vector&)
00316 
00317   inline double angle() const;
00318   // angle against the Z axis -- synonym for theta()
00319 
00320   inline double theta(const Hep3Vector & v2) const;  
00321   // synonym for angle(v2)
00322 
00323   double cosTheta (const Hep3Vector & v2) const;
00324   double cos2Theta(const Hep3Vector & v2) const;
00325   // cos and cos^2 of the angle between two vectors
00326 
00327   inline Hep3Vector project () const;
00328          Hep3Vector project (const Hep3Vector & v2) const;
00329   // projection of a vector along a direction.  
00330 
00331   inline Hep3Vector perpPart() const;
00332   inline Hep3Vector perpPart (const Hep3Vector & v2) const;
00333   // vector minus its projection along a direction.
00334 
00335   double rapidity () const;
00336   // inverse tanh(v.z())
00337 
00338   double rapidity (const Hep3Vector & v2) const;
00339   // rapidity with respect to specified direction:  
00340   // inverse tanh (v.dot(u)) where u is a unit in the direction of v2
00341 
00342   double eta(const Hep3Vector & v2) const;
00343   // - ln tan of the angle beween the vector and the ref direction.
00344 
00345 // 6 - Polar and azimuthal angle decomposition and deltaPhi
00346 
00347   // Decomposition of an angle within reference defined by a direction:
00348 
00349   double polarAngle (const Hep3Vector & v2) const;
00350   // The reference direction is Z: the polarAngle is abs(v.theta()-v2.theta()).
00351 
00352   double deltaPhi (const Hep3Vector & v2) const;
00353   // v.phi()-v2.phi(), brought into the range (-PI,PI]
00354 
00355   double azimAngle  (const Hep3Vector & v2) const;
00356   // The reference direction is Z: the azimAngle is the same as deltaPhi
00357 
00358   double polarAngle (const Hep3Vector & v2, 
00359                                         const Hep3Vector & ref) const;
00360   // For arbitrary reference direction, 
00361   //    polarAngle is abs(v.angle(ref) - v2.angle(ref)).
00362 
00363   double azimAngle  (const Hep3Vector & v2, 
00364                                         const Hep3Vector & ref) const;
00365   // To compute azimangle, project v and v2 into the plane normal to
00366   // the reference direction.  Then in that plane take the angle going
00367   // clockwise around the direction from projection of v to that of v2.
00368 
00369 // 7 - Rotations 
00370 
00371 // These mehtods **DO NOT** use anything in the HepRotation class.
00372 // Thus, use of v.rotate(axis,delta) does not force linking in Rotation.cc.
00373 
00374   Hep3Vector & rotate  (const Hep3Vector & axis, double delta);
00375   // Synonym for rotate (delta, axis)
00376 
00377   Hep3Vector & rotate  (const HepAxisAngle & ax);
00378   // HepAxisAngle is a struct holding an axis direction and an angle.
00379 
00380   Hep3Vector & rotate (const HepEulerAngles & e);
00381   Hep3Vector & rotate (double phi,
00382                         double theta,
00383                         double psi);
00384   // Rotate via Euler Angles. Our Euler Angles conventions are 
00385   // those of Goldstein Classical Mechanics page 107.
00386 
00387 protected:
00388   void setSpherical (double r, double theta, double phi);
00389   void setCylindrical (double r, double phi, double z);
00390   double negativeInfinity() const;
00391 
00392 protected:
00393 
00394   double dx;
00395   double dy;
00396   double dz;
00397   // The components.
00398 
00399   static double tolerance;
00400   // default tolerance criterion for isNear() to return true.
00401 };
00402 
00403 // Global Methods
00404 
00405 Hep3Vector rotationXOf (const Hep3Vector & vec, double delta);
00406 Hep3Vector rotationYOf (const Hep3Vector & vec, double delta);
00407 Hep3Vector rotationZOf (const Hep3Vector & vec, double delta);
00408 
00409 Hep3Vector rotationOf (const Hep3Vector & vec, 
00410                                 const Hep3Vector & axis, double delta);
00411 Hep3Vector rotationOf (const Hep3Vector & vec, const HepAxisAngle & ax);
00412 
00413 Hep3Vector rotationOf (const Hep3Vector & vec, 
00414                                 double phi, double theta, double psi);
00415 Hep3Vector rotationOf (const Hep3Vector & vec, const HepEulerAngles & e);
00416 // Return a new vector based on a rotation of the supplied vector
00417 
00418 HepStd::ostream & operator << (HepStd::ostream &, const Hep3Vector &);
00419 // Output to a stream.
00420 
00421 HepStd::istream & operator >> (HepStd::istream &, Hep3Vector &);
00422 // Input from a stream.
00423 
00424 extern const Hep3Vector HepXHat, HepYHat, HepZHat;
00425 
00426 #ifdef HEP_SHORT_NAMES
00427 typedef Hep3Vector Vector3;
00428 typedef Hep3Vector DVector3;
00429 typedef Hep3Vector FVector3;
00430 static const Hep3Vector & xhat = HepXHat;
00431 static const Hep3Vector & yhat = HepYHat;
00432 static const Hep3Vector & zhat = HepZHat;
00433 #endif
00434 typedef Hep3Vector HepThreeVectorD;
00435 typedef Hep3Vector HepThreeVectorF;
00436 
00437 Hep3Vector operator / (const Hep3Vector &, double a);
00438 // Division of 3-vectors by non-zero real number
00439 
00440 #ifdef HEP_NO_INLINE_IN_DECLARATION
00441 #undef inline
00442 #endif
00443 
00444 #ifdef HEP_DEBUG_INLINE
00445 
00446 // The following methods are at global scope, and are inline in the .icc file.
00447 // Likely, for some early compilers one could not declare such a method and 
00448 // then define it - so one could not merely declare operator+ here.  Instead,
00449 // if inline is enabled, this header you relies on the definition in the .icc
00450 // file to act as a delcaration as well.  But if inline is supressed, then
00451 // we do need declarations for these.
00452 
00453 Hep3Vector operator + (const Hep3Vector &, const Hep3Vector &);
00454 // Addition of 3-vectors.
00455 
00456 Hep3Vector operator - (const Hep3Vector &, const Hep3Vector &);
00457 // Subtraction of 3-vectors.
00458 
00459 double operator * (const Hep3Vector &, const Hep3Vector &);
00460 // double product of 3-vectors.
00461 
00462 Hep3Vector operator * (const Hep3Vector &, double a);
00463 Hep3Vector operator * (double a, const Hep3Vector &);
00464 // Scaling of 3-vectors with a real number
00465 
00466 #else
00467 #include "CLHEP/Vector/ThreeVector.icc"
00468 #endif
00469 
00470 #endif /* HEP_THREEVECTOR_H */

Class Library for High Energy Physics (version 1.8)