MT2 / Stransverse Mass / Oxbridge Kinetics Library

A small C++ library for calculating kinematic variables including:

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


DOWNLOAD


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 using the algorithm 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).

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.
  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 .

Download and install in three easy steps

  1. Our library can be built without any external dependencies by specifying --without-minuit2 as an argument to ./configure 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.
  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 files contained therein. For most users this will consist of
    ./configure --prefix=/somwhere/in/particular
    make
    make install
    
    but users without a ROOT installation will need to do
    ./configure --prefix=/somwhere/in/particular --without-minuit2
    make
    make install
    
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:
./example_helloWorld_Mt2_Without_Minuit2_Example
and/or
./example_helloWorld_Mt2_Example
if you complied with minuit2 support enabled.

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 "--without-minuit2" option to configure 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 example_helloWorld_Mt2_Example \
         -I $PREFIX/include/oxbridgekinetics-1.0 \
         -L $PREFIX/lib/ \
         -loxbridgekinetics-1.0 \
         `root-config --cflags` \
         -Xlinker -rpath $PREFIX/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 "--prefix=BLAH" argument when you configured the library. The default is equivalent to ./configure --prefix=/usr/local)

Running the hello world example:
The automatically built executable will be found in the directory from which you typed make when you built the MT2 library. The executable will be called example_helloWorld_Mt2_Example.

If you run it by typing

./example_helloWorld_Mt2_Example
you should see the following output:

[lxplus214] > ./example_helloWorld_Mt2_Example
----------------------------------------------------------------------
 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 --without-minuit2 option supplied to configure like this:
./configure --without-minuit2
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]$ ./example_helloWorld_Mt2_Without_Minuit2_Example 
----------------------------------------------------------------------
 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
----------------------------------------------------------------------
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.62883811 for ChengHanBisect_Mt2_332 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et = 422.49260349, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et = 395.72717875, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_mass = 100
ANSWER: mt2 = 412.62883811 for ChengHanBisect_Mt2_332 algorithm
Going to calculate MT2 with
   ltv_Vis_A  = Lor2Vec: x =       410, y =        20, Et = 422.49260349, mass = 100
   ltv_Vis_B  = Lor2Vec: x =      -210, y =      -300, Et = 395.72717875, mass = 150
   pT_Miss    = TwoVector: x =      -200, y =       280
   invis_mass = 100
ANSWER: mt2 = 412.62883811 for ChengHanBisect_Mt2_332 algorithm
Building the second hello world example manually

Regardless of whether or not you specified the "--without-minuit2" option to configure 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 example_helloWorld_Mt2_Without_Minuit2_Example \
         -I $PREFIX/include/oxbridgekinetics-1.0 \
         -L $PREFIX/lib/ \
         -loxbridgekinetics-1.0 \
         `root-config --cflags` \
         -Xlinker -rpath $PREFIX/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 "--prefix=BLAH" argument when you configured the library. The default is equivalent to ./configure --prefix=/usr/local).

Note that if you have no ROOT installation and you compiled with the --without-minuit2 option, then above you should omit the line:

        `root-config --cflags` \

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
Recommended "home grown" MT2 algorithm.See the Basic_Mt2_332 Algorithm entry below.
Recommended "external" MT2 algorithm.See the ChengHanBisect_Mt2_332 Algorithm entry below. Does not need minuit2
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_Asymmetric332This 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.
ChengHanBisect_Mt2_332This is the very fast, accurate, and 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:

Which MT2 algorithm should I use?

We recommend that most users use the Basic_Mt2_332 aglorigthm as demonstrated in the simple Hello World example.

Users could also consider using the independent ChengHanBisect_Mt2_332 algorithm as demontrated in the second "Hello World" example. In fact, by all estimates (including our own!) the method of Cheng and Han is the fastest and most accurate of all implementations provided in our library. (Note: the interface to the ChengHanBisect algorithm provided in this library is just a wrapper around the very efficient and self-contained library described in arXiv:0810.5178. We are grateful that Cheng and Han permit us to include their code here. Users of their code should, of course, ensure to give them the approriate citations.) The only reason the Cheng and Han method is not our "default" recommendation, is that the code-base is not one we maintain, and so we cannot undertake to fix or undertand any bugs it might contain. This said, we have great confidence in their implementation, and use it frequently ourselves. Indeed, if all you need is an mt2 implementation, you may be better of using their implementation directly (see the section on alternatives to this library) as it has no external dependencies, and sits only in two files.

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:

./configure --without-minuit2 --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. One such algorithm is the very fast implementation of Cheng and Han described here. 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.