1 // -*- C++ -*-
2 // CLASSDOC OFF
3 // ---------------------------------------------------------------------------
4 // CLASSDOC ON
5 //
6 // This file is a part of the CLHEP - a Class Library for High Energy Physics.
7 //
8 // This is the definition of the HepRotationX class for performing rotations
9 // around the X axis on objects of the Hep3Vector (and HepLorentzVector) class.
10 //
11 // HepRotationX is a concrete implementation of Hep3RotationInterface.
12 //
13 // .SS See Also
14 // RotationInterfaces.h
15 // ThreeVector.h, LorentzVector.h, LorentzRotation.h
16 //
17 // .SS Author
18 // Mark Fischler
19 
20 #ifndef HEP_ROTATIONX_H
21 #define HEP_ROTATIONX_H
22 
23 #ifdef GNUPRAGMA
24 #pragma interface
25 #endif
26 
27 #include "CLHEP/Vector/defs.h"
28 #include "CLHEP/Vector/RotationInterfaces.h"
29 
30 namespace CLHEP  {
31 
32 class HepRotationX;
33 
34 class HepRotation;
35 class HepBoost;
36 
37 inline HepRotationX inverseOf(const HepRotationX & r);
38 // Returns the inverse of a RotationX.
39 
40 /**
41  * @author
42  * @ingroup vector
43  */
44 class HepRotationX {
45 
46 public:
47 
48   // ----------  Constructors and Assignment:
49 
50   inline HepRotationX();
51   // Default constructor. Gives an identity rotation.
52 
53   HepRotationX(double delta);
54   // supply angle of rotation
55 
56   inline HepRotationX(const HepRotationX & orig);
57   // Copy constructor.
58 
59   inline HepRotationX & operator = (const HepRotationX & r);
60   // Assignment from a Rotation, which must be RotationX
61 
62   HepRotationX & set ( double delta );
63   // set angle of rotation
64 
65   inline ~HepRotationX();
66   // Trivial destructor.
67 
68   // ----------  Accessors:
69 
70   inline Hep3Vector colX() const;
71   inline Hep3Vector colY() const;
72   inline Hep3Vector colZ() const;
73   // orthogonal unit-length column vectors
74 
75   inline Hep3Vector rowX() const;
76   inline Hep3Vector rowY() const;
77   inline Hep3Vector rowZ() const;
78   // orthogonal unit-length row vectors
79 
80   inline double xx() const;
81   inline double xy() const;
82   inline double xz() const;
83   inline double yx() const;
84   inline double yy() const;
85   inline double yz() const;
86   inline double zx() const;
87   inline double zy() const;
88   inline double zz() const;
89   // Elements of the rotation matrix (Geant4).
90 
91   inline HepRep3x3 rep3x3() const;
92   //   3x3 representation:
93 
94   // ------------  Euler angles:
95   inline  double getPhi  () const;
96   inline  double getTheta() const;
97   inline  double getPsi  () const;
98   double    phi  () const;
99   double    theta() const;
100   double    psi  () const;
101   HepEulerAngles eulerAngles() const;
102 
103   // ------------  axis & angle of rotation:
104   inline  double  getDelta() const;
105   inline  Hep3Vector getAxis () const;
106   inline  double     delta() const;
107   inline  Hep3Vector    axis () const;
108   inline  HepAxisAngle  axisAngle() const;
109   inline  void getAngleAxis(double & delta, Hep3Vector & axis) const;
110   // Returns the rotation angle and rotation axis (Geant4).
111 
112   // ------------- Angles of rotated axes
113   double phiX() const;
114   double phiY() const;
115   double phiZ() const;
116   double thetaX() const;
117   double thetaY() const;
118   double thetaZ() const;
119   // Return angles (RADS) made by rotated axes against original axes (Geant4).
120 
121   // ----------  Other accessors treating pure rotation as a 4-rotation
122 
123   inline HepLorentzVector col1() const;
124   inline HepLorentzVector col2() const;
125   inline HepLorentzVector col3() const;
126   //  orthosymplectic 4-vector columns - T component will be zero
127 
128   inline HepLorentzVector col4() const;
129   // Will be (0,0,0,1) for this pure Rotation.
130 
131   inline HepLorentzVector row1() const;
132   inline HepLorentzVector row2() const;
133   inline HepLorentzVector row3() const;
134   //  orthosymplectic 4-vector rows - T component will be zero
135 
136   inline HepLorentzVector row4() const;
137   // Will be (0,0,0,1) for this pure Rotation.
138 
139   inline double xt() const;
140   inline double yt() const;
141   inline double zt() const;
142   inline double tx() const;
143   inline double ty() const;
144   inline double tz() const;
145   // Will be zero for this pure Rotation
146 
147   inline double tt() const;
148   // Will be one for this pure Rotation
149 
150   inline HepRep4x4 rep4x4() const;
151   //   4x4 representation.
152 
153   // ---------   Mutators
154 
155   void setDelta (double delta);
156   // change angle of rotation, leaving rotation axis unchanged.
157 
158   // ----------  Decomposition:
159 
160   void decompose (HepAxisAngle & rotation, Hep3Vector & boost) const;
161   void decompose (Hep3Vector & boost, HepAxisAngle & rotation) const;
162   void decompose (HepRotation & rotation, HepBoost & boost) const;
163   void decompose (HepBoost & boost, HepRotation & rotation) const;
164   // These are trivial, as the boost vector is 0.
165 
166   // ----------  Comparisons:
167 
168   inline bool isIdentity() const;
169   // Returns true if the identity matrix (Geant4).
170 
171   inline int compare( const HepRotationX & r  ) const;
172   // Dictionary-order comparison, in order of delta
173   // Used in operator<, >, <=, >=
174 
175   inline bool operator== ( const HepRotationX & r ) const;
176   inline bool operator!= ( const HepRotationX & r ) const;
177   inline bool operator<  ( const HepRotationX & r ) const;
178   inline bool operator>  ( const HepRotationX & r ) const;
179   inline bool operator<= ( const HepRotationX & r ) const;
180   inline bool operator>= ( const HepRotationX & r ) const;
181 
182   double distance2( const HepRotationX & r  ) const;
183   // 3 - Tr ( this/r )
184 
185   double distance2( const HepRotation &  r  ) const;
186   // 3 - Tr ( this/r ) -- This works with RotationY or Z also
187 
188   double howNear( const HepRotationX & r ) const;
189   double howNear( const HepRotation  & r ) const;
190   bool isNear( const HepRotationX & r,
191                double epsilon=Hep4RotationInterface::tolerance) const;
192   bool isNear( const HepRotation  & r,
193                double epsilon=Hep4RotationInterface::tolerance) const;
194 
195   double distance2( const HepBoost           & lt  ) const;
196   // 3 - Tr ( this ) + |b|^2 / (1-|b|^2)
197   double distance2( const HepLorentzRotation & lt  ) const;
198   // 3 - Tr ( this/r ) + |b|^2 / (1-|b|^2) where b is the boost vector of lt
199 
200   double howNear( const HepBoost           & lt ) const;
201   double howNear( const HepLorentzRotation & lt ) const;
202   bool isNear( const HepBoost           & lt,
203                double epsilon=Hep4RotationInterface::tolerance) const;
204   bool isNear( const HepLorentzRotation & lt,
205                double epsilon=Hep4RotationInterface::tolerance) const;
206 
207   // ----------  Properties:
208 
209   double norm2() const;
210   // distance2 (IDENTITY), which is 3 - Tr ( *this )
211 
212   inline void rectify();
213   // non-const but logically moot correction for accumulated roundoff errors
214 
215   // ---------- Application:
216 
217   inline Hep3Vector operator() (const Hep3Vector & p) const;
218   // Rotate a Hep3Vector.
219 
220   inline  Hep3Vector operator * (const Hep3Vector & p) const;
221   // Multiplication with a Hep3Vector.
222 
223   inline HepLorentzVector operator()( const HepLorentzVector & w ) const;
224   // Rotate (the space part of) a HepLorentzVector.
225 
226   inline  HepLorentzVector operator* ( const HepLorentzVector & w ) const;
227   // Multiplication with a HepLorentzVector.
228 
229   // ---------- Operations in the group of Rotations
230 
231   inline HepRotationX operator * (const HepRotationX & rx) const;
232   // Product of two X rotations: (this) * rx is known to be RotationX.
233 
234   inline  HepRotationX & operator *= (const HepRotationX & r);
235   inline  HepRotationX & transform   (const HepRotationX & r);
236   // Matrix multiplication.
237   // Note a *= b; <=> a = a * b; while a.transform(b); <=> a = b * a;
238   // However, in this special case, they commute:  Both just add deltas.
239 
240   inline HepRotationX inverse() const;
241   // Returns the inverse.
242 
243   friend HepRotationX inverseOf(const HepRotationX & r);
244   // Returns the inverse of a RotationX.
245 
246   inline HepRotationX & invert();
247   // Inverts the Rotation matrix (be negating delta).
248 
249   // ---------- I/O:
250 
251   std::ostream & print( std::ostream & os ) const;
252   // Output, identifying type of rotation and delta.
253 
254   // ---------- Tolerance
255 
256   static inline double getTolerance();
257   static inline double setTolerance(double tol);
258 
259 protected:
260 
261   double its_d;
262   // The angle of rotation.
263 
264   double its_s;
265   double its_c;
266   // Cache the trig functions, for rapid operations.
267 
268   inline HepRotationX ( double dd, double ss, double cc );
269   // Unchecked load-the-data-members
270 
271   static inline double proper (double delta);
272   // Put an angle into the range of (-PI, PI].  Useful helper method.
273 
274 };  // HepRotationX
275 // ---------- Free-function operations in the group of Rotations
276 
277 inline
278 std::ostream & operator <<
279 	( std::ostream & os, const HepRotationX & r ) {return r.print(os);}
280 
281 }  // namespace CLHEP
282 
283 #include "CLHEP/Vector/RotationX.icc"
284 
285 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
286 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
287 using namespace CLHEP;
288 #endif
289 
290 #endif /* HEP_ROTATIONX_H */
291