Skip to content

Commit 23f2059

Browse files
hageboeckhageboeck
committed
[math][Docs] Further improve GenVector documentation.
- Group helper functions in the GenVector group, so all helpers can be found on one page. - Remove mathcore::LorentzVector references from doxygen. - Add a missing docstring. - Change a [!note] into \note for doxygen
1 parent 5c88ac1 commit 23f2059

File tree

3 files changed

+56
-46
lines changed

3 files changed

+56
-46
lines changed

‎math/genvector/doc/index.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,10 @@ The metric used for any such LorentzVector is (-,-,-,+).
121121
\anchor GenVectorOperations
122122
## Operations
123123

124+
### Utility Functions for all Vectors
125+
126+
Check the functions below, as well as in \ref ROOT::Math::VectorUtil for non-member functions such as DeltaR, Angle, boost.
127+
124128
### Constructors and Assignment
125129

126130
A vector can be constructed from its coordinate representation:
@@ -162,8 +166,7 @@ v3 = v1 - v2;
162166
Note that the multiplication between two vectors using the `operator *` is not supported
163167
because it is ambiguous.
164168

165-
> [!note]
166-
> For the vectors using the 4D coordinate systems based on mass instead of energy (such as **`ROOT::Math::PxPyPzM4D`** or **`ROOT::Math::PtEtaPhiM4D`**) the unary operator `-` (negation) doesn't perform a 4-vector negation. Instead, it negates only the spatial components, which might result in unintuive behaviours (for instance, for PxPyPzM4D coordinate system, \f$\textbf{v}+ \left(-\textbf{v}\right) \neq \textbf{v} -\textbf{v}\f$).
169+
\note For the vectors using the 4D coordinate systems based on mass instead of energy (such as **`ROOT::Math::PxPyPzM4D`** or **`ROOT::Math::PtEtaPhiM4D`**) the unary operator `-` (negation) doesn't perform a 4-vector negation. Instead, it negates only the spatial components, which might result in unintuive behaviours (for instance, for PxPyPzM4D coordinate system, \f$\textbf{v}+ \left(-\textbf{v}\right) \neq \textbf{v} -\textbf{v}\f$).
167170

168171
### Other Methods
169172

‎math/genvector/inc/Math/GenVector/LorentzVector.h‎

Lines changed: 45 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -718,31 +718,32 @@ Pt (or rho) refers to transverse momentum, whereas eta refers to pseudorapidity.
718718

719719
// global methods
720720

721-
/**
722-
Scale of a LorentzVector with a scalar quantity a
723-
\param a scalar quantity of type a
724-
\param v mathcore::LorentzVector based on any coordinate system
725-
\return a new mathcoreLorentzVector q = v * a same type as v
726-
*/
727-
template< class CoordSystem >
728-
inline LorentzVector<CoordSystem> operator *
729-
( const typename LorentzVector<CoordSystem>::Scalar & a,
730-
const LorentzVector<CoordSystem>& v) {
721+
/**
722+
Scale of a LorentzVector with a scalar quantity a
723+
\param a scalar quantity of type a
724+
\param v LorentzVector based on any coordinate system
725+
\return a new mathcoreLorentzVector q = v * a same type as v
726+
*/
727+
template <class CoordSystem>
728+
inline LorentzVector<CoordSystem>
729+
operator*(const typename LorentzVector<CoordSystem>::Scalar &a, const LorentzVector<CoordSystem> &v)
730+
{
731731
LorentzVector<CoordSystem> tmp(v);
732732
tmp *= a;
733733
return tmp;
734734
}
735735

736-
/**
737-
pair (p+ p-) acoplanarity `alpha = 1 - |phi+ - phi-|/pi`.
738-
\param pp p+, mathcore::LorentzVector based on any coordinate system
739-
\param pm p-, mathcore::LorentzVector based on any coordinate system
740-
\return a scalar
741-
\ingroup GenVector
742-
\see http://doi.org/10.1103/PhysRevLett.121.212301
743-
*/
744-
template< class CoordSystem >
745-
typename LorentzVector<CoordSystem>::Scalar Acoplanarity(LorentzVector<CoordSystem> const &pp, LorentzVector<CoordSystem> const &pm)
736+
/**
737+
pair (p+ p-) acoplanarity `alpha = 1 - |phi+ - phi-|/pi`.
738+
\param pp p+, LorentzVector based on any coordinate system
739+
\param pm p-, LorentzVector based on any coordinate system
740+
\return a scalar
741+
\ingroup GenVector
742+
\see http://doi.org/10.1103/PhysRevLett.121.212301
743+
*/
744+
template <class CoordSystem>
745+
typename LorentzVector<CoordSystem>::Scalar
746+
Acoplanarity(LorentzVector<CoordSystem> const &pp, LorentzVector<CoordSystem> const &pm)
746747
{
747748
auto dphi = pp.Phi() - pm.Phi();
748749
// convert dphi angle to the interval (-PI,PI]
@@ -755,21 +756,22 @@ Pt (or rho) refers to transverse momentum, whereas eta refers to pseudorapidity.
755756
dphi += TMath::TwoPi() * n;
756757
}
757758
}
758-
return 1 - std::abs(dphi)/TMath::Pi();
759+
return 1 - std::abs(dphi) / TMath::Pi();
759760
}
760761

761-
/**
762-
pair (p+ p-) vectorial asymmetry `Av = |Pt+ - Pt-|/|Pt+ + Pt-|`.
763-
In an experimental setting, it reflects a convolution of the experimental resolutions
764-
of particle energy and azimuthal angle measurement.
765-
\param pp p+, mathcore::LorentzVector based on any coordinate system
766-
\param pm p-, mathcore::LorentzVector based on any coordinate system
767-
\return a scalar. Returns -1 if both momenta are exactly mirrored.
768-
\ingroup GenVector
769-
\see http://doi.org/10.1103/PhysRevLett.121.212301, https://doi.org/10.1103/PhysRevD.99.093013
770-
*/
771-
template< class CoordSystem >
772-
typename LorentzVector<CoordSystem>::Scalar AsymmetryVectorial(LorentzVector<CoordSystem> const &pp, LorentzVector<CoordSystem> const &pm)
762+
/**
763+
pair (p+ p-) vectorial asymmetry `Av = |Pt+ - Pt-|/|Pt+ + Pt-|`.
764+
In an experimental setting, it reflects a convolution of the experimental resolutions
765+
of particle energy and azimuthal angle measurement.
766+
\param pp p+, LorentzVector based on any coordinate system
767+
\param pm p-, LorentzVector based on any coordinate system
768+
\return a scalar. Returns -1 if both momenta are exactly mirrored.
769+
\ingroup GenVector
770+
\see http://doi.org/10.1103/PhysRevLett.121.212301, https://doi.org/10.1103/PhysRevD.99.093013
771+
*/
772+
template <class CoordSystem>
773+
typename LorentzVector<CoordSystem>::Scalar
774+
AsymmetryVectorial(LorentzVector<CoordSystem> const &pp, LorentzVector<CoordSystem> const &pm)
773775
{
774776
ROOT::Math::XYVector vp(pp.Px(), pp.Py());
775777
ROOT::Math::XYVector vm(pm.Px(), pm.Py());
@@ -779,16 +781,16 @@ Pt (or rho) refers to transverse momentum, whereas eta refers to pseudorapidity.
779781
return (vp - vm).R() / denom;
780782
}
781783

782-
/**
783-
pair (p+ p-) scalar asymmetry `As = ||Pt+| - |Pt-|/||Pt+| + |Pt-||`.
784-
Measures the relative difference in transverse momentum of the pair, e.g. two photons,
785-
and would be ideally zero for two back-to-back photons.
786-
\param pp p+, mathcore::LorentzVector based on any coordinate system
787-
\param pm p-, mathcore::LorentzVector based on any coordinate system
788-
\return a scalar. Returns 0 if both transverse momenta are zero
789-
\ingroup GenVector
790-
\see http://doi.org/10.1103/PhysRevLett.121.212301, https://doi.org/10.1103/PhysRevD.99.093013
791-
*/
784+
/**
785+
pair (p+ p-) scalar asymmetry `As = ||Pt+| - |Pt-|/||Pt+| + |Pt-||`.
786+
Measures the relative difference in transverse momentum of the pair, e.g. two photons,
787+
and would be ideally zero for two back-to-back photons.
788+
\param pp p+, LorentzVector based on any coordinate system
789+
\param pm p-, LorentzVector based on any coordinate system
790+
\return a scalar. Returns 0 if both transverse momenta are zero
791+
\ingroup GenVector
792+
\see http://doi.org/10.1103/PhysRevLett.121.212301, https://doi.org/10.1103/PhysRevD.99.093013
793+
*/
792794
template< class CoordSystem >
793795
typename LorentzVector<CoordSystem>::Scalar AsymmetryScalar(LorentzVector<CoordSystem> const &pp, LorentzVector<CoordSystem> const &pm)
794796
{

‎math/genvector/inc/Math/GenVector/VectorUtil.h‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ namespace ROOT {
4545

4646
namespace VectorUtil {
4747

48+
/// \addtogroup GenVector
49+
/// @{
4850

4951
// methods for 3D vectors
5052

@@ -258,6 +260,8 @@ namespace ROOT {
258260
//return ( v1 + v2).mag();
259261
}
260262

263+
/// @brief Returns the square of what InvariantMass(const Vector1&, const Vector2&) would return.
264+
/// This is mostly useful for speed optimisations, because the expensive sqrt operation is skipped.
261265
template <class Vector1, class Vector2>
262266
inline typename Vector1::Scalar InvariantMass2( const Vector1 & v1, const Vector2 & v2) {
263267
typedef typename Vector1::Scalar Scalar;
@@ -553,7 +557,8 @@ namespace ROOT {
553557
*/
554558
double Phi_mpi_pi(double phi);
555559

556-
560+
// Close of doxygen group:
561+
/// @}
557562

558563
} // end namespace Vector Util
559564

0 commit comments

Comments
 (0)