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 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
• How to contribute
• Wiki
• 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: bash mkdir build; cd build; cmake ../ make -jN [Where N is number of threads] make install

Don't forget to: bash source bin/setup.MaCh3.sh

Building against MaCh3

To include MaCh3 in your cmake project you can use following syntax cmake 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 cmake find_package(MaCh3)

Once you found MaCh3 you might want to link your library against MaCh3. You can do this as follows: cmake 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 (see here for documentation).

You can tell the build system to set up the pyMaCh3 interface by specifying

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

when building

Building with Pip

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

bash pip install -t <install location> . The (optional) -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 bash 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 bash 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 |

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:

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

bash 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: bash 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 string for many structures |

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: bash GCC: >= 8.5 [lower versions may work] C++: >= 14 CMake: >= 3.14 ROOT: >= 6.18

Supported operational systems

| Name | Status | |-------------|--------| | Alma9 | ✅ | | Rocky9 | ✅ | | Ubi9 | ✅ | | Ubuntu22.04 | ✅ | | Ubuntu24.10 | ✅ | | Fedora32 | ✅ | | CentOS7 | ❔ | | Windows | ❌ | | MacOS | ❌ |

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

Supported compilers

| Name | Status | |-------------|--------| | GNU | ✅ | | CLANG | ❔ | | INTELLLVM | ❔ | | MSVC | ❌ |

✅ - Fully working with every feature fully tested by CI/CD
❔ - Not every feature may work, only compilation being tested by CI/CD
❌ - Not supported and no plans right now

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: ```cpp //Manager is responsible for reading from config std::unique_ptr fitMan = MaCh3ManagerFactory(argc, argv);

std::vector sample; //vector storing information about sample for different detector std::vector Cov; // vector with systematic implementation MakeMaCh3Instance(fitMan.get(), sample, Cov); //Factory like function which initialises everything

// FitterBase class, can be replaced with other fitting method std::unique_ptr MarkovChain = MaCh3FitterFactory(FitManager.get());

//Adding samples and covariances to the Fitter class could be in the factory for(unsigned int i = 0; sample.size(); i++) MarkovChain->AddSampleHandler(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 ``` For more see here