mmf.examples.inline_example

example1()

Here is a simple example where we pass a numpy array called x to weave.

Documentation for mmf.examples.inline_example.

Inline C++ Code

Here we give some concrete examples of the use of scipy.weave for including C++ code in your python code. First, the documentation:

C/C++ integration

inline – a function for including C/C++ code within Python blitz – a function for compiling Numeric expressions to C++ ext_tools – a module that helps construct C/C++ extension modules. accelerate – a module that inline accelerates Python functions

Note

On Linux one needs to have the Python development headers installed in order to be able to compile things with the weave module. Since this is a runtime dependency these headers (typically in a pythonX.Y-dev package) are not always installed when installing scipy.

scipy.weave.inline(code, arg_names=[], local_dict=None, global_dict=None, force=0, compiler='', verbose=0, support_code=None, headers=[], customize=None, type_converters=None, auto_downcast=1, newarr_converter=0, **kw)

Inline C/C++ code within Python scripts.

inline() compiles and executes C/C++ code on the fly. Variables in the local and global Python scope are also available in the C/C++ code. Values are passed to the C/C++ code by assignment much like variables passed are passed into a standard Python function. Values are returned from the C/C++ code through a special argument called return_val. Also, the contents of mutable objects can be changed within the C/C++ code and the changes remain after the C code exits and returns to Python.

inline has quite a few options as listed below. Also, the keyword arguments for distutils extension modules are accepted to specify extra information needed for compiling.

Parameters :

code : string

A string of valid C++ code. It should not specify a return statement. Instead it should assign results that need to be returned to Python in the return_val.

arg_names : [str], optional

A list of Python variable names that should be transferred from Python into the C/C++ code. It defaults to an empty string.

local_dict : dict, optional

If specified, it is a dictionary of values that should be used as the local scope for the C/C++ code. If local_dict is not specified the local dictionary of the calling function is used.

global_dict : dict, optional

If specified, it is a dictionary of values that should be used as the global scope for the C/C++ code. If global_dict is not specified, the global dictionary of the calling function is used.

force : {0, 1}, optional

If 1, the C++ code is compiled every time inline is called. This is really only useful for debugging, and probably only useful if your editing support_code a lot.

compiler : str, optional

The name of compiler to use when compiling. On windows, it understands ‘msvc’ and ‘gcc’ as well as all the compiler names understood by distutils. On Unix, it’ll only understand the values understood by distutils. (I should add ‘gcc’ though to this).

On windows, the compiler defaults to the Microsoft C++ compiler. If this isn’t available, it looks for mingw32 (the gcc compiler).

On Unix, it’ll probably use the same compiler that was used when compiling Python. Cygwin’s behavior should be similar.

verbose : {0,1,2}, optional

Speficies how much much information is printed during the compile phase of inlining code. 0 is silent (except on windows with msvc where it still prints some garbage). 1 informs you when compiling starts, finishes, and how long it took. 2 prints out the command lines for the compilation process and can be useful if your having problems getting code to work. Its handy for finding the name of the .cpp file if you need to examine it. verbose has no affect if the compilation isn’t necessary.

support_code : str, optional

A string of valid C++ code declaring extra code that might be needed by your compiled function. This could be declarations of functions, classes, or structures.

headers : [str], optional

A list of strings specifying header files to use when compiling the code. The list might look like ["<vector>","'my_header'"]. Note that the header strings need to be in a form than can be pasted at the end of a #include statement in the C++ code.

customize : base_info.custom_info, optional

An alternative way to specify support_code, headers, etc. needed by the function. See scipy.weave.base_info for more details. (not sure this’ll be used much).

type_converters : [type converters], optional

These guys are what convert Python data types to C/C++ data types. If you’d like to use a different set of type conversions than the default, specify them here. Look in the type conversions section of the main documentation for examples.

auto_downcast : {1,0}, optional

This only affects functions that have numpy arrays as input variables. Setting this to 1 will cause all floating point values to be cast as float instead of double if all the Numeric arrays are of type float. If even one of the arrays has type double or double complex, all variables maintain there standard types.

newarr_converter : int, optional

Unused.

Other Parameters:  

Relevant :mod:`distutils` keywords. These are duplicated from Greg Ward’s :

:class:`distutils.extension.Extension` class for convenience: :

sources : [string]

list of source filenames, relative to the distribution root (where the setup script lives), in Unix form (slash-separated) for portability. Source files may be C, C++, SWIG (.i), platform-specific resource files, or whatever else is recognized by the “build_ext” command as source for a Python extension.

Note

The module_path file is always appended to the front of this list

include_dirs : [string]

list of directories to search for C/C++ header files (in Unix form for portability)

define_macros : [(name

list of macros to define; each macro is defined using a 2-tuple, where ‘value’ is either the string to define it to or None to define it without a particular value (equivalent of “#define FOO” in source or -DFOO on Unix C compiler command line)

undef_macros : [string]

list of macros to undefine explicitly

library_dirs : [string]

list of directories to search for C/C++ libraries at link time

libraries : [string]

list of library names (not filenames or paths) to link against

runtime_library_dirs : [string]

list of directories to search for C/C++ libraries at run time (for shared extensions, this is when the extension is loaded)

extra_objects : [string]

list of extra files to link with (eg. object files not implied by ‘sources’, static library that must be explicitly specified, binary resource files, etc.)

extra_compile_args : [string]

any extra platform- and compiler-specific information to use when compiling the source files in ‘sources’. For platforms and compilers where “command line” makes sense, this is typically a list of command-line arguments, but for other platforms it could be anything.

extra_link_args : [string]

any extra platform- and compiler-specific information to use when linking object files together to create the extension (or to create a new static Python interpreter). Similar interpretation as for ‘extra_compile_args’.

export_symbols : [string]

list of symbols to be exported from a shared extension. Not used on all platforms, and not generally necessary for Python extensions, which typically export exactly one symbol: “init” + extension_name.

swig_opts : [string]

any extra options to pass to SWIG if a source file has the .i extension.

depends : [string]

list of files that the extension depends on

language : string

extension language (i.e. “c”, “c++”, “objc”). Will be detected from the source extensions if not provided.

See also

distutils.extension.Extension

Describes additional parameters.

Here we demonstrate some key features.

mmf.examples.inline_example.example1()

Here is a simple example where we pass a numpy array called x to weave. Inspecting the generated code (listed below) we obtain the following information:

npy_intp:

Type of index into array (usually int or long). Use this as your type for iterators.

PyArrayObject * x_array:

Pointer to the he actually python array object.

int Dx = x_array->nd = len(x.shape):

Number of dimensions for x.

npy_intp * Nx = x_array->dimensions = x.shape:

An array containing the dimensions.

npy_intp* Sx = x_array->strides = x.strides:

These are used to index into the array for multidimensional arrays. See below and the numpy documentation.

X1(i) = x[i]:

Macro indexing into the array as a 1D object.

X2(i,j) = x[i,j]:

Macro indexing into the array as a 2D object.

X3(i,j,k) = x[i,j,k]:

Macro indexing into the array as a 4D object.

X4(i,j,k,l) = x[i,j,k,l]:

Macro indexing into the array as a 4D object.

double * x = (double*) x_array->data = x.data:

The actual array data.

py::object return_val:

This is the return value. It supports casting from types like double, int etc.

This is the type of code generated by weave:

py::object return_val;
int exception_occured = 0;
PyObject *py__locals = NULL;
PyObject *py__globals = NULL;
PyObject *py_x;
py_x = NULL;

/* argument conversion code */     
py_x = get_variable("x", raw_locals, raw_globals);
PyArrayObject* x_array = convert_to_numpy(py_x, "x");

// Number of dimensions
int Dx = x_array->nd;    
npy_intp* Nx = x_array->dimensions;
npy_intp* Sx = x_array->strides;

#define X1(i) (*((double*)(x_array->data + (i)*Sx[0])))
#define X2(i,j) (*((double*)(x_array->data + (i)*Sx[0] + (j)*Sx[1])))
#define X3(i,j,k) (*((double*)(x_array->data + (i)*Sx[0] + (j)*Sx[1] + (k)*Sx[2])))
#define X4(i,j,k,l) (*((double*)(x_array->data + (i)*Sx[0] + (j)*Sx[1] + (k)*Sx[2] + (l)*Sx[3])))

double* x = (double*) x_array->data;
    /* inline code */                   
/* NDARRAY API VERSION 1000009 */

           /* hash(support_code) = 831520531. This is used to force",
              a recompile if the support_code changes. */
Py_BEGIN_ALLOW_THREADS

    return_val = norm(x.data, x->dimensions);

Py_END_ALLOW_THREADS        /*I would like to fill in changed locals and globals here...*/   
}
catch(...)                        
{                                 
    return_val =  py::object();   
    exception_occured = 1;        
}                                 
/* cleanup code */                   
Py_XDECREF(py_x);
#undef X1
#undef X2
#undef X3
#undef X4

Examples

Here is the square root of the sum of the squares of the integers from 1 to 24 inclusive computed using a custom norm function.

>>> example1()
70.0