MaCh3 <img src="Doc/mach3logo.png" alt="MaCh3" align="center" width="100"/>

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 using MaCh3 you must cite our doi from Zenodo. The bibtex file can be found by exporting the citation from this link: on Zenodo .

Help and Guidelines 📄

Tutorial
Documentation
Indico If you need a password, please reach out to MaCh3-leadership for access.
How to contribute
Slack
Discussions
Benchmark

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

If the build fails, check your system/environment requirements.

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 has an optional python interface (pyMaCh3) which provides much of the same functionality as the c++ interface. The recommended way of building the pyMaCh3 module is using pip. After checking out the MaCh3 repository, from the root directory (the one containing pyproject.toml) simply run:

pip install .

This will give you a pyMaCh3 module with all functionality of core MaCh3. You can implement any experiment specific code by extending the base classes purely in python. MaCh3 also provides functionality to bind your c++ based experiment specific code so you can maintain all the speed benifits of c++ with the ease of use of python. Details on how to do this are given in the wiki here.

You can also find documentation for the pyMaCh3 module here.

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 ../ -DMaCh3_GPU_ENABLED=OFF

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 has access to several neutrino oscillation calculators via NuOscillator framework.

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 | | OscProb | CPU | Beam/Atm | Ref | | NuSQUIDSLinear | CPU | Beam | Ref | | GLoBESLinear | 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 -DOscProb_ENABLED=ON

You can specify more than one engine, and MaCh3 support different engines for different samples. For example, you can use NuFast for beam samples and CUDAProb3 for atmospheric samples.

Fitting algorithms

The following fitting algorithms are available:

| Algorithm | Reference |Need Ext Lib | |--------------|------------------|--------------| | MR2T2 | Ref | No | | DelayedMR2T2 | 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>

Logger

Several logging options are available. By default, MaCh3 uses INFO level logging. You can enable more verbose logging by specifying the desired level during configuration:

cmake ../ -DLOG_LEVEL="TRACE"

You can find more here.

Other CMake Options

| Option | Meaning | | ------ | ------- | | MaCh3_NATIVE_ENABLED | Enables native CPU optimizations for improved performance. Not recommended on clusters with multiple CPU configurations due to potential compatibility issues. | | MaCh3_NuOsc_GPU_ENABLED | By default MaCh3 will use NuOscillator with GPU if MaCh3 is compiled with GPU, this flag allows disabling GPU for NuOscillator even if MaCh3 has GPU enabled | | MaCh3_LOW_MEMORY_STRUCTS_ENABLED | This will use float/short int for many structures |

System Requirements

MaCh3 requires a C++ compiler (e.g. gcc), CMake, and ROOT. Based on several tests, recommended versions are:

  GCC:   >= 8.5   [lower versions may work]
  C++:   >= 14
  CMake: >= 3.14
  ROOT:  >= 6.20

If you don't already have the correct dependencies, you can install them in a variety of ways, e.g. building from source, via a package manager. If you have access to cvmfs, the easiest solution is probably to source an LCG release. For example, on an x86_64 Alma9 machine:

source /cvmfs/sft.cern.ch/lcg/views/LCG_108/x86_64-el9-gcc1

MaCh3

Install / Use

README