Interfacing with Cpp

Using Cython to connect Cpp to Python

First, install cython using conda (from within the project's virtual environment):

$ conda install cython

To build cython extensions for a python project, we must add the extension to setup.py and call

$ python setup.py build_ext --inplace            # build cpp extension

This compiles and builds the cpp code and returns a dynamic library that can be linked to from python.

Most of the work is done in the .pyx cython wrapper files.

To link a C++ library to python using cython, a wrapper .pyx file is necessary. The Cython wrapper is very similar to python, except objects can be statically typed using the cdef command (as oppose to python's dynamically duck-typed at runtime).

See cython userguide for more details.

Building Cpp

The C++ code is stored in the cython folder. The header and source files are in cython/src. The unit tests are in cython/test.

To build (stand-alone) C++ files/executables, we use CMake. Recall CMake is a structured language that helps organize and generate Makefiles. Then by calling make, the Makefiles compile the code.

Because CMake generates a lot of junk, the workflow is to build the project in a build directory

$ cd [...]/cython
$ mkdir build
$ cd build
$ cmake ..  # Setups up the Makefiles in the `build` directory
$ make      # Compiles the code in the `build` directory

To clean up the project, just remove the build folder.

Adding new C++ sources, headers, and tests, requires modifying the appropriate CMakeLists.txt files.

Cpp Unit Test

The unit tests are written using the CXX_TEST framework and are added to the CMakeLists using FindCxxTest. To run the tests, build the project and call make test or use the command ctest (both from the build folder). I prefer to call ctest --verbose from the build folder.

Don't forget you can run tests individually via the cxx_test executables (compiled in the build\test folder).

Connecting C++ with Numpy using Eigen

We connect python's numpy with C++ eigen we use Eigency.

Eigen

First install eigen by downloading the most recent copy and using cmake to install it to /usr/local/include/eigen3. Read the Install guide in the archived tar file. For convenience, add syslinks from eigen3 to include

$ cd /usr/local/include
$ sudo ln -sf eigen3/Eigen Eigen

For more documentation on how to use eigen, read the docs link and quickreference guide link

Eigency

First install eigency by cloning the repo and calling python setup.py install (make sure cython is installed). Then read the README.md.