CLHEP/Vector/ThreeVector.h

// -*- C++ -*-
// CLASSDOC OFF
// $Id: ThreeVector.h,v 1.21 2001/01/18 17:35:15 mf Exp $
// ---------------------------------------------------------------------------
// CLASSDOC ON
//
// This file is a part of the CLHEP - a Class Library for High Energy Physics.
//
// Hep3Vector is a general 3-vector class defining vectors in three
// dimension using HepDouble components. Rotations of these vectors are
// performed by multiplying with an object of the HepRotation class.
//
// .SS See Also
// LorentzVector.h, Rotation.h, LorentzRotation.h 
//
// .SS Authors
// Leif Lonnblad and Anders Nilsson; ZOOM additions by Mark Fischler
//

#ifndef HEP_THREEVECTOR_H
#define HEP_THREEVECTOR_H

#ifdef GNUPRAGMA
#pragma interface
#endif

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

#ifdef HEP_NO_INLINE_IN_DECLARATION
#define inline
#endif

class HepRotation;
class HepEulerAngles;
class HepAxisAngle;

class Hep3Vector {

public:

// Basic properties and operations on 3-vectors:  

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

  inline Hep3Vector(HepDouble x = 0.0, HepDouble y = 0.0, HepDouble z = 0.0);
  // The constructor.  

  inline Hep3Vector(const Hep3Vector &);
  // The copy constructor.

  inline ~Hep3Vector();
  // The destructor.  Not virtual - inheritance from this class is dangerous.

  HepDouble operator () (int) const;
  // Get components by index -- 0-based (Geant4) 

  inline HepDouble operator [] (int) const;
  // Get components by index -- 0-based (Geant4) 

  HepDouble & operator () (int);
  // Set components by index.  0-based.

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

  inline HepDouble x() const;
  inline HepDouble y() const;
  inline HepDouble z() const;
  // The components in cartesian coordinate system.  Same as getX() etc.

  inline void setX(HepDouble);
  inline void setY(HepDouble);
  inline void setZ(HepDouble);
  // Set the components in cartesian coordinate system.

  inline void set( HepDouble x, HepDouble y, HepDouble z); 
  // Set all three components in cartesian coordinate system.

  inline HepDouble phi() const;
  // The azimuth angle.

  inline HepDouble theta() const;
  // The polar angle.

  inline HepDouble cosTheta() const;
  // Cosine of the polar angle.

  inline HepDouble cos2Theta() const;
  // Cosine squared of the polar angle - faster than cosTheta(). (ZOOM)

  inline HepDouble mag2() const;
  // The magnitude squared (r^2 in spherical coordinate system).

  inline HepDouble mag() const;
  // The magnitude (r in spherical coordinate system).

  inline void setPhi(HepDouble);
  // Set phi keeping mag and theta constant (BaBar).

  inline void setTheta(HepDouble);
  // Set theta keeping mag and phi constant (BaBar).

  inline void setMag(HepDouble);
  // Set magnitude keeping theta and phi constant (BaBar).

  inline HepDouble perp2() const;
  // The transverse component squared (rho^2 in cylindrical coordinate system).

  inline HepDouble perp() const;
  // The transverse component (rho in cylindrical coordinate system).

  inline void setPerp(HepDouble);
  // Set the transverse component keeping phi and z constant.

  void setCylTheta(HepDouble);
  // Set theta while keeping transvers component and phi fixed 

  inline HepDouble perp2(const Hep3Vector &) const;
  // The transverse component w.r.t. given axis squared.

  inline HepDouble perp(const Hep3Vector &) const;
  // The transverse component w.r.t. given axis.

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

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

  HepBoolean isNear (const Hep3Vector &, HepDouble epsilon=tolerance) const;
  // Check for equality within RELATIVE tolerance (default 2.2E-14). (ZOOM)
  // |v1 - v2|**2 <= epsilon**2 * |v1.dot(v2)| 

  HepDouble howNear(const Hep3Vector & v ) const;
  // sqrt ( |v1-v2|**2 / v1.dot(v2) ) with a maximum of 1.
  // If v1.dot(v2) is negative, will return 1.

  HepDouble deltaR(const Hep3Vector & v) const;
  // sqrt( pseudorapity_difference**2 + phi_differnce **2 )

  inline Hep3Vector & operator += (const Hep3Vector &);
  // Addition.

  inline Hep3Vector & operator -= (const Hep3Vector &);
  // Subtraction.

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

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

         Hep3Vector & operator /= (HepDouble);
  // Division by (non-zero) real number.

  inline Hep3Vector unit() const;
  // Vector parallel to this, but of length 1.

  inline Hep3Vector orthogonal() const;
  // Vector orthogonal to this (Geant4).

  inline HepDouble dot(const Hep3Vector &) const;
  // HepDouble product.

  inline Hep3Vector cross(const Hep3Vector &) const;
  // Cross product.

  HepDouble angle(const Hep3Vector &) const;
  // The angle w.r.t. another 3-vector.

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

  void setEta  ( HepDouble p );
  // Set pseudo-rapidity, keeping magnitude and phi fixed.  (ZOOM)

  void setCylEta  ( HepDouble p );
  // Set pseudo-rapidity, keeping transverse component and phi fixed.  (ZOOM)

  Hep3Vector & rotateX(HepDouble);
  // Rotates the Hep3Vector around the x-axis.

  Hep3Vector & rotateY(HepDouble);
  // Rotates the Hep3Vector around the y-axis.

  Hep3Vector & rotateZ(HepDouble);
  // Rotates the Hep3Vector around the z-axis.

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

    Hep3Vector & rotate(HepDouble, const Hep3Vector &);
  // Rotates around the axis specified by another Hep3Vector.
  // (Uses methods of HepRotation, forcing linking in of Rotation.cc.)

  Hep3Vector & operator *= (const HepRotation &);
  Hep3Vector & transform(const HepRotation &);
  // Transformation with a Rotation matrix.


// = = = = = = = = = = = = = = = = = = = = = = = =
//
// Esoteric properties and operations on 3-vectors:  
//
// 1 - Set vectors in various coordinate systems
// 2 - Synonyms for accessing coordinates and properties
// 3 - Comparisions (dictionary, near-ness, and geometric)
// 4 - Intrinsic properties 
// 5 - Properties releative to z axis and arbitrary directions
// 6 - Polar and azimuthal angle decomposition
// 7 - Rotations 
//
// = = = = = = = = = = = = = = = = = = = = = = = =

// 1 - Set vectors in various coordinate systems

  inline void setRThetaPhi  (HepDouble r, HepDouble theta, HepDouble phi);
  // Set in spherical coordinates:  Angles are measured in RADIANS

  inline void setREtaPhi  ( HepDouble r, HepDouble eta,  HepDouble phi );
  // Set in spherical coordinates, but specify peudorapidiy to determine theta.

  inline void setRhoPhiZ   (HepDouble rho, HepDouble phi, HepDouble z);
  // Set in cylindrical coordinates:  Phi angle is measured in RADIANS

  void setRhoPhiTheta ( HepDouble rho, HepDouble phi, HepDouble theta);
  // Set in cylindrical coordinates, but specify theta to determine z.

  void setRhoPhiEta ( HepDouble rho, HepDouble phi, HepDouble eta);
  // Set in cylindrical coordinates, but specify pseudorapidity to determine z.

// 2 - Synonyms for accessing coordinates and properties

  inline HepDouble getX() const; 
  inline HepDouble getY() const;
  inline HepDouble getZ() const; 
  // x(), y(), and z()

  inline HepDouble getR    () const;
  inline HepDouble getTheta() const;
  inline HepDouble getPhi  () const;
  // mag(), theta(), and phi()

  inline HepDouble r       () const;
  // mag()

  inline HepDouble rho     () const;
  inline HepDouble getRho  () const;
  // perp()

  HepDouble eta     () const;
  HepDouble getEta  () const;
  // pseudoRapidity() 

  inline void setR ( HepDouble s );
  // setMag()

  inline void setRho ( HepDouble s );
  // setPerp()

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

  int compare (const Hep3Vector & v) const;
  HepBoolean operator > (const Hep3Vector & v) const;
  HepBoolean operator < (const Hep3Vector & v) const;
  HepBoolean operator>= (const Hep3Vector & v) const;
  HepBoolean operator<= (const Hep3Vector & v) const;
  // dictionary ordering according to z, then y, then x component

  inline HepDouble diff2 (const Hep3Vector & v) const;
  // |v1-v2|**2

  static HepDouble setTolerance (HepDouble tol);
  static inline HepDouble getTolerance ();
  // Set the tolerance used in isNear() for Hep3Vectors 

  HepBoolean isParallel (const Hep3Vector & v, HepDouble epsilon=tolerance) const;
  // Are the vectors parallel, within the given tolerance?

  HepBoolean isOrthogonal (const Hep3Vector & v, HepDouble epsilon=tolerance) const;
  // Are the vectors orthogonal, within the given tolerance?

  HepDouble howParallel   (const Hep3Vector & v) const;
  // | v1.cross(v2) / v1.dot(v2) |, to a maximum of 1.

  HepDouble howOrthogonal (const Hep3Vector & v) const;
  // | v1.dot(v2) / v1.cross(v2) |, to a maximum of 1.

  enum { ToleranceTicks = 100 };

// 4 - Intrinsic properties 

  HepDouble beta    () const;
  // relativistic beta (considering v as a velocity vector with c=1)
  // Same as mag() but will object if >= 1

  HepDouble gamma() const;
  // relativistic gamma (considering v as a velocity vector with c=1)

  HepDouble coLinearRapidity() const;
  // inverse tanh (beta)

// 5 - Properties relative to Z axis and to an arbitrary direction

	  // Note that the non-esoteric CLHEP provides 
	  // theta(), cosTheta(), cos2Theta, and angle(const Hep3Vector&)

  inline HepDouble angle() const;
  // angle against the Z axis -- synonym for theta()

  inline HepDouble theta(const Hep3Vector & v2) const;  
  // synonym for angle(v2)

  HepDouble cosTheta (const Hep3Vector & v2) const;
  HepDouble cos2Theta(const Hep3Vector & v2) const;
  // cos and cos^2 of the angle between two vectors

  inline Hep3Vector project () const;
         Hep3Vector project (const Hep3Vector & v2) const;
  // projection of a vector along a direction.  

  inline Hep3Vector perpPart() const;
  inline Hep3Vector perpPart (const Hep3Vector & v2) const;
  // vector minus its projection along a direction.

  HepDouble rapidity () const;
  // inverse tanh(v.z())

  HepDouble rapidity (const Hep3Vector & v2) const;
  // rapidity with respect to specified direction:  
  // inverse tanh (v.dot(u)) where u is a unit in the direction of v2

  HepDouble eta(const Hep3Vector & v2) const;
  // - ln tan of the angle beween the vector and the ref direction.

// 6 - Polar and azimuthal angle decomposition

  // Decomposition of an angle within reference defined by a direction:

  HepDouble polarAngle (const Hep3Vector & v2) const;
  // The reference direction is Z: the polarAngle is abs(v.theta()-v2.theta()).

  HepDouble azimAngle  (const Hep3Vector & v2) const;
  // The reference direction is Z: the azimAngle is v.phi()-v2.phi()


  HepDouble polarAngle (const Hep3Vector & v2, 
					const Hep3Vector & ref) const;
  // For arbitrary reference direction, 
  // 	polarAngle is abs(v.angle(ref) - v2.angle(ref)).

  HepDouble azimAngle  (const Hep3Vector & v2, 
					const Hep3Vector & ref) const;
  // To compute azimangle, project v and v2 into the plane normal to
  // the reference direction.  Then in that plane take the angle going
  // clockwise around the direction from projection of v to that of v2.

// 7 - Rotations 

// These mehtods **DO NOT** use anything in the HepRotation class.
// Thus, use of v.rotate(axis,delta) does not force linking in Rotation.cc.

  Hep3Vector & rotate  (const Hep3Vector & axis, HepDouble delta);
  // Synonym for rotate (delta, axis)

  Hep3Vector & rotate  (const HepAxisAngle & ax);
  // HepAxisAngle is a struct holding an axis direction and an angle.

  Hep3Vector & rotate (const HepEulerAngles & e);
  Hep3Vector & rotate (HepDouble phi,
                        HepDouble theta,
                        HepDouble psi);
  // Rotate via Euler Angles. Our Euler Angles conventions are 
  // those of Goldstein Classical Mechanics page 107.

protected:
  void setSpherical (HepDouble r, HepDouble theta, HepDouble phi);
  void setCylindrical (HepDouble r, HepDouble phi, HepDouble z);
  HepDouble negativeInfinity() const;

protected:

  HepDouble dx;
  HepDouble dy;
  HepDouble dz;
  // The components.

  static HepDouble tolerance;
  // default tolerance criterion for isNear() to return true.
};

// Global Methods

Hep3Vector rotationXOf (const Hep3Vector & vec, HepDouble delta);
Hep3Vector rotationYOf (const Hep3Vector & vec, HepDouble delta);
Hep3Vector rotationZOf (const Hep3Vector & vec, HepDouble delta);

Hep3Vector rotationOf (const Hep3Vector & vec, 
				const Hep3Vector & axis, HepDouble delta);
Hep3Vector rotationOf (const Hep3Vector & vec, const HepAxisAngle & ax);

Hep3Vector rotationOf (const Hep3Vector & vec, 
				HepDouble phi, HepDouble theta, HepDouble psi);
Hep3Vector rotationOf (const Hep3Vector & vec, const HepEulerAngles & e);
// Return a new vector based on a rotation of the supplied vector

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

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

extern const Hep3Vector HepXHat, HepYHat, HepZHat;

#ifdef HEP_SHORT_NAMES
typedef Hep3Vector Vector3;
typedef Hep3Vector DVector3;
typedef Hep3Vector FVector3;
static const Hep3Vector & xhat = HepXHat;
static const Hep3Vector & yhat = HepYHat;
static const Hep3Vector & zhat = HepZHat;
#endif
typedef Hep3Vector HepThreeVectorD;
typedef Hep3Vector HepThreeVectorF;

Hep3Vector operator / (const Hep3Vector &, HepDouble a);
// Division of 3-vectors by non-zero real number

#ifdef HEP_NO_INLINE_IN_DECLARATION
#undef inline
#endif

#ifdef HEP_DEBUG_INLINE

// The following methods are at global scope, and are inline in the .icc file.
// Likely, for some early compilers one could not declare such a method and 
// then define it - so one could not merely declare operator+ here.  Instead,
// if inline is enabled, this header you relies on the definition in the .icc
// file to act as a delcaration as well.  But if inline is supressed, then
// we do need declarations for these.

Hep3Vector operator + (const Hep3Vector &, const Hep3Vector &);
// Addition of 3-vectors.

Hep3Vector operator - (const Hep3Vector &, const Hep3Vector &);
// Subtraction of 3-vectors.

HepDouble operator * (const Hep3Vector &, const Hep3Vector &);
// HepDouble product of 3-vectors.

Hep3Vector operator * (const Hep3Vector &, HepDouble a);
Hep3Vector operator * (HepDouble a, const Hep3Vector &);
// Scaling of 3-vectors with a real number

#else
#include "CLHEP/Vector/ThreeVector.icc"
#endif

#endif /* HEP_THREEVECTOR_H */