// top doc page for Doxygen /** \mainpage MathCore library @b MathCore provides a collection of functions and C++ classes for HEP numerical computing. This library provides only the basic mathem atical functions and algorithms and not all the functionality required by the HEP community. The current set includes classes and functions for:
@authors The %ROOT Math Library Team
@b Contact:
We adopted a compromised between a simple interface and user convenience. We could have gone to the extreme of having a class containing only the scalar data, with member functions only returning the data themself and move all the other functionality in separate functions. This approach, although it has some appeal, it requires a complete change from the way these classes are used. We have therefore prefer to keep a more conservative approach, mantaining the most used functions inside the vector classes, and moving other fuctionality outside as global functions in a namespace.
In addition, our choice of having all the coordinate accessors inside the vector classes, provides us the possibility of specializing the vector classes depending on the coordinate system.
We describe also geometrical 3D transfromations such as rotations and translations and Lorentz transformations which are composed by a boost and a 3D rotation.
All the Transfromations classes are template on the scalar values. To easy the use of these classes, we define also for all the available transformation types, typedef's to classes based on double and single precision
(see the examples on \ref TransformPage)
For the time scale, we expect to have a first version available in the %ROOT CVS directory in the next days and have a first released version at the end of June.
*/
Generic Vectors for 2, 3 and 4 dimensions
This is a proposal for a new vector package, @b GenVector,
describing vectors and their operations in 2, 3, and 4 dimensions.
The 4 dimensional space is used for describing relativistic particles.
These vectors are different from generic vectors of the Linear Algebra package which describe N-dimensional vectors. The functionality of this package 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.
The main characteristics of this package are :
Minimal interface
We define a minimal interface trying to avoid duplications in contrast to what is currently provided by the Vector package of CLHEP.
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.
Generic scalar type
For maximum flexibility and minimize in some use case memory allocation, the vector classes are templated on the scalar type. To avoid exposing templated parameter to the users, typedefs are defined for
vectors based on float and double's.
Coordinate Type
The Vector (and point classes) are based on a generic type of coordinates. Various classes exist to describe the different coordinates, such as Cartesian (for 3, and 4 dimensions), Polar for dimension 3 and Cylindrical for 3 and 4 dimensions.
Users can define the Vectors according to the coordinate type which is most efficient for their use. For performances reason, we prefer to implement this concept using template classes instead of inheritance.
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. In contrast to the CLHEP Vector package, but as in the CLHEP Geometry package and in the CMS Vector package,
we distinguish for the 3 dimensions, between Points and Vectors. They are defined as two distinct types; Points are described by the
ROOT::Math::PositionVector3D class while Vectors by the
ROOT::Math::DisplacementVector3D class.
Therefore only some transformations are allowed, for example it is not allowed to add two points, and translations have no effect on Vectors. Comparing to the CMS Vector package, we don't want to distinguish between Vectors according to their reference frame, for example between local frame vector and global frame vectors.
We have recognized a limited needs for this functionality and a too high cost for including this additional complexity.
Transformations
3D Rotations
As for Vectors, Rotations can be expressed in various ways according to their base. For example a rotation can be described by a 3x3 orthogonal matrix or by 3 Euler angles or by a direction axis and an angle. We implement this concept by defining a generic class for describing all rotation (ROOT::Math::Basic3DRotation) which is template on the rotation representation. The possible types of rotation representations are:
3D Transformation
A 3D transformation is composed of a rotation and a translation. We describe transformations using a class which is template on the 3D rotation types and the vector type.
It is important to note that transformations act differently on Vectors and Points. The Vectors only rotate, therefore when applying a transfomation (rotation + translation) on a Vector, only the rotation operates while the translation has no effect. The interface for Transformations is similar to the one used in the CLHEP Geometry package
(class Transform3D).
Lorentz Rotation
A generic Lorentz Rotation can be expressed as a 4x4 matrix containing a 3D rotation part and a boost part. A pure boost can be instead described by a 4x4 symmetric matrix. We describe therefore LorentzVector with a generic class (ROOT::Math::BasicLorentzRotation) which is templated on these types:
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 Vectors types based on Cartesian coordinates and the transformations which are based on matrices have their private data stored using C arrays. They can therefore be constructed passing a C array pointer and they can also return a
pointer to their data structure. This allows a easy connection with any linear algebra package (like the %ROOT TMatrix classes) which allows creation of matrices using C arrays. Furthermore, the %ROOT TMatrix classes allow to create a matrix without owning the data, using an external data storage. This gives the option to use, from the Vector classes, linear algebra functionality without copying the data.
Example of Usage
Packaging
This classes will be part of the basic Math library, libMathCore.
All of the classes and functions will be in the namespace,
ROOT::Math.
It is still not decided, if in the CVS repository of ROOT, they will be part of a separate Vector directory, or if they will be in the same directory as the other mathcore classes.
Current Status and Time Scale
A prototype is already available in the SEAL CVS directory. A tar file of the latest frozen version is downloadable from
here.
The current version provides Vector and transfromation for 3 and 4 dimensions. The interfaces are probably not complete,
some important methods are probably missing and, what is there, it is not currently all implemented and tested.
The source code therefore is not yet really usable, it can be used only for browsing and for trying simple things.
Backward compatibility with %ROOT and CLHEP Vector classes
When these classes will be available in ROOT, we will create adapter (proxy) classes replacing the current %ROOT Vector classes (TVector3, TLorentzVector, TRotation and TLorentzRotation). For example a new TLorentzVector, will still inherit from TObject and contain an instance to the new ROOT::Math::LorentzVector class. All the TLorentzVector member functions will be implemented forwarding the calls to the ROOT::Math::LorentzVector. Since all these methods will be inlined, the performance overhead expected for TLorentzVector will be negligible.
For mantaining some compatibility with CLHEP and easy the migration, we have decided to keep the same naming convention as CLHEP for the interfaces. Functions which have the same functionality as in CLHEP, will have, whenever possible the same name.
For example we will have a ROOT::Math::XYZVector::x(), y() and z() as in CLHEP.
Error Reporting
To report errors conditions caused by infinities and NaN, We use exceptions through a simple class, ROOT::Math::GenVector_exception, inheriting from std::runtime_error.
References