Simple packaging of C code with cython

Question

I have a number of C functions and I would like to name them from python. cython seems to be the way to go, but I cannot find an example of exactly how this is done. My C function looks like this:

void calculate_daily ( char *db_name, int grid_id, int year, double *dtmp, double *dtmn, double *dtmx, double *dprec, double *ddtr, double *dayl, double *dpet, double *dpar ) ; 

All I want to do is specify the first three parameters (a string and two integers) and restore 8 numpy arrays (or python lists. All double arrays have N elements). My code assumes that pointers point to an already allocated piece of memory. In addition, the resulting C code must reference some external libraries.

Answer 1

Here's a tiny but complete example of passing numpy arrays to an external C function, logically

 fc( int N, double* a, double* b, double* z ) # z = a + b 

using cython. (This is certainly well known to those who know it well. Comments are welcome. Last modified: February 23, 2011, for Cython 0.14.)

First reading or removing Cython build and Cython with NumPy .

2 steps:

• python f-setup.py build_ext --inplace
  rotates f.pyx and fc.cpp f.so , the dynamic library
• python test-f.py
import f loads f.so ; f.fpy( ... ) calls C fc( ... ) .

python f-setup.py uses distutils to run cython, compile and link:
cython f.pyx -> f.cpp
compile f.cpp and fc.cpp
link fo fc.o f.so , the dynamic lib that will load python import f .

For students, I would suggest: outline these steps, view the files below, then download and run them.

( distutils is a huge, confusing package used to make Python packages for distribution and install them. Here we use only a small part to compile and link to f.so This step has nothing to do with Keaton, but it may confuse confusing; simple errors in .pyx can cause pages of obscure error messages from g ++ compilation and links. See also distutils doc and / or SO questions about distutils .)

Like make , setup.py will repeat cython f.pyx and g++ -c ... f.cpp if f.pyx newer than f.cpp .
To clean rm -r build/ .

An alternative to setup.py would be to run the steps separately in a script or Makefile:
cython --cplus f.pyx -> f.cpp # see cython -h
g++ -c ... f.cpp -> fo
g++ -c ... fc.cpp -> fc.o
cc-lib fo fc.o -> dynamic library f.so
Change the cc-lib-mac wrapper below for your platform and installation: this is not very, but not enough.

For real-world examples of Cython C packaging, look at .pyx files in almost any SciKit .

See also: Cython for NumPy and SO users questions / tagged / cython .

---

To unzip the following files, cut-paste the lot into one large file, say cython-numpy-c-demo , then on Unix (in a clean new directory) run sh cython-numpy-c-demo .

 #-------------------------------------------------------------------------------- cat >f.pyx <<\! # f.pyx: numpy arrays -> extern from "fc.h" # 3 steps: # cython f.pyx -> fc # link: python f-setup.py build_ext --inplace -> f.so, a dynamic library # py test-f.py: import f gets f.so, f.fpy below calls fc() import numpy as np cimport numpy as np cdef extern from "fc.h": int fc( int N, double* a, double* b, double* z ) # z = a + b def fpy( N, np.ndarray[np.double_t,ndim=1] A, np.ndarray[np.double_t,ndim=1] B, np.ndarray[np.double_t,ndim=1] Z ): """ wrap np arrays to fc( a.data ... ) """ assert N <= len(A) == len(B) == len(Z) fcret = fc( N, <double*> A.data, <double*> B.data, <double*> Z.data ) # fcret = fc( N, A.data, B.data, Z.data ) grr char* return fcret ! #-------------------------------------------------------------------------------- cat >fc.h <<\! // fc.h: numpy arrays from cython , double* int fc( int N, const double a[], const double b[], double z[] ); ! #-------------------------------------------------------------------------------- cat >fc.cpp <<\! // fc.cpp: z = a + b, numpy arrays from cython #include "fc.h" #include <stdio.h> int fc( int N, const double a[], const double b[], double z[] ) { printf( "fc: N=%da[0]=%fb[0]=%f \n", N, a[0], b[0] ); for( int j = 0; j < N; j ++ ){ z[j] = a[j] + b[j]; } return N; } ! #-------------------------------------------------------------------------------- cat >f-setup.py <<\! # python f-setup.py build_ext --inplace # cython f.pyx -> f.cpp # g++ -c f.cpp -> fo # g++ -c fc.cpp -> fc.o # link fo fc.o -> f.so # distutils uses the Makefile distutils.sysconfig.get_makefile_filename() # for compiling and linking: a sea of options. # http://docs.python.org/distutils/introduction.html # http://docs.python.org/distutils/apiref.html 20 pages ... # https://stackoverflow.com/questions/tagged/distutils+python import numpy from distutils.core import setup from distutils.extension import Extension from Cython.Distutils import build_ext # from Cython.Build import cythonize ext_modules = [Extension( name="f", sources=["f.pyx", "fc.cpp"], # extra_objects=["fc.o"], # if you compile fc.cpp separately include_dirs = [numpy.get_include()], # .../site-packages/numpy/core/include language="c++", # libraries= # extra_compile_args = "...".split(), # extra_link_args = "...".split() )] setup( name = 'f', cmdclass = {'build_ext': build_ext}, ext_modules = ext_modules, # ext_modules = cythonize(ext_modules) ? not in 0.14.1 # version= # description= # author= # author_email= ) # test: import f ! #-------------------------------------------------------------------------------- cat >test-f.py <<\! #!/usr/bin/env python # test-f.py import numpy as np import f # loads f.so from cc-lib: f.pyx -> fc + fc.o -> f.so N = 3 a = np.arange( N, dtype=np.float64 ) b = np.arange( N, dtype=np.float64 ) z = np.ones( N, dtype=np.float64 ) * np.NaN fret = f.fpy( N, a, b, z ) print "fpy -> fc z:", z ! #-------------------------------------------------------------------------------- cat >cc-lib-mac <<\! #!/bin/sh me=${0##*/} case $1 in "" ) set -- f.cpp fc.cpp ;; # default: g++ these -h* | --h* ) echo " $me [g++ flags] xx.c yy.cpp zz.o ... compiles .c .cpp .o files to a dynamic lib xx.so " exit 1 esac # Logically this is simple, compile and link, # but platform-dependent, layers upon layers, gloom, doom base=${1%.c*} base=${base%.o} set -x g++ -dynamic -arch ppc \ -bundle -undefined dynamic_lookup \ -fno-strict-aliasing -fPIC -fno-common -DNDEBUG `# -g` -fwrapv \ -isysroot /Developer/SDKs/MacOSX10.4u.sdk \ -I/Library/Frameworks/Python.framework/Versions/2.6/include/python2.6 \ -I${Pysite?}/numpy/core/include \ -O2 -Wall \ "$@" \ -o $base.so # undefs: nm -gpv $base.so | egrep '^ *U _+[^P]' ! # 23 Feb 2011 13:38 

Answer 2

The following Cython code from http://article.gmane.org/gmane.comp.python.cython.user/5625 does not require explicit tricks and also processes continuous arrays:

 def fpy(A): cdef np.ndarray[np.double_t, ndim=2, mode="c"] A_c A_c = np.ascontiguousarray(A, dtype=np.double) fc(&A_c[0,0]) 

Answer 3

Basically, you can write your Cython function so that it allocates arrays (make sure you are cimport numpy as np ):

 cdef np.ndarray[np.double_t, ndim=1] rr = np.zeros((N,), dtype=np.double) 

then pass the .data pointer to each of your C functions. This should work. If you don't need to start with zeros, you can use np.empty to increase the speed a bit.

See Cython for NumPy users in the docs (fixed link to the correct link).

Answer 4

You should check out Ctypes , this is probably the easiest thing to use if you want only one function.