CLHEP/Vector/LorentzRotation.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 // This is the definition of the HepLorentzRotation class for performing
0009 // Lorentz transformations (rotations and boosts) on objects of the
0010 // HepLorentzVector class.
0011 //
0012 // HepLorentzRotation is a concrete implementation of Hep4RotationInterface.
0013 //
0014 // .SS See Also
0015 // RotationInterfaces.h
0016 // ThreeVector.h, LorentzVector.h
0017 // Rotation.h, Boost.h
0018 //
0019 // .SS Author
0020 // Leif Lonnblad, Mark Fischler
0021
0022 #ifndef HEP_LORENTZROTATION_H
0023 #define HEP_LORENTZROTATION_H
0024
0025 #include "CLHEP/Vector/defs.h"
0026 #include "CLHEP/Vector/RotationInterfaces.h"
0027 #include "CLHEP/Vector/Rotation.h"
0028 #include "CLHEP/Vector/Boost.h"
0029 #include "CLHEP/Vector/LorentzVector.h"
0030
0031 namespace CLHEP {
0032
0033 // Global methods
0034
0035 inline HepLorentzRotation inverseOf ( const HepLorentzRotation & lt );
0036 HepLorentzRotation operator * (const HepRotation & r,
0037                                         const HepLorentzRotation & lt);
0038 HepLorentzRotation operator * (const HepRotationX & r,
0039                                         const HepLorentzRotation & lt);
0040 HepLorentzRotation operator * (const HepRotationY & r,
0041                                         const HepLorentzRotation & lt);
0042 HepLorentzRotation operator * (const HepRotationZ & r,
0043                                         const HepLorentzRotation & lt);
0044
0045 /**
0046  * @author
0047  * @ingroup vector
0048  */
0049 class HepLorentzRotation {
0050
0051 public:
0052   // ----------  Identity HepLorentzRotation:
0053
0054   static const HepLorentzRotation IDENTITY;
0055
0056   // ----------  Constructors and Assignment:
0057
0058   inline HepLorentzRotation();
0059   // Default constructor. Gives a unit matrix.
0060
0061   inline  HepLorentzRotation (const HepLorentzRotation & r);
0062   inline  HepLorentzRotation (HepLorentzRotation && r) = default;
0063   // Copy and move constructors.
0064
0065   inline           HepLorentzRotation (const HepRotation  & r);
0066   inline  explicit HepLorentzRotation (const HepRotationX & r);
0067   inline  explicit HepLorentzRotation (const HepRotationY & r);
0068   inline  explicit HepLorentzRotation (const HepRotationZ & r);
0069   inline           HepLorentzRotation (const HepBoost  &    b);
0070   inline  explicit HepLorentzRotation (const HepBoostX &    b);
0071   inline  explicit HepLorentzRotation (const HepBoostY &    b);
0072   inline  explicit HepLorentzRotation (const HepBoostZ &    b);
0073   // Constructors from special cases.
0074
0075   inline HepLorentzRotation & operator = (HepLorentzRotation && m) = default;
0076   inline HepLorentzRotation & operator = (const HepLorentzRotation & m);
0077   inline HepLorentzRotation & operator = (const HepRotation        & m);
0078   inline HepLorentzRotation & operator = (const HepBoost           & m);
0079   // Assignment.
0080
0081          HepLorentzRotation & set (double bx, double by, double bz);
0082   inline HepLorentzRotation & set (const Hep3Vector & p);
0083   inline HepLorentzRotation & set (const HepRotation  & r);
0084   inline HepLorentzRotation & set (const HepRotationX & r);
0085   inline HepLorentzRotation & set (const HepRotationY & r);
0086   inline HepLorentzRotation & set (const HepRotationZ & r);
0087   inline HepLorentzRotation & set (const HepBoost & boost);
0088   inline HepLorentzRotation & set (const HepBoostX & boost);
0089   inline HepLorentzRotation & set (const HepBoostY & boost);
0090   inline HepLorentzRotation & set (const HepBoostZ & boost);
0091   inline HepLorentzRotation (double bx, double by, double bz);
0092   inline HepLorentzRotation (const Hep3Vector & p);
0093   // Other Constructors giving a Lorentz-boost.
0094
0095          HepLorentzRotation & set( const HepBoost & B, const HepRotation & R );
0096   inline HepLorentzRotation (      const HepBoost & B, const HepRotation & R );
0097   //   supply B and R:  T = B R:
0098
0099          HepLorentzRotation & set( const HepRotation & R, const HepBoost & B );
0100   inline HepLorentzRotation (      const HepRotation & R, const HepBoost & B );
0101   //   supply R and B:  T = R B:
0102
0103   HepLorentzRotation ( const HepLorentzVector & col1,
0104                const HepLorentzVector & col2,
0105                const HepLorentzVector & col3,
0106                const HepLorentzVector & col4 );
0107   // Construct from four *orthosymplectic* LorentzVectors for the columns:
0108     // NOTE:
0109         //      This constructor, and the two set methods below,
0110         //      will check that the columns (or rows) form an orthosymplectic
0111         //      matrix, and will adjust values so that this relation is
0112         //      as exact as possible.
0113     //  Orthosymplectic means the dot product USING THE METRIC
0114     //  of two different coumns will be 0, and of a column with
0115     //  itself will be one.
0116
0117   HepLorentzRotation & set( const HepLorentzVector & col1,
0118                             const HepLorentzVector & col2,
0119                             const HepLorentzVector & col3,
0120                             const HepLorentzVector & col4 );
0121   //   supply four *orthosymplectic* HepLorentzVectors for the columns
0122
0123   HepLorentzRotation & setRows( const HepLorentzVector & row1,
0124                                 const HepLorentzVector & row2,
0125                                 const HepLorentzVector & row3,
0126                                 const HepLorentzVector & row4 );
0127   //   supply four *orthosymplectic* HepLorentzVectors for the columns
0128
0129   inline HepLorentzRotation & set( const HepRep4x4 & rep );
0130   inline HepLorentzRotation      ( const HepRep4x4 & rep );
0131   //   supply a HepRep4x4 structure (16 numbers)
0132   // WARNING:
0133   //            This constructor and set method will assume the
0134   //            HepRep4x4 supplied is in fact an orthosymplectic matrix.
0135   //            No checking or correction is done.  If you are
0136   //            not certain the matrix is orthosymplectic, break it
0137   //            into four HepLorentzVector columns and use the form
0138   //            HepLorentzRotation (col1, col2, col3, col4)
0139
0140   // ----------  Accessors:
0141
0142   inline double xx() const;
0143   inline double xy() const;
0144   inline double xz() const;
0145   inline double xt() const;
0146   inline double yx() const;
0147   inline double yy() const;
0148   inline double yz() const;
0149   inline double yt() const;
0150   inline double zx() const;
0151   inline double zy() const;
0152   inline double zz() const;
0153   inline double zt() const;
0154   inline double tx() const;
0155   inline double ty() const;
0156   inline double tz() const;
0157   inline double tt() const;
0158   // Elements of the matrix.
0159
0160   inline HepLorentzVector col1() const;
0161   inline HepLorentzVector col2() const;
0162   inline HepLorentzVector col3() const;
0163   inline HepLorentzVector col4() const;
0164   // orthosymplectic column vectors
0165
0166   inline HepLorentzVector row1() const;
0167   inline HepLorentzVector row2() const;
0168   inline HepLorentzVector row3() const;
0169   inline HepLorentzVector row4() const;
0170   // orthosymplectic row vectors
0171
0172   inline HepRep4x4 rep4x4() const;
0173   //   4x4 representation:
0174
0175   // ------------  Subscripting:
0176
0177   class HepLorentzRotation_row {
0178   public:
0179     inline HepLorentzRotation_row(const HepLorentzRotation &, int);
0180     inline double operator [] (int) const;
0181   private:
0182     const HepLorentzRotation & rr;
0183     int ii;
0184   };
0185   // Helper class for implemention of C-style subscripting r[i][j]
0186
0187   inline const HepLorentzRotation_row operator [] (int) const;
0188   // Returns object of the helper class for C-style subscripting r[i][j]
0189
0190   double operator () (int, int) const;
0191   // Fortran-style subscripting: returns (i,j) element of the matrix.
0192
0193   // ----------  Decomposition:
0194
0195   void decompose (Hep3Vector & boost, HepAxisAngle & rotation) const;
0196   void decompose (HepBoost   & boost, HepRotation  & rotation) const;
0197   // Find B and R such that L = B*R
0198
0199   void decompose (HepAxisAngle & rotation, Hep3Vector & boost) const;
0200   void decompose (HepRotation  & rotation, HepBoost   & boost) const;
0201   // Find R and B such that L = R*B
0202
0203   // ----------  Comparisons:
0204
0205   int compare( const HepLorentzRotation & m  ) const;
0206   // Dictionary-order comparison, in order tt,tz,...zt,zz,zy,zx,yt,yz,...,xx
0207   // Used in operator<, >, <=, >=
0208
0209   inline bool operator == (const HepLorentzRotation &) const;
0210   inline bool operator != (const HepLorentzRotation &) const;
0211   inline bool operator <= (const HepLorentzRotation &) const;
0212   inline bool operator >= (const HepLorentzRotation &) const;
0213   inline bool operator <  (const HepLorentzRotation &) const;
0214   inline bool operator >  (const HepLorentzRotation &) const;
0215
0216   inline bool isIdentity() const;
0217   // Returns true if the Identity matrix.
0218
0219   double distance2( const HepBoost & b  ) const;
0220   double distance2( const HepRotation & r  ) const;
0221   double distance2( const HepLorentzRotation & lt  ) const;
0222   // Decomposes L = B*R, returns the sum of distance2 for B and R.
0223
0224   double howNear(   const HepBoost & b ) const;
0225   double howNear(   const HepRotation & r) const;
0226   double howNear(   const HepLorentzRotation & lt ) const;
0227
0228   bool isNear(const HepBoost & b,
0229              double epsilon=Hep4RotationInterface::tolerance) const;
0230   bool isNear(const HepRotation & r,
0231              double epsilon=Hep4RotationInterface::tolerance) const;
0232   bool isNear(const HepLorentzRotation & lt,
0233              double epsilon=Hep4RotationInterface::tolerance) const;
0234
0235   // ----------  Properties:
0236
0237   double norm2() const;
0238   // distance2 (IDENTITY), which involves decomposing into B and R and summing
0239   // norm2 for the individual B and R parts.
0240
0241   void rectify();
0242   // non-const but logically moot correction for accumulated roundoff errors
0243         // rectify averages the matrix with the orthotranspose of its actual
0244         // inverse (absent accumulated roundoff errors, the orthotranspose IS
0245         // the inverse)); this removes to first order those errors.
0246         // Then it formally decomposes that, extracts axis and delta for its
0247     // Rotation part, forms a LorentzRotation from a true HepRotation
0248     // with those values of axis and delta, times the true Boost
0249     // with that boost vector.
0250
0251   // ---------- Application:
0252
0253   inline HepLorentzVector vectorMultiplication(const HepLorentzVector&) const;
0254   inline HepLorentzVector operator()( const HepLorentzVector & w ) const;
0255   inline HepLorentzVector operator* ( const HepLorentzVector & p ) const;
0256   // Multiplication with a Lorentz Vector.
0257
0258   // ---------- Operations in the group of 4-Rotations
0259
0260   HepLorentzRotation matrixMultiplication(const HepRep4x4 & m) const;
0261
0262   inline HepLorentzRotation operator * (const HepBoost & b) const;
0263   inline HepLorentzRotation operator * (const HepRotation & r) const;
0264   inline HepLorentzRotation operator * (const HepLorentzRotation & lt) const;
0265   // Product of two Lorentz Rotations (this) * lt - matrix multiplication
0266
0267   inline  HepLorentzRotation & operator *= (const HepBoost & b);
0268   inline  HepLorentzRotation & operator *= (const HepRotation & r);
0269   inline  HepLorentzRotation & operator *= (const HepLorentzRotation & lt);
0270   inline  HepLorentzRotation & transform   (const HepBoost & b);
0271   inline  HepLorentzRotation & transform   (const HepRotation & r);
0272   inline  HepLorentzRotation & transform   (const HepLorentzRotation & lt);
0273   // Matrix multiplication.
0274   // Note a *= b; <=> a = a * b; while a.transform(b); <=> a = b * a;
0275
0276   // Here there is an opportunity for speedup by providing specialized forms
0277   // of lt * r and lt * b where r is a RotationX Y or Z or b is a BoostX Y or Z
0278   // These are, in fact, provided below for the transform() methods.
0279
0280   HepLorentzRotation & rotateX(double delta);
0281   // Rotation around the x-axis; equivalent to LT = RotationX(delta) * LT
0282
0283   HepLorentzRotation & rotateY(double delta);
0284   // Rotation around the y-axis; equivalent to LT = RotationY(delta) * LT
0285
0286   HepLorentzRotation & rotateZ(double delta);
0287   // Rotation around the z-axis; equivalent to LT = RotationZ(delta) * LT
0288
0289   inline HepLorentzRotation & rotate(double delta, const Hep3Vector& axis);
0290   inline HepLorentzRotation & rotate(double delta, const Hep3Vector *axis);
0291   // Rotation around specified vector - LT = Rotation(delta,axis)*LT
0292
0293   HepLorentzRotation & boostX(double beta);
0294   // Pure boost along the x-axis; equivalent to LT = BoostX(beta) * LT
0295
0296   HepLorentzRotation & boostY(double beta);
0297   // Pure boost along the y-axis; equivalent to LT = BoostX(beta) * LT
0298
0299   HepLorentzRotation & boostZ(double beta);
0300   // Pure boost along the z-axis; equivalent to LT = BoostX(beta) * LT
0301
0302   inline HepLorentzRotation & boost(double, double, double);
0303   inline HepLorentzRotation & boost(const Hep3Vector &);
0304   // Lorenz boost.
0305
0306   inline HepLorentzRotation inverse() const;
0307   // Return the inverse.
0308
0309   inline HepLorentzRotation & invert();
0310   // Inverts the LorentzRotation matrix.
0311
0312   // ---------- I/O:
0313
0314   std::ostream & print( std::ostream & os ) const;
0315   // Aligned six-digit-accurate output of the transformation matrix.
0316
0317   // ---------- Tolerance
0318
0319   static inline double getTolerance();
0320   static inline double setTolerance(double tol);
0321
0322   friend HepLorentzRotation inverseOf ( const HepLorentzRotation & lt );
0323
0324 protected:
0325
0326   inline HepLorentzRotation
0327        (double mxx, double mxy, double mxz, double mxt,
0328     double myx, double myy, double myz, double myt,
0329     double mzx, double mzy, double mzz, double mzt,
0330     double mtx, double mty, double mtz, double mtt);
0331   // Protected constructor.
0332   // DOES NOT CHECK FOR VALIDITY AS A LORENTZ TRANSFORMATION.
0333
0334   inline void setBoost(double, double, double);
0335   // Set elements according to a boost vector.
0336
0337   double mxx, mxy, mxz, mxt,
0338             myx, myy, myz, myt,
0339             mzx, mzy, mzz, mzt,
0340             mtx, mty, mtz, mtt;
0341   // The matrix elements.
0342
0343 };  // HepLorentzRotation
0344
0345 inline std::ostream & operator<<
0346         ( std::ostream & os, const  HepLorentzRotation& lt )
0347   {return lt.print(os);}
0348
0349 inline bool operator==(const HepRotation &r, const HepLorentzRotation & lt)
0350   { return lt==HepLorentzRotation(r); }
0351 inline bool operator!=(const HepRotation &r, const HepLorentzRotation & lt)
0352   { return lt!=HepLorentzRotation(r); }
0353 inline bool operator<=(const HepRotation &r, const HepLorentzRotation & lt)
0354   { return lt<=r; }
0355 inline bool operator>=(const HepRotation &r, const HepLorentzRotation & lt)
0356   { return lt>=r; }
0357 inline bool operator<(const HepRotation &r, const HepLorentzRotation & lt)
0358   { return lt<r; }
0359 inline bool operator>(const HepRotation &r, const HepLorentzRotation & lt)
0360   { return lt>r; }
0361
0362 inline bool operator==(const HepBoost &b, const HepLorentzRotation & lt)
0363   { return lt==HepLorentzRotation(b); }
0364 inline bool operator!=(const HepBoost &b, const HepLorentzRotation & lt)
0365   { return lt!=HepLorentzRotation(b); }
0366 inline bool operator<=(const HepBoost &b, const HepLorentzRotation & lt)
0367   { return lt<=b; }
0368 inline bool operator>=(const HepBoost &b, const HepLorentzRotation & lt)
0369   { return lt>=b; }
0370 inline bool operator<(const HepBoost &b, const HepLorentzRotation & lt)
0371   { return lt<b; }
0372 inline bool operator>(const HepBoost &b, const HepLorentzRotation & lt)
0373   { return lt>b; }
0374
0375 }  // namespace CLHEP
0376
0377 #include "CLHEP/Vector/LorentzRotation.icc"
0378
0379 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
0380 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
0381 using namespace CLHEP;
0382 #endif
0383
0384 #endif /* HEP_LORENTZROTATION_H */
0385