Logo ROOT  

Reference Guide
Generic Vector for 2, 3 and 4 Dimensions

GenVector, is a new package intended to prepresent vectors and their operations and transformations, such as rotations and Lorentz transformations, in 2, 3 and 4 dimensions. The 2D and 3D space are used to describe the geometry vectors and points, while the 4D space-time is used for physics vectors representing relativistic particles.
These 2D,3D and 4D vectors are different from vectors of the Linear Algebra package which describe generic N-dimensional vectors. Similar functionality is currently provided by the CLHEP Vector and Geometry packages and the ROOT Physics Vector classes (Tvector2, TVector3 and TLorentzVector). It is also re-uses concepts and ideas from the CMS Common Vector package.

In contrast to CLHEP or the ROOT physics libraries, GenVector provides class templates for modelling the vectors. There is a user-controlled freedom on how the vector is internally represented. This is expressed by a choice of coordinate system which is supplied as a template prameter when the vector is constructed. Furthermore each coordinate system is itself a template, so that the user can specify the underlying scalar type.
In more detail, the main characteristics of GenVector are:

  • Optimal runtime performances

    We try to minimize any overhead in the run-time performances. We have deliberatly avoided to have any virtual function and even virtual destructors in the classes and have inlined as much as possible all the functions. For this reason, we have chosen to use template classes to implement the GenVector concepts instead of abstract or base classes and virtual functions.

  • Points and Vector concept

    Mathematically vectors and points are two distinct concepts. They have different transformations, like vectors only rotate while points rotate and translate. 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:

  • 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:

  • Coordinate System Tag

    The 2D and 3D points 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.

  • 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 and Poincarre transformations, which are Translation/Rotation combinations. 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:

Other main characteristics of the GenVector classes are:

  • Minimal Vector classes interface

    We have tried to keep the interface to a minimal level:

    • We try to avoid methods providing the same functionality but with different names ( like getX() and x() ).
    • we minimize the number of setter methods, avoiding methods which can be ambigous and set the Vector classes in an inconsistent state. We provide only methods which set all the coordinates at the same time or set only the coordinates on which the vector is based, for example SetX() for a cartesian vector. We then enforce the use of transformations as rotations or translations (additions) for modifying the vector contents.
    • The majority of the functionality, which is present in the CLHEP package, involving operations on two vectors, is moved in separated helper functions (see ROOT::Math::VectorUtil). This has the advantage that the basic interface will remain more stable with time while additional functions can be added easily.

  • Naming Convention

    As part of ROOT, the GenVector package adheres to the prescribed ROOT naming convention, with some (approved) exceptions, as described here:

    • Every class and function is in the ROOT::Math namespace
    • Member function names starts with upper-case letter, apart some exceptions (see later CLHEP compatibility)
  • Compatibility with CLHEP Vector classes
    • For backward compatibility with CLHEP the Vector classes can be constructed easly from a CLHEP HepVector or HepLorentzVector, by using a template constructor, which requires only that the classes implement the accessors x(), y() and z() (and t() for the 4D).
    • we have decided to provide Vector member function with the same naming convention as CLHEP for the most used functions like x(), y() and z().

  • Connection to Linear Algebra package

    In some use cases, like in track reconstruction, it is needed to use the content of the vector and rotation classes in conjunction with linear algebra operations. We prefer to avoid any direct dependency to any Linear algebra package. However, we provide some hooks to convert to and from Linear Algebra classes.

    • The vector and the transformation classes have methods which allow to get and set their data members (like SetCoordinates and GetCoordinates ) passing either a generic iterator or a pointer to a contigous set of data, like a C array. This allows a easy connection with linear algebra package which allows creation of matrices using C arrays (like the ROOT TMatrix classes) or iterators ( SMatrix classes )
    • Multiplication between Linear Algebra matrix and GenVector Vectors is possible by using the template free functions ROOT::Math::VectorUtil::Mult. This works for any Linear Algebra matrix which implement the operator(i,j) and with first matrix element at i=j=0.

Example of Usage

Packaging

This GenVector package is part of the ROOT Reference Documentation and it can be built as an independent package. A tar file can be downloaded from here.

Additional Documentation

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

References

  1. CLHEP Vector package (User guide and reference doc)
  2. CLHEP Geometry package
  3. ROOT Physics Vector classes
  4. CMS Vector package

*/