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

Complete:
Detailed Review status

Contents

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

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

Topic revision: r14 - 2017-04-12 - TimCox

ESSENTIALS