Skip to content
Snippets Groups Projects
Commit 370a73b3 authored by Lorenzo Moneta's avatar Lorenzo Moneta
Browse files

- update doc for mathcore, mathmore and genvector 

git-svn-id: http://root.cern.ch/svn/root/trunk@24496 27541ba8-7e3a-0410-8455-c3a389f83636
parent a8e2af31
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 246 additions and 19 deletions
math/doc/index.html
+ 1
− 1
View file @ 370a73b3
......@@ -63,5 +63,5 @@ Further information is available at the following links:
<hr>
<address></address>
<!-- hhmts start --> Last modified: Mon Jun 23 10:10:16 CEST 2008 <!-- hhmts end -->
<!-- hhmts start --> Last modified: Mon Jun 23 22:52:35 CEST 2008 <!-- hhmts end -->
</body> </html>
math/mathcore/doc/Point3D.html → math/genvector/Point3D.html
+ 0
− 0
View file @ 370a73b3
File moved
math/mathcore/doc/Vector3D.html → math/genvector/doc/Vector3D.html
+ 0
− 0
View file @ 370a73b3
File moved
math/genvector/doc/index.html 0 → 100644
+ 190
− 0
View file @ 370a73b3
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>GenVector Library</title>
</head>
<body>
<h2>GenVector Library</h2>
<b>GenVector</b>, 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.
<br>
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 <A HREF="http://proj-clhep.web.cern.ch/proj-clhep/manual/UserGuide/VectorDefs/index.html">Vector</A> and
<A HREF="http://www.hep.phy.cam.ac.uk/lhcb/doc/CLHEP/1.9.1.2/html/namespaceHepGeom.html">Geometry</A> packages and the ROOT <A HREF="http://root.cern.ch/root/html/PHYSICS_Index.html">Physics Vector</A> classes (Tvector2, TVector3 and TLorentzVector). It is also re-uses concepts and ideas from the CMS <A HREF="http://lcgapp.cern.ch/doxygen/SEAL/snapshot/html/dir_000007.html">Common Vector package</A>.
<p>
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.
<br>
In more detail, the main characteristics of GenVector are:
<ul>
<li><h4>Optimal runtime performances</h4>
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.
<li><h4>Points and Vector concept</h4>
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:
<ul>
<li>ROOT::Math::DisplacementVector3D and ROOT::Math::DisplacementVector2D template classes describing 3 and 2 component direction and magnitude vectors, not rooted at any particular point;</li>
<li>ROOT::Math::PositionVector3D template and ROOT::Math::PositionVector3D class modeling the points in 3 and 2 dimensions</li>.
</ul>
For the 4D space-time vectors, we use the same class to model them, ROOT::Math::LorentzVector, since we have recognized a limited needs for modeling the functionality of a 4D point.
</li>
<li><h4>Generic Coordinate System </h4>
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:
<ul>
<li> <strong>2D coordinate system</strong> classes:
<ul>
<li>ROOT::Math::Cartesian2D, based on <em>(x,y)</em>;</li>
<li>ROOT::Math::Polar2D, based on <em>(r, phi)</em>; </li>
</ul></li>
<li> <strong>3D coordinate system</strong> classes:
<ul>
<li>ROOT::Math::Cartesian3D, based on <em>(x,y,z)</em>;</li>
<li>ROOT::Math::Polar3D, based on <em>(r, theta, phi)</em>; </li>
<li>ROOT::Math::Cylindrical3D, based on <em>(rho, z, phi)</em></li>
<li>ROOT::Math::CylindricalEta3D, based on <em>(rho, eta, phi)</em>, where eta is the pseudo-rapidity;</li>
</ul></li>
<li> <strong>4D coordinate system</strong> classes:
<ul>
<li>ROOT::Math::PxPyPzE4D, based on based on <em>(px,py,pz,E)</em>;</li>
<li>ROOT::Math::PxPyPzM4D, based on based on <em>(px,py,pz,M)</em>;</li>
<li>ROOT::Math::PtEtaPhiE4D, based on based on <em>(pt,eta,phi,E)</em>;</li>
<li>ROOT::Math::PtEtaPhiM4D, based on based on <em>(pt,eta,phi,M)</em>;</li>
</ul>
</li>
</ul>
The angle <em>theta</em> is defined between [0,PI] and <em>phi</em> between [-PI,PI]. The angles are expressed in radians.
<br>
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 <em>(=)</em> operator.
<br>
For maximum flexibility and minimize in some use case memory allocation, the coordinate system classes are templated on the scalar type. To avoid exposing templated parameter to the users, typedefs are defined for all types of vectors based an double's.
<br>
See the
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/VectorPoint2D.html">2D Vector and Point</a>,
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/Vector3DPage.html">3D Vector</a>,
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/Point3DPage.html">3D Point</a>,
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/LorentzVector.html">LorentzVector</a> classes
classes for all the possible types of vector classes which can be constructed by the user with the available coordinate system types.
</li>
<li><h4>Coordinate System Tag</h4>
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 funcitonality.
<li><h3>Transformations</h3>
<p>
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 <em>operator()</em> or the <em>operator *</em> and the transformations can also be combined via the <em>operator *</em>. In more detail the transformations available are:
<ul>
<li><h4>3D Rotations classes</h4>
<ul>
<li>Rotation described by a 3x3 matrix (ROOT::Math::Rotation3D)
<li>Rotation described by Euler angles, Goldstein representation, (ROOT::Math::EulerAngles)
<li>Rotation described by 3-2-1 Euler angles (ROOT::Math::RotationZYX)
<li>Rotation described by a direction axis and an angle (ROOT::Math::AxisAngle)
<li>Rotation described by a quaternion (ROOT::Math::Quaternion)
<li>Optimized rotation around the x (ROOT::Math::RotationX), y (ROOT::Math::RotationY) and z (ROOT::Math::RotationZ) axis and described by just one angle.
</ul>
</li>
<li><h4>3D Transformation</h4>
We describe the transformations defined as a composition between a rotation and a translation using the class ROOT::Math::Transform3D.
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 <A href="http://www.hep.phy.cam.ac.uk/lhcb/doc/CLHEP/1.9.1.2/html/classHepGeom_1_1Transform3D.html">Transform3D</A>).<br>
A class, ROOT::Math::Translation3D. describe transformations consisting of only a translation. Translation can be applied only on Points, applying them on Vector objects has no effect. The Translation3D class can be combined with both ROOT::Math::Rotation3D and ROOT::Math::Transform3D using the <em>operator *</em> to obtain a new transformation as an instance of a Transform3D class.
</li>
<li><h4>Lorentz Rotation</h4>
<ul>
<li>Generic Lorentz Rotation described by a 4x4 matrix containing a 3D rotation part and a boost part (class ROOT::Math::LorentzRotation)</li>
<li>A pure boost in an arbitrary direction and described by a 4x4 symmetric matrix or 10 numbers (class ROOT::Math::Boost)</li>
<li>Boost along the x (ROOT::Math::BoostX), y (ROOT::Math::BoostY) and z (ROOT::Math::BoostZ) axis. </li>
</ul>
</li>
</ul>
</li>
</ul>
<p>
Other main characteristics of the GenVector classes are:
<ul>
<li><h4>Minimal Vector classes interface</h4>
We have tried to keep the interface to a minimal level:
<ul>
<li>We try to avoid methods providing the same functionality but with different names ( like getX() and x() ).
<li>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.
<li>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.
</ul>
</li>
<li><h4>Naming Convention</h4>
As part of ROOT, the GenVector package adheres to the prescribed ROOT naming convention, with some (approved) exceptions, as described here:
<ul>
<li>Every class and function is in the <em>ROOT::Math</em> namespace</li>
<li>Member function names starts with upper-case letter, apart some exceptions (see later CLHEP compatibility)
</ul>
</li>
<li><h4>Compatibility with CLHEP Vector classes</h4>
<ul>
<li>
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).
<li>we have decided to provide Vector member function with the same naming convention as CLHEP for the most used functions like <em>x()</em>, <em>y()</em> and <em>z()</em>.</li>
</ul>
</li>
<li><h3>Connection to Linear Algebra package</h3>
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.
<ul>
<li>
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 )
</li>
<li>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 <em>operator(i,j)</em> and with first matrix element at <em>i=j=0</em>.
</li>
</ul>
</li>
</ul>
<p>
<p>
<h2>Example of Usage</h2>
<ul>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/VectorPoint2D.html">2D Vector and Point Classes</a>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/Vector3DPage.html">3D Vector Classes</a>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/Point3DPage.html">3D Point Classes</a>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/LorentzVector.html">LorentzVector Classes</a>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/Transformation.html">Transformation Classes</a>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/externalUsage.html">Examples with external package</a>
</ul>
<p>
<p>
<h2>Additional Documentation</h2>
A more detailed description of all the GenVector classes is available in this
<A HREF="http://seal.cern.ch/documents/mathlib/GenVector.pdf">document</A>.
<h2>References</h2>
<ol>
<li>CLHEP Vector package (<A HREF="http://proj-clhep.web.cern.ch/proj-clhep/manual/UserGuide/VectorDefs/index.html">User guide</A> and <A HREF="http://www.hep.phy.cam.ac.uk/lhcb/doc/CLHEP/1.9.1.2/html/dir_000027.html">reference doc</A>)
<li><A HREF="http://www.hep.phy.cam.ac.uk/lhcb/doc/CLHEP/1.9.1.2/html/namespaceH">CLHEP Geometry package</A>
<li><A HREF="http://root.cern.ch/root/html/PHYSICS_Index.html">ROOT Physics Vector classes</A>
<li><A HREF="http://lcgapp.cern.ch/doxygen/SEAL/snapshot/html/dir_000007.html">CMS Vector package</A>
</ol>
<p>
<p>
<hr>
<p>
@authors The ROOT Math Library Team
<p>
@b Contact: <Lorenzo.Moneta@cern.ch>
*/
math/mathcore/doc/vector.html → math/genvector/vector.html
+ 0
− 0
View file @ 370a73b3
File moved
math/mathcore/doc/MathCore.html
+ 17
− 2
View file @ 370a73b3
......@@ -8,13 +8,28 @@
@b MathCore provides a collection of functions and C++ classes for HEP numerical computing. This library provides only the basic mathematical functions and algorithms and not all the functionality required by the HEP community. More advanced mathematical functionalities is provided by the \ref MathMore.
The current set includes classes and functions for:
<ul>
<li>\ref Vector "GenVector": physics and geometry vectors for 2,3 and 4 dimensions with their transformations (rotations and boost).
<li>\ref SpecFunc "Basic special functions" used in HEP like the gamma, beta and error function;
<li> \ref StatFunc : mathematical functions used in statistics, such as the probability density functions and the cumulative distributions functions (lower and upper integral of the pdf's) for continuous and discrete distributions.;
<li>\ref CppFunctions : Interfaces for generic functions in one and multi dimensions, including helper class to wrap free (static) and non-static member functions</li>
<li>\ref CppFunctions :
<ul>
<li>\ref GenFunc, including helper class to wrap free (static) and non-static member functions
<li>\ref ParamFunc
</ul>
</li>
<li>Numerical algorithms: user classes with (in some cases) basic implementations for:
<ul>
<li>\ref Integration
<li>\ref Deriv
<li>\ref RootFinders
<li>\ref Min1D and \ref MultiMin
</ul>
<li>\ref Fit :classes for fitting and parameter estimation from a given data set.
</ul>
Note that in this latest release the \ref Vector "GenVector" (physics and geometry vectors for 2,3 and 4 dimensions with their transformations) is not anymore part of MathCore, but is built as a separate library.
MathCore and its CINT dictionary is normally built by default in %ROOT. Alternatively MathCore can be built as a stand-alone library, downloading the current version from <A HREF="../MathCore.tar.gz">here</A>.
Note, that the stand-alone library, in contrast to the one distributed by %ROOT, <strong>does not</strong> contain the dictionary information and therefore cannot be used interactivly.
......
math/mathcore/doc/index.txt → math/mathcore/doc/index.html
+ 27
− 7
View file @ 370a73b3
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>MathCore Library</title>
</head>
BEGIN_HTML
<body>
<h2>MathCore library</h2>
<b>MathCore</b> provides a collection of functions, C++ classes for numerical calcultions.
It provides the basic and minimal functionality, while more advanced mathematical functionalities is provided by the <a class="el" href="http://www.cern.ch/mathlibs/sw/html/MathMore.html">MathMore</a> library.
<b>MathCore</b> provides a collection of functions, C++ classes for numerical calculations.
It provides the basic and minimal functionality, while more advanced mathematical functionality is provided by the <a class="el" href="http://www.cern.ch/mathlibs/sw/html/MathMore.html">MathMore</a> library.
The current set includes classes and functions for: <ul>
<li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/Vector.html">GenVector</a>: physics and geometry vectors for 2,3 and 4 dimensions with their transformations (rotations and boost). </li>
<li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__SpecFunc.html">Basic special functions</a> used in HEP like the gamma, beta and error function. </li>
<li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__StatFunc.html">Statistical functions</a> : mathematical functions used in statistics, such as the probability density functions, the cumulative distributions functions (lower and upper integral of the pdf's) and their inverses (quantile functions) for continuous and discrete distributions. </li>
<li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__CppFunctions.html">Function Classes and Interfaces</a> : Interfaces for generic functions in one and multi dimensions, including helper class to wrap free (static) and non-static member functions.<p>
</li>
<li>Numerical algorithms: user classes with (in some cases) basic implementations for:
<ul>
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Integration.html">Numerical Integration</a>;
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Deriv.html">Numerical Differentiation</a>;
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__RootFinders.html">Root-Finding methods</a>;
<li><a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Min1D.html">One-dimensional</a> and <a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__MultiMin.html">multi-dimensional Minimization</a>. </li>
</ul>
<li>Classes for <a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Fit.html">fitting and parameter estimation</a> from a given data set.
</ul>
<p>
Classes and functions are provided in the namespace <em>ROOT::Math</em> or <em>ROOT::Fit</em> in the case of the
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Fit.html">fitting classes</a>.
<p>
Classes and functions are provided in the namespace <em>ROOT::Math</em>.
From the release 5.20, the <a class="el" href="http://www.cern.ch/mathlibs/sw/html/Vector.html">GenVector</a>
(physics and geometry vector) package
is not anymore part of MathCore, but it belongs to a separate library (<em>libGenVector</em>).
<p>
See also:
<ul>
......@@ -31,4 +48,7 @@ See also:
to look at <a href="http://www.cern.ch/mathlibs/sw/html/MathCore.html">these online doc</a></strong>. The class documentation shown from the class links below is not complete, it is missing ROOT::Math functions, template methods and in same case the class descriptions are not appropriate.
<hr>
<p>
END_HTML
<!-- hhmts start --> Last modified: Mon Jun 23 23:52:52 CEST 2008 <!-- hhmts end -->
</body> </html>
math/mathmore/doc/MathMore.html
+ 1
− 6
View file @ 370a73b3
......@@ -21,12 +21,7 @@ The current set includes classes and functions for:
<li>\ref Interpolation
<li>\ref FuncApprox, based on Chebyshev polynomials
<li>\ref Random
<li>\ref CppFunctions :
<ul>
<li>Interface for generic and parameteric functions in one and multi dimensions
<li>Concrete function classes like ROOT::Math::Polynomial for polynomial evaluation and root solvers
<li>Wrapper class inheriting from the ROOT::Math function interfaces for the %ROOT TF1 objects in the case of one (ROOT::Math::WrappedTF1) and multi dimensions (ROOT::Math::WrappedMultiTF1).
</ul>
</ul>
<p>
The mathematical functions are implemented as a set of free functions in the namespace \em ROOT::Math. The naming used for the special functions is the same proposed for the C++ standard (see C++ standard extension <A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1687.pdf"> proposal document</A>).
......
math/mathmore/doc/index.txt → math/mathmore/doc/index.html
+ 10
− 3
View file @ 370a73b3
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>MathMore Library</title>
</head>
<body>
BEGIN_HTML
<h2>MathMore library</a></h2>
<b>MathMore</b> provides an advanced collection of functions and C++ classes for HEP numerical computing.<p>
......@@ -20,7 +25,7 @@ Numerical algorithms: <ul>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__RootFinders.html">Root-Finding algorithms</a> </li>
<li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__Min1D.html">One-dimensional</a> and
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__MultiMin.html">Multidimensional Minimization</a> </li>
<a class="el" href="http://www.cern.ch/mathlibs/sw/html/group__MultiMin.html">multi-dimensional Minimization</a> </li>
</ul>
</li>
<li>
......@@ -57,4 +62,6 @@ to look at <a href="http://www.cern.ch/mathlibs/sw/html/MathMore.html">these on
<hr>
<p>
END_HTML
<!-- hhmts start --> Last modified: Tue Jun 24 00:06:47 CEST 2008 <!-- hhmts end -->
</body> </html>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment