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()
.