Cython

Overview

Cython is an hybrid language between python and c/cpp that allows the libMuscat.so and python modules to communicate. In Muscat, cython files are mixed with pure python files under the src directory. The main type of cython file you might encounter when browsing the sources are:

  • pyx: these are the “.cpp” equivalents. They contain implentation of

  • pxd: these are the “.h” equivalents. They hold information used

Note

To import a cython file from another cython file, please use the cimport instruction.
It first tries to find a pxd file or its pyx equivalent if it does not exist.

These files contain mixed cython and python code that allow interfacing the two languages.

Interfacing with cpp

In order to interface with the cpp code base, you can simply use the cdef extern from instruction:

cdef extern from "LinAlg/Kokkos/Utils.h" namespace "Muscat::KK" :
    cdef int MyFunction(int arg) nogil

Note

A lot of cpp types are not natively available in cython but you can simply import them using from libcpp import xxx (xxx denoting the type). For example, bool is one of them !

Warning

Templates in cython are denoted as method[T] or class[T]

Numpy and eigency

In cython, you can import numpy using:

import numpy as np
cimport numpy as cnp
cnp.import_array()

You can specify requirements for the matrices defined as parameter of your cython function

def mymethod(cnp.ndarray[CMuscatIndex, ndim=2, mode="c"] array):

Please refer to the cython documentation<https://cython.readthedocs.io/en/latest/src/tutorial/numpy.html#buffer-options> for further information about it.

However, the numpy arrays’ pointers will not be available to cpp. The Eigency library is used to make the bridge between numpy and cpp. Therefore, it is first necessary to turn the numpy array into an Eigen::Map type by calling:

GetSharedMMatrixTYY(myNumpyArray).get()[0]

Note

The pointer is just wrapped by eigency and no copy is made !

Where:

  • T denotes the type of the matrix: D for floating/double or I for integers.

  • X denotes the first dimensionality of the matrix: D for dynamic or 1 for single dimension.

  • Y denotes the second dimensionality of the matrix: D for dynamic or 1 for single dimension.

All of this function return a pointer to MapMaptrixTXY type that need to be dereferenced using .get()[0] to retrieve a pointer to the first element.

Note

Please refer to the CythonTypes.pxd and EigenTypes.h files to check every single types defined.

Compilation

Compilation is done by the CMake build system and generate sequentially:

  1. .cpp file from the pyx

  2. .cpp.o file from the cpp

  3. .libXXX-cythonXXX.so file from the cpp.o

In other words, cython generates a cpp file for every single cython module. Then, the cpp source file is compiled to create a shared library.

Warning

You need to launch the program with the same cython version than you compiled it with.