9.4 Commonly used vector/matrix classes in CMSSW (GlobalPoint, LorentzVector, etc.)

Complete:
Detailed Review status

Contents

• Introduction

• GlobalPoint and GlobalVector
  • GlobalPoint Constructors
  • GlobalPoint Functions
    • Notes on GlobalPoint Functions
  • GlobalVector Constructors
  • GlobalVector Functions

• Particle::Point, Vertex::Point, Particle::Vector and Vertex::Vector

• Lorentz Vectors

• AlgebraicSymMatrix55 and AlgebraicVector55

• Acknowledgements
• Review Status

Goal of this page

This page describes commonly used vector/matrix classes in CMSSW. These use heavily templated classes, so it is not straightforward to discover their functionality by direct reading of the code. (The templating is used for generality, and would make it trivial to define, for example, analogous classes using double precision rather than float).

GlobalPoint and GlobalVector

The main constructors and functions of GlobalPoint and GlobalVector are summarized here. This is a fairly complete list. These classes are based on PV3DBase - see http://cmslxr.fnal.gov/source/DataFormats/GeometryVector/interface/PV3DBase.h] OR https://cmssdt.cern.ch/lxr/source/DataFormats/GeometryVector/interface/PV3DBase.h - which lists additional functions inside them.

GlobalPoint and GlobalVector are classes in DataFormats/GeometryVector for representing, with float precision, a 3-dim space point and 3-dim direction vector respectively in the CMS global coordinate system. They are widely used in track reconstruction code.

Similar classes called LocalPoint and LocalVector represent points and vectors in the local coordinate system of a given Detector Unit. They are not described here, but have an entirely analogous set of functions (due once again to templating). Transforming between global and local coordinates is a functionality of the GeomDet class, the fundamental base class of many tracking subdetector units in CMS.

GlobalPoint constructors

constructor	what it does
GlobalPoint( float x, float y float z );	// construct from Cartesian x, y, z coordinates
GlobalPoint();	// effectively GlobalPoint( 0., 0., 0. )
GlobalPoint( float x, float y );	// effectively GlobalPoint( x, y, 0. )
GlobalPoint( Polar(float theta, float phi, float r) );	// construct from spherical polar coordinates, phi angular range (-pi,+pi]
GlobalPoint( Cylindrical(float r, float phi, float z) );
GlobalPoint( GlobalPoint gp );

GlobalPoint functions

function	what it does
GlobalPoint& operator+=( const GlobalVector& gv );	// shifts a point - the Cartesian components are added
GlobalPoint& operator-=( const GlobalVector& gv );	// shifts a point - the Cartesian components are subtracted
float x() const;	// Cartesian x component
float y() const;	// Cartesian y component
float z() const;	// Cartesian z component
float mag2() const;	// x*x + y*y + z*z
float mag() const;	// sqrt( x*x + y*y + z*z )
float perp2() const;	// x*x + y*y
float perp() const;	// sqrt( x*x + y*y )
float transverse() const;	// same as perp()
Geom::Phi phi() const;	// azimuthal phi, radians, range (-pi, +pi]
Geom::Theta theta() const;	// polar theta, radians, range [0, pi]
float eta() const;	// pseudorapidity

Notes on GlobalPoint functions

i) BEWARE! Geom::Phi enforces its range to be (-pi, +pi] and includes various functions, e.g. operator*, which may confuse you. For example, if you try to scale phi() it will subvert your probable intentions:

 
gp.phi() * 180./3.14159; // gp is a GlobalPoint

does not give you the phi in degrees!

But Geom::Phi has a function degrees() which you can use instead of doing your own scaling:

float ang3 = gp.phi().degrees(); // returns the phi in degrees

There's a matching function to return the value in radians:

float ang2 = gp.phi().value();    // returns the angle in radians

However Phi has a type conversion operator so that the following simple call works:

float ang1 = gp.phi();          // returns the angle in radians using implicit 
                                 // type conversion to template type (float)

ii) phi() and theta() use atan2 to calculate their values.

iii) eta() is calculated as

{ float x(z()/perp()); return log(x+sqrt(x*x+1));}

which is claimed to be faster than the direct -log( tan( theta()/2.). It does not check for zero transverse component; in this case the behavior is as for divide-by zero, i.e. system-dependent.

GlobalVector constructors

constructor	what it does
GlobalVector( float x, float y float z );	// construct from Cartesian x, y, z coordinates
GlobalVector();	// effectively GlobalVector( 0., 0., 0. )
GlobalVector( float x, float y );	// effectively GlobalVector( x, y, 0. )
GlobalVector( Polar(float theta, float phi, float r) );	// construct from spherical polar coordinates, phi angular range (-pi,+pi]
GlobalVector( Cylindrical(float r, float phi, float z) );
GlobalVector( GlobalVector gv );

GlobalVector functions

function	what it does
GlobalVector& operator+=( const GlobalVector& gv );	// adds a vector - the Cartesian components are added
GlobalVector& operator-=( const GlobalVector& gv );	// subtracts a vector - the Cartesian components are subtracted
GlobalVector& operator*=( float );	// multiply by a scalar
GlobalVector& operator/=( float );	// divide by a scalar
GlobalVector operator-() const;	// returns GlobalVector(-x, -y, -z)
GlobalVector cross( const GlobalVector& gv ) const;	// cross (vector) product
float dot( const GlobalVector& gv ) const;	// dot (scalar) product
GlobalVector unit() const;	// unit vector parallel to this. If mag()=0 a zero vector is returned.
GlobalVector also has the same functions as GlobalPoint (and the same caveats apply - see above):
float x() const;	// Cartesian x component
float y() const;	// Cartesian y component
float z() const;	// Cartesian z component
float mag2() const;	// x*x + y*y + z*z
float mag() const;	// sqrt( x*x + y*y + z*z )
float perp2() const;	// x*x + y*y
float perp() const;	// sqrt( x*x + y*y )
float transverse() const;	// same as perp()
Geom::Phi phi() const;	// azimuthal phi, radians, range (-pi, +pi]
Geom::Theta theta() const;	// polar theta, radians, range [0, pi]
float eta() const;	// pseudorapidity

Particle::Point, Vertex::Point, Particle::Vector and Vertex::Vector

Particle::Point and Particle:Vector are defined in DataFormats/Candidate/ . They are used to represent 3-dimension space-point and direction information about MC truth particles and of most reconstructed objects (except tracks).

Vertex::Point and Vertex::Vector are identical to Particle::Point and Particle:Vector . They are defined in DataFormats/VertexReco and used to provide information about reconstructed vertices.

These classes are all based on the ROOT objects:

PositionVector3D<ROOT::Math::Cartesian3D >

DisplacementVector3D<ROOT::Math::Cartesian3D >

which are described in the ROOT User Manual.

Lorentz Vectors

To manipulate Lorentz vectors, CMSSW uses (notably in the Candidate class) code similar to the following example:

  // N.B. Confusingly this #include defines XYZTLorentzVector, not LorentzVector !
  #include "DataFormats/Math/interface/LorentzVector.h"
  using namespace math;

  XYZTLorentzVector p4Sum;
  for (i=0; ....) {
      p4Sum += XYZTLorentzVector(px[i], py[i], pz[i], E[i]);
  }
  double massSum = p4Sum.M();

Note you can also create a ROOT Lorentz vector specifying the 3-momentum and the mass (instead of the energy):

  #include "Math/LorentzVector.h" 
  #include "Math/PxPyPzM4D.h"
  ROOT::Math::LorentzVector<ROOT::Math::PxPyPzM4D<double> > p4(px, py, pz, m);

These Lorentz vectors are based on _ ROOT::Math::LorentzVector<ROOT::Math::PxPyPzE4D > _ which explains which functions are available.

AlgebraicSymMatrix55 and AlgebraicVector55

These are matrix and vector classes commonly used inside the track reconstruction software. They are usually only used by tracking software developers, so are described in the CMSSW Offline Guide.

Warning: Do not confuse these with AlgebraicVector and AlgebraicSymMatrix (with no number "55"). These also exist, but are completely different classes based on CLHEP/Matrix/SymMatrix.h !

Acknowledgements

GlobalPoint and GlobalVector have been part of CMS software since 1999. They were written by Teddy Todorov.

Review Status

Editor/Reviewer and Comments	Comments
TimCox - 02 Jul 2007	page author
JennyWilliams - 03 Jul 2007	added workbook markup and moved page into cms workbook
IanTomalin - 25 Jun 2008	added info on Particle::Point and Vertex and AlgebraicSymMatrix55
IanTomalin - 11 Nov 2009	various improvements. Added LorentzVector documentation

Responsible: TimCox
Last reviewed by: -- TimCox - 25 Jan 2008 Last reviewed by: -- IanTomalin - 25 Jun 2008