MaCh3

The Markov Chain 3 flavour is a framework born in 2013 as a Bayesian MCMC fitter for T2K oscillation analysis. It has now been used for multiple T2K Oscillation analyses at both the Near and Far detectors throughout the years. The framework is also utilized by the DUNE and HK oscillation analysis groups. Additionally, it supports joint fits between T2K and NOvA, as well as T2K and SK's atmospheric data.

The framework has also evolved to allow non-MCMC modules to interrogate the likelihoods implemented.

Famous Plots

Example of plots made using MaCh3 apparent in scientific publications, for more see here

Cite

When citing MaCh3, please use on Zenodo .

How to Compile

MaCh3 follows standard cmake pattern. By default you should get most optimal build setting although below we list many configurable options:

mkdir build;
cd build;
cmake ../
make -jN [Where N is number of threads]
make install

Don't forget to:

source bin/setup.MaCh3.sh

Building against MaCh3

To include MaCh3 in your cmake project you can use following syntax

CPMFindPackage(
  NAME MaCh3
  GIT_TAG "blarb"
  GITHUB_REPOSITORY mach3-software/MaCh3
)

Where "blarb" is the MaCh3 version. You can find a list of releases here
If you compiled MaCh3 and sourced it you can simply call

find_package(MaCh3)

Once you found MaCh3 you might want to link your library against MaCh3. You can do this as follows:

target_link_libraries(blarb MaCh3::All)

Some functionalities rely on setting Env{MACH3} which should point to path experiment specific MaCh3. This way MaCh3 can easily find Env{MACH3}/inputs/SomeInput.root for example.

Python

MaCh3 can be compiled with a python interface by specifying the cmake option

cmake ../ -DMaCh3_PYTHON_ENABLED=ON
make && make install

Currently the python module only contains an interface to the plotting library (see here for more information on how to use it)

Building with Pip

Additionally, you can build just the Python module by doing:

pip install -t <install location> .

The -t option specifies an install location which can be useful if you are on a computing cluster and don't have write access to the default install location. If you specify a non-standard location you will need to add it to your PYTHONPATH as above so that python can find the module.

Multithreading

MaCh3 quite heavily relies on Multithreading, it is turned on by default. If for debugging purposes you would like to turn it off please use

cmake ../ -DMaCh3_MULTITHREAD_ENABLED=OFF

CUDA

If the system has access to GPU, MaCh3 will enable GPU functionality automatically. If you would like to CPU only despite having access to CUDA

mkdir build; cd build;
cmake ../ -DUSE_CPU=ON

MaCh3 supports quite a high range of CUDA architectures if something doesn't work on your GPU let us know. MaCh3 supports only NVIDIA GPUs.

Oscillator

MaCh3 uses several neutrino oscillation calculators.

Following neutrino oscillation calculators are available:

Oscillator	Hardware	Source	Reference
CUDAProb3Linear	CPU/GPU	Beam
CUDAProb3	CPU/GPU	Atm	Ref
ProbGPULinear	GPU	Beam	Ref
Prob3++Linear	CPU	Beam
NuFastLinear	CPU	Beam	Ref

If nothing is specified in cmake build then NuFastLinear_ENABLED will be used. To control which oscillation calculators you want to use here is syntax:

cmake ../ -DCUDAProb3Linear_ENABLED=ON -DCUDAProb3_ENABLED=ON -DProbGPULinear_ENABLED=ON -DProb3ppLinear_ENABLED=ON -DNuFastLinear_ENABLED=ON

You can only specify engines you want to use, and you can in principle use more than one.

Fitting algorithms

The following fitting algorithms are available:

Algorithm	Reference	Need Ext Lib
MR2T2	Ref	No
MINUIT2	Ref	Yes
PSO	Ref	No

Debug

Several debugging options are available which are heavy for RAM and performance and, therefore not used by default. To enable it:

cmake ../ -DMaCh3_DEBUG_ENABLED=<ON,OFF>

There are several debug modes, to enable more detailed but very heavy specific debug levels. Level 1 is the default debug activated by the above.

cmake ../ -DMaCh3_DEBUG_ENABLED=<ON,OFF> -DDEBUG_LEVEL=<1,2,3>

System Requirements

Most of external libraries are being handled through CPM. The only external library that is not being handled through CPM and is required is ROOT. Currently used external dependencies include:

1. yaml-cpp
2. spdlog

Based on several test here are recommended version:

  GCC: >= 8.5 [lower versions may work]
  CMake: >= 3.14
  ROOT: >= 6.18

Supported operational systems

Name	Status
Alma9	✅
Ubuntu22.04	✅
Fedora32	✅
CentOS7	❔
Windows	❌

✅ - Part of CI/CD
❔ - Not part of CI/CD but used by some users/developers so it might work
❌ - Not supported and no plans right now

Help and Guidelines

• Tutorial
• How to contribute
• Wiki
• Mailing lists
• Slack
• Discussions

Plotting and Diagnostic

Example of chain diagnostic utils can be found here with example of config. The MaCh3 core plotting library code can be found here along with example config files and some apps for making standard plots.

How To Use

This is an example how your executable can look like using MaCh3:

  manager *fitMan = nullptr; //Manager is responsible for reading from config

  std::vector<samplePDFBase*> sample; //vector storing information about sample for different detector
  std::vector<covarianceBase*> Cov; // vector with systematic implementation
  mcmc *markovChain = nullptr; // MCMC class, can be replaced with other fitting method
  MakeMaCh3Instance(fitMan, sample, Cov, markovChain); //Factory like function which initialises everything

  //Adding samples and covariances to the Fitter class could be in the factory
  for(unsigned int i = 0; sample.size(); i++)
    markovChain->addSamplePDF(sample[i]);
  for(unsigned int i = 0; Cov.size(); i++)
    markovChain->addSystObj(Cov[i]);

  markovChain->RunLLHScan(); // can run LLH scan
  markovChain->runMCMC(); //or run actual fit