Binding modules to python

Binding of C++ functions to python (pyexadis) is done using pybind11 and implemented in the python/ directory of the ExaDiS folder. Wrappers are implemented on both the C++ and the python sides, in files exadis_pybind.h/exadis_pybind.cpp and pyexadis_base.py, respectively. Any C++ ExaDiS class or function must be explicitly wrapped into a corresponding binding object in order to be exposed to python in the pyexadis library. Whenever possible, the binding should be implemented locally in the module files using dedicated registry macros, so that file python/exadis_pybind.cpp does not have to be modified.

Example 1: binding a simple class

For instance, a class MyExaDisClass implemented in C++ ExaDiS

#include "exadis_pybind.h"

class MyExaDisClass {
public:
    MyExaDisClass() {
        // Initialize
    }
    void foo() {
        // Do some stuff
    }
};

must be binded to the pyexadis module using the EXADIS_MODULE_BINDING() registry macro (placed after the class definition):

EXADIS_MODULE_BINDING(MyExaDisClass) {
    py::class_<MyExaDisClass>(m, "MyExaDisClass")
        .def(py::init<>())
        .def("foo", &MyExaDisClass::foo, "Do some stuff");
}

in order to become available on the python side:

import pyexadis
myobject = pyexadis.MyExaDisClass()
myobject.foo()

Example 2: binding an ExaDiS module

For an ExaDiS module implemented in C++ that operates on an ExaDiS System object, e.g.

class MyExaDisModule {
public:
    MyExaDisModule(System* system) {
        // Initialize
    }
    void foo(System* system) {
        // Do some stuff
    }
};

the binding must also act as a wrapper for the System object, which is only internal to ExaDiS and not directly exposed to the python side. This is because, in the context of OpenDiS, one should allow the input system to be provided from an arbitrary core library (e.g PyDiS). One way to proceed is to create a wrapper binding struct on the C++ side and expose this struct to pyexadis, e.g.:

#include "exadis_pybind.h"

struct MyExaDisModuleBind {
    MyExaDisModule* mymodule;
    Params params;
    MyExaDisModuleBind(Params& p) {
        params = p;
        System* system = make_system(new SerialDisNet(), Crystal(), params);
        mymodule = new MyExaDisModule(system);
        exadis_delete(system);
    }
    void foo(ExaDisNet& disnet) {
        System* system = disnet.adjust_system(params);
        mymodule->foo(system);
    }
};

EXADIS_MODULE_BINDING(MyExaDisModule) {
    py::class_<MyExaDisModuleBind>(m, "MyExaDisModule")
        .def(py::init<Params>(), py::arg("params"))
        .def("foo", &MyExaDisModuleBind::foo, "Do some stuff", py::arg("net"));
}

such that the module now becomes available on the python side:

import pyexadis
from pyexadis_base import get_exadis_params
# Initialization
state = {...}
N = DisNetManager(...)
# Instantiate the module
params = get_exadis_params(state)
mymodule = pyexadis.MyExaDisModule(params)
# Call module method on ExaDiS network object
G = N.get_disnet(ExaDisNet)
mymodule.foo(G.net)