Writing Special-Purpose C++ Code with a Python Interface

If you want to perform a specific task which you can’t do with the general tomorun() function (say, implement a different jump function or use a different representation of density matrices), then you can write your basic components in C++ while providing a convenient Python interface for easily controlling and using your code.

The Tomographer Python Interface provides several C++ tools which you can use and which significantly simplifies your task. Also, all Python objects defined in the Tomographer Python Interface are available via C++.

We use the nice pybind11 tool for interfacing C++ with Python. It includes out-of-the-box interfacing NumPy with Eigen. Learn its basic usage before carrying on too far.

Here is minimal but entirely self-contained and fully functional template to get started with your custom C++/Python module.

Create a directory called my_custom_module, and place the two files my_custom_module/my_custom_module.cxx and my_custom_module/setup.py in there. Enter that directory, and run compile the Python module:

> python setup.py build

You will notice that a directory build/lib.XXXXXXXX should have appeared. To test your compiled module, try out this little script, place it also in the my_custom_module directory and run:

> PYTHONPATH=build/lib.XXXXXXXX  python test_run.py

(Of course, you can also run the usual python setup.py install or python setup.py bdist_wheel etc.)

Here is a little overview of the contents of each file.

The C++ Source File(s)

The idea of the C++ file is to write all the computation in C++, using the classes from the Tomographer framework.

Most of the useful generic classes in the Tomographer framework are instantiated with standard template arguments and exposed to Python. See the tpy namespace for the API documentation.

A set of C++ typedefs are provided, which are already exposed to Python via the tomographer module. You’ll find the types tpy::RealType and tpy::CountIntType (by default, double and int, respectively) which serve as template arguments for most classes. For instance, the template class Histogram is typedef’ed as tpy::Histogram.

These classes are then exposed to Python in the tomographer module. When writing your own custom module, you can take advantage of these existing tools so that you don’t have to expose all these helper types yourself; rather they can be transparently passed between Python to/from C++.

The Python setup.py file

This is a standard setup.py file for packaging Python packages, using setuptools. Read up on that (and then try to not commit hara-kiri).

There are various flags which need to be set when compiling your module, which you can simply steal from the tomographer module: indeed, the tomographer module exposes the flags it was compiled with, so you can just recycle them.

This setup.py script allows the user (you!) to specify options as environment variables, for instance:

>  CXX_FLAGS="-O0 -g3 -UNDEBUG -march=generic -std=c++11"  python setup.py build

This is done by using the Vars class: you give it a set of variables and default values, if the variable exists as an environment variable it is read there, else it takes the default value.

Note that if you need to find other custom libraries or include headers, you can use the utilities tomographer.include.find_include_dir() or tomographer.include.find_lib().