User guide

NumPy User Guide, Release 1.9.0
Variable Type Contents
myvar {dtype}* Pointer to the first element of the array
Nmyvar npy_intp* A pointer to the dimensions array
Smyvar npy_intp* A pointer to the strides array
Dmyvar int The number of dimensions
myvar_array PyArrayObject* The entire structure for the array
The in-lined code can contain references to any of these variables as well as to the standard macros MYVAR1(i), MY-
VAR2(i,j), MYVAR3(i,j,k), and MYVAR4(i,j,k,l). These name-based macros (they are the Python name capitalized
followed by the number of dimensions needed) will de- reference the memory for the array at the given location with
no error checking (be-sure to use the correct macro and ensure the array is aligned and in correct byte-swap order in
order to get useful results). The following code shows how you might use these variables and macros to code a loop
in C that computes a simple 2-d weighted averaging filter.
int i,j;
for(i=1;i<Na[0]-1;i++) {
for(j=1;j<Na[1]-1;j++) {
B2(i,j) = A2(i,j) + (A2(i-1,j) +
A2(i+1,j)+A2(i,j-1)
+ A2(i,j+1))
*
0.5
+ (A2(i-1,j-1)
+ A2(i-1,j+1)
+ A2(i+1,j-1)
+ A2(i+1,j+1))
*
0.25
}
}
The above code doesn’t have any error checking and so could fail with a Python crash if, a had the wrong number of
dimensions, or b did not have the same shape as a. However, it could be placed inside a standard Python function with
the necessary error checking to produce a robust but fast subroutine.
One final note about weave.inline: if you have additional code you want to include in the final extension module such as
supporting function calls, include statements, etc. you can pass this code in as a string using the keyword support_code:
weave.inline(code, variables, support_code=support). If you need the extension module to link
against an additional library then you can also pass in distutils-style keyword arguments such as library_dirs, libraries,
and/or runtime_library_dirs which point to the appropriate libraries and directories.
Simplify creation of an extension module
The inline function creates one extension module for each function to- be inlined. It also generates a lot of intermediate
code that is duplicated for each extension module. If you have several related codes to execute in C, it would be better
to make them all separate functions in a single extension module with multiple functions. You can also use the tools
weave provides to produce this larger extension module. In fact, the weave.inline function just uses these more general
tools to do its work.
The approach is to:
1. construct a extension module object using ext_tools.ext_module(module_name);
2. create function objects using ext_tools.ext_function(func_name, code, variables);
3. (optional) add support code to the function using the .customize.add_support_code( support_code ) method
of the function object;
4. add the functions to the extension module object using the .add_function(func) method;
5. when all the functions are added, compile the extension with its .compile() method.
68 Chapter 5. Using Numpy C-API