Physics Vectors

Vector classes (2D, 3D and 4D / Lorentz vector) and their transformations.

These classes represent vectors and their operations and transformations, such as rotations and Lorentz transformations, in two, three and four dimensions. The 4D space-time is used for physics vectors representing relativistic particles in Minkowski-space. These vectors are different from Linear Algebra vectors or `std::vector`

which describe generic N-dimensional vectors.

Hint: the most commonly used Lorentz vector class is ROOT::Math::PtEtaPhiMVector, a typedef to ROOT::Math::LorentzVector < ROOT::Math::PtEtaPhiM4D < double > >.

Mathematically, vectors and points are two distinct concepts. They have different transformations: vectors can only be rotated, while points can be rotated or translated. You can add two vectors but not two points, and the difference between two points is a vector. We then distinguish for the 2 and 3 dimensional case, between points and vectors, modeling them with different classes:

- ROOT::Math::DisplacementVector2D and ROOT::Math::DisplacementVector3D describe 2- and 3-component direction and magnitude vectors, not rooted at any particular point;
- ROOT::Math::PositionVector2D and ROOT::Math::PositionVector3D model points in 2 and 3 dimensions.

ROOT::Math::LorentzVector models 4D space-time vectors. There is no class for a 4D point.

The vector classes are based on a generic type of coordinate system, expressed as a template parameter of the class. Various classes exist to describe the various coordinates systems:

**2D coordinate system**classes:- ROOT::Math::Cartesian2D, based on
*(x,y)*; - ROOT::Math::Polar2D, based on
*(r, phi)*;

- ROOT::Math::Cartesian2D, based on
**3D coordinate system**classes:- ROOT::Math::Cartesian3D, based on
*(x,y,z)*; - ROOT::Math::Polar3D, based on
*(r, theta, phi)*; - ROOT::Math::Cylindrical3D, based on
*(rho, z, phi)* - ROOT::Math::CylindricalEta3D, based on
*(rho, eta, phi)*;

- ROOT::Math::Cartesian3D, based on
**4D coordinate system**classes:- ROOT::Math::PxPyPzE4D, based on based on
*(px,py,pz,E)*; - ROOT::Math::PxPyPzM4D, based on based on
*(px,py,pz,M)*; - ROOT::Math::PtEtaPhiE4D, based on based on
*(pt,eta,phi,E)*; - ROOT::Math::PtEtaPhiM4D, based on based on
*(pt,eta,phi,M)*;

- ROOT::Math::PxPyPzE4D, based on based on

The angle *theta* is defined between [0, \(\pi\)] and *phi* between [- \(\pi\), \(\pi\)]. The angles are expressed in radians. The *eta* component is known as pseudo-rapidity.

Users can define the Vectors according to the coordinate type which is most efficient for their use. Transformations between the various coordinate systems are available through copy constructors or the assignment `operator =`

. The coordinate system classes are templated on the scalar type for maximum flexibility, and to minimize memory usage for some use cases.

The 2D and 3D point and vector classes can be associated to a tag defining the coordinate system. This can be used to distinguish between vectors of different coordinate systems like global or local vectors. The coordinate system tag is a template parameter of the ROOT::Math::DisplacementVector3D (and ROOT::Math::DisplacementVector2D) and ROOT::Math::PositionVector3D (and ROOT::Math::PositionVector2D) classes. A default tag, ROOT::Math::DefaultCoordinateSystemTag, exists for users who don't need this functionality.

To avoid exposing templated parameters to the users, typedefs are defined for all types of vectors based an `double`

s and `float`

s. The table below lists the `double`

versions; the `float`

counterpart ends on an extra `F`

, such as ROOT::Math::XYPointF instead of ROOT::Math::XYPoint.

Type definitions for points in two dimensions, based on ROOT::Math::PositionVector2D, are defined by `Math/Point2D.h`

:

- ROOT::Math::XYPoint vector based on x,y coordinates (cartesian)
- ROOT::Math::Polar2DPoint vector based on r,phi coordinates (polar)

Type definitions for vectors in two dimensions, based on ROOT::Math::DisplacementVector2D, are defined by `Math/Vector2D.h`

:

- ROOT::Math::XYVector vector based on x,y coordinates (cartesian)
- ROOT::Math::Polar2DVector vector based on r,phi coordinates (polar)

Type definitions for points in three dimensions, based on ROOT::Math::PositionVector3D, are defined by `Math/Point3D.h`

:

- ROOT::Math::XYZPoint point based on x,y,z coordinates (cartesian)
- ROOT::Math::Polar3DPoint point based on r,theta,phi coordinates (polar)
- ROOT::Math::RhoZPhiPoint point based on rho,z,phi coordinates (cylindrical using z)
- ROOT::Math::RhoEtaPhiPoint point based on rho,eta,phi coordinates (cylindrical using eta instead of z)

Type definitions for vectors in three dimensions, based on ROOT::Math::DisplacementVector3D, are defined by `Math/Vector3D.h`

:

- ROOT::Math::XYZVector vector based on x,y,z coordinates (cartesian)
- ROOT::Math::Polar3DVector vector based on r,theta,phi coordinates (polar)
- ROOT::Math::RhoZPhiVector vector based on rho, z,phi coordinates (cylindrical)
- ROOT::Math::RhoEtaPhiVector vector based on rho,eta,phi coordinates (cylindrical using eta instead of z)

Type definitions for Lorentz vectors in four dimensions, based on ROOT::Math::LorentzVector, are defined by `Math/Vector4D.h`

:

- ROOT::Math::XYZTVector vector based on x,y,z,t coordinates (cartesian)
- ROOT::Math::PtEtaPhiEVector vector based on pt (rho),eta,phi and E (t) coordinates
- ROOT::Math::PtEtaPhiMVector vector based on pt (rho),eta,phi and M (t) coordinates
- ROOT::Math::PxPyPzMVector vector based on px,py,pz and M (mass) coordinates
- ROOT::Math::PxPyPzEVector vector based on px,py,pz and E (energy) coordinates

The metric used for any such LorentzVector is (-,-,-,+).

A vector can be constructed from its coordinate representation:

Class describing a generic LorentzVector in the 4D space-time, using the specified coordinate system ...

In addition, the vector classes can be constructed from any object that implements the accessors x(), y() and z(). This can be a vector using a different coordinate system, or even an object from a different package as long as it implements the required signatures. One such vector type is CLHEP's `Hep3Vector`

:

RhoEtaPhiVector r2(v1);

CLHEP::Hep3Vector q(1,2,3);

DisplacementVector3D< Cartesian3D< double >, DefaultCoordinateSystemTag > XYZVector

3D Vector based on the cartesian coordinates x,y,z in double precision

DisplacementVector3D< CylindricalEta3D< double >, DefaultCoordinateSystemTag > RhoEtaPhiVector

3D Vector based on the eta based cylindrical coordinates rho, eta, phi in double precision.

The following operations are possible between vector classes, even of different coordinate system types:

Note that the multiplication between two vectors using the `operator *`

is not supported because it is ambiguous.

The vector classes support methods for:

- computation of the dot product via Dot(),
- computation of the cross product via Cross(),
- construction of a unit vector via Unit().

The transformations are modeled using simple (non-template) classes, using `double`

as the scalar type to avoid too large numerical errors. The transformations are grouped in Rotations (in 3 dimensions), Lorentz transformations. Each group has several members which may model physically equivalent trasformations but with different internal representations. Transformation classes can operate on all type of vectors using the `operator()`

or the `operator *`

and the transformations can also be combined via the `operator *`

. In more detail the transformations available are:

- ROOT::Math::Rotation3D, rotation described by a 3x3 matrix of doubles
- ROOT::Math::EulerAngles rotation described by the three Euler angles (phi, theta and psi) following the GoldStein definition.
- ROOT::Math::RotationZYX rotation described by three angles defining a rotation first along the Z axis, then along the rotated Y' axis and then along the rotated X'' axis.
- ROOT::Math::AxisAngle, rotation described by a vector (axis) and an angle
- ROOT::Math::Quaternion, rotation described by a quaternion (4 numbers)
- ROOT::Math::RotationX, specialized rotation along the X axis
- ROOT::Math::RotationY, specialized rotation along the Y axis
- ROOT::Math::RotationZ, specialized rotation along the Z axis

- ROOT::Math::Translation3D, (only translation) described by a 3D vector
- ROOT::Math::Transform3D, (rotations and then translation) described by a 3x4 matrix (12 numbers)

- ROOT::Math::LorentzRotation , 4D rotation (3D rotation plus a boost) described by a 4x4 matrix
- ROOT::Math::Boost, a Lorentz boost in an arbitrary direction and described by a 4x4 symmetric matrix (10 numbers)
- ROOT::Math::BoostX, a boost in the X axis direction
- ROOT::Math::BoostY, a boost in the Y axis direction
- ROOT::Math::BoostZ, a boost in the Z axis direction

For compatibility with CLHEP, the vector classes can be constructed easily from a CLHEP `Hep3Vector`

or `HepLorentzVector`

, by using a template constructor, which requires only that the classes implement the accessors `x()`

, `y()`

and `z()`

(and `t()`

for `HepLorentzVector`

). The vector classes also provide member function with the same naming convention as CLHEP for the most used functions like `x()`

, `y()`

and `z()`

.

A more detailed description of all the GenVector classes is available in this document.

## Namespaces | |

namespace | ROOT::Math::VectorUtil |

Global Helper functions for generic Vector classes. | |

## Classes | |

class | ROOT::Math::AxisAngle |

AxisAngle class describing rotation represented with direction axis (3D Vector) and an angle of rotation around that axis. More... | |

class | ROOT::Math::Boost |

Lorentz boost class with the (4D) transformation represented internally by a 4x4 orthosymplectic matrix. More... | |

class | ROOT::Math::BoostX |

Class representing a Lorentz Boost along the X axis, by beta. More... | |

class | ROOT::Math::BoostY |

Class representing a Lorentz Boost along the Y axis, by beta. More... | |

class | ROOT::Math::BoostZ |

Class representing a Lorentz Boost along the Z axis, by beta. More... | |

class | ROOT::Math::Cartesian2D< T > |

Class describing a 2D cartesian coordinate system (x, y coordinates) More... | |

class | ROOT::Math::Cartesian3D< T > |

Class describing a 3D cartesian coordinate system (x, y, z coordinates) More... | |

class | ROOT::Math::Cylindrical3D< T > |

Class describing a cylindrical coordinate system based on rho, z and phi. More... | |

class | ROOT::Math::CylindricalEta3D< T > |

Class describing a cylindrical coordinate system based on eta (pseudorapidity) instead of z. More... | |

class | ROOT::Math::DefaultCoordinateSystemTag |

DefaultCoordinateSystemTag Default tag for identifying any coordinate system. More... | |

class | ROOT::Math::DisplacementVector2D< CoordSystem, Tag > |

Class describing a generic displacement vector in 2 dimensions. More... | |

class | ROOT::Math::DisplacementVector3D< CoordSystem, Tag > |

Class describing a generic displacement vector in 3 dimensions. More... | |

class | ROOT::Math::EulerAngles |

EulerAngles class describing rotation as three angles (Euler Angles). More... | |

class | ROOT::Math::GlobalCoordinateSystemTag |

Tag for identifying vectors based on a global coordinate system. More... | |

class | ROOT::Math::LocalCoordinateSystemTag |

Tag for identifying vectors based on a local coordinate system. More... | |

class | ROOT::Math::LorentzRotation |

Lorentz transformation class with the (4D) transformation represented by a 4x4 orthosymplectic matrix. More... | |

class | ROOT::Math::LorentzVector< CoordSystem > |

Class describing a generic LorentzVector in the 4D space-time, using the specified coordinate system for the spatial vector part. More... | |

class | ROOT::Math::Impl::Plane3D< T > |

Class describing a geometrical plane in 3 dimensions. More... | |

class | ROOT::Math::Polar2D< T > |

Class describing a polar 2D coordinate system based on r and phi Phi is restricted to be in the range [-PI,PI) More... | |

class | ROOT::Math::Polar3D< T > |

Class describing a polar coordinate system based on r, theta and phi Phi is restricted to be in the range [-PI,PI) More... | |

class | ROOT::Math::PositionVector2D< CoordSystem, Tag > |

Class describing a generic position vector (point) in 2 dimensions. More... | |

class | ROOT::Math::PositionVector3D< CoordSystem, Tag > |

Class describing a generic position vector (point) in 3 dimensions. More... | |

class | ROOT::Math::PtEtaPhiE4D< ScalarType > |

Class describing a 4D cylindrical coordinate system using Pt , Phi, Eta and E (or rho, phi, eta , T) The metric used is (-,-,-,+). More... | |

class | ROOT::Math::PtEtaPhiM4D< ScalarType > |

Class describing a 4D cylindrical coordinate system using Pt , Phi, Eta and M (mass) The metric used is (-,-,-,+). More... | |

class | ROOT::Math::PxPyPzE4D< ScalarType > |

Class describing a 4D cartesian coordinate system (x, y, z, t coordinates) or momentum-energy vectors stored as (Px, Py, Pz, E). More... | |

class | ROOT::Math::PxPyPzM4D< ScalarType > |

Class describing a 4D coordinate system or momentum-energy vectors stored as (Px, Py, Pz, M). More... | |

class | ROOT::Math::Quaternion |

Rotation class with the (3D) rotation represented by a unit quaternion (u, i, j, k). More... | |

class | ROOT::Math::Rotation3D |

Rotation class with the (3D) rotation represented by a 3x3 orthogonal matrix. More... | |

class | ROOT::Math::RotationX |

Rotation class representing a 3D rotation about the X axis by the angle of rotation. More... | |

class | ROOT::Math::RotationY |

Rotation class representing a 3D rotation about the Y axis by the angle of rotation. More... | |

class | ROOT::Math::RotationZ |

Rotation class representing a 3D rotation about the Z axis by the angle of rotation. More... | |

class | ROOT::Math::RotationZYX |

Rotation class with the (3D) rotation represented by angles describing first a rotation of an angle phi (yaw) about the Z axis, followed by a rotation of an angle theta (pitch) about the Y axis, followed by a third rotation of an angle psi (roll) about the X axis. More... | |

class | ROOT::Math::Impl::Transform3D< T > |

Basic 3D Transformation class describing a rotation and then a translation The internal data are a 3D rotation data (represented as a 3x3 matrix) and a 3D vector data. More... | |

class | ROOT::Math::Impl::Translation3D< T > |

Class describing a 3 dimensional translation. More... | |