Python Interface for MaCh3

[ewanwm]

Pull request description

Have now added python bindings for the main objects that the experiments need to interface with. This means that MaCh3 fitters (MCMC and Minuit) can be run purely in python. Additionally these objects can be extended using python so for example someone could quickly prototype some new exotic MCMC algorithm and test it in python before implementing a c++ version.

My initial goal was to get the python interface to a point where it could reproduce everything that can currently be done in the MaCh3Tutorial. I ended up going a bit beyond that and (partially) implementing samplePDF too (see note below).

I have written documentation for "pyMaCh3" which covers high level usage of the bound objects and points to the wiki where helpful. This can be updated further in future with more usage examples.

The API is also fully documented as part of this:

This documentation can be generated using the instructions given in the readme in Doc/sphinx/README.md. In the future these will be automatically generated and can be linked with the existing doxygen docs. This should be a pretty easy job but I will leave it to it's own pull request to avoid clutter.

Note on Sample PDF

At the moment only samplePDFBase has been fully implemented in python. samplePDFFDBase has not yet been fully implemented. The plan is to do this in the future once the interface for this has been more fully settled and samplePDFFDBase and samplePDFBase have been unified.

At the moment however there is enough that a user can implement their own samplePDF object, but need to deal with the reweighting and binning of events themselves and can't make use of the more "automated" ways of doing these things that are provided in samplePDFFDBase.

Changes or fixes

There are very few changes to the underlying c++ code other than the addition of a few getters and setters which are needed to access some private members of the c++ classes (python binding is complicated and the python objects are not able to directly access the private or protected members of the bound c++ class)

Have also moved the existing python plotting interface to be a part of the larger pyMaCh3 module. Have also restructured so that all of the pybind11 code lives in the python/ folder to keep things tidier and keep the cmake cleaner.

Other than this the only changes are the addition of pybind11 binding code.

Examples

I've written and ran some python test scripts:

sample-pdf-test.py.txt

basic-fitter-test.py.txt

spline-monolith-test.py.txt

All of these work and once this PR is merged these can be added to the MaCh3Tutorial as both tutorial examples and as part of the CI

Just to be sure, I've ran a 10M step stat only chain in python and the same using the MaCh3Tutorial and compared:

Python_vs_cpp_10M_step.pdf

[github-actions]

Hi @ewanwm, thank you for contributing to MaCh3! Please wait for MaCh3 developers to review your PR. If no one answers within a week, please message people from this list: https://github.com/orgs/mach3-software/teams/mach3admin . While waiting, please enjoy this

Use this action on your projects. Use jokes on issues instead.

[henry-wallace-phys]

Is there a reason this isn't an std::vector?

[ewanwm]

nope

[henry-wallace-phys]

Looks good, a few minor fixes. Have you tested this in some dummy app?

[ewanwm]

Yeah tested with these

sample-pdf-test.py.txt

basic-fitter-test.py.txt

spline-monolith-test.py.txt

once this is merged will move them to the MaCh3Tutorial to be part of the CI as well

[henry-wallace-phys]

.py.txt is incredibly cursed but looks good!

[ewanwm]

.py.txt is incredibly cursed but looks good!

😆 agreed

[henry-wallace-phys]

Looks fantastic, very exciting to see