MT2 / Stransverse Mass / Oxbridge Kinetics Library

NOTE: If all you want to do is compute MT2, then DO NOT DOWNLOAD AND INSTALL THIS LIBRARY! There are much simpler alternatives -- see Alternatives to this library below!

The Oxbridge Kinetics library is a small C++ library for calculating kinematic variables including:

Contents

Alternatives to this library

If all you need is a quick, reliable, and simple method for calculating MT2 (and no other kinematic variables!) then we recommend you consider doing one of the following two things:

Both of the above options are based on the same common underlying C++ implementation which is contained entirely within the single header file lester_mt2_bisect.h which is distributed as an Ancillary file attached to arXiv:1411.4312, the paper documenting the implementation. No installation is required as the algorithm is contained within a single header file and there are no external dependencies. At time of writing (Spring 2015) this implemetation is the fastest algorithm known to compute MT2 reliably to machine precision, and it can do both symmetric MT2 (where the two invisible particls are considered to have identical mass) and asymmetric MT2 (where the two invisible particles are considered to have different masses).

There is also a third party python wrap of the core C++ implementation. Though it is not maintained by me, it may be useful for users who wish to use MT2 python and cannot get the PiPI version to work. (It's build is easier to tweak being outside of pip.) A fork of the wrapper, for backup purposes, exists here.

You should only need to download and install the Oxbridge Kinetics library if there is something harder or more specialised that you wish to do, for example if you wish to compare different specialist flavours of MT2 or other kinematic variables.

What is MT2 ? (also called The Stransverse Mass)

The "Cambridge MT2 Variable", sometimes also called the "Stransverse Mass", is an event variable used to bound the masses of an unseen pair of particles which are presumed to have decayed semi-invisibly into particles which were seen. MT2 is therefore a function of the momenta of two visible particles and the missing transverse momentum in an event. The main references for the definition of MT2 are:

Other papers with interesting contributions to understanding MT2 include:

Here is a full list of papers which use MT2.

Purpose of the library

The purposes of this library are:

  1. to make sure that the algorithms used to calculate LHC kinematic variables are reliable and accurate.
    • Simple implementations of MT2 can sometimes demonstrate poor performance in certain input regimes - even if they appear to work well on a few test cases. As this is not often apparent at first sight, it is hoped that central MT algorithms might be better maintained and/or have their bugs catalogued more effectively.
  2. to provide a central repository for more "specialised" forms of MT2 beyond the simple "332 type" (see Nomenclature section below) described in Phys.Lett.B463:99-103,1999 .
    • For example, other forms (so called "4441 type" -- see Nomenclature section below) take additional constraints from knowledge of the maximum centre-of-mass energy of the collision, and use information coming from the Z-momentum of the visible particles in the event.

Download and install in three easy steps

  1. Our library can be built without any external dependencies by specifying -DUseROOT=OFF as an argument to cmake in step 3 below. However if you want to get the full features of our library, you should first make sure you have a working ROOT installation in which minuit2 support has been enabled.
    • ATTENTION! The ROOT authors now seem to be releasing versions of ROOT in which the minuit2 libraries are not built by default. See notes here if you are unsure how to test/fix whether your ROOT has minuit2 support.
  2. Download the most recent sourcecode tar file, and untar it. (You can browse the code and other releases here.)
  3. (also you could try to browse in the experimental git repository)
  4. Follow the instructions in the README and INSTALL.txt files contained therein. For most users this will consist of
    mkdir build
    cd build
    cmake .. 
    make 
    
    If the user doesn't want to include any ROOT dependencies, they must add -DUseROOT=OFF to the cmake command:
    cmake -DUseROOT=OFF .. 
    make 
    
An optional -D DEBUG=ON may also be passed to cmake to turn on some helpful debug messages. After doing the above, if you wish, you may check that the installation worked by running a few simple example programs, e.g. by typing:
./examples/helloWorld_Mt2_Without_Minuit2_Example.exe
(inside the build directory) and/or
./examples/example_helloWorld_Mt2_Example.exe
if you complied with minuit2 support enabled. If you don't want to compile with cmake, you may use the ./configure command, see instructions here.

Using the library -- Examples

Hello World for MT2

We recommend that most users wishing to calculate MT2 inspecting the simplest helloWorld_Mt2_Example.cpp example described below, and adapt it to their purposes.

What the hello world example does

This example calculates MT2 three times, with the same inputs, and prints out what it is doing.

Building the hello world example manually

Unless you specified the "-DUseROOT=OFF" option to cmake in Step 3 above (in which case you should instead look here!) the "helloWorld" example should have compiled automatically.

However, you might might want to compile it manually. Assuming you have installed the library, and have a copy of helloWorld_Mt2_Example.cpp in the current directory, the simplest way to build it manually would be something like the following:

g++ -o helloWorld_Mt2_Example.exe \
        -I $PREFIX/include/ \
        -I /path/to/ExampleEvent.h \
        -L $PREFIX/lib/ \
        -loxbridgekinetics \
        `root-config --cflags` \
        -Xlinker -rpath lib/ \
        helloWorld_Mt2_Example.cpp
where $PREFIX should be replaced by the name of the directory into which the library was installed. (You supplied $PREFIX as the -DCMAKE_INSTALL_PREFIX=$PREFIX argument when you configured the library. The default is equivalent to cmake -DCMAKE_INSTALL_PREFIX=/usr/local)

Running a hello world example that tests minuit:
The automatically built executable will be found in the examples sub-directory from which you typed make when you built the MT2 library. The executable will be called helloWorld_Mt2_Example.exe.

If you run it by typing

./helloWorld_Mt2_Example.exe
you should see the following output:

[lxplus214] > ./helloWorld_Mt2_Example.exe
----------------------------------------------------------------------
 M_T2 : a variable for measuring masses when missing energy is expected.
 If you use MT2 or this library, please cite:
        (o) C.G.Lester, D.J.Summers 
            Phys.Lett.B.463:99-103 (1999) hep-ph/9906349
        (o) A.J.Barr, C.G.Lester, P.Stephens 
            J.Phys.G 29:2343-2363  (2003) hep-ph/0304226
 If you use MTGEN please also cite:
        (o) C.G.Lester, A.J.Barr (2007) arXiv:0708.1028 (hep-ph)
            JHEP 12(2007)102
 If you use either of the Elliptic Bisection MT2 calculators, please also cite:
        (o) H.Chen, Z.Han,  arXiv:0810.5178
----------------------------------------------------------------------
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_mass = 100
ANSWER: mt2 = 412.628 for Basic_Mt2_332 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_mass = 100
ANSWER: mt2 = 412.628 for Basic_Mt2_332 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_mass = 100
ANSWER: mt2 = 412.628 for Basic_Mt2_332 algorithm

A different simple hello world example, that doesn't need minuit2:

If you compiled the library with the -DUseROOT=OFF option supplied to cmake like this:
cmake .. -DUseROOT=OFF
, then the first "helloWorld" example won't have been built. However, you will still be able to use an alternative example that is indepentent of minuit2 and which is always built. It is complied from examples/helloWorld_Mt2_Without_Minuit2_Example.cpp and generates the following output when it is run:
[lester@LesterHP mt2ExampleWithOptionalRoot]$ ./helloWorld_Mt2_Without_Minuit2_Example.exe 
----------------------------------------------------------------------
 M_T2 : a variable for measuring masses when missing energy is expected.
 If you use MT2 or this library, please cite:
 	(o) C.G.Lester, D.J.Summers
 	    Phys.Lett.B.463:99-103 (1999) hep-ph/9906349
 	(o) A.J.Barr, C.G.Lester, P.Stephens
 	    J.Phys.G 29:2343-2363  (2003) hep-ph/0304226
 If you use MTGEN please also cite:
 	(o) C.G.Lester, A.J.Barr (2007) arXiv:0708.1028 (hep-ph)
 	    JHEP 12(2007)102
 If you use the ChengHanBisection MT2 calculator, please also cite:
 	(o) H.Cheng, Z.Han,  arXiv:0810.5178
 If you use the LesterNachmanBisection MT2 calculator, please also cite:
 	(o) C.G.Lester, B.Nachman (2014) arXiv:1411.4312
----------------------------------------------------------------------
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_massA = 100
   invis_massA = 100
ANSWER: mt2 = 412.628 for LesterNachmanBisect_Mt2_3322 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_massA = 100
   invis_massA = 100
ANSWER: mt2 = 412.628 for LesterNachmanBisect_Mt2_3322 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et =   422.493, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et =   395.727, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_massA = 100
   invis_massA = 100
ANSWER: mt2 = 412.628 for LesterNachmanBisect_Mt2_3322 algorithm
Building the second hello world example manually

Regardless of whether or not you specified the "-DUseROOT=OFF" option to cmake in Step 3 above, this second "helloWorld" example should always have compiled automatically.

However, you might might want to compile it manually. Assuming you have installed the library, and have a copy of helloWorld_Mt2_Without_Minuit2_Example.cpp in the current directory, the simplest way to build it manually would be something like the following:

g++ -o helloWorld_Mt2_Without_Minuit2_Example.exe \
    -I $PREFIX/include/ \
    -I path/to/ExampleEvent.h \
    -L $PREFIX/lib/ \
    -loxbridgekinetics \
    -Xlinker -rpath lib/ \
    helloWorld_Mt2_Without_Minuit2_Example.cpp
where $PREFIX should be replaced by the name of the directory into which the library was installed. (You supplied $PREFIX as the -DCMAKE_INSTALL_PREFIX=$PREFIX argument when you configured the library. The default is equivalent to cmake -DCMAKE_INSTALL_PREFIX=/usr/local). Note that the path/to/ExampleEvent.h need only be the path to the directory containing the ExampleEvent.h header file.

Other more complicated examples:

The sourcecode for many more complicated examples can be found in the examples subdirectory of the distributed tar file. Browse their sourcecode here. The full list of examples binaries built at time of writing is as follows:

bash-3.2$ ls example_*

Example of interactive use with ROOT

To use the library semi-interactively from within ROOT, follow the instructions at the top of the example ROOT macro demo_1_for_ROOT_usage.C which shows how MT2 values can be calculated from within ROOT. This example requires the mt2 library to have first been built outside ROOT.

The algorithms / kinematic variables provided (list incomplete)

AlgorithmNotes
A well debugged but easy to understand MT2 algorithm. Not the fastest or most accurate.See the Basic_Mt2_332 Algorithm entry below.
Recommended "external" MT2 algorithm for non-asymmetric use-cases.See the LesterNachmanBisect_Mt2_332 Algorithm entry below. Does not need minuit2, is the most accurate and fastest.
Recommended "external" Asymmetric MT2 algorithm.See the LesterNachmanBisect_Mt2_3322 Algorithm entry below. Does not need minuit2, is the most accurate and fastest, and can cope with dissimilar mass invisible particles.
Advanced_Mt2_332The "Advanced" MT2 332 calculator tries to improve on the "Basic" Mt2 332 algorithm, by avoiding the use of an iterative solution for so-called "unbalanced" cases. In practice, this saves very little time, and may even introduce more potential for instabilities (divide by small) for certain input cases. In short, we recommend users stick with "Basic" MT2 332 algorithm.
AlphaT_MultijetAttempts to figure out what the definition of alphaT really is.Does not need minuit2
Analytic_Mt2_2220There is a closed form (non-iterative) expression for calculating MT2 valid in the case that (1) both visible particles are massless, and (2) the assumed mass of the invisible particles is zero. The "Analytic_Mt2_2220_Calculator" implements that expression.Does not need minuit2
Analytic_Mt2_330There is a closed form (non-iterative) expression for calculating MT2 valid in the case that the missing transverse momentum is exactly balanced by the (combined) visible transverse momentum of the two sets of "important" visible particles. Put another way, this is the case where the "upstream transverse momentum" or "other sources of recoil" are zero. The Analytic_Mt2_330 calculator implements that special case. Note that it does not take PTMISS as an input, since it is deducable (in this special case) from minus the sum of the visible particle momenta.Does not need minuit2
Basic_MCT2_332Calculates Cho and Kim's MCT2 (see arXiv:0912.2354 and arXiv:1006.2568)
Basic_MPairProdMPairProd is a bit like MT2, except that it assumes that neither parent particle had any invisible daughter particles. As a consequence, it does not need to use PTMISS and does not discard z-momenta. It places a bound on the mass of the pair of identical parents that could have lead to the observed final state.Does not need minuit2
Basic_Mt2_332This is the recommended (i.e. most well tested) algorithmm for calculating MT2. You can see an example of its use in the "helloWorld" example described above. It is a very simple implementation that harks back to the original definition of MT2. It numerically minimises the larger of two transverse masses over a two dimensional space of momentum splittings.
Basic_Mt2_4441This was an evolutionary dead-end for MT2. It came from considering whether there was anything to be gained from adding an additional constraint to the usual space over which the MT2 search over momentum splittins is conducted. That additional constraint was to be the requirement that the rootSHat of the splitting hypothesis should not exceed the collider rootSHat. Reasonable though this requirement is, it turns out to make next to no observable difference to any real MT2 value. So ignore this calculator.
Basic_Mt2_AsymmParents332This is an algorithm for calculating bounds on parental particle masses, when those parents are produced in pairs, have DIS-SIMILAR masses, but yet decay into the same invisible particle (and some visible particles). Eg A->BC and D->EC with C an invisible particle, B and E visible decay products, and A and D heavy parents that need not share the same mass.
Basic_MtGen_330Calculates MTGEN under the assumption of UTM=0, using a very "dumb" exhaustive search of every single possible partition of the visible momenta into two sets. Can be very slow.Does not need minuit2
Basic_MtGen_332Calculates MTGEN under the assumption of UTM=0, using a very "dumb" exhaustive search of every single possible partition of the visible momenta into two sets. Can be very slow.Does not need minuit2
Basic_Nt2_332NT2 is like MT2 but "backwards": wheras in MT2 you determine a bound on the mass of the parents given a hypothesis for the mass of the invisible daughters, in NT2 you determine a bound on the mass of the invisible daughter given a hypothesis for the mass of teh parents.
LesterNachmanBisect_Mt2_332This is the fastest and most accurate algorithm for calculating vanilla (non asymmetric) MT2. It is a wrapper around the minuit2-independent Lester and Nachman Bisection algorthm of arXiv:1411.4312. If you have no preference, we recommend you use this one for vanilla MT2 problems. Does not need minuit2
LesterNachmanBisect_Mt2_3322This is the fastest and most accurate algorithm for calculating MT2 in the so-called AsymmetricMT2 in which the invisible particles have different masses. It is a wrapper around the minuit2-independent Lester and Nachman Bisection algorthm of arXiv:1411.4312. If you have no preference, we recommend you use this one for asymmetric MT2 problems. It can also be used for symmetric MT2 at no computational or accuracy cost.Does not need minuit2
ChengHanBisect_Mt2_332This is the second fastest, and second-most accurate, minuit2-independent Cheng and Han Bisection algorthm. Actually, in our library all there really is is a wrapper around Cheng an Han's own implementation. See this more detailed discussion earlier.Does not need minuit2
Frugal_MPairProdThis implementation improves on that of the Basic MPairProd Calculator by being economical and intelligent with its search through parititions. Does not need minuit2
Frugal_MtGen_330Calculates MTGEN under the assumption of UTM=0, using the fewest possible number of MT2 evaluations.Does not need minuit2
Frugal_MtGen_332Calculates MTGEN using the fewest possible number of MT2 evaluations.Does not need minuit2
M2C_332Calculates Serna and Ross's M2C (see arXiv:0712.0943).
MC_330Calculates Tovey's MC -- the Contralinear-Boost Invariant Mass -- (see arXiv:0802.2879).Does not need minuit2
MCT_330Calculates Tovey's MCT -- the Contransverse Mass -- (see arXiv:0802.2879).Does not need minuit2
SUSYPhys_Mt2_222Do not use! This is included only for historical reasons. It is an archive of an algorithm used to calculate MT2 for some very early ATLAS susy studies. The algorithm was only accurate for massless input particles.

Nomenclature

Short lists of number like 332, 4441, 222 in names of MT2 algorithms describe the number of degrees of freedom in the algorighm's inputs. Reading the digits from left to right, the number of degrees of freedom and the nature of those degrees of freedom are as follows:

External dependencies

To get all the features of our library, you need a version of ROOT compiled with minuit2 support. However, it is possible to compile our library without any external dependencies by specifying the "--without-minuit2" option at the configure stage:

cmake .. -DUseROOT=OFF -DCMAKE_INSTALL_PREFIX=/somewhere
make
make install
If you do this, only the algorithms and example programs which are indepentent of minuit2 and ROOT will be compiled. This is not a problem if you want the fastest available implmentation (LesterNachman) as this has no ROOT or minuit2 dependencies. If all you need is MT2 or MCT, then you might want to compile in this mode.

Notes regarding the OLD version of the library available to ATLAS users:

There are some notes for ATLAS users relevant only to the old version of the library on the ATLAS CVS repository.

Notes for Maintainers

See StransverseMassMaintainers.

Shameless advertisement designed to boost google rank: if you want to study study natural sciences at Cambridge, apply to Peterhouse. It's the best college for natural sciences: physics, chemistry, materials science, etc.

Go back to my home page.