Logo ROOT  
Reference Guide
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> >.

Points and Vector concept

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::LorentzVector models 4D space-time vectors. There is no class for a 4D point.

Coordinate Systems

Generic Coordinate System

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:

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.

Coordinate System Tag

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.

Concrete Vector typedefs

To avoid exposing templated parameters to the users, typedefs are defined for all types of vectors based an doubles and floats. 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.

Point2D

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

Vector2D

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

Point3D

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

Vector3D

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

LorentzVector

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

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

Operations

Constructors and Assignment

A vector can be constructed from its coordinate representation:

ROOT::Math::PtEtaPhiMVector v1(10. /*pt*/, 0.1 /*eta*/, 0.24 /*phi*/, 5 /*M*/);
Class describing a generic LorentzVector in the 4D space-time, using the specified coordinate system ...
Definition: LorentzVector.h:59

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:

XYZVector v1(1,2,3);
CLHEP::Hep3Vector q(1,2,3);
float * q
Definition: THbookFile.cxx:89
DisplacementVector3D< Cartesian3D< double >, DefaultCoordinateSystemTag > XYZVector
3D Vector based on the cartesian coordinates x,y,z in double precision
Definition: Vector3Dfwd.h:44
DisplacementVector3D< CylindricalEta3D< double >, DefaultCoordinateSystemTag > RhoEtaPhiVector
3D Vector based on the eta based cylindrical coordinates rho, eta, phi in double precision.
Definition: Vector3Dfwd.h:62

Arithmetic Operations

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

v1 += v2;
v1 -= v2;
v1 = - v2;
v1 *= a;
v1 /= a;
v2 = a * v1;
v2 = v1 / a;
v2 = v1 * a;
v3 = v1 + v2;
v3 = v1 - v2;
auto * a
Definition: textangle.C:12

Note that the multiplication between two vectors using the operator * is not supported because it is ambiguous.

Other Methods

The vector classes support methods for:

Transformations

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:

3D Rotations

3D Transformation

Lorentz Rotation

Compatibility with CLHEP Vector classes

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().

Additional Documentation

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...