CLHEP/Vector/LorentzVector.h

// -*- C++ -*-
// CLASSDOC OFF
// $Id: LorentzVector.h,v 1.26 2001/04/03 16:36:16 mf Exp $
// ---------------------------------------------------------------------------
// CLASSDOC ON
//
// This file is a part of the CLHEP - a Class Library for High Energy Physics.
//
// HepLorentzVector is a Lorentz vector consisting of Hep3Vector and
// HepDouble components. Lorentz transformations (rotations and boosts)
// of these vectors are perfomed by multiplying with objects of
// the HepLorenzRotation class.
//
// .SS See Also
// ThreeVector.h, Rotation.h, LorentzRotation.h
//
// .SS Authors
// Leif Lonnblad and Anders Nilsson. Modified by Evgueni Tcherniaev, Mark Fischler
//

#ifndef HEP_LORENTZVECTOR_H
#define HEP_LORENTZVECTOR_H

#ifdef GNUPRAGMA
#pragma interface
#endif

#include "CLHEP/config/CLHEP.h"
#include "CLHEP/Vector/ThreeVector.h"
#include "CLHEP/config/iostream.h"

#ifdef HEP_NO_INLINE_IN_DECLARATION
#define inline
#endif

// Declarations of classes and global methods
class HepLorentzVector;
class HepLorentzRotation;
class HepRotation;
class HepAxisAngle;
class HepEulerAngles;
class Tcomponent;
HepLorentzVector rotationXOf( const HepLorentzVector & vec, HepDouble delta );
HepLorentzVector rotationYOf( const HepLorentzVector & vec, HepDouble delta );
HepLorentzVector rotationZOf( const HepLorentzVector & vec, HepDouble delta );
HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const Hep3Vector & axis, HepDouble delta );
HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const HepAxisAngle & ax );
HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const HepEulerAngles & e );
HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, HepDouble phi,
                                    HepDouble theta,
                                    HepDouble psi );
inline 
HepLorentzVector  boostXOf( const HepLorentzVector & vec, HepDouble beta );
inline 
HepLorentzVector  boostYOf( const HepLorentzVector & vec, HepDouble beta );
inline 
HepLorentzVector  boostZOf( const HepLorentzVector & vec, HepDouble beta );
inline HepLorentzVector  boostOf
    ( const HepLorentzVector & vec, const Hep3Vector & betaVector );
inline HepLorentzVector  boostOf
    ( const HepLorentzVector & vec, const Hep3Vector & axis,  HepDouble beta );

enum ZMpvMetric_t { TimePositive, TimeNegative };


class HepLorentzVector {

public:

  enum { X=0, Y=1, Z=2, T=3, NUM_COORDINATES=4, SIZE=NUM_COORDINATES };
  // Safe indexing of the coordinates when using with matrices, arrays, etc.
  // (BaBar)

  inline HepLorentzVector(HepDouble x, HepDouble y,
			  HepDouble z, HepDouble t);
  // Constructor giving the components x, y, z, t.

  inline HepLorentzVector(HepDouble x, HepDouble y, HepDouble z);
  // Constructor giving the components x, y, z with t-component set to 0.0.

  inline HepLorentzVector(HepDouble t);
  // Constructor giving the t-component with x, y and z set to 0.0.

  inline HepLorentzVector();
  // Default constructor with x, y, z and t set to 0.0.

  inline HepLorentzVector(const Hep3Vector & p, HepDouble e);
  inline HepLorentzVector(HepDouble e, const Hep3Vector & p);
  // Constructor giving a 3-Vector and a time component.

  inline HepLorentzVector(const HepLorentzVector &);
  // Copy constructor.

  inline ~HepLorentzVector();
  // The destructor.

  inline operator const Hep3Vector & () const;
  inline operator Hep3Vector & ();
  // Conversion (cast) to Hep3Vector.

  inline HepDouble x() const;
  inline HepDouble y() const;
  inline HepDouble z() const;
  inline HepDouble t() const;
  // Get position and time.

  inline void setX(HepDouble);
  inline void setY(HepDouble);
  inline void setZ(HepDouble);
  inline void setT(HepDouble);
  // Set position and time.

  inline HepDouble px() const;
  inline HepDouble py() const;
  inline HepDouble pz() const;
  inline HepDouble e() const;
  // Get momentum and energy.

  inline void setPx(HepDouble);
  inline void setPy(HepDouble);
  inline void setPz(HepDouble);
  inline void setE(HepDouble);
  // Set momentum and energy.

  inline Hep3Vector vect() const;
  // Get spatial component. 

  inline void setVect(const Hep3Vector &);
  // Set spatial component. 

  inline HepDouble theta() const;
  inline HepDouble cosTheta() const;
  inline HepDouble phi() const;
  inline HepDouble rho() const;
  // Get spatial vector components in spherical coordinate system.

  inline void setTheta(HepDouble);
  inline void setPhi(HepDouble);
  inline void setRho(HepDouble);
  // Set spatial vector components in spherical coordinate system.

  HepDouble operator () (int) const;
  inline HepDouble operator [] (int) const;
  // Get components by index.

  HepDouble & operator () (int);
  inline HepDouble & operator [] (int);
  // Set components by index.

  inline HepLorentzVector & operator = (const HepLorentzVector &);
  // Assignment. 

  inline HepLorentzVector   operator +  (const HepLorentzVector &) const;
  inline HepLorentzVector & operator += (const HepLorentzVector &);
  // Additions.

  inline HepLorentzVector   operator -  (const HepLorentzVector &) const;
  inline HepLorentzVector & operator -= (const HepLorentzVector &);
  // Subtractions.

  inline HepLorentzVector operator - () const;
  // Unary minus.

  inline HepLorentzVector & operator *= (HepDouble);
         HepLorentzVector & operator /= (HepDouble);
  // Scaling with real numbers.

  inline HepBoolean operator == (const HepLorentzVector &) const;
  inline HepBoolean operator != (const HepLorentzVector &) const;
  // Comparisons.

  inline HepDouble perp2() const;
  // Transverse component of the spatial vector squared.

  inline HepDouble perp() const;
  // Transverse component of the spatial vector (R in cylindrical system).

  inline void setPerp(HepDouble);
  // Set the transverse component of the spatial vector.

  inline HepDouble perp2(const Hep3Vector &) const;
  // Transverse component of the spatial vector w.r.t. given axis squared.

  inline HepDouble perp(const Hep3Vector &) const;
  // Transverse component of the spatial vector w.r.t. given axis.

  inline HepDouble angle(const Hep3Vector &) const;
  // Angle wrt. another vector.

  inline HepDouble mag2() const;
  // Dot product of 4-vector with itself. 
  // By default the metric is TimePositive, and mag2() is the same as m2().

  inline HepDouble m2() const;
  // Invariant mass squared.

  inline HepDouble mag() const;
  inline HepDouble m() const;
  // Invariant mass. If m2() is negative then -sqrt(-m2()) is returned.

  inline HepDouble mt2() const;
  // Transverse mass squared.

  inline HepDouble mt() const;
  // Transverse mass.

  inline HepDouble et2() const;
  // Transverse energy squared.

  inline HepDouble et() const;
  // Transverse energy.

  inline HepDouble dot(const HepLorentzVector &) const;
  inline HepDouble operator * (const HepLorentzVector &) const;
  // Scalar product.

  inline HepDouble invariantMass2( const HepLorentzVector & w ) const;
  // Invariant mass squared of pair of 4-vectors 

  HepDouble invariantMass ( const HepLorentzVector & w ) const;
  // Invariant mass of pair of 4-vectors 

  inline void setVectMag(const Hep3Vector & spatial, HepDouble magnitude);
  inline void setVectM(const Hep3Vector & spatial, HepDouble mass);
  // Copy spatial coordinates, and set energy = sqrt(mass^2 + spatial^2)

  inline HepDouble plus() const;
  inline HepDouble minus() const;
  // Returns the positive/negative light-cone component t +/- z.

  Hep3Vector boostVector() const;
  // Boost needed from rest4Vector in rest frame to form this 4-vector
  // Returns the spatial components divided by the time component.

  HepLorentzVector & boost(HepDouble, HepDouble, HepDouble);
  inline HepLorentzVector & boost(const Hep3Vector &);
  // Lorentz boost.

  HepLorentzVector & boostX( HepDouble beta );
  HepLorentzVector & boostY( HepDouble beta );
  HepLorentzVector & boostZ( HepDouble beta );
  // Boost along an axis, by magnitue beta (fraction of speed of light)

  HepDouble rapidity() const;
  // Returns the rapidity, i.e. 0.5*ln((E+pz)/(E-pz))

  inline HepDouble pseudoRapidity() const;
  // Returns the pseudo-rapidity, i.e. -ln(tan(theta/2))

  inline HepBoolean isTimelike() const;
  // Test if the 4-vector is timelike

  inline HepBoolean isSpacelike() const;
  // Test if the 4-vector is spacelike

  inline HepBoolean isLightlike(HepDouble epsilon=tolerance) const;
  // Test for lightlike is within tolerance epsilon

  HepLorentzVector &  rotateX(HepDouble);
  // Rotate the spatial component around the x-axis.

  HepLorentzVector &  rotateY(HepDouble);
  // Rotate the spatial component around the y-axis.

  HepLorentzVector &  rotateZ(HepDouble);
  // Rotate the spatial component around the z-axis.

  HepLorentzVector &  rotateUz(const Hep3Vector &);
  // Rotates the reference frame from Uz to newUz (unit vector).

  HepLorentzVector & rotate(HepDouble, const Hep3Vector &);
  // Rotate the spatial component around specified axis.

  inline HepLorentzVector & operator *= (const HepRotation &);
  inline HepLorentzVector & transform(const HepRotation &);
  // Transformation with HepRotation.

  HepLorentzVector & operator *= (const HepLorentzRotation &);
  HepLorentzVector & transform(const HepLorentzRotation &);
  // Transformation with HepLorenzRotation.

// = = = = = = = = = = = = = = = = = = = = = = = =
//
// Esoteric properties and operations on 4-vectors:  
//
// 0 - Flexible metric convention and axial unit 4-vectors
// 1 - Construct and set 4-vectors in various ways 
// 2 - Synonyms for accessing coordinates and properties
// 2a - Setting space coordinates in different ways 
// 3 - Comparisions (dictionary, near-ness, and geometric)
// 4 - Intrinsic properties 
// 4a - Releativistic kinematic properties 
// 4b - Methods combining two 4-vectors
// 5 - Properties releative to z axis and to arbitrary directions
// 7 - Rotations and Boosts
//
// = = = = = = = = = = = = = = = = = = = = = = = =

// 0 - Flexible metric convention 

  static ZMpvMetric_t setMetric( ZMpvMetric_t m );
  static ZMpvMetric_t getMetric();

// 1 - Construct and set 4-vectors in various ways 

  inline void set        (HepDouble x, HepDouble y, HepDouble z, HepDouble  t);
  inline void set        (HepDouble x, HepDouble y, HepDouble z, Tcomponent t);
  inline HepLorentzVector(HepDouble x, HepDouble y, HepDouble z, Tcomponent t);
  // Form 4-vector by supplying cartesian coordinate components

  inline void set        (Tcomponent t, HepDouble x, HepDouble y, HepDouble z);
  inline HepLorentzVector(Tcomponent t, HepDouble x, HepDouble y, HepDouble z);
  // Deprecated because the 4-HepDoubles form uses x,y,z,t, not t,x,y,z.

  inline void set                 ( HepDouble t );

  inline void set                 ( Tcomponent t );
  inline explicit HepLorentzVector( Tcomponent t );
  // Form 4-vector with zero space components, by supplying t component

  inline void set                 ( const Hep3Vector & v );
  inline explicit HepLorentzVector( const Hep3Vector & v );
  // Form 4-vector with zero time component, by supplying space 3-vector 

  inline HepLorentzVector & operator=( const Hep3Vector & v );
  // Form 4-vector with zero time component, equal to space 3-vector 

  inline void set ( const Hep3Vector & v, HepDouble t );
  inline void set ( HepDouble t, const Hep3Vector & v );
  // Set using specified space vector and time component

// 2 - Synonyms for accessing coordinates and properties

  inline HepDouble getX() const;
  inline HepDouble getY() const;
  inline HepDouble getZ() const;
  inline HepDouble getT() const;
  // Get position and time.

  inline Hep3Vector v() const;
  inline Hep3Vector getV() const;
  // Get spatial component.   Same as vect.

  inline void setV(const Hep3Vector &);
  // Set spatial component.   Same as setVect.

// 2a - Setting space coordinates in different ways 

  inline void setV( HepDouble x, HepDouble y, HepDouble z );

  inline void setRThetaPhi( HepDouble r, HepDouble theta, HepDouble phi);
  inline void setREtaPhi( HepDouble r, HepDouble eta, HepDouble phi);
  inline void setRhoPhiZ( HepDouble rho, HepDouble phi, HepDouble z );

// 3 - Comparisions (dictionary, near-ness, and geometric)

  int compare( const HepLorentzVector & w ) const;

  HepBoolean operator >( const HepLorentzVector & w ) const;
  HepBoolean operator <( const HepLorentzVector & w ) const;
  HepBoolean operator>=( const HepLorentzVector & w ) const;
  HepBoolean operator<=( const HepLorentzVector & w ) const;

  HepBoolean   isNear ( const HepLorentzVector & w, 
					HepDouble epsilon=tolerance ) const;
  HepDouble howNear( const HepLorentzVector & w ) const;
  // Is near using Euclidean measure t**2 + v**2

  HepBoolean   isNearCM ( const HepLorentzVector & w, 
					HepDouble epsilon=tolerance ) const;
  HepDouble howNearCM( const HepLorentzVector & w ) const;
  // Is near in CM frame:  Applicable only for two timelike HepLorentzVectors

        // If w1 and w2 are already in their CM frame, then w1.isNearCM(w2)
        // is exactly equivalent to w1.isNear(w2).
        // If w1 and w2 have T components of zero, w1.isNear(w2) is exactly
        // equivalent to w1.getV().isNear(w2.v()).  

  HepBoolean isParallel( const HepLorentzVector & w, 
					HepDouble epsilon=tolerance ) const;
  // Test for isParallel is within tolerance epsilon
  HepDouble howParallel (const HepLorentzVector & w) const;

  static HepDouble getTolerance();
  static HepDouble setTolerance( HepDouble tol );
  // Set the tolerance for HepLorentzVectors to be considered near
  // The same tolerance is used for determining isLightlike, and isParallel

  HepDouble deltaR(const HepLorentzVector & v) const;
  // sqrt ( (delta eta)^2 + (delta phi)^2 ) of space part

// 4 - Intrinsic properties 

         HepDouble howLightlike() const;
  // Close to zero for almost lightlike 4-vectors; up to 1.

  inline HepDouble euclideanNorm2()  const;
  // Sum of the squares of time and space components; not Lorentz invariant. 

  inline HepDouble euclideanNorm()  const; 
  // Length considering the metric as (+ + + +); not Lorentz invariant.


// 4a - Relativistic kinematic properties 

// All Relativistic kinematic properties are independent of the sense of metric

  inline HepDouble restMass2() const;
  inline HepDouble invariantMass2() const; 
  // Rest mass squared -- same as m2()

  inline HepDouble restMass() const;
  inline HepDouble invariantMass() const; 
  // Same as m().  If m2() is negative then -sqrt(-m2()) is returned.

// The following properties are rest-frame related, 
// and are applicable only to non-spacelike 4-vectors

  HepLorentzVector rest4Vector() const;
  // This 4-vector, boosted into its own rest frame:  (0, 0, 0, m()) 
          // The following relation holds by definition:
          // w.rest4Vector().boost(w.boostVector()) == w

  // Beta and gamma of the boost vector
  HepDouble beta() const;
  // Relativistic beta of the boost vector

  HepDouble gamma() const;
  // Relativistic gamma of the boost vector

  inline HepDouble eta() const;
  // Pseudorapidity (of the space part)

  inline HepDouble eta(const Hep3Vector & ref) const;
  // Pseudorapidity (of the space part) w.r.t. specified direction

  HepDouble rapidity(const Hep3Vector & ref) const;
  // Rapidity in specified direction

  HepDouble coLinearRapidity() const;
  // Rapidity, in the relativity textbook sense:  atanh (|P|/E)

  Hep3Vector findBoostToCM() const;
  // Boost needed to get to center-of-mass  frame:
          // w.findBoostToCM() == - w.boostVector()
          // w.boost(w.findBoostToCM()) == w.rest4Vector()

  Hep3Vector findBoostToCM( const HepLorentzVector & w ) const;
  // Boost needed to get to combined center-of-mass frame:
          // w1.findBoostToCM(w2) == w2.findBoostToCM(w1)
          // w.findBoostToCM(w) == w.findBoostToCM()

  inline HepDouble et2(const Hep3Vector &) const;
  // Transverse energy w.r.t. given axis squared.

  inline HepDouble et(const Hep3Vector &) const;
  // Transverse energy w.r.t. given axis.

// 4b - Methods combining two 4-vectors

  inline HepDouble diff2( const HepLorentzVector & w ) const;
  // (this - w).dot(this-w); sign depends on metric choice

  inline HepDouble delta2Euclidean ( const HepLorentzVector & w ) const;
  // Euclidean norm of differnce:  (delta_T)^2  + (delta_V)^2

// 5 - Properties releative to z axis and to arbitrary directions

  HepDouble  plus(  const Hep3Vector & ref ) const;
  // t + projection in reference direction

  HepDouble  minus( const Hep3Vector & ref ) const;
  // t - projection in reference direction

// 7 - Rotations and boosts

  HepLorentzVector & rotate ( const Hep3Vector & axis, HepDouble delta );
  // Same as rotate (delta, axis)

  HepLorentzVector & rotate ( const HepAxisAngle & ax );
  HepLorentzVector & rotate ( const HepEulerAngles & e );
  HepLorentzVector & rotate ( HepDouble phi,
                              HepDouble theta,
                              HepDouble psi );
  // Rotate using these HepEuler angles - see Goldstein page 107 for conventions

  HepLorentzVector & boost ( const Hep3Vector & axis,  HepDouble beta );
  // Normalizes the Hep3Vector to define a direction, and uses beta to
  // define the magnitude of the boost.

  friend HepLorentzVector rotationXOf
    ( const HepLorentzVector & vec, HepDouble delta );
  friend HepLorentzVector rotationYOf
    ( const HepLorentzVector & vec, HepDouble delta );
  friend HepLorentzVector rotationZOf
    ( const HepLorentzVector & vec, HepDouble delta );
  friend HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const Hep3Vector & axis, HepDouble delta );
  friend HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const HepAxisAngle & ax );
  friend HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, const HepEulerAngles & e );
  friend HepLorentzVector rotationOf
    ( const HepLorentzVector & vec, HepDouble phi,
                                    HepDouble theta,
                                    HepDouble psi );

  inline friend HepLorentzVector  boostXOf
    ( const HepLorentzVector & vec, HepDouble beta );
  inline friend HepLorentzVector  boostYOf
    ( const HepLorentzVector & vec, HepDouble beta );
  inline friend HepLorentzVector  boostZOf
    ( const HepLorentzVector & vec, HepDouble beta );
  inline friend HepLorentzVector  boostOf
    ( const HepLorentzVector & vec, const Hep3Vector & betaVector );
  inline friend HepLorentzVector  boostOf
    ( const HepLorentzVector & vec, const Hep3Vector & axis,  HepDouble beta );
 
private:

  Hep3Vector pp;
  HepDouble  ee;

  static HepDouble tolerance;
  static HepDouble metric;

};

// 8 - Axial Unit 4-vectors

static const HepLorentzVector X_HAT4 = HepLorentzVector( 1, 0, 0, 0 );
static const HepLorentzVector Y_HAT4 = HepLorentzVector( 0, 1, 0, 0 );
static const HepLorentzVector Z_HAT4 = HepLorentzVector( 0, 0, 1, 0 );
static const HepLorentzVector T_HAT4 = HepLorentzVector( 0, 0, 0, 1 );

// Global methods

HepStd::ostream & operator << (HepStd::ostream &, const HepLorentzVector &);
// Output to a stream.

HepStd::istream & operator >> (HepStd::istream &, HepLorentzVector &);
// Input from a stream.

#ifdef HEP_NO_INLINE_IN_DECLARATION
#undef inline
#endif

#ifdef HEP_SHORT_NAMES
typedef HepLorentzVector VectorL;
typedef HepLorentzVector Vector4;
typedef HepLorentzVector DVectorL;
typedef HepLorentzVector DVector4;
typedef HepLorentzVector FVectorL;
typedef HepLorentzVector FVector4;
#endif

typedef HepLorentzVector HepLorentzVectorD;
typedef HepLorentzVector HepLorentzVectorF;

inline HepLorentzVector operator * (const HepLorentzVector &, HepDouble a);
inline HepLorentzVector operator * (HepDouble a, const HepLorentzVector &);
// Scaling LorentzVector with a real number

       HepLorentzVector operator / (const HepLorentzVector &, HepDouble a);
// Dividing LorentzVector by a real number

// Tcomponent definition:

// Signature protection for 4-vector constructors taking 4 components
class Tcomponent {
private:
  HepDouble t_;
public:
  explicit Tcomponent(HepDouble t) : t_(t) {}
  operator HepDouble() const { return t_; }
};

#ifndef HEP_DEBUG_INLINE
#include "CLHEP/Vector/LorentzVector.icc"
#endif

#endif /* HEP_LORENTZVECTOR_H */