diff options
Diffstat (limited to 'numpy/doc/numpybook/capi.lyx')
| -rw-r--r-- | numpy/doc/numpybook/capi.lyx | 24232 |
1 files changed, 24232 insertions, 0 deletions
diff --git a/numpy/doc/numpybook/capi.lyx b/numpy/doc/numpybook/capi.lyx new file mode 100644 index 000000000..04522d13d --- /dev/null +++ b/numpy/doc/numpybook/capi.lyx @@ -0,0 +1,24232 @@ +#LyX 1.5.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 276 +\begin_document +\begin_header +\textclass mybook +\language english +\inputencoding auto +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 +\graphics default +\paperfontsize default +\spacing onehalf +\papersize default +\use_geometry true +\use_amsmath 2 +\use_esint 0 +\cite_engine basic +\use_bibtopic false +\paperorientation portrait +\leftmargin 1in +\topmargin 1in +\rightmargin 1in +\bottommargin 1in +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\defskip medskip +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\author "" +\author "" +\end_header + +\begin_body + +\begin_layout Part +C-API +\end_layout + +\begin_layout Chapter +New Python Types and C-Structures +\end_layout + +\begin_layout Quotation +Beware of the man who won't be bothered with details. +\end_layout + +\begin_layout Right Address +--- +\emph on +William Feather, Sr. +\end_layout + +\begin_layout Quotation +The truth is out there. +\end_layout + +\begin_layout Right Address +---Chris Carter, The X Files +\end_layout + +\begin_layout Standard +NumPy provides a C-API to enable users to extend the system and get access + to the array object for use in other routines. + The best way to truly understand the C-API is to read the source code. + If you are unfamiliar with (C) source code, however, this can be a daunting + experience at first. + Be assured that the task becomes easier with practice, and you may be surprised + at how simple the C-code can be to understand. + Even if you don't think you can write C-code from scratch, it is much easier + to understand and modify already-written source code then create it +\emph on +de novo +\emph default +. + +\end_layout + +\begin_layout Standard +Python extensions are especially straightforward to understand because they + all have a very similar structure. + Admittedly, NumPy is not a trivial extension to Python, and may take a + little more snooping to grasp. + This is especially true because of the code-generation techniques, which + simplify maintenance of very similar code, but can make the code a little + less readable to beginners. + Still, with a little persistence, the code can be opened to your understanding. + It is my hope, that this guide to the C-API can assist in the process of + becoming familiar with the compiled-level work that can be done with NumPy + in order to squeeze that last bit of necessary speed out of your code. +\end_layout + +\begin_layout Standard +Several new types are defined in the C-code. + Most of these are accessible from Python, but a few are not exposed due + to their limited use. + Every new Python type has an associated PyObject * with an internal structure + that includes a pointer to a +\begin_inset Quotes eld +\end_inset + +method table +\begin_inset Quotes erd +\end_inset + + that defines how the new object behaves in Python. + When you receive a Python object into C code, you always get a pointer + to a +\family typewriter +PyObject +\family default + structure. + Because a +\family typewriter +PyObject +\family default + structure is very generic and defines only +\family typewriter +PyObject_HEAD +\family default +, by itself it is not very interesting. + However, different objects contain more details after the +\family typewriter +PyObject_HEAD +\family default + (but you have to cast to the correct type to access them --- or use accessor + functions or macros). + +\end_layout + +\begin_layout Section +New Python Types Defined +\end_layout + +\begin_layout Standard +Python types are the functional equivalent in C of classes in Python. + By constructing a new Python type you make available a new object for Python. + The ndarray object is an example of a new type defined in C. + New types are defined in C by two basic steps: +\end_layout + +\begin_layout Enumerate +creating a C-structure (usually named Py<Name>Object) that is binary-compatible + with the +\family typewriter +PyObject +\family default + structure itself but holds the additional information needed for that particula +r object; +\end_layout + +\begin_layout Enumerate +populating the +\family typewriter +PyTypeObject +\family default + table (pointed to by the ob_type member of the +\family typewriter +PyObject +\family default + structure) with pointers to functions that implement the desired behavior + for the type. + +\end_layout + +\begin_layout Standard +Instead of special method names which define behavior for Python classes, + there are +\begin_inset Quotes eld +\end_inset + +function tables +\begin_inset Quotes erd +\end_inset + + which point to functions that implement the desired results. + Since Python 2.2, the PyTypeObject itself has become dynamic which allows + C types that can be +\begin_inset Quotes eld +\end_inset + +sub-typed +\begin_inset Quotes erd +\end_inset + + from other C-types in C, and sub-classed in Python. + The children types inherit the attributes and methods from their parent(s). + +\end_layout + +\begin_layout Standard +There are two major new types: the ndarray ( +\family typewriter +PyArray_Type +\family default +) and the ufunc ( +\family typewriter +PyUFunc_Type +\family default +). + Additional types play a supportive role: the +\family typewriter +PyArrayIter_Type +\family default +, the +\family typewriter +PyArrayMultiIter_Type +\family default +, and the +\family typewriter +PyArrayDescr_Type +\family default +. + The +\family typewriter +PyArrayIter_Type +\family default + is the type for a flat iterator for an ndarray (the object that is returned + when getting the flat attribute). + The +\family typewriter +PyArrayMultiIter_Type +\family default + is the type of the object returned when calling +\family typewriter +broadcast +\family default +(). + It handles iteration and broadcasting over a collection of nested sequences. + Also, the +\family typewriter +PyArrayDescr_Type +\family default + is the data-type-descriptor type whose instances describe the data. + Finally, there are 21 new scalar-array types which are new Python scalars + corresponding to each of the fundamental data types available for arrays. + An additional 10 other types are place holders that allow the array scalars + to fit into a hierarchy of actual Python types. + +\end_layout + +\begin_layout Subsection +PyArray_Type +\end_layout + +\begin_layout Standard +The Python type of the ndarray is +\family typewriter +PyArray_Type +\family default + +\begin_inset LatexCommand index +name "PyArray\\_Type" + +\end_inset + +. + In C, every ndarray is a pointer to a +\family typewriter +PyArrayObject +\family default + structure. + The ob_type member of this structure contains a pointer to the +\family typewriter +PyArray_Type +\family default + typeobject. + +\end_layout + +\begin_layout Standard +The +\family typewriter +PyArrayObject +\family default + C-structure contains all of the required information for an array. + All instances of an ndarray (and its subclasses) will have this structure. + For future compatibility, these structure members should normally be accessed + using the provided macros. + If you need a shorter name, then you can make use of +\family typewriter +NPY_AO +\family default + which is defined to be equivalent to +\family typewriter +PyArrayObject +\family default +. +\end_layout + +\begin_layout LyX-Code +typedef struct PyArrayObject { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +char * +\emph default +data; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nd; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp * +\emph default +dimensions; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp * +\emph default +strides; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject * +\emph default +base; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_Descr * +\emph default +descr; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + flags; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject * +\emph default +weakreflist; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArrayObject +\emph default +; +\end_layout + +\begin_layout Description +PyObject_HEAD This is needed by all Python objects. + It consists of (at least) a reference count member ( +\family typewriter +ob_refcnt +\family default +) and a pointer to the typeobject ( +\family typewriter +ob_type +\family default +). + (Other elements may also be present if Python was compiled with special + options see Include/object.h in the Python source tree for more information). + The ob_type member points to a Python type object. + +\end_layout + +\begin_layout Description +data A pointer to the first element of the array. + This pointer can (and normally should) be recast to the data type of the + array. + +\end_layout + +\begin_layout Description +nd An integer providing the number of dimensions for this array. + When nd is 0, the array is sometimes called a rank-0 array. + Such arrays have undefined dimensions and strides and cannot be accessed. + +\family typewriter +NPY_MAXDIMS +\family default + is the largest number of dimensions for any array. +\end_layout + +\begin_layout Description +dimensions An array of integers providing the shape in each dimension as + long as nd +\begin_inset Formula $\geq$ +\end_inset + +1. + The integer is always large enough to hold a pointer on the platform, so + the dimension size is only limited by memory. + +\end_layout + +\begin_layout Description +strides An array of integers providing for each dimension the number of + bytes that must be skipped to get to the next element in that dimension. + +\end_layout + +\begin_layout Description +base This member is used to hold a pointer to another Python object that + is related to this array. + There are two use cases: 1) If this array does not own its own memory, + then base points to the Python object that owns it (perhaps another array + object), 2) If this array has the +\family typewriter +NPY_UPDATEIFCOPY +\family default + flag set, then this array is a working copy of a +\begin_inset Quotes eld +\end_inset + +misbehaved +\begin_inset Quotes erd +\end_inset + + array. + As soon as this array is deleted, the array pointed to by base will be + updated with the contents of this array. + +\end_layout + +\begin_layout Description +descr A pointer to a data-type descriptor object (see below). + The data-type descriptor object is an instance of a new built-in type which + allows a generic description of memory. + There is a descriptor structure for each data type supported. + This descriptor structure contains useful information about the type as + well as a pointer to a table of function pointers to implement specific + functionality. +\end_layout + +\begin_layout Description +flags Flags indicating how the memory pointed to by data is to be interpreted. + Possible flags are +\family typewriter +NPY_C_CONTIGUOUS +\family default +, +\family typewriter +NPY_F_CONTIGUOUS +\family default +, +\family typewriter +NPY_OWNDATA +\family default +, +\family typewriter +NPY_ALIGNED +\family default +, +\family typewriter +NPY_WRITEABLE +\family default +, and +\family typewriter +NPY_UPDATEIFCOPY +\family default +. +\end_layout + +\begin_layout Description +weakreflist This member allows array objects to have weak references (using + the weakref module). + +\end_layout + +\begin_layout Subsection +PyArrayDescr_Type +\end_layout + +\begin_layout Standard +The +\family typewriter +PyArrayDescr_Type +\family default + +\begin_inset LatexCommand index +name "PyArrayDescr\\_Type" + +\end_inset + + is the built-in type of the data-type-descriptor objects used to describe + how the bytes comprising the array are to be interpreted. + There are 21 statically-defined +\family typewriter +PyArray_Descr +\family default + objects for the built-in data-types. + While these participate in reference counting, their reference count should + never reach zero. + There is also a dynamic table of user-defined +\family typewriter +PyArray_Descr +\family default + objects that is also maintained. + Once a data-type-descriptor object is +\begin_inset Quotes eld +\end_inset + +registered +\begin_inset Quotes erd +\end_inset + + it should never be deallocated either. + The function +\family typewriter +PyArray_DescrFromType +\family default +(...) can be used to retrieve a +\family typewriter +PyArray_Descr +\family default + object from an enumerated type-number (either built-in or user-defined). + The format of the structure that lies at the heart of the +\family typewriter +PyArrayDescr_Type +\family default + is. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +PyTypeObject * +\emph default +typeobj; +\end_layout + +\begin_layout LyX-Code + +\emph on +char +\emph default + kind; +\end_layout + +\begin_layout LyX-Code + +\emph on +char +\emph default + type; +\end_layout + +\begin_layout LyX-Code + +\emph on +char +\emph default + byteorder; +\end_layout + +\begin_layout LyX-Code + +\emph on +char +\emph default + hasobject; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + type_num; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + elsize; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + alignment; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ArrayDescr +\emph default + *subarray; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject +\emph default + *fields; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ArrFuncs +\emph default + *f; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArray_Descr +\emph default +; +\end_layout + +\begin_layout Description +typeobj Pointer to a typeobject that is the corresponding Python type for + the elements of this array. + For the builtin types, this points to the corresponding array scalar. + For user-defined types, this should point to a user-defined typeobject. + This typeobject can either inherit from array scalars or not. + If it does not inherit from array scalars, then the +\family typewriter +NPY_USE_GETITEM +\family default + and +\family typewriter +NPY_USE_SETITEM +\family default + flags should be set in the +\family typewriter +hasobject +\family default + flag. +\end_layout + +\begin_layout Description +kind A character code indicating the kind of array (using the array interface + typestring notation). + A 'b' represents Boolean, a 'i' represents signed integer, a 'u' represents + unsigned integer, 'f' represents floating point, 'c' represents complex + floating point, 'S' represents 8-bit character string, 'U' represents 32-bit/ch +aracter unicode string, and 'V' repesents arbitrary. + +\end_layout + +\begin_layout Description +type A traditional character code indicating the data type. + +\end_layout + +\begin_layout Description +byteorder A character indicating the byte-order: '>' (big-endian), '<' (little-e +ndian), '=' (native), '|' (irrelevant, ignore). + All builtin data-types have byteorder '='. + +\end_layout + +\begin_layout Description +hasobject A data-type bit-flag that determines if the data-type exhibits + object-array like behavior. + Each bit in this member is a flag which are named as: +\end_layout + +\begin_deeper +\begin_layout Description +NPY_ITEM_REFCOUNT\InsetSpace ~ +(NPY_ITEM_HASOBJECT) Indicates that items of this data-type + must be reference counted (using +\family typewriter +Py_INCREF +\family default + and +\family typewriter +Py_DECREF +\family default +). + +\end_layout + +\begin_layout Description +NPY_ITEM_LISTPICKLE Indicates arrays of this data-type must be converted + to a list before pickling. + +\end_layout + +\begin_layout Description +NPY_ITEM_IS_POINTER Indicates the item is a pointer to some other data-type +\end_layout + +\begin_layout Description +NPY_NEEDS_INIT Indicates memory for this data-type must be initialized (set + to 0) on creation. + +\end_layout + +\begin_layout Description +NPY_NEEDS_PYAPI Indicates this data-type requires the Python C-API during + access (so don't give up the GIL if array access is going to be needed). + +\end_layout + +\begin_layout Description +NPY_USE_GETITEM On array access use the +\family typewriter +f->getitem +\family default + function pointer instead of the standard conversion to an array scalar. + Must use if you don't define an array scalar to go along with the data-type. + +\end_layout + +\begin_layout Description +NPY_USE_SETITEM When creating a 0-d array from an array scalar use +\family typewriter +f->setitem +\family default + instead of the standard copy from an array scalar. + Must use if you don't define an array scalar to go along with the data-type. + +\end_layout + +\begin_layout Description +NPY_FROM_FIELDS The bits that are inherited for the parent data-type if + these bits are set in any field of the data-type. + Currently ( +\family typewriter +NPY_NEEDS_INIT +\family default + | +\family typewriter +NPY_LIST_PICKLE +\family default + | +\family typewriter +NPY_ITEM_REFCOUNT +\family default + | +\family typewriter +NPY_NEEDS_PYAPI +\family default +). + +\end_layout + +\begin_layout Description +NPY_OBJECT_DTYPE_FLAGS Bits set for the object data-type: ( +\family typewriter +NPY_LIST_PICKLE +\family default + | +\family typewriter +NPY_USE_GETITEM +\family default + | +\family typewriter +NPY_ITEM_IS_POINTER +\family default + | +\family typewriter +NPY_REFCOUNT +\family default + | +\family typewriter +NPY_NEEDS_INIT +\family default + | +\family typewriter +NPY_NEEDS_PYAPI +\family default +). + +\end_layout + +\begin_layout Description +PyDataType_FLAGCHK ( +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + flags) Return true if all the given flags are set for the data-type object. + +\end_layout + +\begin_layout Description +PyDataType_REFCHK ( +\family typewriter +PyArray_Descr* +\family default + dtype) Equivalent to +\family typewriter +PyDataType_FLAGCHK +\family default +( +\emph on +dtype +\emph default +, +\family typewriter +NPY_ITEM_REFCOUNT +\family default +). +\end_layout + +\end_deeper +\begin_layout Description +type_num A number that uniquely identifies the data type. + For new data-types, this number is assigned when the data-type is registered. +\end_layout + +\begin_layout Description +elsize For data types that are always the same size (such as long), this + holds the size of the data type. + For flexible data types where different arrays can have a different elementsize +, this should be 0. +\end_layout + +\begin_layout Description +alignment A number providing alignment information for this data type. + Specifically, it shows how far from the start of a 2-element structure + (whose first element is a +\family typewriter +char +\family default +), the compiler places an item of this type: +\family typewriter +offsetof(struct {char c; type v;}, v) +\end_layout + +\begin_layout Description +subarray If this is non- +\family typewriter +NULL +\family default +, then this data-type descriptor is a C-style contiguous array of another + data-type descriptor. + In other-words, each element that this descriptor describes is actually + an array of some other base descriptor. + This is most useful as the data-type descriptor for a field in another + data-type descriptor. + The fields member should be +\family typewriter +NULL +\family default + if this is non- +\family typewriter +NULL +\family default + (the fields member of the base descriptor can be non- +\family typewriter +NULL +\family default + however). + The +\family typewriter +PyArray_ArrayDescr +\family default + structure is defined using +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_Descr +\emph default + *base; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject +\emph default + *shape; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArray_ArrayDescr; +\end_layout + +\begin_layout Description +\InsetSpace ~ + The elements of this structure are: +\end_layout + +\begin_deeper +\begin_layout Description +base The data-type-descriptor object of the base-type. + +\end_layout + +\begin_layout Description +shape The shape (always C-style contiguous) of the sub-array as a Python + tuple. + +\end_layout + +\end_deeper +\begin_layout Description +fields If this is non-NULL, then this data-type-descriptor has fields described + by a Python dictionary whose keys are names (and also titles if given) + and whose values are tuples that describe the fields. + Recall that a data-type-descriptor always describes a fixed-length set + of bytes. + A field is a named sub-region of that total, fixed-length collection. + A field is described by a tuple composed of another data-type-descriptor + and a byte offset. + Optionally, the tuple may contain a title which is normally a Python string. + These tuples are placed in this dictionary keyed by name (and also title + if given). + +\end_layout + +\begin_layout Description +f A pointer to a structure containing functions that the type needs to implement + internal features. + These functions are not the same thing as the universal functions (ufuncs) + described later. + Their signatures can vary arbitrarily. + Not all of these function pointers must be defined for a given type. + The required members are +\family typewriter +nonzero +\family default +, +\family typewriter +copyswap +\family default +, +\family typewriter +copyswapn +\family default +, +\family typewriter +setitem +\family default +, +\family typewriter +getitem +\family default +, and +\family typewriter +cast +\family default +. + These are assumed to be non- +\family typewriter +NULL +\family default + and +\family typewriter +NULL +\family default + entries will cause a program crash. + The other functions may be +\family typewriter +NULL +\family default + which will just mean reduced functionality for that data-type. + (Also, the nonzero function will be filled in with a default function if + it is +\family typewriter +NULL +\family default + when you register a user-defined data-type). +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + +\emph on + PyArray_VectorUnaryFunc +\emph default + +\emph on +* +\emph default +cast[PyArray_NTYPES]; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_GetItemFunc * +\emph default +getitem; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_SetItemFunc * +\emph default +setitem; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_CopySwapNFunc * +\emph default +copyswapn; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_CopySwapFunc * +\emph default +copyswap; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_CompareFunc * +\emph default +compare; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ArgFunc * +\emph default +argmax; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_DotFunc * +\emph default +dotfunc; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ScanFunc * +\emph default +scanfunc; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_FromStrFunc +\emph default + *fromstr; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_NonzeroFunc * +\emph default +nonzero; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_FillFunc +\emph default + *fill; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_FillWithScalarFunc +\emph default + *fillwithscalar; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_SortFunc +\emph default + *sort[PyArray_NSORTS]; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ArgSortFunc +\emph default + *argsort[PyArray_NSORTS]; +\newline + +\emph on +PyObject +\emph default + *castdict; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArray_ScalarKindFunc +\emph default + *scalarkind; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + **cancastscalarkindto; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + *cancastto; +\end_layout + +\begin_layout LyX-Code + +\shape italic +int +\shape default + listpickle +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArray_ArrFuncs +\emph default +; +\end_layout + +\begin_layout Description +\InsetSpace ~ + The concept of a behaved segment is used in the description of the function + pointers. + A behaved segment is one that is aligned and in native machine byte-order + for the data-type. + The +\family typewriter +nonzero +\family default +, +\family typewriter +copyswap +\family default +, +\family typewriter +copyswapn +\family default +, +\family typewriter +getitem +\family default +, and +\family typewriter +setitem +\family default + functions can (and must) deal with mis-behaved arrays. + The other functions require behaved memory segments. +\end_layout + +\begin_deeper +\begin_layout Description +cast ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + from, +\family typewriter +void* +\family default + to, +\family typewriter +npy_intp +\family default + n, +\family typewriter +void* +\family default + fromarr, +\family typewriter +void* +\family default + toarr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + An array of function pointers to cast from the current type to all of the + other builtin types. + Each function casts a contiguous, aligned, and notswapped buffer pointed + at by +\emph on +from +\emph default + to a contiguous, aligned, and notswapped buffer pointed at by +\emph on +to +\emph default + The number of items to cast is given by +\emph on +n +\emph default +, and the arguments +\emph on +fromarr +\emph default + and +\emph on +toarr +\emph default + are interpreted as PyArrayObjects for flexible arrays to get itemsize informati +on. +\end_layout + +\begin_layout Description +getitem ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that returns a standard Python object from a single + element of the array object +\emph on +arr +\emph default + pointed to by +\emph on +data +\emph default +. + This function must be able to deal with +\begin_inset Quotes eld +\end_inset + +misbehaved +\begin_inset Quotes erd +\end_inset + + (misaligned and/or swapped) arrays correctly. + +\end_layout + +\begin_layout Description +setitem ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + item, +\family typewriter +void* +\family default + data, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that sets the Python object +\emph on +item +\emph default + into the array, +\emph on +arr +\emph default +, at the position pointed to by +\emph on +data +\emph default +. + This function deals with +\begin_inset Quotes eld +\end_inset + +misbehaved +\begin_inset Quotes erd +\end_inset + + arrays. + If successful, a zero is returned, otherwise, a negative one is returned + (and a Python error set). + +\end_layout + +\begin_layout Description +copyswapn ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + dest, +\family typewriter +npy_intp +\family default + dstride, +\family typewriter +void* +\family default + src, +\family typewriter +npy_intp +\family default + sstride, +\family typewriter +npy_intp +\family default + n, +\family typewriter +int +\family default + swap, void *arr) +\end_layout + +\begin_layout Description +copyswap ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + dest, +\family typewriter +void* +\family default + src, +\family typewriter +int +\family default + swap, void *arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + These members are both pointers to functions to copy data from +\emph on +src +\emph default + to +\emph on +dest +\emph default + and +\emph on +swap +\emph default + if indicated. + The value of arr is only used for flexible ( +\family typewriter +NPY_STRING +\family default +, +\family typewriter +NPY_UNICODE +\family default +, and +\family typewriter +NPY_VOID +\family default +) arrays (and is obtained from +\family typewriter +arr->descr->elsize +\family default +). + The second function copies a single value, while the first loops over n + values with the provided strides. + These functions can deal with misbehaved +\emph on +src +\emph default + data. + If +\emph on +src +\emph default + is NULL then no copy is performed. + If +\emph on +swap +\emph default + is 0, then no byteswapping occurs. + It is assumed that +\emph on +dest +\emph default + and +\emph on +src +\emph default + do not overlap. + If they overlap, then use +\family typewriter +memmove +\family default +(...) first followed by +\family typewriter +copyswap(n) +\family default + with NULL valued +\family typewriter +src +\family default +. +\end_layout + +\begin_layout Description +compare ( +\family typewriter +int +\family default +) ( +\family typewriter +const void* +\family default + d1, +\family typewriter +const void* +\family default + d2, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that compares two elements of the array, +\family typewriter +arr +\family default +, pointed to by +\family typewriter +d1 +\family default + and +\family typewriter +d2 +\family default +. + This function requires behaved arrays. + The return value is 1 if * +\family typewriter +d1 +\family default + > * +\family typewriter +d2 +\family default +, 0 if * +\family typewriter +d1 +\family default + == * +\family typewriter +d2 +\family default +, and -1 if * +\family typewriter +d1 +\family default + < * +\family typewriter +d2 +\family default +. + The array object arr is used to retrieve itemsize and field information + for flexible arrays. +\end_layout + +\begin_layout Description +argmax ( +\family typewriter +int +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +npy_intp +\family default + n, +\family typewriter +npy_intp* +\family default + max_ind, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that retrieves the index of the largest of +\family typewriter +n +\family default + elements in +\family typewriter +arr +\family default + beginning at the element pointed to by +\family typewriter +data +\family default +. + This function requires that the memory segment be contiguous and behaved. + The return value is always 0. + The index of the largest element is returned in +\family typewriter +max_ind +\family default +. +\end_layout + +\begin_layout Description +dotfunc ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + ip1, +\family typewriter +npy_intp +\family default + is1, +\family typewriter +void* +\family default + ip2, +\family typewriter +npy_intp +\family default + is2, +\family typewriter +void* +\family default + op, +\family typewriter +npy_intp +\family default + n, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that multiplies two +\family typewriter +n +\family default +-length sequences together, adds them, and places the result in element + pointed to by +\family typewriter +op +\family default + of +\family typewriter +arr +\family default +. + The start of the two sequences are pointed to by +\family typewriter +ip1 +\family default + and +\family typewriter +ip2 +\family default +. + To get to the next element in each sequence requires a jump of +\family typewriter +is1 +\family default + and +\family typewriter +is2 +\family default + +\emph on +bytes +\emph default +, respectively. + This function requires behaved (though not necessarily contiguous) memory. + +\end_layout + +\begin_layout Description +scanfunc ( +\family typewriter +int +\family default +) ( +\family typewriter +FILE* +\family default + fd, +\family typewriter +void* +\family default + ip , +\family typewriter +void* +\family default + sep , +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that scans (scanf style) one element of the correspondi +ng type from the file descriptor +\family typewriter +fd +\family default + into the array memory pointed to by +\family typewriter +ip +\family default +. + The array is assumed to be behaved. + If +\family typewriter +sep +\family default + is not NULL, then a separator string is also scanned from the file before + returning. + The last argument +\family typewriter +arr +\family default + is the array to be scanned into. + A 0 is returned if the scan is successful. + A negative number indicates something went wrong: -1 means the end of file + was reached before the separator string could be scanned, -4 means that + the end of file was reached before the element could be scanned, and -3 + means that the element could not be interpreted from the format string. + Requires a behaved array. +\end_layout + +\begin_layout Description +fromstr ( +\family typewriter +int +\family default +) ( +\family typewriter +char* +\family default + str, +\family typewriter +void* +\family default + ip, +\family typewriter +char** +\family default + endptr, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that converts the string pointed to by +\family typewriter +str +\family default + to one element of the corresponding type and places it in the memory location + pointed to by +\family typewriter +ip +\family default +. + After the conversion is completed, +\family typewriter +*endptr +\family default + points to the rest of the string. + The last argument +\family typewriter +arr +\family default + is the array into which ip points (needed for variable-size data-types). + Returns 0 on success or -1 on failure. + Requires a behaved array. +\end_layout + +\begin_layout Description +nonzero ( +\family typewriter +Bool +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that returns TRUE if the item of +\family typewriter +arr +\family default + pointed to by +\family typewriter +data +\family default + is nonzero. + This function can deal with misbehaved arrays. + +\end_layout + +\begin_layout Description +fill ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +npy_intp +\family default + length, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that fills a contiguous array of given length with + data. + The first two elements of the array must already be filled-in. + From these two values, a delta will be computed and the values from item + 3 to the end will be computed by repeatedly adding this computed delta. + The data buffer must be well-behaved. +\end_layout + +\begin_layout Description +fillwithscalar ( +\family typewriter +void +\family default +)( +\family typewriter +void* +\family default + buffer, +\family typewriter +npy_intp +\family default + length, +\family typewriter +void* +\family default + value, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to a function that fills a contiguous +\family typewriter +buffer +\family default + of the given +\family typewriter +length +\family default + with a single scalar +\family typewriter +value +\family default + whose address is given. + The final argument is the array which is needed to get the itemsize for + variable-length arrays. + +\end_layout + +\begin_layout Description +sort ( +\family typewriter +int +\family default +) ( +\family typewriter +void* +\family default + start, +\family typewriter +npy_intp +\family default + length, +\family typewriter +void* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + An array of function pointers to a particular sorting algorithms. + A particular sorting algorithm is obtained using a key (so far +\family typewriter +PyArray_QUICKSORT +\family default +, +\family typewriter +PyArray_HEAPSORT +\family default +, and +\family typewriter +PyArray_MERGESORT +\family default + are defined). + These sorts are done in-place assuming contiguous and aligned data. + +\end_layout + +\begin_layout Description +argsort ( +\family typewriter +int +\family default +) ( +\family typewriter +void* +\family default + start, +\family typewriter +npy_intp* +\family default + result, +\family typewriter +npy_intp +\family default + length, void *arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + An array of function pointers to sorting algorithms for this data type. + The same sorting algorithms as for sort are available. + The indices producing the sort are returned in result (which must be initialize +d with indices 0 to length-1 inclusive). + +\end_layout + +\begin_layout Description +castdict +\end_layout + +\begin_layout Description +\InsetSpace ~ + Either +\family typewriter +NULL +\family default + or a dictionary containing low-level casting functions for user-defined + data-types. + Each function is wrapped in a +\family typewriter +PyCObject* +\family default + and keyed by the data-type number. + +\end_layout + +\begin_layout Description +scalarkind ( +\family typewriter +PyArray_SCALARKIND +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A function to determine how scalars of this type should be interpreted. + The argument is +\family typewriter +NULL +\family default + or a 0-dimensional array containing the data (if that is needed to determine + the kind of scalar). + The return value must be of type +\family typewriter +PyArray_SCALARKIND +\family default +. + +\end_layout + +\begin_layout Description +cancastscalarkindto +\end_layout + +\begin_layout Description +\InsetSpace ~ + Either +\family typewriter +NULL +\family default + or an array of +\family typewriter +PyArray_NSCALARKINDS +\family default + pointers. + These pointers should each be either +\family typewriter +NULL +\family default + or a pointer to an array of integers (terminated by +\family typewriter +PyArray_NOTYPE +\family default +) indicating data-types that a scalar of this data-type of the specified + kind can be cast to safely (this usually means without losing precision). +\end_layout + +\begin_layout Description +cancastto +\end_layout + +\begin_layout Description +\InsetSpace ~ + Either +\family typewriter +NULL +\family default + or an array of integers (terminated by +\family typewriter +PyArray_NOTYPE +\family default +) indicated data-types that this data-type can be cast to safely (this usually + means without losing precision). +\end_layout + +\begin_layout Description +listpickle +\end_layout + +\begin_layout Description +\InsetSpace ~ + Unused. +\end_layout + +\end_deeper +\begin_layout Standard +The +\family typewriter +PyArray_Type +\family default + typeobject implements many of the features of Python objects including + the tp_as_number, tp_as_sequence, tp_as_mapping, and tp_as_buffer interfaces. + The rich comparison (tp_richcompare) is also used along with new-style + attribute lookup for methods (tp_methods) and properties (tp_getset). + The +\family typewriter +PyArray_Type +\family default + can also be sub-typed. + +\end_layout + +\begin_layout Tip +The tp_as_number methods use a generic approach to call whatever function + has been registered for handling the operation. + The function PyNumeric_SetOps(..) can be used to register functions to handle + particular mathematical operations (for all arrays). + When the umath module is imported, it sets the numeric operations for all + arrays to the corresponding ufuncs. + +\newline +The tp_str and tp_repr methods can also be altered using PyString_SetStringFunc +tion(...). +\end_layout + +\begin_layout Subsection +PyUFunc_Type +\end_layout + +\begin_layout Standard +The ufunc object is implemented by creation of the +\family typewriter +PyUFunc_Type +\family default + +\begin_inset LatexCommand index +name "PyUFunc\\_Type" + +\end_inset + +. + It is a very simple type that implements only basic getattribute behavior, + printing behavior, and has call behavior which allows these objects to + act like functions. + The basic idea behind the ufunc is to hold a reference to fast 1-dimensional + (vector) loops for each data type that supports the operation. + These one-dimensional loops all have the same signature and are the key + to creating a new ufunc. + They are called by the generic looping code as appropriate to implement + the N-dimensional function. + There are also some generic 1-d loops defined for floating and complexfloating + arrays that allow you to define a ufunc using a single scalar function + ( +\emph on +e.g. + +\emph default + atanh). + +\end_layout + +\begin_layout Standard +The core of the ufunc is the +\family typewriter +PyUFuncObject +\family default + which contains all the information needed to call the underlying C-code + loops that perform the actual work. + It has the following structure. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nin; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nout; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nargs; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + identity; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyUFuncGenericFunction * +\emph default +functions; +\end_layout + +\begin_layout LyX-Code + +\emph on +void ** +\emph default +data; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + ntypes; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + check_return; +\end_layout + +\begin_layout LyX-Code + +\emph on +char * +\emph default +name; +\end_layout + +\begin_layout LyX-Code + +\emph on +char * +\emph default +types; +\end_layout + +\begin_layout LyX-Code + +\emph on +char * +\emph default +doc; +\end_layout + +\begin_layout LyX-Code + +\emph on +void * +\emph default +ptr; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject * +\emph default +obj; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject * +\emph default +userloops; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyUFuncObject +\emph default +; +\end_layout + +\begin_layout Description +PyObject_HEAD required for all Python objects. +\end_layout + +\begin_layout Description +nin The number of input arguments. +\end_layout + +\begin_layout Description +nout The number of output arguments. +\end_layout + +\begin_layout Description +nargs The total number of arguments ( +\emph on +nin +\emph default ++ +\emph on +nout +\emph default +). + This must be less than +\family typewriter +NPY_MAXARGS +\family default +. +\end_layout + +\begin_layout Description +identity Either +\family typewriter +PyUFunc_One +\family default +, +\family typewriter +PyUFunc_Zero +\family default +, or +\family typewriter +PyUFunc_None +\family default + to indicate the identity for this operation. + It is only used for a reduce-like call on an empty array. +\end_layout + +\begin_layout Description +functions ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + extradata ) +\end_layout + +\begin_layout Description +\InsetSpace ~ + An array of function pointers --- one for each data type supported by the + ufunc. + This is the vector loop that is called to implement the underlying function + +\emph on +dims +\emph default +[0] times. + The first argument, +\emph on +args +\emph default +, is an array of +\emph on +nargs +\emph default + pointers to behaved memory. + Pointers to the data for the input arguments are first, followed by the + pointers to the data for the output arguments. + How many bytes must be skipped to get to the next element in the sequence + is specified by the corresponding entry in the +\emph on +steps +\emph default + array. + The last argument allows the loop to receive extra information. + This is commonly used so that a single, generic vector loop can be used + for multiple functions. + In this case, the actual scalar function to call is passed in as +\emph on +extradata +\emph default +. + The size of this function pointer array is ntypes. + +\end_layout + +\begin_layout Description +data Extra data to be passed to the 1-d vector loops or +\family typewriter +NULL +\family default + if no extra-data is needed. + This C-array must be the same size ( +\emph on +i.e. + +\emph default + ntypes) as the functions array. + +\family typewriter +NULL +\family default + is used if extra_data is not needed. + Several C-API calls for UFuncs are just 1-d vector loops that make use + of this extra data to receive a pointer to the actual function to call. + +\end_layout + +\begin_layout Description +ntypes The number of supported data types for the ufunc. + This number specifies how many different 1-d loops (of the builtin data + types) are available. + +\end_layout + +\begin_layout Description +check_return Obsolete and unused. + However, it is set by the corresponding entry in the main ufunc creation + routine: +\family typewriter +PyUFunc_FromFuncAndData +\family default +(...). +\end_layout + +\begin_layout Description +name A string name for the ufunc. + This is used dynamically to build the __doc__ attribute of ufuncs. +\end_layout + +\begin_layout Description +types An array of +\emph on +nargs +\series bold +\emph default + +\begin_inset Formula $\times$ +\end_inset + + +\series default +\emph on +ntypes +\emph default + 8-bit type_numbers which contains the type signature for the function for + each of the supported (builtin) data types. + For each of the +\emph on +ntypes +\emph default + functions, the corresponding set of type numbers in this array shows how + the +\emph on +args +\emph default + argument should be interpreted in the 1-d vector loop. + These type numbers do not have to be the same type and mixed-type ufuncs + are supported. + +\end_layout + +\begin_layout Description +doc Documentation for the ufunc. + Should not contain the function signature as this is generated dynamically + when __doc__ is retrieved. +\end_layout + +\begin_layout Description +ptr Any dynamically allocated memory. + Currently, this is used for dynamic ufuncs created from a python function + to store room for the types, data, and name members. +\end_layout + +\begin_layout Description +obj For ufuncs dynamically created from python functions, this member holds + a reference to the underlying Python function. +\end_layout + +\begin_layout Description +userloops A dictionary of user-defined 1-d vector loops (stored as CObject + ptrs) for user-defined types. + A loop may be registered by the user for any user-defined type. + It is retrieved by type number. + User defined type numbers are always larger than +\family typewriter +NPY_USERDEF +\family default +. + +\end_layout + +\begin_layout Subsection +PyArrayIter_Type +\end_layout + +\begin_layout Standard +This +\begin_inset LatexCommand index +name "PyArrayIter\\_Type" + +\end_inset + + is an iterator object that makes it easy to loop over an N-dimensional + array. + It is the object returned from the flat attribute of an ndarray. + It is also used extensively throughout the implementation internals to + loop over an N-dimensional array. + The tp_as_mapping interface is implemented so that the iterator object + can be indexed (using 1-d indexing), and a few methods are implemented + through the tp_methods table. + This object implements the next method and can be used anywhere an iterator + can be used in Python. +\end_layout + +\begin_layout Standard +The C-structure corresponding to an object of +\family typewriter +PyArrayIter_Type +\family default + is the +\family typewriter +PyArrayIterObject +\family default +. + The +\family typewriter +PyArrayIterObject +\family default + is used to keep track of a pointer into an N-dimensional array. + It contains associated information used to quickly march through the array. + The pointer can be adjusted in three basic ways: 1) advance to the +\begin_inset Quotes eld +\end_inset + +next +\begin_inset Quotes erd +\end_inset + + position in the array in a C-style contiguous fashion, 2) advance to an + arbitrary N-dimensional coordinate in the array, and 3) advance to an arbitrary + one-dimensional index into the array. + The members of the +\family typewriter +PyArrayIterObject +\family default + structure are used in these calculations. + Iterator objects keep their own dimension and strides information about + an array. + This can be adjusted as needed for +\begin_inset Quotes eld +\end_inset + +broadcasting, +\begin_inset Quotes erd +\end_inset + + or to loop over only specific dimensions. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nd_m1; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + index; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + size; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + coordinates +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + dims_m1 +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + strides +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + backstrides +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + factors +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArrayObject * +\emph default +ao; +\end_layout + +\begin_layout LyX-Code + +\emph on +char * +\emph default +dataptr; +\end_layout + +\begin_layout LyX-Code + +\emph on +Bool +\emph default + contiguous; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArrayIterObject +\emph default +; +\end_layout + +\begin_layout Description +nd_m1 +\begin_inset Formula $N-1$ +\end_inset + + where +\begin_inset Formula $N$ +\end_inset + + is the number of dimensions in the underlying array. +\end_layout + +\begin_layout Description +index The current 1-d index into the array. +\end_layout + +\begin_layout Description +size The total size of the underlying array. +\end_layout + +\begin_layout Description +coordinates An +\begin_inset Formula $N$ +\end_inset + +-dimensional index into the array. +\end_layout + +\begin_layout Description +dims_m1 The size of the array minus 1 in each dimension. +\end_layout + +\begin_layout Description +strides The strides of the array. + How many bytes needed to jump to the next element in each dimension. + +\end_layout + +\begin_layout Description +backstrides How many bytes needed to jump from the end of a dimension back + to its beginning. + Note that +\emph on +backstrides +\emph default +[k]= +\emph on +strides +\emph default +[k]*d +\emph on +ims_m1 +\emph default +[k], but it is stored here as an optimization. +\end_layout + +\begin_layout Description +factors This array is used in computing an N-d index from a 1-d index. + It contains needed products of the dimensions. + +\end_layout + +\begin_layout Description +ao A pointer to the underlying ndarray this iterator was created to represent. +\end_layout + +\begin_layout Description +dataptr This member points to an element in the ndarray indicated by the + index. +\end_layout + +\begin_layout Description +contiguous This flag is true if the underlying array is +\family typewriter +NPY_C_CONTIGUOUS +\family default +. + It is used to simplify calculations when possible. + +\end_layout + +\begin_layout Standard +How to use an array iterator on a C-level is explained more fully in later + sections. + Typically, you do not need to concern yourself with the internal structure + of the iterator object, and merely interact with it through the use of + the macros +\family typewriter +PyArray_ITER_NEXT +\family default +(it), +\family typewriter +PyArray_ITER_GOTO +\family default +(it, dest), or +\family typewriter +PyArray_ITER_GOTO1D +\family default +(it, index). + All of these macros require the argument +\emph on +it +\emph default + to be a +\family typewriter +PyArrayIterObject* +\family default +. + +\end_layout + +\begin_layout Subsection +PyArrayMultiIter_Type +\end_layout + +\begin_layout Standard +This type provides an iterator that encapsulates the concept of broadcasting. + It allows +\begin_inset Formula $N$ +\end_inset + + arrays to be broadcast together so that the loop progresses in C-style + contiguous fashion over the broadcasted array. + The corresponding C-structure is the +\family typewriter +PyArrayMultiIterObject +\family default + whose memory layout must begin any object, +\emph on +obj +\emph default +, passed in to the +\family typewriter +PyArray_Broadcast +\family default +(obj) function. + Broadcasting is performed by adjusting array iterators so that each iterator + represents the broadcasted shape and size, but has its strides adjusted + so that the correct element from the array is used at each iteration. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + numiter; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + size; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + index; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nd; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + dimensions +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code + +\emph on +PyArrayIterObject * +\emph default +iters +\emph on +[NPY_MAXDIMS] +\emph default +; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArrayMultiIterObject +\emph default +; +\end_layout + +\begin_layout Description +PyObject_HEAD Needed at the start of every Python object (holds reference + count and type identification). +\end_layout + +\begin_layout Description +numiter The number of arrays that need to be broadcast to the same shape. +\end_layout + +\begin_layout Description +size The total broadcasted size. +\end_layout + +\begin_layout Description +index The current (1-d) index into the broadcasted result. +\end_layout + +\begin_layout Description +nd The number of dimensions in the broadcasted result. +\end_layout + +\begin_layout Description +dimensions The shape of the broadcasted result (only +\family typewriter +nd +\family default + slots are used). +\end_layout + +\begin_layout Description +iters An array of iterator objects that holds the iterators for the arrays + to be broadcast together. + On return, the iterators are adjusted for broadcasting. + +\end_layout + +\begin_layout Subsection +PyArrayFlags_Type +\end_layout + +\begin_layout Standard +When the flags attribute is retrieved from Python, a special builtin object + of this type is constructed. + This special type makes it easier to work with the different flags by accessing + them as attributes or by accessing them as if the object were a dictionary + with the flag names as entries. + +\end_layout + +\begin_layout Subsection +ScalarArrayTypes +\end_layout + +\begin_layout Standard +There is a Python type for each of the different built-in data types that + can be present in the array Most of these are simple wrappers around the + corresponding data type in C. + The C-names for these types are +\series bold +Py +\series default +<TYPE> +\series bold +ArrType_Type +\series default + where <TYPE> can be +\end_layout + +\begin_layout Quote + +\series bold +Bool +\series default +, +\series bold +Byte +\series default +, +\series bold +Short +\series default +, +\series bold +Int +\series default +, +\series bold +Long +\series default +, +\series bold +LongLong +\series default +, +\series bold +UByte +\series default +, +\series bold +UShort +\series default +, +\series bold +UInt +\series default +, +\series bold +ULong +\series default +, +\series bold +ULongLong +\series default +, +\series bold +Float +\series default +, +\series bold +Double +\series default +, +\series bold +LongDouble +\series default +, +\series bold +CFloat +\series default +, +\series bold +CDouble +\series default +, +\series bold +CLongDouble +\series default +, +\series bold +String +\series default +, +\series bold +Unicode +\series default +, +\series bold +Void +\series default +, and +\series bold +Object +\series default +. + +\end_layout + +\begin_layout Standard +These type names are part of the C-API and can therefore be created in extension + C-code. + There is also a +\family typewriter +PyIntpArrType_Type +\family default + and a +\family typewriter +PyUIntpArrType_Type +\family default + that are simple substitutes for one of the integer types that can hold + a pointer on the platform. + The structure of these scalar objects is not exposed to C-code. + The function +\family typewriter +PyArray_ScalarAsCtype +\family default +(..) can be used to extract the C-type value from the array scalar and the + function +\family typewriter +PyArray_Scalar +\family default +(...) can be used to construct an array scalar from a C-value. + +\end_layout + +\begin_layout Section +Other C-Structures +\end_layout + +\begin_layout Standard +A few new C-structures were found to be useful in the development of NumPy. + These C-structures are used in at least one C-API call and are therefore + documented here. + The main reason these structures were defined is to make it easy to use + the Python ParseTuple C-API to convert from Python objects to a useful + C-Object. + +\end_layout + +\begin_layout Subsection +PyArray_Dims +\end_layout + +\begin_layout Standard +This structure is very useful when shape and/or strides information is supposed + to be interpreted. + The structure is +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp * +\emph default +ptr; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + len; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArray_Dims +\emph default +; +\end_layout + +\begin_layout Standard +The members of this structure are +\end_layout + +\begin_layout Description +ptr A pointer to a list of ( +\family typewriter +npy_intp +\family default +) integers which usually represent array shape or array strides. + +\end_layout + +\begin_layout Description +len The length of the list of integers. + It is assumed safe to access +\emph on +ptr +\emph default +[0] to +\emph on +ptr +\emph default +[len-1]. + +\end_layout + +\begin_layout Subsection +PyArray_Chunk +\end_layout + +\begin_layout Standard +This is equivalent to the buffer object structure in Python up to the ptr + member. + On 32-bit platforms ( +\emph on +i.e. + +\emph default + if +\family typewriter +NPY_SIZEOF_INT +\family default +== +\family typewriter +NPY_SIZEOF_INTP +\family default +) or in Python 2.5, the len member also matches an equivalent member of the + buffer object. + It is useful to represent a generic single-segment chunk of memory. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD +\end_layout + +\begin_layout LyX-Code + +\emph on +PyObject * +\emph default +base; +\end_layout + +\begin_layout LyX-Code + +\emph on +void * +\emph default +ptr; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp +\emph default + len; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + flags; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArray_Chunk +\emph default +; +\end_layout + +\begin_layout Standard +The members are +\end_layout + +\begin_layout Description +PyObject_HEAD Necessary for all Python objects. + Included here so that the +\family typewriter +PyArray_Chunk +\family default + structure matches that of the buffer object (at least to the len member). + +\end_layout + +\begin_layout Description +base The Python object this chunk of memory comes from. + Needed so that memory can be accounted for properly. +\end_layout + +\begin_layout Description +ptr A pointer to the start of the single-segment chunk of memory. + +\end_layout + +\begin_layout Description +len The length of the segment in bytes. +\end_layout + +\begin_layout Description +flags Any data flags ( +\emph on +e.g. + +\emph default + +\family typewriter +NPY_WRITEABLE +\family default +) that should be used to interpret the memory. + +\end_layout + +\begin_layout Subsection +PyArrayInterface +\end_layout + +\begin_layout Standard +The +\family typewriter +PyArrayInterface +\family default + +\begin_inset LatexCommand index +name "PyArrayInterface" + +\end_inset + + structure is defined so that NumPy and other extension modules can use + the rapid array interface protocol. + The +\series bold +__array_struct__ +\series default + method of an object that supports the rapid array interface protocol should + return a +\family typewriter +PyCObject +\family default + that contains a pointer to a +\family typewriter +PyArrayInterface +\family default + structure with the relevant details of the array. + After the new array is created, the attribute should be +\family typewriter +DECREF +\family default +'d which will free the +\family typewriter +PyArrayInterface +\family default + structure. + Remember to +\family typewriter +INCREF +\family default + the object (whose +\series bold +__array_struct__ +\series default + attribute was retrieved) and point the base member of the new +\family typewriter +PyArrayObject +\family default + to this same object. + In this way the memory for the array will be managed correctly. + +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + two; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + nd; +\end_layout + +\begin_layout LyX-Code + +\emph on +char +\emph default + typekind; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + itemsize; +\end_layout + +\begin_layout LyX-Code + +\emph on +int +\emph default + flags; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp * +\emph default +shape; +\end_layout + +\begin_layout LyX-Code + +\emph on +npy_intp * +\emph default +strides; +\end_layout + +\begin_layout LyX-Code + +\emph on +void * +\emph default +data; +\end_layout + +\begin_layout LyX-Code + PyObject *descr; +\end_layout + +\begin_layout LyX-Code +} +\emph on +PyArrayInterface +\emph default +; +\end_layout + +\begin_layout Description +two the integer 2 as a sanity check. +\end_layout + +\begin_layout Description +nd the number of dimensions in the array. +\end_layout + +\begin_layout Description +typekind A character indicating what kind of array is present according + to the typestring convention with 't' -> bitfield, 'b' -> Boolean, 'i' + -> signed integer, 'u' -> unsigned integer, 'f' -> floating point, 'c' + -> complex floating point, 'O' -> object, 'S' -> string, 'U' -> unicode, + 'V' -> void. +\end_layout + +\begin_layout Description +itemsize the number of bytes each item in the array requires. +\end_layout + +\begin_layout Description +flags any of the bits +\family typewriter +NPY_C_CONTIGUOUS +\family default + (1), +\family typewriter +NPY_F_CONTIGUOUS +\family default + (2), +\family typewriter +NPY_ALIGNED +\family default + (0x100), +\family typewriter +NPY_NOTSWAPPED +\family default + (0x200), or +\family typewriter +NPY_WRITEABLE +\family default + (0x400) to indicate something about the data. + The +\family typewriter +NPY_ALIGNED +\family default +, +\family typewriter +NPY_C_CONTIGUOUS +\family default +, and +\family typewriter +NPY_F_CONTIGUOUS +\family default + flags can actually be determined from the other parameters. + The flag +\family typewriter +NPY_ARR_HAS_DESCR +\family default + (0x800) can also be set to indicate to objects consuming the version 3 + array interface that the descr member of the structure is present (it will + be ignored by objects consuming version 2 of the array interface). + +\end_layout + +\begin_layout Description +shape An array containing the size of the array in each dimension. +\end_layout + +\begin_layout Description +strides An array containing the number of bytes to jump to get to the next + element in each dimension. +\end_layout + +\begin_layout Description +data A pointer +\emph on +to +\emph default + the first element of the array. +\end_layout + +\begin_layout Description +descr A Python object describing the data-type in more detail (currently + an array_description list of tuples). + This can be +\family typewriter +NULL +\family default + if +\emph on +typekind +\emph default + and +\emph on +itemsize +\emph default + provide enough information. + +\end_layout + +\begin_layout Subsection +Internally used structures +\end_layout + +\begin_layout Standard +Internally, the code uses some additional Python objects primarily for memory + management. + These types are not accessible directly from Python, and are not exposed + to the C-API. + They are included here only for completeness and assistance in understanding + the code. + +\end_layout + +\begin_layout Subsubsection +PyUFuncLoopObject +\end_layout + +\begin_layout Standard +A loose wrapper for a C-structure that contains the information needed for + looping. + This is useful if you are trying to understand the ufunc looping code. + The +\family typewriter +PyUFuncLoopObject +\family default + is the associated C-structure. + It is defined in the +\family typewriter +ufuncobject.h +\family default + header. +\end_layout + +\begin_layout Subsubsection +PyUFuncReduceObject +\end_layout + +\begin_layout Standard +A loose wrapper for the C-structure that contains the information needed + for reduce-like methods of ufuncs. + This is useful if you are trying to understand the reduce, accumulate, + and reduce-at code. + The +\family typewriter +PyUFuncReduceObject +\family default + is the associated C-structure. + It is defined in the +\family typewriter +ufuncobject.h +\family default + header. +\end_layout + +\begin_layout Subsubsection +PyUFunc_Loop1d +\end_layout + +\begin_layout Standard +A simple linked-list of C-structures containing the information needed to + define a 1-d loop for a ufunc for every defined signature of a user-defined + data-type. + +\end_layout + +\begin_layout Subsubsection +PyArrayMapIter_Type +\end_layout + +\begin_layout Standard +Advanced indexing is handled with this Python type. + It is simply a loose wrapper around the C-structure containing the variables + needed for advanced array indexing. + The associated C-structure, +\family typewriter +PyArrayMapIterObject +\family default +, is useful if you are trying to understand the advanced-index mapping code. + It is defined in the +\family typewriter +arrayobject.h +\family default + header. + This type is not exposed to Python and could be replaced with a C-structure. + As a Python type it takes advantage of reference-counted memory management. +\end_layout + +\begin_layout Chapter +Complete API +\end_layout + +\begin_layout Quotation +The test of a first-rate intelligence is the ability to hold two opposed + ideas in the mind at the same time, and still retain the ability to function. +\end_layout + +\begin_layout Right Address +--- +\emph on +F. + Scott Fitzgerald +\end_layout + +\begin_layout Quotation +For a successful technology, reality must take precedence over public relations, + for Nature cannot be fooled. + +\end_layout + +\begin_layout Right Address +--- +\emph on +Richard P. + Feynman +\end_layout + +\begin_layout Section +Configuration defines +\end_layout + +\begin_layout Standard +When NumPy is built, a configuration file is constructed and placed as config.h + in the NumPy include directory. + This configuration file ensures that specific macros are defined and defines + other macros based on whether or not your system has certain features. + It is included by the arrayobject.h file. + +\end_layout + +\begin_layout Subsection +Guaranteed to be defined +\end_layout + +\begin_layout Standard +The +\series bold +SIZEOF_ +\series default +<CTYPE> constants are defined so that sizeof information is available to + the pre-processor. + +\end_layout + +\begin_layout Description +CHAR_BIT The number of bits of a char. + The char is the unit of all sizeof definitions +\end_layout + +\begin_layout Description +SIZEOF_SHORT sizeof(short) +\end_layout + +\begin_layout Description +SIZEOF_INT sizeof(int) +\end_layout + +\begin_layout Description +SIZEOF_LONG sizeof(long) +\end_layout + +\begin_layout Description +SIZEOF_LONG_LONG sizeof(longlong) where longlong is defined appropriately + on the platform (A macro defines +\series bold +SIZEOF_LONGLONG +\series default + as well.) +\end_layout + +\begin_layout Description +SIZEOF_PY_LONG_LONG +\end_layout + +\begin_layout Description +SIZEOF_FLOAT sizeof(float) +\end_layout + +\begin_layout Description +SIZEOF_DOUBLE sizeof(double) +\end_layout + +\begin_layout Description +SIZEOF_LONG_DOUBLE sizeof(longdouble) (A macro defines +\series bold +SIZEOF_LONGDOUBLE +\series default + as well.) +\end_layout + +\begin_layout Description +SIZEOF_PY_INTPTR_T Size of a pointer on this platform (sizeof(void *)) (A + macro defines SIZEOF_INTP as well.) +\end_layout + +\begin_layout Subsection +Possible defines +\end_layout + +\begin_layout Standard +These defines will cause the compilation to ignore compatibility code that + is placed in NumPy and use the system code instead. + If they are not defined, then the system does not have that capability. +\end_layout + +\begin_layout Description +HAVE_LONGDOUBLE_FUNCS System has C99 long double math functions. +\end_layout + +\begin_layout Description +HAVE_FLOAT_FUNCS System has C99 float math functions. +\end_layout + +\begin_layout Description +HAVE_INVERSE_HYPERBOLIC System has inverse hyperbolic functions: asinh, + acosh, and atanh. +\end_layout + +\begin_layout Description +HAVE_INVERSE_HYPERBOLIC_FLOAT System has C99 float extensions to inverse + hyperbolic functions: asinhf, acoshf, atanhf +\end_layout + +\begin_layout Description +HAVE_INVERSE_HYPERBOLIC_LONGDOUBLE System has C99 long double extensions + to inverse hyperbolic functions: asinhl, acoshl, atanhl. +\end_layout + +\begin_layout Description +HAVE_ISNAN System has an isnan function. +\end_layout + +\begin_layout Description +HAVE_ISINF System has an isinf function. + +\end_layout + +\begin_layout Description +HAVE_LOG1P System has the log1p function: +\begin_inset Formula $\log\left(x+1\right)$ +\end_inset + +. +\end_layout + +\begin_layout Description +HAVE_EXPM1 System has the expm1 function: +\begin_inset Formula $\exp\left(x\right)-1$ +\end_inset + +. +\end_layout + +\begin_layout Description +HAVE_RINT System has the rint function. + +\end_layout + +\begin_layout Section +Array Data Types +\end_layout + +\begin_layout Standard +The standard array can have 21 different data types (and has some support + for adding your own types). + These data types all have an enumerated type, an enumerated type-character, + and a corresponding array scalar Python type object (placed in a hierarchy). + There are also standard C typedefs to make it easier to manipulate elements + of the given data type. + For the numeric types, there are also bit-width equivalent C typedefs and + named typenumbers that make it easier to select the precision desired. + +\end_layout + +\begin_layout Warning +The names for the types in c code follows c naming conventions more closely. + The Python names for these types follow Python conventions. + Thus, NPY_FLOAT picks up a 32-bit float in C, but +\begin_inset Quotes eld +\end_inset + +float_ +\begin_inset Quotes erd +\end_inset + + in python corresponds to a 64-bit double. + The bit-width names can be used in both Python and C for clarity. +\end_layout + +\begin_layout Subsection +Enumerated Types +\end_layout + +\begin_layout Standard +There is a list of enumerated types defined providing the basic 21 data + types plus some useful generic names. + Whenever the code requires a type number, one of these enumerated types + is requested. + The types are all called +\series bold +NPY_ +\series default +<NAME> where <NAME> can be +\end_layout + +\begin_layout Quote + +\series bold +BOOL +\series default +, +\series bold +BYTE +\series default +, +\series bold +UBYTE +\series default +, +\series bold +SHORT +\series default +, +\series bold +USHORT +\series default +, +\series bold +INT +\series default +, +\series bold +UINT +\series default +, +\series bold +LONG +\series default +, +\series bold +ULONG +\series default +, +\series bold +LONGLONG +\series default +, +\series bold +ULONGLONG +\series default +, +\series bold +FLOAT +\series default +, +\series bold +DOUBLE +\series default +, +\series bold +LONGDOUBLE +\series default +, +\series bold +CFLOAT +\series default +, +\series bold +CDOUBLE +\series default +, +\series bold +CLONGDOUBLE +\series default +, +\series bold +OBJECT +\series default +, +\series bold +STRING +\series default +, +\series bold +UNICODE +\series default +, +\series bold +VOID +\end_layout + +\begin_layout Quote + +\series bold +NTYPES +\series default +, +\series bold +NOTYPE +\series default +, +\series bold +USERDEF +\series default +, +\series bold +DEFAULT_TYPE +\end_layout + +\begin_layout Standard +The various character codes indicating certain types are also part of an + enumerated list. + References to type characters (should they be needed at all) should always + use these enumerations. + The form of them is +\series bold +NPY_ +\series default +<NAME> +\series bold +LTR +\series default + where <NAME> can be +\end_layout + +\begin_layout Quote + +\series bold +BOOL +\series default +, +\series bold +BYTE +\series default +, +\series bold +UBYTE +\series default +, +\series bold +SHORT +\series default +, +\series bold +USHORT +\series default +, +\series bold +INT +\series default +, +\series bold +UINT +\series default +, +\series bold +LONG +\series default +, +\series bold +ULONG +\series default +, +\series bold +LONGLONG +\series default +, +\series bold +ULONGLONG +\series default +, +\series bold +FLOAT +\series default +, +\series bold +DOUBLE +\series default +, +\series bold +LONGDOUBLE +\series default +, +\series bold +CFLOAT +\series default +, +\series bold +CDOUBLE +\series default +, +\series bold +CLONGDOUBLE +\series default +, +\series bold +OBJECT +\series default +, +\series bold +STRING +\series default +, +\series bold +VOID +\series default + +\end_layout + +\begin_layout Quote + +\series bold +INTP +\series default +, +\series bold +UINTP +\end_layout + +\begin_layout Quote + +\series bold +GENBOOL +\series default +, +\series bold +SIGNED +\series default +, +\series bold +UNSIGNED +\series default +, +\series bold +FLOATING +\series default +, +\series bold +COMPLEX +\end_layout + +\begin_layout Standard +The latter group of <NAME>s corresponds to letters used in the array interface + typestring specification. + +\end_layout + +\begin_layout Subsection +Defines +\end_layout + +\begin_layout Subsubsection +Max and min values for integers +\end_layout + +\begin_layout Description +NPY_MAX_INT +\series medium +<bits> +\end_layout + +\begin_layout Description +NPY_MAX_UINT +\series medium +<bits> +\end_layout + +\begin_layout Description +NPY_MIN_INT +\series medium +<bits> +\series default + +\end_layout + +\begin_layout Description +\InsetSpace ~ + These are defined for <bits> = 8, 16, 32, 64, 128, and 256 and provide + the maximum (minimum) value of the corresponding (unsigned) integer type. + Note: the actual integer type may not be available on all platforms (i.e. + 128-bit and 256-bit integers are rare). + +\end_layout + +\begin_layout Description +NPY_MIN_ +\series medium +<type> +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is defined for <type> = +\series bold +BYTE +\series default +, +\series bold +SHORT +\series default +, +\series bold +INT +\series default +, +\series bold +LONG +\series default +, +\series bold +LONGLONG +\series default +, +\series bold +INTP +\end_layout + +\begin_layout Description +NPY_MAX_ +\series medium +<type> +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is defined for all defined for <type> = +\series bold +BYTE +\series default +, +\series bold +UBYTE +\series default +, +\series bold +SHORT +\series default +, +\series bold +USHORT +\series default +, +\series bold +INT +\series default +, +\series bold +UINT +\series default +, +\series bold +LONG +\series default +, +\series bold +ULONG +\series default +, +\series bold +LONGLONG +\series default +, +\series bold +ULONGLONG +\series default +, +\series bold +INTP +\series default +, +\series bold +UINTP +\end_layout + +\begin_layout Subsubsection +Number of bits in data types +\end_layout + +\begin_layout Standard +All +\series bold +NPY_SIZEOF_ +\series default +<CTYPE> constants have corresponding +\series bold +NPY_BITSOF_ +\series default +<CTYPE> constants defined. + The +\series bold +NPY_BITSOF_ +\series default +<CTYPE> constants provide the number of bits in the data type. + Specifically, the available <CTYPE>s are +\end_layout + +\begin_layout Quote + +\series bold +BOOL +\series default +, +\series bold +CHAR +\series default +, +\series bold +SHORT +\series default +, +\series bold +INT +\series default +, +\series bold +LONG +\series default +, +\series bold +LONGLONG +\series default +, +\series bold +FLOAT +\series default +, +\series bold +DOUBLE +\series default +, +\series bold +LONGDOUBLE +\end_layout + +\begin_layout Subsubsection +Bit-width references to enumerated typenums +\end_layout + +\begin_layout Standard +All of the numeric data types (integer, floating point, and complex) have + constants that are defined to be a specific enumerated type number. + Exactly which enumerated type a bit-width type refers to is platform dependent. + In particular, the constants available are +\series bold +PyArray_ +\series default +<NAME><BITS> where <NAME> is +\series bold +INT +\series default +, +\series bold +UINT +\series default +, +\series bold +FLOAT +\series default +, +\series bold +COMPLEX +\series default + and <BITS> can be 8, 16, 32, 64, 80, 96, 128, 160, 192, 256, and 512. + Obviously not all bit-widths are available on all platforms for all the + kinds of numeric types. + Commonly 8-, 16-, 32-, 64-bit integers; 32-, 64-bit floats; and 64-, 128-bit + complex types are available. + +\end_layout + +\begin_layout Subsubsection +Integer that can hold a pointer +\end_layout + +\begin_layout Standard +The constants +\series bold +PyArray_INTP +\series default + and +\series bold +PyArray_UINTP +\series default + refer to an enumerated integer type that is large enough to hold a pointer + on the platform. + Index arrays should always be converted to +\series bold +PyArray_INTP +\series default +, because the dimension of the array is of type npy_intp. + +\end_layout + +\begin_layout Subsection +C-type names +\end_layout + +\begin_layout Standard +There are standard variable types for each of the numeric data types and + the bool data type. + Some of these are already available in the C-specification. + You can create variables in extension code with these types. + +\end_layout + +\begin_layout Subsubsection +Boolean +\end_layout + +\begin_layout Description +npy_bool unsigned char; The constants NPY_FALSE and NPY_TRUE are also defined. + +\end_layout + +\begin_layout Subsubsection +(Un)Signed Integer +\end_layout + +\begin_layout Standard +Unsigned versions of the integers can be defined by pre-pending a 'u' to + the front of the integer name. + +\end_layout + +\begin_layout Description +npy_(u)byte (unsigned) char +\end_layout + +\begin_layout Description +npy_(u)short (unsigned) short +\end_layout + +\begin_layout Description +npy_(u)int (unsigned) int +\end_layout + +\begin_layout Description +npy_(u)long (unsigned) long int +\end_layout + +\begin_layout Description +npy_(u)longlong (unsigned long long int) +\end_layout + +\begin_layout Description +npy_(u)intp (unsigned) Py_intptr_t (an integer that is the size of a pointer + on the platform). + +\end_layout + +\begin_layout Subsubsection +(Complex) Floating point +\end_layout + +\begin_layout Description +npy_(c)float float +\end_layout + +\begin_layout Description +npy_(c)double double +\end_layout + +\begin_layout Description +npy_(c)longdouble long double +\end_layout + +\begin_layout Standard +complex types are structures with +\series bold +.real +\series default + and +\series bold +.imag +\series default + members (in that order). +\end_layout + +\begin_layout Subsubsection +Bit-width names +\end_layout + +\begin_layout Standard +There are also typedefs for signed integers, unsigned integers, floating + point, and complex floating point types of specific bit-widths. + The available type names are +\end_layout + +\begin_layout Quote + +\series bold +npy_int +\series default +<bits>, +\series bold +npy_uint +\series default +<bits>, +\series bold +npy_float +\series default +<bits>, and +\series bold +npy_complex +\series default +<bits> +\end_layout + +\begin_layout Standard +where <bits> is the number of bits in the type and can be +\series bold +8 +\series default +, +\series bold +16 +\series default +, +\series bold +32 +\series default +, +\series bold +64 +\series default +, 128, and 256 for integer types; 16, +\series bold +32 +\series default +, +\series bold +64 +\series default +, 80, 96, 128, and 256 for floating-point types; and 32, +\series bold +64 +\series default +, +\series bold +128 +\series default +, 160, 192, and 512 for complex-valued types. + Which bit-widths are available is platform dependent. + The bolded bit-widths are usually available on all platforms. + +\end_layout + +\begin_layout Subsection +Printf Formatting +\end_layout + +\begin_layout Standard +For help in printing, the following strings are defined as the correct format + specifier in printf and related commands. +\end_layout + +\begin_layout Quote + +\series bold +NPY_LONGLONG_FMT +\series default +, +\series bold +NPY_ULONGLONG_FMT +\series default +, +\series bold +NPY_INTP_FMT +\series default +, +\series bold +NPY_UINTP_FMT +\series default +, +\series bold +NPY_LONGDOUBLE_FMT +\end_layout + +\begin_layout Section +Array API +\begin_inset LatexCommand index +name "ndarray!C-API|(" + +\end_inset + + +\begin_inset LatexCommand index +name "C-API!array|(" + +\end_inset + + +\end_layout + +\begin_layout Subsection +Array structure and data access +\end_layout + +\begin_layout Standard +These macros all access the PyArrayObject structure members. + The input argument, obj, can be any +\family typewriter +PyObject* +\family default + that is directly interpretable as a +\family typewriter +PyArrayObject* +\family default + (any instance of the +\series bold +PyArray_Type +\series default + and its sub-types). + +\end_layout + +\begin_layout Description +PyArray_DATA ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +PyArray_BYTES ( +\family typewriter +char* +\family default +) ( +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + These two macros are similar and obtain the pointer to the data-buffer + for the array. + The first macro can (and should be) assigned to a particular pointer where + the second is for generic processing. + If you have not guaranteed a contiguous and/or aligned array then be sure + you understand how to access the data in the array to avoid memory and/or + alignment problems. + +\end_layout + +\begin_layout Description +PyArray_DIMS ( +\family typewriter +npy_intp* +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +PyArray_STRIDES ( +\family typewriter +npy_intp* +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +PyArray_DIM ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +int +\family default + n) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the shape in the +\emph on +n +\emph default + +\begin_inset Formula $^{\textrm{th}}$ +\end_inset + + dimension. +\end_layout + +\begin_layout Description +PyArray_STRIDE ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +int +\family default + n) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the stride in the +\emph on +n +\emph default + +\begin_inset Formula $^{\textrm{th}}$ +\end_inset + + dimension. +\end_layout + +\begin_layout Description +PyArray_BASE ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +PyArray_DESCR ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +PyArray_FLAGS ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +PyArray_ITEMSIZE ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the itemsize for the elements of this array. +\end_layout + +\begin_layout Description +PyArray_TYPE ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the (builtin) typenumber for the elements of this array. + +\end_layout + +\begin_layout Description +PyArray_GETITEM ( +\family typewriter +PyObject +\family default + *) ( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +void* +\family default + itemptr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Get a Python object from the ndarray, +\emph on +arr +\emph default +, at the location pointed to by itemptr. + Return +\family typewriter +NULL +\family default + on failure. + +\end_layout + +\begin_layout Description +PyArray_SETITEM ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +void* +\family default + itemptr, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert obj and place it in the ndarray, +\emph on +arr +\emph default +, at the place pointed to by itemptr. + Return -1 if an error occurs or 0 on success. + +\end_layout + +\begin_layout Description +PyArray_SIZE ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns the total size (in number of elements) of the array. +\end_layout + +\begin_layout Description +PyArray_Size ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns 0 if +\emph on +obj +\emph default + is not a sub-class of bigndarray. + Otherwise, returns the total number of elements in the array. + Safer version of +\family typewriter +PyArray_SIZE +\family default +( +\emph on +obj +\emph default +). +\end_layout + +\begin_layout Description +PyArray_NBYTES ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns the total number of bytes consumed by the array. + +\end_layout + +\begin_layout Subsubsection +Data access +\end_layout + +\begin_layout Standard +These functions and macros provide easy access to elements of the ndarray + from C. + These work for all arrays. + You may need to take care when accessing the data in the array, however, + if it is not in machine byte-order, misaligned, or not writeable. + In other words, be sure to respect the state of the flags unless you know + what you are doing, or have previously guaranteed an array that is writeable, + aligned, and in machine byte-order using PyArray_FromAny. + If you wish to handle all types of arrays, the copyswap function for each + type is useful for handling misbehaved arrays. + Some platforms (e.g. + Solaris) do not like misaligned data and will crash if you de-reference + a misaligned pointer. + Other platforms (e.g. + x86 Linux) will just work more slowly with misaligned data. + +\end_layout + +\begin_layout Description +PyArray_GetPtr ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + aobj, +\family typewriter +npy_intp* +\family default + ind) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a pointer to the data of the ndarray, +\emph on +aobj +\emph default +, at the N-dimensional index given by the c-array, +\emph on +ind +\emph default +, (which must be at least +\emph on +aobj +\emph default +->nd in size). + You may want to typecast the returned pointer to the data type of the ndarray. +\end_layout + +\begin_layout Description +PyArray_GETPTR1 ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +<npy_intp> +\family default + i) +\end_layout + +\begin_layout Description +PyArray_GETPTR2 ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +<npy_intp> +\family default + i, +\family typewriter +<npy_intp> +\family default + j) +\end_layout + +\begin_layout Description +PyArray_GETPTR3 ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +<npy_intp> +\family default + i, +\family typewriter +<npy_intp> +\family default + j, +\family typewriter +<npy_intp> +\family default + k) +\end_layout + +\begin_layout Description +PyArray_GETPTR4 ( +\family typewriter +void* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +<npy_intp> +\family default + i, +\family typewriter +<npy_intp> +\family default + j, +\family typewriter +<npy_intp> +\family default + k, +\family typewriter +<npy_intp> +\family default + l) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Quick, inline access to the element at the given coordinates in the ndarray, + +\emph on +obj +\emph default +, which must have respectively 1, 2, 3, or 4 dimensions (this is not checked). + The corresponding +\emph on +i +\emph default +, +\emph on +j +\emph default +, +\emph on +k +\emph default +, and +\emph on +l +\emph default + coordinates can be any integer but will be interpreted as +\family typewriter +npy_intp +\family default +. + You may want to typecast the returned pointer to the data type of the ndarray. + +\end_layout + +\begin_layout Subsection +Creating arrays +\end_layout + +\begin_layout Subsubsection +From scratch +\end_layout + +\begin_layout Description +PyArray_NewFromDescr ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyTypeObject* +\family default + subtype, +\family typewriter +PyArray_Descr* +\family default + descr, +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +npy_intp* +\family default + strides, +\family typewriter +void* +\family default + data, +\family typewriter +int +\family default + flags, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is the main array creation function. + Most new arrays are created with this flexible function. + The returned object is an object of Python-type +\emph on +subtype +\emph default +, which must be a subtype of +\family typewriter +PyArray_Type +\family default +. + The array has +\emph on +nd +\emph default + dimensions, described by +\emph on +dims +\emph default +. + The data-type descriptor of the new array is +\emph on +descr +\emph default +. + If +\emph on +subtype +\emph default + is not +\family typewriter +&PyArray_Type +\family default + ( +\emph on +e.g. + +\emph default + a Python subclass of the ndarray), then +\emph on +obj +\emph default + is the object to pass to the +\series bold +__array_finalize__ +\series default + method of the subclass. + If +\emph on +data +\emph default + is +\family typewriter +NULL +\family default +, then new memory will be allocated and +\emph on +flags +\emph default + can be non-zero to indicate a Fortran-style contiguous array. + If +\emph on +data +\emph default + is not +\family typewriter +NULL +\family default +, then it is assumed to point to the memory to be used for the array and + the +\emph on +flags +\emph default + argument is used as the new flags for the array (except the state of +\family typewriter +NPY_OWNDATA +\family default + and +\family typewriter +UPDATEIFCOPY +\family default + flags of the new array will be reset). + In addition, if +\emph on +data +\emph default + is non-NULL, then +\emph on +strides +\emph default + can also be provided. + If +\emph on +strides +\emph default + is +\family typewriter +NULL +\family default +, then the array strides are computed as C-style contiguous (default) or + Fortran-style contiguous ( +\emph on +flags +\emph default + is nonzero for +\emph on +data +\emph default += +\family typewriter +NULL +\family default + or +\emph on +flags +\emph default + & +\family typewriter +NPY_F_CONTIGUOUS +\family default + is nonzero non-NULL +\emph on +data +\emph default +). + Any provided +\emph on +dims +\emph default + and +\emph on +strides +\emph default + are copied into newly allocated dimension and strides arrays for the new + array object. +\end_layout + +\begin_layout Description +PyArray_New ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyTypeObject* +\family default + subtype, +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + type_num, +\family typewriter +npy_intp* +\family default + strides, +\family typewriter +void* +\family default + data, +\family typewriter +int +\family default + itemsize, +\family typewriter +int +\family default + flags, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is similar to +\family typewriter +PyArray +\family default +\series bold +_ +\family typewriter +\series default +DescrNew +\family default +(...) except you specify the data-type descriptor with +\emph on +type_num +\emph default + and +\emph on +itemsize +\emph default +, where +\emph on +type_num +\emph default + corresponds to a builtin (or user-defined) type. + If the type always has the same number of bytes, then itemsize is ignored. + Otherwise, itemsize specifies the particular size of this array. + +\end_layout + +\begin_layout Warning +If data is passed to +\family typewriter +PyArray_NewFromDescr +\family default + or +\family typewriter +PyArray_New +\family default +, this memory must not be deallocated until the new array is deleted. + If this data came from another Python object, this can be accomplished + using +\family typewriter +Py_INCREF +\family default + on that object and setting the base member of the new array to point to + that object. + If strides are passed in they must be consistent with the dimensions, the + itemsize, and the data of the array. +\end_layout + +\begin_layout Description +PyArray_SimpleNew ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create a new unitialized array of type, +\emph on +typenum +\emph default +, whose size in each of +\emph on +nd +\emph default + dimensions is given by the integer array, +\emph on +dims +\emph default +. + This function cannot be used to create a flexible-type array (no itemsize + given). +\end_layout + +\begin_layout Description +PyArray_SimpleNewFromData ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + typenum, +\family typewriter +void* +\family default + data) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create an array wrapper around +\emph on +data +\emph default + pointed to by the given pointer. + The array flags will have a default that the data area is well-behaved + and C-style contiguous. + The shape of the array is given by the +\emph on +dims +\emph default + c-array of length +\emph on +nd +\emph default +. + The data-type of the array is indicated by +\emph on +typenum +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_SimpleNewFromDescr ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +PyArray_Descr* +\family default + descr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create a new array with the provided data-type descriptor, +\emph on +descr +\emph default +, of the shape deteremined by +\emph on +nd +\emph default + and +\emph on +dims +\emph default +. +\end_layout + +\begin_layout Description +PyArray_FILLWBYTE ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + val) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Fill the array pointed to by +\emph on +obj +\emph default +---which must be a (subclass of) bigndarray---with the contents of +\emph on +val +\emph default + (evaluated as a byte). +\end_layout + +\begin_layout Description +PyArray_Zeros ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a new +\emph on +nd +\emph default +-dimensional array with shape given by +\emph on +dims +\emph default + and data type given by +\emph on +dtype +\emph default +. + If +\emph on +fortran +\emph default + is non-zero, then a Fortran-order array is created, otherwise a C-order + array is created. + Fill the memory with zeros (or the 0 object if +\emph on +dtype +\emph default + corresponds to +\family typewriter +PyArray_OBJECT +\family default +). + +\end_layout + +\begin_layout Description +PyArray_ZEROS ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + type_num, +\family typewriter +int +\family default + fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Macro form of +\family typewriter +PyArray_Zeros +\family default + which takes a type-number instead of a data-type object. +\end_layout + +\begin_layout Description +PyArray_Empty ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a new +\emph on +nd +\emph default +-dimensional array with shape given by +\emph on +dims +\emph default + and data type given by +\emph on +dtype +\emph default +. + If +\emph on +fortran +\emph default + is non-zero, then a Fortran-order array is created, otherwise a C-order + array is created. + The array is uninitialized unless the data type corresponds to +\family typewriter +PyArray_OBJECT +\family default + in which case the array is filled with +\family typewriter +Py_None +\family default +. + +\end_layout + +\begin_layout Description +PyArray_EMPTY ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Macro form of +\family typewriter +PyArray_Empty +\family default + which takes a type-number, +\emph on +typenum +\emph default +, instead of a data-type object. +\end_layout + +\begin_layout Description +PyArray_Arange ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +double +\family default + start, +\family typewriter +double +\family default + stop, +\family typewriter +double +\family default + step, +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a new 1-dimensional array of data-type, +\emph on +typenum +\emph default +, that ranges from +\emph on +start +\emph default + to +\emph on +stop +\emph default + (exclusive) in increments of +\emph on +step +\emph default +. + Equivalent to +\series bold +arange +\series default +( +\emph on +start +\emph default +, +\emph on +stop +\emph default +, +\emph on +step +\emph default +, dtype). +\end_layout + +\begin_layout Description +PyArray_ArangeObj ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + start, +\family typewriter +PyObject* +\family default + stop, +\family typewriter +PyObject* +\family default + step, +\family typewriter +PyArray_Descr* +\family default + descr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a new 1-dimensional array of data-type determined by +\family typewriter +descr +\family default +, that ranges from +\family typewriter +start +\family default + to +\family typewriter +stop +\family default + (exclusive) in increments of +\family typewriter +step +\family default +. + Equivalent to arange( +\family typewriter +start +\family default +, +\family typewriter +stop +\family default +, +\family typewriter +step +\family default +, +\family typewriter +typenum +\family default +). + +\end_layout + +\begin_layout Subsubsection +From other objects +\end_layout + +\begin_layout Description +PyArray_FromAny ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + min_depth, +\family typewriter +int +\family default + max_depth, +\family typewriter +int +\family default + requirements, +\family typewriter +PyObject* +\family default + context) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is the main function used to obtain an array from any nested sequence, + or object that exposes the array interface, +\family typewriter +op +\family default +. + The parameters allow specification of the required +\emph on +type +\emph default +, the minimum ( +\emph on +min_depth +\emph default +) and maximum ( +\emph on +max_depth +\emph default +) number of dimensions acceptable, and other +\emph on +requirements +\emph default + for the array. + The +\emph on +dtype +\emph default + argument needs to be a +\family typewriter +PyArray_Descr +\family default + structure indicating the desired data-type (including required byteorder). + The +\emph on +dtype +\emph default + argument may be NULL, indicating that any data-type (and byteorder) is + acceptable. + If you want to use +\family typewriter +NULL +\family default + for the +\emph on +dtype +\emph default + and ensure the array is notswapped then use +\family typewriter +PyArray_CheckFromAny +\family default +. + A value of 0 for either of the depth parameters causes the parameter to + be ignored. + Any of the following array flags can be added ( +\emph on +e.g. + +\emph default + using |) to get the +\emph on +requirements +\emph default + argument. + If your code can handle general ( +\emph on +e.g. + +\emph default + strided, byte-swapped, or unaligned arrays) then +\emph on +requirements +\emph default + may be 0. + Also, if +\emph on +op +\emph default + is not already an array (or does not expose the array interface), then + a new array will be created (and filled from +\emph on +op +\emph default + using the sequence protocol). + The new array will have +\family typewriter +NPY_DEFAULT +\family default + as its flags member. + The +\emph on +context +\emph default + argument is passed to the +\series bold +__array__ +\series default + method of +\emph on +op +\emph default + and is only used if the array is constructed that way. + +\end_layout + +\begin_deeper +\begin_layout Description +NPY_C_CONTIGUOUS Make sure the returned array is C-style contiguous +\end_layout + +\begin_layout Description +NPY_F_CONTIGUOUS Make sure the returned array is Fortran-style contiguous. + +\end_layout + +\begin_layout Description +NPY_ALIGNED Make sure the returned array is aligned on proper boundaries + for its data type. + An aligned array has the data pointer and every strides factor as a multiple + of the alignment factor for the data-type-descriptor. +\end_layout + +\begin_layout Description +NPY_WRITEABLE Make sure the returned array can be written to. + +\end_layout + +\begin_layout Description +NPY_ENSURECOPY Make sure a copy is made of +\emph on +op +\emph default +. + If this flag is not present, data is not copied if it can be avoided. + +\end_layout + +\begin_layout Description +NPY_ENSUREARRAY Make sure the result is a base-class ndarray or bigndarray. + By default, if +\emph on +op +\emph default + is an instance of a subclass of the bigndarray, an instance of that same + subclass is returned. + If this flag is set, an ndarray object will be returned instead. +\end_layout + +\begin_layout Description +NPY_FORCECAST Force a cast to the output type even if it cannot be done + safely. + Without this flag, a data cast will occur only if it can be done safely, + otherwise an error is reaised. + +\end_layout + +\begin_layout Description +NPY_UPDATEIFCOPY If +\emph on +op +\emph default + is already an array, but does not satisfy the requirements, then a copy + is made (which will satisfy the requirements). + If this flag is present and a copy (of an object that is already an array) + must be made, then the corresponding +\family typewriter +NPY_UPDATEIFCOPY +\family default + flag is set in the returned copy and +\emph on +op +\emph default + is made to be read-only. + When the returned copy is deleted (presumably after your calculations are + complete), its contents will be copied back into +\emph on +op +\emph default + and the +\emph on +op +\emph default + array will be made writeable again. + If +\emph on +op +\emph default + is not writeable to begin with, then an error is raised. + If +\emph on +op +\emph default + is not already an array, then this flag has no effect. +\end_layout + +\begin_layout Description +NPY_BEHAVED +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +NPY_WRITEABLE +\end_layout + +\begin_layout Description +NPY_CARRAY +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_BEHAVED +\end_layout + +\begin_layout Description +NPY_CARRAY_RO +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_FARRAY +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_BEHAVED +\end_layout + +\begin_layout Description +NPY_FARRAY_RO +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_DEFAULT +\family typewriter +NPY_CARRAY +\end_layout + +\begin_layout Description +NPY_IN_ARRAY +\family typewriter +NPY_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_IN_FARRAY +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_INOUT_ARRAY +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_INOUT_FARRAY +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_OUT_ARRAY +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +NPY_UPDATEIFCOPY +\end_layout + +\begin_layout Description +NPY_OUT_FARRAY +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +UPDATEIFCOPY +\end_layout + +\end_deeper +\begin_layout Description +PyArray_CheckFromAny ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + min_depth, +\family typewriter +int +\family default + max_depth, +\family typewriter +int +\family default + requirements, +\family typewriter +PyObject* +\family default + context) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Nearly identical to +\family typewriter +PyArray_FromAny +\family default +(...) except +\emph on +requirements +\emph default + can contain +\family typewriter +NPY_NOTSWAPPED +\family default + (over-riding the specification in +\emph on +dtype +\emph default +) and +\family typewriter +NPY_ELEMENTSTRIDES +\family default + which indicates that the array should be aligned in the sense that the + strides are multiples of the element size. + +\end_layout + +\begin_layout Description +NPY_NOTSWAPPED Make sure the returned array has a data-type descriptor that + is in machine byte-order, over-riding any specification in the +\emph on +dtype +\emph default + argument. + Normally, the byte-order requirement is determined by the +\emph on +dtype +\emph default + argument. + If this flag is set and the dtype argument does not indicate a machine + byte-order descriptor (or is NULL and the object is already an array with + a data-type descriptor that is not in machine byte-order), then a new data-type + descriptor is created and used with its byte-order field set to native. +\end_layout + +\begin_layout Description +NPY_BEHAVED_NS +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_NOTSWAPPED +\end_layout + +\begin_layout Description +NPY_ELEMENTSTRIDES Make sure the returned array has strides that are multiples + of the element size. + +\end_layout + +\begin_layout Description +PyArray_FromArray ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + newtype, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Special case of +\family typewriter +PyArray_FromAny +\family default + for when +\emph on +op +\emph default + is already an array but it needs to be of a specific +\emph on +newtype +\emph default + (including byte-order) or has certain +\emph on +requirements +\emph default +. +\end_layout + +\begin_layout Description +PyArray_FromStructInterface ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns an ndarray object from a Python object that exposes the +\series bold +__array_struct__ +\series default + method and follows the array interface protocol. + If the object does not contain this method then a borrowed reference to + +\family typewriter +Py_NotImplemented +\family default + is returned. +\end_layout + +\begin_layout Description +PyArray_FromInterface ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns an ndarray object from a Python object that exposes the +\series bold +__array_shape__ +\series default + and +\series bold +__array_typestr__ +\series default + methods following the array interface protocol. + If the object does not contain one of these method then a borrowed reference + to +\family typewriter +Py_NotImplemented +\family default + is returned. +\end_layout + +\begin_layout Description +PyArray_FromArrayAttr ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +PyObject* +\family default + context) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an ndarray object from a Python object that exposes the +\series bold +__array__ +\series default + method. + The +\series bold +__array__ +\series default + method can take 0, 1, or 2 arguments ([dtype, context]) where +\emph on +context +\emph default + is used to pass information about where the +\series bold +__array__ +\series default + method is being called from (currently only used in ufuncs). + +\end_layout + +\begin_layout Description +PyArray_ContiguousFromAny ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + min_depth, +\family typewriter +int +\family default + max_depth) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function returns a (C-style) contiguous and behaved function array + from any nested sequence or array interface exporting object, +\emph on +op +\emph default +, of (non-flexible) type given by the enumerated +\emph on +typenum +\emph default +, of minimum depth +\emph on +min_depth +\emph default +, and of maximum depth +\emph on +max_depth +\emph default +. + Equivalent to a call to +\family typewriter +PyArray_FromAny +\family default + with requirements set to +\family typewriter +NPY_DEFAULT +\family default + and the type_num member of the type argument set to +\emph on +typenum +\emph default +. +\end_layout + +\begin_layout Description +PyArray_FromObject (PyObject *) (PyObject * op, int typenum, int min_depth, + int max_depth) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an aligned and in native-byteorder array from any nested sequence + or array-interface exporting object, op, of a type given by the enumerated + typenum. + The minimum number of dimensions the array can have is given by min_depth + while the maximum is max_depth. + This is equivalent to a call to PyArray_FromAny with requirements set to + BEHAVED. + +\end_layout + +\begin_layout Description +PyArray_EnsureArray ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function +\series bold +steals a reference +\series default + to +\family typewriter +op +\family default + and makes sure that +\family typewriter +op +\family default + is a base-class ndarray. + It special cases array scalars, but otherwise calls +\series bold +PyArray_FromAny +\series default +( +\family typewriter +op +\family default +, NULL, 0, 0, NPY_ENSUREARRAY). +\end_layout + +\begin_layout Description +PyArray_FromString ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +char* +\family default + string, +\family typewriter +npy_intp +\family default + slen, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +npy_intp +\family default + num, +\family typewriter +char* +\family default + sep) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a one-dimensional ndarray of a single type from a binary or (ASCII) + text +\family typewriter +string +\family default + of length +\family typewriter +slen +\family default +. + The data-type of the array to-be-created is given by +\family typewriter +dtype +\family default +. + If num is -1, then +\series bold +copy +\series default + the entire string and return an appropriately sized array, otherwise, +\family typewriter +num +\family default + is the number of items to +\series bold +copy +\series default + from the string. + If +\family typewriter +sep +\family default + is NULL (or +\begin_inset Quotes eld +\end_inset + + +\begin_inset Quotes erd +\end_inset + +), then interpret the string as bytes of binary data, otherwise convert + the sub-strings separated by +\family typewriter +sep +\family default + to items of data-type +\family typewriter +dtype +\family default +. + Some data-types may not be readable in text mode and an error will be raised + if that occurs. + All errors return NULL. + +\end_layout + +\begin_layout Description +PyArray_FromFile ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +FILE* +\family default + fp, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +npy_intp +\family default + num, +\family typewriter +char* +\family default + sep) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a one-dimensional ndarray of a single type from a binary or text + file. + The open file pointer is +\family typewriter +fp +\family default +, the data-type of the array to be created is given by +\family typewriter +dtype +\family default +. + This must match the data in the file. + If +\family typewriter +num +\family default + is -1, then read until the end of the file and return an appropriately + sized array, otherwise, +\family typewriter +num +\family default + is the number of items to read. + If +\family typewriter +sep +\family default + is NULL (or +\begin_inset Quotes eld +\end_inset + + +\begin_inset Quotes erd +\end_inset + +), then read from the file in binary mode, otherwise read from the file + in text mode with +\family typewriter +sep +\family default + providing the item separator. + Some array types cannot be read in text mode in which case an error is + raised. +\end_layout + +\begin_layout Description +PyArray_FromBuffer ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + buf, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +npy_intp +\family default + count, +\family typewriter +npy_intp +\family default + offset) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Construct a one-dimensional ndarray of a single type from an object, +\family typewriter +buf +\family default +, that exports the (single-segment) buffer protocol (or has an attribute + __buffer__ that returns an object that exports the buffer protocol). + A writeable buffer will be tried first followed by a read-only buffer. + The NPY_WRITEABLE flag of the returned array will reflect which one was + successful. + The data is assumed to start at +\family typewriter +offset +\family default + bytes from the start of the memory location for the object. + The type of the data in the buffer will be interpreted depending on the + data-type descriptor, +\family typewriter +dtype. + +\family default + If +\family typewriter +count +\family default + is negative then it will be determined from the size of the buffer and + the requested itemsize, otherwise, +\family typewriter +count +\family default + represents how many elements should be converted from the buffer. + +\end_layout + +\begin_layout Description +PyArray_CopyInto ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + dest, +\family typewriter +PyArrayObject* +\family default + src) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Copy from the source array, +\family typewriter +src +\family default +, into the destination array, +\family typewriter +dest +\family default +, performing a data-type conversion if necessary. + If an error occurs return -1 (otherwise 0). + The shape of +\family typewriter +src +\family default + must be broadcastable to the shape of +\family typewriter +dest +\family default +. + The data areas of dest and src must not overlap. + +\end_layout + +\begin_layout Description +PyArray_MoveInto ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + dest, +\family typewriter +PyArrayObject* +\family default + src) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Move data from the source array, +\family typewriter +src +\family default +, into the destination array, +\family typewriter +dest +\family default +, performing a data-type conversion if necessary. + If an error occurs return -1 (otherwise 0). + The shape of +\family typewriter +src +\family default + must be broadcastable to the shape of +\family typewriter +dest +\family default +. + The data areas of dest and src may overlap. + +\end_layout + +\begin_layout Description +PyArray_GETCONTIGUOUS ( +\family typewriter +PyArrayObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + If +\family typewriter +op +\family default + is already (C-style) contiguous and well-behaved then just return a reference, + otherwise return a (contiguous and well-behaved) copy of the array. + The parameter op must be a (sub-class of an) ndarray and no checking for + that is done. +\end_layout + +\begin_layout Description +PyArray_FROM_O ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert +\family typewriter +obj +\family default + to an ndarray. + The argument can be any nested sequence or object that exports the array + interface. + This is a macro form of +\family typewriter +PyArray_FromAny +\family default + using +\family typewriter +NULL +\family default +, 0, 0, 0 for the other arguments. + Your code must be able to handle any data-type descriptor and any combination + of data-flags to use this macro. + +\end_layout + +\begin_layout Description +PyArray_FROM_OF ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Similar to +\family typewriter +PyArray_FROM_O +\family default + except it can take an argument of +\emph on +requirements +\emph default + indicating properties the resulting array must have. + Available requirements that can be enforced are +\family typewriter +NPY_CONTIGUOUS +\family default +, +\family typewriter +NPY_F_CONTIGUOUS +\family default +, +\family typewriter +NPY_ALIGNED +\family default +, +\family typewriter +NPY_WRITEABLE +\family default +, +\family typewriter +NPY_NOTSWAPPED +\family default +, +\family typewriter +NPY_ENSURECOPY +\family default +, +\family typewriter +NPY_UPDATEIFCOPY +\family default +, +\family typewriter +NPY_FORCECAST +\family default +, and +\family typewriter +NPY_ENSUREARRAY +\family default +. + Standard combinations of flags can also be used: +\end_layout + +\begin_layout Description +PyArray_FROM_OT ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Similar to +\family typewriter +PyArray_FROM_O +\family default + except it can take an argument of +\emph on +typenum +\emph default + specifying the type-number the returned array. +\end_layout + +\begin_layout Description +PyArray_FROM_OTF ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Combination of +\family typewriter +PyArray_FROM_OF +\family default + and +\family typewriter +PyArray_FROM_OT +\family default + allowing both a +\emph on +typenum +\emph default + and a +\emph on +flags +\emph default + argument to be provided.. +\end_layout + +\begin_layout Description +PyArray_FROMANY ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + min, +\family typewriter +int +\family default + max, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Similar to +\family typewriter +PyArray_FromAny +\family default + except the data-type is specified using a typenumber. + +\family typewriter +PyArray_DescrFromType +\family default +( +\emph on +typenum +\emph default +) is passed directly to +\family typewriter +PyArray_FromAny +\family default +. + This macro also adds +\family typewriter +NPY_DEFAULT +\family default + to requirements if +\family typewriter +NPY_ENSURECOPY +\family default + is passed in as requirements. + +\end_layout + +\begin_layout Description +PyArray_CheckAxis ( +\family typewriter +PyObject* +\family default +)( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int* +\family default + axis, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Encapsulate the functionality of functions and methods that take the axis= + keyword and work properly with None as the axis argument. + The input array is +\family typewriter +obj +\family default +, while +\family typewriter +*axis +\family default + is a converted integer (so that >=MAXDIMS is the None value), and +\family typewriter +requirements +\family default + gives the needed properties of +\family typewriter +obj +\family default +. + The output is a converted version of the input so that requirements are + met and if needed a flattening has occurred. + On output negative values of +\family typewriter +*axis +\family default + are converted and the new value is checked to ensure consistency with the + shape of +\family typewriter +obj +\family default +. +\end_layout + +\begin_layout Subsection +Dealing with types +\end_layout + +\begin_layout Subsubsection +General check of Python Type +\end_layout + +\begin_layout Description +PyArray_Check (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is a Python object whose type is a sub-type of +\family typewriter +PyArray_Type +\family default +. + +\end_layout + +\begin_layout Description +PyArray_CheckExact (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is a Python object with type +\family typewriter +PyArray_Type +\family default +. +\end_layout + +\begin_layout Description +PyArray_HasArrayInterface (op, out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + If +\family typewriter +op +\family default + implements any part of the array interface, then +\family typewriter +out +\family default + will contain a new reference to the newly created ndarray using the interface + or +\family typewriter +out +\family default + will contain +\family typewriter +NULL +\family default + if an error during conversion occurs. + Otherwise, out will contain a borrowed reference to +\family typewriter +Py_NotImplemented +\family default + and no error condition is set. + +\end_layout + +\begin_layout Description +PyArray_HasArrayInterfaceType (op, type, context, out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + If +\family typewriter +op +\family default + implements any part of the array interface, then +\family typewriter +out +\family default + will contain a new reference to the newly created ndarray using the interface + or +\family typewriter +out +\family default + will contain +\family typewriter +NULL +\family default + if an error during conversion occurs. + Otherwise, out will contain a borrowed reference to Py_NotImplemented and + no error condition is set. + This version allows setting of the type and context in the part of the + array interface that looks for the +\series bold +__array__ +\series default + attribute. + +\end_layout + +\begin_layout Description +PyArray_IsZeroDim (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is an instance of (a subclass of) +\family typewriter +PyArray_Type +\family default + and has 0 dimensions. +\end_layout + +\begin_layout Description +PyArray_IsScalar (op, cls) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is an instance of +\family typewriter +Py<cls>ArrType_Type +\family default +. +\end_layout + +\begin_layout Description +PyArray_CheckScalar (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is either an array scalar (an instance of a sub-type of +\family typewriter +PyGenericArr_Type +\family default +), or an instance of (a sub-class of) +\family typewriter +PyArray_Type +\family default + whose dimensionality is 0. +\end_layout + +\begin_layout Description +PyArray_IsPythonScalar (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is a builtin Python +\begin_inset Quotes eld +\end_inset + +scalar +\begin_inset Quotes erd +\end_inset + + object (int, float, complex, str, unicode, long, bool). +\end_layout + +\begin_layout Description +PyArray_IsAnyScalar (op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is either a Python scalar or an array scalar (an instance of a sub-type + of +\family typewriter +PyGenericArr_Type +\family default +). + +\end_layout + +\begin_layout Subsubsection +Data-type checking +\end_layout + +\begin_layout Standard +For the typenum macros, the argument is an integer representing an enumerated + array data type. + For the array type checking macros the argument must be a +\family typewriter +PyObject* +\family default + that can be directly interpreted as a +\family typewriter +PyArrayObject* +\family default +. + +\end_layout + +\begin_layout Description +PyTypeNum_ISUNSIGNED (num) +\end_layout + +\begin_layout Description +PyDataType_ISUNSIGNED (descr) +\end_layout + +\begin_layout Description +PyArray_ISUNSIGNED (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents an unsigned integer. +\end_layout + +\begin_layout Description +PyTypeNum_ISSIGNED (num) +\end_layout + +\begin_layout Description +PyDataType_ISSIGNED (descr) +\end_layout + +\begin_layout Description +PyArray_ISSIGNED (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents a signed integer. +\end_layout + +\begin_layout Description +PyTypeNum_ISINTEGER (num) +\end_layout + +\begin_layout Description +PyDataType_ISINTEGER (descr) +\end_layout + +\begin_layout Description +PyArray_ISINTEGER (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents any integer. +\end_layout + +\begin_layout Description +PyTypeNum_ISFLOAT (num) +\end_layout + +\begin_layout Description +PyDataType_ISFLOAT (descr) +\end_layout + +\begin_layout Description +PyArray_ISFLOAT (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents any floating point number. +\end_layout + +\begin_layout Description +PyTypeNum_ISCOMPLEX (num) +\end_layout + +\begin_layout Description +PyDataType_ISCOMPLEX (descr) +\end_layout + +\begin_layout Description +PyArray_ISCOMPLEX (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents any complex floating point number. +\end_layout + +\begin_layout Description +PyTypeNum_ISNUMBER (num) +\end_layout + +\begin_layout Description +PyDataType_ISNUMBER (descr) +\end_layout + +\begin_layout Description +PyArray_ISNUMBER (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents any integer, floating point, or complex floating point + number. +\end_layout + +\begin_layout Description +PyTypeNum_ISSTRING (num) +\end_layout + +\begin_layout Description +PyDataType_ISSTRING (descr) +\end_layout + +\begin_layout Description +PyArray_ISSTRING (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents a string data type. +\end_layout + +\begin_layout Description +PyTypeNum_ISPYTHON (num) +\end_layout + +\begin_layout Description +PyDataType_ISPYTHON (descr) +\end_layout + +\begin_layout Description +PyArray_ISPYTHON (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents an enumerated type corresponding to one of the standard + Python scalar (bool, int, float, or complex). + +\end_layout + +\begin_layout Description +PyTypeNum_ISFLEXIBLE (num) +\end_layout + +\begin_layout Description +PyDataType_ISFLEXIBLE (descr) +\end_layout + +\begin_layout Description +PyArray_ISFLEXIBLE (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents one of the flexible array types ( +\family typewriter +NPY_STRING +\family default +, +\family typewriter +NPY_UNICODE +\family default +, or +\family typewriter +NPY_VOID +\family default +). +\end_layout + +\begin_layout Description +PyTypeNum_ISUSERDEF (num) +\end_layout + +\begin_layout Description +PyDataType_ISUSERDEF (descr) +\end_layout + +\begin_layout Description +PyArray_ISUSERDEF (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents a user-defined type. +\end_layout + +\begin_layout Description +PyTypeNum_ISEXTENDED (num) +\end_layout + +\begin_layout Description +PyDataType_ISEXTENDED (descr) +\end_layout + +\begin_layout Description +PyArray_ISEXTENDED (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type is either flexible or user-defined. +\end_layout + +\begin_layout Description +PyTypeNum_ISOBJECT (num) +\end_layout + +\begin_layout Description +PyDataType_ISOBJECT (descr) +\end_layout + +\begin_layout Description +PyArray_ISOBJECT (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents object data type. +\end_layout + +\begin_layout Description +PyTypeNum_ISBOOL (num) +\end_layout + +\begin_layout Description +PyDataType_ISBOOL (descr) +\end_layout + +\begin_layout Description +PyArray_ISBOOL (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type represents Boolean data type. +\end_layout + +\begin_layout Description +PyDataType_HASFIELDS (descr) +\end_layout + +\begin_layout Description +PyArray_HASFIELDS (obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type has fields associated with it. +\end_layout + +\begin_layout Description +PyArray_ISNOTSWAPPED (m) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of the ndarray +\emph on +m +\emph default + is in machine byte-order according to the array's data-type descriptor. +\end_layout + +\begin_layout Description +PyArray_ISBYTESWAPPED (m) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of the ndarray +\emph on +m +\emph default + is +\series bold +not +\series default + in machine byte-order according to the array's data-type descriptor. + +\end_layout + +\begin_layout Description +PyArray_EquivTypes ( +\family typewriter +Bool +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + type1, +\family typewriter +PyArray_Descr* +\family default + type2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return +\family typewriter +NPY_TRUE +\family default + if +\emph on +type1 +\emph default + and +\emph on +type2 +\emph default + actually represent equivalent types for this platform (the fortran member + of each type is ignored). + For example, on 32-bit platforms, +\family typewriter +NPY_LONG +\family default + and +\family typewriter +NPY_INT +\family default + are equivalent. + Otherwise return +\family typewriter +NPY_FALSE +\family default +. +\end_layout + +\begin_layout Description +PyArray_EquivArrTypes ( +\family typewriter +Bool +\family default +) ( +\family typewriter +PyArrayObject* +\family default + a1, +\family typewriter +PyArrayObject +\family default +* a2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return +\family typewriter +NPY_TRUE +\family default + if +\emph on +a1 +\emph default + and +\emph on +a2 +\emph default + are arrays with equivalent types for this platform. + +\end_layout + +\begin_layout Description +PyArray_EquivTypenums ( +\family typewriter +Bool +\family default +) ( +\family typewriter +int +\family default + typenum1, +\family typewriter +int +\family default + typenum2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Special case of +\family typewriter +PyArray_EquivTypes +\family default +(...) that does not accept flexible data types but may be easier to call. + +\end_layout + +\begin_layout Description +PyArray_EquivByteorders (int) (<byteorder> b1, <byteorder> b2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + True if byteorder characters ( +\family typewriter +NPY_LITTLE +\family default +, +\family typewriter +NPY_BIG +\family default +, +\family typewriter +NPY_NATIVE +\family default +, +\family typewriter +NPY_IGNORE +\family default +) are either equal or equivalent as to their specification of a native byte + order. + Thus, on a little-endian machine +\family typewriter +NPY_LITTLE +\family default + and +\family typewriter +NPY_NATIVE +\family default + are equivalent where they are not equivalent on a big-endian machine. + +\end_layout + +\begin_layout Subsubsection +Converting data types +\end_layout + +\begin_layout Description +PyArray_Cast ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr, +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Mainly for backwards compatibility to the Numeric C-API and for simple + casts to non-flexible types. + Return a new array object with the elements of +\emph on +arr +\emph default + cast to the data-type +\emph on +typenum +\emph default + which must be one of the enumerated types and not a flexible type. +\end_layout + +\begin_layout Description +PyArray_CastToType ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr, +\family typewriter +PyArray_Descr* +\family default + type, +\family typewriter +int +\family default + fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a new array of the +\emph on +type +\emph default + specified, casting the elements of +\emph on +arr +\emph default + as appropriate. + The fortran argument specifies the ordering of the output array. + +\end_layout + +\begin_layout Description +PyArray_CastTo ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + out, +\family typewriter +PyArrayObject* +\family default + in) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Cast the elements of the array +\emph on +in +\emph default + into the array +\emph on +out +\emph default +. + The output array should be writeable, have an integer-multiple of the number + of elements in the input array (more than one copy can be placed in out), + and have a data type that is one of the builtin types. + Returns 0 on success and -1 if an error occurs. +\end_layout + +\begin_layout Description +PyArray_GetCastFunc ( +\family typewriter +PyArray_VectorUnaryFunc* +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + from, +\family typewriter +int +\family default + totype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the low-level casting function to cast from the given descriptor + to the builtin type number. + If no casting function exists return +\family typewriter +NULL +\family default + and set an error. + Using this function instead of direct access to +\emph on +from +\emph default +->f->cast will allow support of any user-defined casting functions added + to a descriptors casting dictionary. + +\end_layout + +\begin_layout Description +PyArray_CanCastSafely ( +\family typewriter +int +\family default +) ( +\family typewriter +int +\family default + fromtype, +\family typewriter +int +\family default + totype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns non-zero if an array of data type +\emph on +fromtype +\emph default + can be cast to an array of data type +\emph on +totype +\emph default + without losing information. + An exception is that 64-bit integers are allowed to be cast to 64-bit floating + point values even though this can lose precision on large integers so as + not to proliferate the use of long doubles without explict requests. + Flexible array types are not checked according to their lengths with this + function. + +\end_layout + +\begin_layout Description +PyArray_CanCastTo ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + fromtype, +\family typewriter +PyArray_Descr* +\family default + totype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns non-zero if an array of data type +\emph on +fromtype +\emph default + (which can include flexible types) can be cast safely to an array of data + type +\emph on +totype +\emph default + (which can include flexible types). + This is basically a wrapper around +\family typewriter +PyArray_CanCastSafely +\family default + with additional support for size checking if +\emph on +fromtype +\emph default + and +\emph on +totype +\emph default + are +\family typewriter +NPY_STRING +\family default + or +\family typewriter +NPY_UNICODE +\family default +. +\end_layout + +\begin_layout Description +PyArray_ObjectType ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +int +\family default + mintype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function is useful for determining a common type that two or more + arrays can be converted to. + It only works for non-flexible array types as no itemsize information is + passed. + The +\emph on +mintype +\emph default + argument represents the minimum type acceptable, and +\emph on +op +\emph default + represents the object that will be converted to an array. + The return value is the enumerated typenumber that represents the data-type + that +\emph on +op +\emph default + should have. +\end_layout + +\begin_layout Description +PyArray_ArrayType ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + mintype, +\family typewriter +PyArray_Descr* +\family default + outtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function works similarly to +\family typewriter +PyArray_ObjectType +\family default +(...) except it handles flexible arrays. + The +\emph on +mintype +\emph default + argument can have an itemsize member and the +\emph on +outtype +\emph default + argument will have an itemsize member at least as big but perhaps bigger + depending on the object +\emph on +op +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_ConvertToCommonType ( +\family typewriter +PyArrayObject** +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +int* +\family default + n) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert a sequence of Python objects contained in +\emph on +op +\emph default + to an array of ndarrays each having the same data type. + The type is selected based on the typenumber (larger type number is chosen + over a smaller one) ignoring objects that are only scalars. + The length of the sequence is returned in +\emph on +n +\emph default +, and an +\emph on +n +\emph default +-length array of +\family typewriter +PyArrayObject +\family default + pointers is the return value (or +\family typewriter +NULL +\family default + if an error occurs). + The returned array must be freed by the caller of this routine (using +\family typewriter +PyDataMem_FREE +\family default +) and all the array objects in it +\family typewriter +DECREF +\family default +'d or a memory-leak will occur. + The example template-code below shows a typically usage. +\end_layout + +\begin_layout LyX-Code +mps = PyArray_ConvertToCommonType(obj, &n); +\end_layout + +\begin_layout LyX-Code +if (mps==NULL) return NULL; +\end_layout + +\begin_layout LyX-Code +<code> +\end_layout + +\begin_layout LyX-Code +<before return> +\end_layout + +\begin_layout LyX-Code +for (i=0; i<n; i++) Py_DECREF(mps[i]); +\end_layout + +\begin_layout LyX-Code +PyDataMem_FREE(mps); +\end_layout + +\begin_layout LyX-Code +<return> +\end_layout + +\begin_layout Description +PyArray_Zero ( +\family typewriter +char* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to newly created memory of size +\emph on +arr +\emph default +->itemsize that holds the representation of 0 for that type. + The returned pointer, +\emph on +ret +\emph default +, +\series bold +must be freed +\series default + using +\family typewriter +\emph on +PyDataMem_FREE +\family default +\emph default +(ret) when it is not needed anymore. +\end_layout + +\begin_layout Description +PyArray_One ( +\family typewriter +char* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to newly created memory of size +\emph on +arr +\emph default +->itemsize that holds the representation of 1 for that type. + The returned pointer, +\emph on +ret +\emph default +, +\series bold +must be freed +\series default + using +\family typewriter +PyDataMem_FREE +\family default +(ret) when it is not needed anymore. +\end_layout + +\begin_layout Description +PyArray_ValidType ( +\family typewriter +int +\family default +) ( +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns +\family typewriter +NPY_TRUE +\family default + if +\family typewriter +\emph on +typenum +\family default +\emph default + represents a valid type-number (builtin or user-defined or character code). + Otherwise, this function returns +\family typewriter +NPY_FALSE +\family default +. +\end_layout + +\begin_layout Subsubsection +New data types +\end_layout + +\begin_layout Description +PyArray_InitArrFuncs ( +\family typewriter +void +\family default +) ( +\family typewriter +PyArray_ArrFuncs* +\family default + f) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Initialize all function pointers and members to +\family typewriter +NULL +\family default +. +\end_layout + +\begin_layout Description +PyArray_RegisterDataType ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Register a data-type as a new user-defined data type for arrays. + The type must have most of its entries filled in. + This is not always checked and errors can produce segfaults. + In particular, the typeobj member of the +\family typewriter +dtype +\family default + structure must be filled with a Python type that has a fixed-size element-size + that corresponds to the elsize member of +\emph on +dtype +\emph default +. + Also the +\family typewriter +f +\family default + member must have the required functions: nonzero, copyswap, copyswapn, + getitem, setitem, and cast (some of the cast functions may be +\family typewriter +NULL +\family default + if no support is desired). + To avoid confusion, you should choose a unique character typecode but this + is not enforced and not relied on internally. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + A user-defined type number is returned that uniquely identifies the type. + A pointer to the new structure can then be obtained from +\family typewriter +PyArray_DescrFromType +\family default + using the returned type number. + A -1 is returned if an error occurs. + If this +\family typewriter +\emph on +dtype +\family default +\emph default + has already been registered (checked only by the address of the pointer), + then return the previously-assigned type-number. + +\end_layout + +\begin_layout Description +PyArray_RegisterCastFunc ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + descr, +\family typewriter +int +\family default + totype, +\family typewriter +PyArray_VectorUnaryFunc* +\family default + castfunc) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Register a low-level casting function, +\emph on +castfunc +\emph default +, to convert from the data-type, +\emph on +descr +\emph default +, to the given data-type number, +\emph on +totype +\emph default +. + Any old casting function is over-written. + A +\family typewriter +0 +\family default + is returned on success or a +\family typewriter +-1 +\family default + on failure. + +\end_layout + +\begin_layout Description +PyArray_RegisterCanCast ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + descr, +\family typewriter +int +\family default + totype, +\family typewriter +PyArray_SCALARKIND +\family default + scalar) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Register the data-type number, +\emph on +totype +\emph default +, as castable from data-type object, +\emph on +descr +\emph default +, of the given +\emph on +scalar +\emph default + kind. + Use +\emph on +scalar +\emph default + = +\family typewriter +NPY_NOSCALAR +\family default + to register that an array of data-type +\emph on +descr +\emph default + can be cast safely to a data-type whose type_number is +\emph on +totype +\emph default +. + +\end_layout + +\begin_layout Subsubsection +Special functions for PyArray_OBJECT +\end_layout + +\begin_layout Description +PyArray_INCREF ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Used for an array, +\emph on +op +\emph default +, that contains any Python objects. + It increments the reference count of every object in the array according + to the data-type of +\emph on +op +\emph default +. + A -1 is returned if an error occurs, otherwise 0 is returned. +\end_layout + +\begin_layout Description +PyArray_Item_INCREF ( +\family typewriter +void +\family default +) ( +\family typewriter +char* +\family default + ptr, +\family typewriter +PyArray_Descr* +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A function to INCREF all the objects at the location +\emph on +ptr +\emph default + according to the data-type +\emph on +dtype +\emph default +. + If +\emph on +ptr +\emph default + is the start of a record with an object at any offset, then this will (recursiv +ely) increment the reference count of all object-like items in the record. +\end_layout + +\begin_layout Description +PyArray_XDECREF ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Used for an array, +\emph on +op +\emph default +, that contains any Python objects. + It decrements the reference count of every object in the array according + to the data-type of +\emph on +op +\emph default +. + Normal return value is 0. + A -1 is returned if an error occurs. +\end_layout + +\begin_layout Description +PyArray_Item_XDECREF ( +\family typewriter +void +\family default +) ( +\family typewriter +char* +\family default + ptr, +\family typewriter +PyArray_Descr* +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A function to XDECREF all the object-like items at the loacation +\emph on +ptr +\emph default + as recorded in the data-type, +\emph on +dtype +\emph default +. + This works recursively so that if +\family typewriter +dtype +\family default + itself has fields with data-types that contain object-like items, all the + object-like fields will be XDECREF +\family typewriter +'d +\family default +. + +\end_layout + +\begin_layout Description +PyArray_FillObjectArray ( +\family typewriter +void +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Fill a newly created array with a single value obj at all locations in + the structure with object data-types. + No checking is performed but +\emph on +arr +\emph default + must be of data-type +\family typewriter +PyArray_OBJECT +\family default + and be single-segment and uninitialized (no previous objects in position). + Use +\family typewriter +PyArray_DECREF +\family default +( +\emph on +arr +\emph default +) if you need to decrement all the items in the object array prior to calling + this function. + +\end_layout + +\begin_layout Subsection +Array flags +\end_layout + +\begin_layout Subsubsection +Basic Array Flags +\end_layout + +\begin_layout Standard +An ndarray can have a data segment that is not a simple contiguous chunk + of well-behaved memory you can manipulate. + It may not be aligned with word boundaries (very important on some platforms). + It might have its data in a different byte-order than the machine recognizes. + It might not be writeable. + It might be in Fortan-contiguous order. + The array flags are used to indicate what can be said about data associated + with an array. +\end_layout + +\begin_layout Description +NPY_C_CONTIGUOUS The data area is in C-style contiguous order (last index + varies the fastest). +\end_layout + +\begin_layout Description +NPY_F_CONTIGUOUS The data area is in Fortran-style contiguous order (first + index varies the fastest). +\end_layout + +\begin_layout Description +NPY_OWNDATA The data area is owned by this array. +\end_layout + +\begin_layout Description +NPY_ALIGNED The data area is aligned appropriately (for all strides). +\end_layout + +\begin_layout Description +NPY_WRITEABLE The data area can be written to. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + Notice that the above 3 flags are are defined so that a new, well-behaved + array has these flags defined as true. + +\end_layout + +\begin_layout Description +NPY_UPDATEIFCOPY The data area represents a (well-behaved) copy whose informatio +n should be transferred back to the original when this array is deleted. +\end_layout + +\begin_layout Subsubsection +Combinations of array flags +\end_layout + +\begin_layout Description +NPY_BEHAVED +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +NPY_WRITEABLE +\end_layout + +\begin_layout Description +NPY_CARRAY +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_BEHAVED +\end_layout + +\begin_layout Description +NPY_CARRAY_RO +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_FARRAY +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_BEHAVED +\end_layout + +\begin_layout Description +NPY_FARRAY_RO +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Description +NPY_DEFAULT +\family typewriter +NPY_CARRAY +\end_layout + +\begin_layout Description +NPY_UPDATE_ALL +\family typewriter +NPY_C_CONTIGUOUS +\family default + | +\family typewriter +NPY_F_CONTIGUOUS +\family default + | +\family typewriter +NPY_ALIGNED +\end_layout + +\begin_layout Subsubsection +Flag-like constants +\end_layout + +\begin_layout Standard +These constants are used in PyArray_FromAny (and its macro forms) to specify + desired properties of the new array. +\end_layout + +\begin_layout Description +NPY_FORCECAST Cast to the desired type, even if it can't be done without + losing information. +\end_layout + +\begin_layout Description +NPY_ENSURECOPY Make sure the resulting array is a copy of the original. +\end_layout + +\begin_layout Description +NPY_ENSUREARRAY Make sure the resulting object is an actual ndarray (or + bigndarray), and not a sub-class. +\end_layout + +\begin_layout Description +NPY_NOTSWAPPED Only used in +\family typewriter +PyArray_CheckFromAny +\family default + to over-ride the byteorder of the data-type object passed in. + +\end_layout + +\begin_layout Description +NPY_BEHAVED_NS +\family typewriter +NPY_ALIGNED +\family default + | +\family typewriter +NPY_WRITEABLE +\family default + | +\family typewriter +NPY_NOTSWAPPED +\end_layout + +\begin_layout Subsubsection +Flag checking +\end_layout + +\begin_layout Standard +For all of these macros +\emph on +arr +\emph default + must be an instance of a (subclass of) +\family typewriter +PyArray_Type +\family default +, but no checking is done. +\end_layout + +\begin_layout Description +PyArray_CHKFLAGS (arr, flags) +\end_layout + +\begin_layout Description +\InsetSpace ~ + The first parameter, arr, must be an ndarray or subclass. + The parameter, +\emph on +flags +\emph default +, should be an integer consisting of bitwise combinations of the possible + flags an array can have: +\family typewriter +NPY_C_CONTIGUOUS +\family default +, +\family typewriter +NPY_F_CONTIGUOUS +\family default +, +\family typewriter +NPY_OWNDATA +\family default +, +\family typewriter +NPY_ALIGNED +\family default +, +\family typewriter +NPY_WRITEABLE +\family default +, +\family typewriter +NPY_UPDATEIFCOPY +\family default +. +\end_layout + +\begin_layout Description +PyArray_ISCONTIGUOUS (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +arr +\emph default + is C-style contiguous. +\end_layout + +\begin_layout Description +PyArray_ISFORTRAN (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +arr +\emph default + is Fortran-style contiguous. +\end_layout + +\begin_layout Description +PyArray_ISWRITEABLE (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + can be written to +\end_layout + +\begin_layout Description +PyArray_ISALIGNED (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is properly aligned on the machine. +\end_layout + +\begin_layout Description +PyArray_ISBEHAVED (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evalutes true if the data area of +\emph on +arr +\emph default + is aligned and writeable and in machine byte-order according to its descriptor. +\end_layout + +\begin_layout Description +PyArray_ISBEHAVED_RO (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is aligned and in machine byte-order. +\end_layout + +\begin_layout Description +PyArray_ISCARRAY (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is C-style contiguous, and +\family typewriter +PyArray_ISBEHAVED +\family default +( +\emph on +arr +\emph default +) is true. +\end_layout + +\begin_layout Description +PyArray_ISFARRAY (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is Fortran-style contiguous and +\family typewriter +PyArray_ISBEHAVED +\family default +( +\emph on +arr +\emph default +) is true. +\end_layout + +\begin_layout Description +PyArray_ISCARRAY_RO (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is C-style contiguous, aligned, and in machine byte-order. + +\end_layout + +\begin_layout Description +PyArray_ISFARRAY_RO (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + is Fortran-style contiguous, aligned, and in machine byte-order +\series bold +. + +\end_layout + +\begin_layout Description +PyArray_ISONESEGMENT (arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if the data area of +\emph on +arr +\emph default + consists of a single (C-style or Fortran-style) contiguous segment. +\end_layout + +\begin_layout Description +PyArray_UpdateFlags ( +\family typewriter +void +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr, +\family typewriter +int +\family default + flagmask) +\end_layout + +\begin_layout Description +\InsetSpace ~ + The +\family typewriter +NPY_C_CONTIGUOUS +\family default +, +\family typewriter +NPY_ALIGNED +\family default +, and +\family typewriter +NPY_F_CONTIGUOUS +\family default + array flags can be +\begin_inset Quotes eld +\end_inset + +calculated +\begin_inset Quotes erd +\end_inset + + from the array object itself. + This routine updates one or more of these flags of +\emph on +arr +\emph default + as specified in +\emph on +flagmask +\emph default + by performing the required calculation. + +\end_layout + +\begin_layout Warning +It is important to keep the flags updated (using PyArray_UpdateFlags can + help) whenever a manipulation with an array is performed that might cause + them to change. + Later calculations in NumPy that rely on the state of these flags do not + repeat the calculation to update them. + +\end_layout + +\begin_layout Subsection +Array method alternative API +\end_layout + +\begin_layout Subsubsection +Conversion +\end_layout + +\begin_layout Description +PyArray_GetField ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + offset) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +getfield +\series default +( +\emph on +dtype +\emph default +, +\emph on +offset +\emph default +). + Return a new array of the given +\emph on +dtype +\emph default + using the data in the current array at a specified +\emph on +offset +\emph default + in bytes. + The +\emph on +offset +\emph default + plus the itemsize of the new array type must be less than +\emph on +self +\emph default +->descr->elsize or an error is raised. + The same shape and strides as the original array are used. + Therefore, this function has the effect of returning a field from a record + array. + But, it can also be used to select specific bytes or groups of bytes from + any array type. + +\end_layout + +\begin_layout Description +PyArray_SetField ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +int +\family default + offset, +\family typewriter +PyObject* +\family default + val) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +setfield +\series default +( +\emph on +val +\emph default +, +\emph on +dtype +\emph default +, +\emph on +offset +\emph default +). + Set the field starting at +\emph on +offset +\emph default + in bytes and of the given +\emph on +dtype +\emph default + to +\emph on +val +\emph default +. + The +\emph on +offset +\emph default + plus +\emph on +dtype +\emph default +->elsize must be less than +\emph on +self +\emph default +->descr->elsize or an error is raised. + Otherwise, the +\emph on +val +\emph default + argument is converted to an array and copied into the field pointed to. + If necessary, the elements of +\emph on +val +\emph default + are repeated to fill the destination array, But, the number of elements + in the destination must be an integer multiple of the number of elements + in +\emph on +val +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_Byteswap ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +Bool +\family default + inplace) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +byteswap +\series default +( +\emph on +inplace +\emph default +). + Return an array whose data area is byteswapped. + If +\emph on +inplace +\emph default + is non-zero, then do the byteswap inplace and return a reference to self. + Otherwise, create a byteswapped copy and leave self unchanged. +\end_layout + +\begin_layout Description +PyArray_NewCopy ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + old, +\family typewriter +NPY_ORDER +\family default + order) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +copy +\series default +( +\emph on +fortran +\emph default +). + Make a copy of the +\emph on +old +\emph default + array. + The returned array is always aligned and writeable with data interpreted + the same as the old array. + If +\emph on +order +\emph default + is +\family typewriter +NPY_CORDER +\family default +, then a C-style contiguous array is returned. + If +\emph on +order +\emph default + is +\family typewriter +NPY_FORTRANORDER +\family default +, then a Fortran-style contiguous array is returned. + If +\emph on +order is +\emph default + +\family typewriter +NPY_ANYORDER +\family default +, then the array returned is Fortran-style contiguous only if the old one + is; otherwise, it is C-style contiguous. + +\end_layout + +\begin_layout Description +PyArray_ToList ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +tolist +\series default +(). + Return a nested Python list from +\emph on +self +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_ToString (PyObject*) (PyArrayObject* self, NPY_ORDER order) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +tostring +\series default +( +\emph on +order +\emph default +). + Return the bytes of this array in a Python string. + +\end_layout + +\begin_layout Description +PyArray_ToFile ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +FILE* +\family default + fp, +\family typewriter +char* +\family default + sep, +\family typewriter +char* +\family default + format) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Write the contents of +\emph on +self +\emph default + to the file pointer +\emph on +fp +\emph default + in C-style contiguous fashion. + Write the data as binary bytes if +\family typewriter +\emph on +sep +\family default +\emph default + is the string +\begin_inset Quotes eld +\end_inset + + +\begin_inset Quotes erd +\end_inset + + or +\family typewriter +NULL +\family default +. + Otherwise, write the contents of +\emph on +self +\emph default + as text using the +\family typewriter +\emph on +sep +\family default +\emph default + string as the item separator. + Each item will be printed to the file. + If the +\emph on +format +\emph default + string is not +\family typewriter +NULL +\family default + or +\begin_inset Quotes eld +\end_inset + + +\begin_inset Quotes erd +\end_inset + +, then it is a Python print statement format string showing how the items + are to be written. +\end_layout + +\begin_layout Description +PyArray_Dump ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + self, +\family typewriter +PyObject* +\family default + file, +\family typewriter +int +\family default + protocol) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Pickle the object in +\emph on +self +\emph default + to the given +\emph on +file +\emph default + (either a string or a Python file object). + If +\emph on +file +\emph default + is a Python string it is considered to be the name of a file which is then + opened in binary mode. + The given +\emph on +protocol +\emph default + is used (if +\emph on +protocol +\emph default + is negative, or the highest available is used). + This is a simple wrapper around cPickle.dump( +\emph on +self +\emph default +, +\emph on +file +\emph default +, +\emph on +protocol +\emph default +). +\end_layout + +\begin_layout Description +PyArray_Dumps ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + self, +\family typewriter +int +\family default + protocol) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Pickle the object in +\emph on +self +\emph default + to a Python string and return it. + Use the Pickle +\emph on +protocol +\emph default + provided (or the highest available if +\emph on +protocol +\emph default + is negative). + +\end_layout + +\begin_layout Description +PyArray_FillWithScalar ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Fill the array, +\emph on +arr +\emph default +, with the given scalar object, +\emph on +obj +\emph default +. + The object is first converted to the data type of +\emph on +arr +\emph default +, and then copied into every location. + A -1 is returned if an error occurs, otherwise 0 is returned. +\end_layout + +\begin_layout Description +PyArray_View ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Descr* +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +view +\series default +( +\emph on +dtype +\emph default +). + Return a new view of the array +\emph on +self +\emph default + as possibly a different data-type, +\emph on +dtype +\emph default +. + If +\emph on +dtype +\emph default + is +\family typewriter +NULL +\family default +, then the returned array will have the same data type as +\emph on +self +\emph default +. + The new data-type must be consistent with the size of +\emph on +self +\emph default +. + Either the itemsizes must be identical, or +\emph on +self +\emph default + must be single-segment and the total number of bytes must be the same. + In the latter case the dimensions of the returned array will be altered + in the last (or first for Fortran-style contiguous arrays) dimension. + The data area of the returned array and self is exactly the same. +\end_layout + +\begin_layout Subsubsection +Shape Manipulation +\end_layout + +\begin_layout Description +PyArray_Newshape ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Dims* +\family default + newshape) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Result will be a new array (pointing to the same memory location as +\emph on +self +\emph default + if possible), but having a shape given by +\emph on +newshape +\emph default +. + If the new shape is not compatible with the strides of +\emph on +self +\emph default +, then a copy of the array with the new specified shape will be returned. + +\end_layout + +\begin_layout Description +PyArray_Reshape ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + shape) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\family typewriter +\emph on +self +\family default +\emph default +. +\series bold +reshape +\series default +( +\family typewriter +\emph on +shape +\family default +\emph default +) where +\emph on +shape +\emph default + is a sequence. + Converts +\emph on +shape +\emph default + to a +\family typewriter +PyArray_Dims +\family default + structure and calls +\family typewriter +PyArray_Newshape +\family default + internally. + +\end_layout + +\begin_layout Description +PyArray_Squeeze ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +squeeze +\series default +(). + Return a new view of +\emph on +self +\emph default + with all of the dimensions of length 1 removed from the shape. + +\end_layout + +\begin_layout Warning +matrix objects are always 2-dimensional. + Therefore, +\family typewriter +PyArray_Squeeze +\family default + has no effect on arrays of matrix sub-class. + +\end_layout + +\begin_layout Description +PyArray_SwapAxes ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + a1, +\family typewriter +int +\family default + a2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +swapaxes +\series default +( +\emph on +a1 +\emph default +, +\emph on +a2 +\emph default +). + The returned array is a new view of the data in +\emph on +self +\emph default + with the given axes, +\emph on +a1 +\emph default + and +\emph on +a2 +\emph default +, swapped. +\end_layout + +\begin_layout Description +PyArray_Resize ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Dims* +\family default + newshape, +\family typewriter +int +\family default + refcheck, NPY_ORDER fortran) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +resize +\series default +( +\emph on +newshape +\emph default +, refcheck +\family typewriter += +\family default +\emph on +refcheck +\emph default +, order= +\shape italic +fortran +\shape default +). + This function only works on single-segment arrays. + It changes the shape of +\emph on +self +\emph default + inplace and will reallocate the memory for +\emph on +self +\emph default + if +\emph on +newshape +\emph default + has a different total number of elements then the old shape. + If reallocation is necessary, then +\emph on +self +\emph default + must own its data, have +\emph on +self +\emph default +- +\family typewriter +>base==NULL +\family default +, have +\emph on +self +\emph default +- +\family typewriter +>weakrefs==NULL +\family default +, and (unless refcheck is 0) not be referenced by any other array. + A reference to the new array is returned. + The +\shape italic +fortran +\shape default + argument can be NPY_ANYORDER, NPY_CORDER, or NPY_FORTRANORDER. + This argument is used if the number of dimension is (or is being resized + to be) greater than 2. + It currently has no effect. + Eventually it could be used to determine how the resize operation should + view the data when constructing a differently-dimensioned array. + +\end_layout + +\begin_layout Description +PyArray_Transpose ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyArray_Dims* +\family default + permute) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +transpose +\series default +( +\emph on +permute +\emph default +). + Permute the axes of the ndarray object +\emph on +self +\emph default + according to the data structure +\emph on +permute +\emph default + and return the result. + If +\emph on +permute +\emph default + is +\family typewriter +NULL +\family default +, then the resulting array has its axes reversed. + For example if +\emph on +self +\emph default + has shape +\begin_inset Formula $10\times20\times30$ +\end_inset + +, and +\emph on +permute +\family typewriter +\emph default +.ptr +\family default + is (0,2,1) the shape of the result is +\begin_inset Formula $10\times30\times20.$ +\end_inset + + If +\emph on +permute +\emph default + is +\family typewriter +NULL +\family default +, the shape of the result is +\begin_inset Formula $30\times20\times10.$ +\end_inset + + +\end_layout + +\begin_layout Description +PyArray_Flatten ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +NPY_ORDER +\family default + order) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +flatten +\series default +( +\emph on +order +\emph default +). + Return a 1-d copy of the array. + If +\emph on +order +\emph default + is +\family typewriter +NPY_FORTRANORDER +\family default + the elements are scanned out in Fortran order (first-dimension varies the + fastest). + If +\emph on +order +\emph default + is +\family typewriter +NPY_CORDER +\family default +, the elements of +\family typewriter +self +\family default + are scanned in C-order (last dimension varies the fastest). + If +\emph on +order +\emph default + +\family typewriter +NPY_ANYORDER +\family default +, then the result of +\family typewriter +PyArray_ISFORTRAN +\family default +( +\emph on +self +\emph default +) is used to determine which order to flatten. +\end_layout + +\begin_layout Description +PyArray_Ravel ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +NPY_ORDER +\family default + order) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +.ravel( +\emph on +order +\emph default +). + Same basic functionality as +\family typewriter +PyArray_Flatten +\family default +( +\emph on +self +\emph default +, +\emph on +order +\emph default +) except if +\emph on +order +\emph default + is 0 and +\emph on +self +\emph default + is C-style contiguous, the shape is altered but no copy is performed. +\end_layout + +\begin_layout Subsubsection +Item selection and manipulation +\end_layout + +\begin_layout Description +PyArray_TakeFrom ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + indices, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + ret, +\family typewriter +NPY_CLIPMODE +\family default + clipmode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +take +\series default +( +\emph on +indices +\emph default +, +\emph on +axis +\emph default +, +\emph on +ret +\emph default +, +\emph on +clipmode +\emph default +) except +\emph on +axis +\emph default +=None in Python is obtained by setting +\emph on +axis +\emph default += +\family typewriter +NPY_MAXDIMS +\family default + in C. + Extract the items from self indicated by the integer-valued +\emph on +indices +\emph default + along the given +\emph on +axis. + +\emph default + The clipmode argument can be +\family typewriter +NPY_RAISE +\family default +, +\family typewriter +NPY_WRAP +\family default +, or +\family typewriter +NPY_CLIP +\family default + to indicate what to do with out-of-bound indices. + The +\emph on +ret +\emph default + argument can specify an output array rather than having one created internally. + +\end_layout + +\begin_layout Description +PyArray_PutTo ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + values, +\family typewriter +PyObject* +\family default + indices, +\family typewriter +NPY_CLIPMODE +\family default + clipmode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +.put( +\emph on +values +\emph default +, +\emph on +indices +\emph default +, +\emph on +clipmode +\emph default +). + Put +\emph on +values +\emph default + into +\emph on +self +\emph default + at the corresponding (flattened) +\emph on +indices +\emph default +. + If +\emph on +values +\emph default + is too small it will be repeated as necessary. + +\end_layout + +\begin_layout Description +PyArray_PutMask ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + values, +\family typewriter +PyObject* +\family default + mask) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Place the +\emph on +values +\emph default + in +\emph on +self +\emph default + wherever corresponding positions (using a flattened context) in +\emph on +mask +\emph default + are true. + The +\emph on +mask +\emph default + and +\emph on +self +\emph default + arrays must have the same total number of elements. + If +\emph on +values +\emph default + is too small, it will be repeated as necessary. +\end_layout + +\begin_layout Description +PyArray_Repeat ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + op, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +repeat +\series default +( +\emph on +op +\emph default +, +\emph on +axis +\emph default +). + Copy the elements of +\emph on +self +\emph default +, +\emph on +op +\emph default + times along the given +\emph on +axis +\emph default +. + Either +\emph on +op +\emph default + is a scalar integer or a sequence of length +\emph on +self +\emph default +->dimensions[ +\emph on +axis +\emph default +] indicating how many times to repeat each item along the axis. +\end_layout + +\begin_layout Description +PyArray_Choose ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArrayObject* +\family default + ret, +\family typewriter +NPY_CLIPMODE +\family default + clipmode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +choose +\series default +( +\emph on +op +\emph default +, +\emph on +ret +\emph default +, +\emph on +clipmode +\emph default +). + Create a new array by selecting elements from the sequence of arrays in + +\emph on +op +\emph default + based on the integer values in +\emph on +self +\emph default +. + The arrays must all be broadcastable to the same shape and the entries + in +\emph on +self +\emph default + should be between 0 and len( +\emph on +op +\emph default +). + The output is placed in +\emph on +ret +\emph default + unless it is +\family typewriter +NULL +\family default + in which case a new output is created. + The +\emph on +clipmode +\emph default + argument determines behavior for when entries in +\emph on +self +\emph default + are not between 0 and len( +\emph on +op +\emph default +). +\end_layout + +\begin_deeper +\begin_layout Description +NPY_RAISE raise a ValueError; +\end_layout + +\begin_layout Description +NPY_WRAP wrap values <0 by adding len( +\emph on +op +\emph default +) and values >=len( +\emph on +op +\emph default +) by subtracting len( +\emph on +op +\emph default +) until they are in range; +\end_layout + +\begin_layout Description +NPY_CLIP all values are clipped to the region [0, len( +\emph on +op +\emph default +) ). +\end_layout + +\end_deeper +\begin_layout Description +PyArray_Sort ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +sort +\series default +( +\emph on +axis +\emph default +). + Return an array with the items of +\emph on +self +\emph default + sorted along +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Description +PyArray_ArgSort ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +argsort +\series default +( +\emph on +axis +\emph default +). + Return an array of indices such that selection of these indices along the + given +\family typewriter +axis +\family default + would return a sorted version of +\emph on +self +\emph default +. + If +\emph on +self +\emph default +->descr is a data-type with fields defined, then self->descr->names is used + to determine the sort order. + A comparison where the first field is equal will use the second field and + so on. + To alter the sort order of a record array, create a new data-type with + a different order of names and construct a view of the array with that + new data-type. + +\end_layout + +\begin_layout Description +PyArray_LexSort ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + sort_keys, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Given a sequence of arrays ( +\emph on +sort_keys +\emph default +) of the same shape, return an array of indices (similar to +\family typewriter +PyArray_ArgSort +\family default +(...)) that would sort the arrays lexicographically. + A lexicographic sort specifies that when two keys are found to be equal, + the order is based on comparison of subsequent keys. + A merge sort (which leaves equal entries unmoved) is required to be defined + for the types. + The sort is accomplished by sorting the indices first using the first +\emph on +sort_key +\emph default + and then using the second +\emph on +sort_key +\emph default + and so forth. + This is equivalent to the lexsort( +\emph on +sort_keys +\emph default +, +\emph on +axis +\emph default +) Python command. + Because of the way the merge-sort works, be sure to understand the order + the +\emph on +sort_keys +\emph default + must be in (reversed from the order you would use when comparing two elements). +\end_layout + +\begin_layout Description +\InsetSpace ~ + If these arrays are all collected in a record array, then +\family typewriter +PyArray_Sort +\family default +(...) can also be used to sort the array directly. + +\end_layout + +\begin_layout Description +PyArray_SearchSorted ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + values) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +searchsorted +\series default +( +\emph on +values +\emph default +). + Assuming +\emph on +self +\emph default + is a 1-d array in ascending order representing bin boundaries then the + output is an array the same shape as +\emph on +values +\emph default + of bin numbers, giving the bin into which each item in +\emph on +values +\emph default + would be placed. + No checking is done on whether or not self is in ascending order. +\end_layout + +\begin_layout Description +PyArray_Diagonal ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + offset, +\family typewriter +int +\family default + axis1, +\family typewriter +int +\family default + axis2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +diagonal +\series default +( +\emph on +offset +\emph default +, +\emph on +axis1 +\emph default +, +\emph on +axis2 +\emph default +). + Return the +\emph on +offset +\emph default + diagonals of the 2-d arrays defined by +\emph on +axis1 +\emph default + and +\emph on +axis2 +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_Nonzero ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +nonzero +\series default +(). + Returns a tuple of index arrays that select elements of +\emph on +self +\emph default + that are nonzero. + If (nd= +\family typewriter +PyArray_NDIM +\family default +( +\family typewriter +self +\family default +))==1, then a single index array is returned. + The index arrays have data type +\family typewriter +NPY_INTP +\family default +. + If a tuple is returned (nd +\begin_inset Formula $\neq$ +\end_inset + +1), then its length is nd. + +\end_layout + +\begin_layout Description +PyArray_Compress ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + condition, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +compress +\series default +( +\emph on +condition +\emph default +, +\emph on +axis +\emph default +). + Return the elements along +\emph on +axis +\emph default + corresponding to elements of +\emph on +condition +\emph default + that are true. + +\end_layout + +\begin_layout Subsubsection +Calculation +\end_layout + +\begin_layout Tip +Pass in NPY_MAXDIMS for axis in order to achieve the same effect that is + obtained by passing in axis = None in Python (treating the array as a 1-d + array). + +\end_layout + +\begin_layout Description +PyArray_ArgMax ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +argmax +\series default +( +\emph on +axis +\emph default +). + Return the index of the largest element of +\emph on +self +\emph default + along +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Description +PyArray_ArgMin ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +argmin +\series default +( +\emph on +axis +\emph default +). + Return the index of the smallest element of +\emph on +self +\emph default + along +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Max ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +max +\series default +( +\emph on +axis +\emph default +). + Return the largest element of +\emph on +self +\emph default + along the given +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Min ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +min +\series default +( +\emph on +axis +\emph default +). + Return the smallest element of +\emph on +self +\emph default + along the given +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Ptp ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +ptp +\series default +( +\emph on +axis +\emph default +). + Return the difference between the largest element of +\emph on +self +\emph default + along +\emph on +axis +\emph default + and the smallest element of +\emph on +self +\emph default + along +\emph on +axis +\emph default +. +\end_layout + +\begin_layout Note +The rtype argument specifies the data-type the reduction should take place + over. + This is important if the data-type of the array is not +\begin_inset Quotes eld +\end_inset + +large +\begin_inset Quotes erd +\end_inset + + enough to handle the output. + By default, all integer data-types are made at least as large as NPY_LONG + for the +\begin_inset Quotes eld +\end_inset + +add +\begin_inset Quotes erd +\end_inset + + and +\begin_inset Quotes eld +\end_inset + +multiply +\begin_inset Quotes erd +\end_inset + + ufuncs (which form the basis for mean, sum, cumsum, prod, and cumprod functions +). +\end_layout + +\begin_layout Description +PyArray_Mean ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +mean +\series default +( +\emph on +axis +\emph default +, +\emph on +rtype +\emph default +). + Returns the mean of the elements along the given +\emph on +axis +\emph default +, using the enumerated type +\emph on +rtype +\emph default + as the data type to sum in. + Default sum behavior is obtained using +\family typewriter +PyArray_NOTYPE +\family default + for +\emph on +rtype +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Trace ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + offset, +\family typewriter +int +\family default + axis1, +\family typewriter +int +\family default + axis2, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +trace +\series default +( +\emph on +offset +\emph default +, +\emph on +axis1 +\emph default +, +\emph on +axis2 +\emph default +, +\emph on +rtype +\emph default +). + Return the sum (using +\emph on +rtype +\emph default + as the data type of summation) over the +\emph on +offset +\emph default + diagonal elements of the 2-d arrays defined by +\emph on +axis1 +\emph default + and +\emph on +axis2 +\emph default + variables. + A positive offset chooses diagonals above the main diagonal. + A negative offset selects diagonals below the main diagonal. + +\end_layout + +\begin_layout Description +PyArray_Clip ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +PyObject* +\family default + min, +\family typewriter +PyObject* +\family default + max) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +clip +\series default +( +\emph on +min +\emph default +, +\emph on +max +\emph default +). + Clip an array, +\emph on +self +\emph default +, so that values larger than +\emph on +max +\emph default + are fixed to +\emph on +max +\emph default + and values less than +\emph on +min +\emph default + are fixed to +\emph on +min +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Conjugate ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +conjugate +\series default +() and +\emph on +self +\emph default +. +\series bold +conj +\series default +() Return the complex conjugate of +\emph on +self +\emph default +. + If +\emph on +self +\emph default + is not of complex data type, then return +\emph on +self +\emph default + with an reference. +\end_layout + +\begin_layout Description +PyArray_Round ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + decimals, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +round +\series default +( +\emph on +decimals +\emph default +, +\emph on +out +\emph default +). + Returns the array with elements rounded to the nearest decimal place. + The decimal place is defined as the +\begin_inset Formula $10^{-\textrm{decimals}}$ +\end_inset + + digit so that negative +\emph on +decimals +\emph default + cause rounding to the nearest 10's, 100's, etc. + If out is +\family typewriter +NULL +\family default +, then the output array is created, otherwise the output is placed in +\family typewriter +\emph on +out +\family default +\emph default + which must be the correct size and type. + +\end_layout + +\begin_layout Description +PyArray_Std ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +std +\series default +( +\emph on +axis +\emph default +, +\emph on +rtype +\emph default +). + Return the standard deviation using data along +\emph on +axis +\emph default + converted to data type +\emph on +rtype +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_Sum ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +sum +\series default +( +\family typewriter +\emph on +axis +\family default +\emph default +, +\family typewriter +\emph on +rtype +\family default +\emph default +). + Return 1-d vector sums of elements in +\emph on +self +\emph default + along +\emph on +axis +\emph default +. + Perform the sum after converting data to data type +\emph on +rtype +\emph default +. +\end_layout + +\begin_layout Description +PyArray_CumSum ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +cumsum +\series default +( +\family typewriter +\emph on +axis +\family default +\emph default +, +\family typewriter +\emph on +rtype +\family default +\emph default +). + Return cumulative 1-d sums of elements in +\emph on +self +\emph default + along +\emph on +axis +\emph default +. + Perform the sum after converting data to data type +\emph on +rtype +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Prod ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +prod +\series default +( +\emph on +axis +\emph default +, +\emph on +rtype +\emph default +). + Return 1-d products of elements in +\emph on +self +\emph default + along +\emph on +axis +\emph default +. + Perform the product after converting data to data type +\emph on +rtype +\emph default +. +\end_layout + +\begin_layout Description +PyArray_CumProd ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +int +\family default + rtype, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +cumprod +\series default +( +\emph on +axis +\emph default +, +\emph on +rtype +\emph default +). + Return 1-d cumulative products of elements in +\family typewriter +self +\family default + along +\family typewriter +axis +\family default +. + Perform the product after converting data to data type +\family typewriter +rtype +\family default +. +\end_layout + +\begin_layout Description +PyArray_All ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +all +\series default +( +\emph on +axis +\emph default +). + Return an array with True elements for every 1-d sub-array of +\family typewriter +self +\family default + defined by +\family typewriter +axis +\family default + in which all the elements are True. + +\end_layout + +\begin_layout Description +PyArray_Any ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + self, +\family typewriter +int +\family default + axis, +\family typewriter +PyArrayObject* +\family default + out) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Equivalent to +\emph on +self +\emph default +. +\series bold +any +\series default +( +\emph on +axis +\emph default +). + Return an array with True elements for every 1-d sub-array of +\emph on +self +\emph default + defined by +\emph on +axis +\emph default + in which any of the elements are True. + +\end_layout + +\begin_layout Subsection +Functions +\end_layout + +\begin_layout Subsubsection +Array Functions +\end_layout + +\begin_layout Description +PyArray_AsCArray ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject** +\family default + op, +\family typewriter +void* +\family default + ptr, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + nd, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + itemsize) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Sometimes it is useful to access a multidimensional array as a C-style + multi-dimensional array so that algorithms can be implemented using C's + a[i][j][k] syntax. + This routine returns a pointer, +\emph on +ptr +\emph default +, that simulates this kind of C-style array, for 1-, 2-, and 3-d ndarrays. + +\end_layout + +\begin_deeper +\begin_layout Description +op The address to any Python object. + This Python object will be replaced with an equivalent well-behaved, C-style + contiguous, ndarray of the given data type specifice by the last two arguments. + Be sure that stealing a reference in this way to the input object is justified. + +\end_layout + +\begin_layout Description +ptr The address to a (ctype* for 1-d, ctype** for 2-d or ctype*** for 3-d) + variable where ctype is the equivalent C-type for the data type. + On return, +\emph on +ptr +\emph default + will be addressable as a 1-d, 2-d, or 3-d array. + +\end_layout + +\begin_layout Description +dims An output array that contains the shape of the array object. + This array gives boundaries on any looping that will take place. + +\end_layout + +\begin_layout Description +nd The dimensionality of the array (1, 2, or 3). + +\end_layout + +\begin_layout Description +typenum The expected data type of the array. + +\end_layout + +\begin_layout Description +itemsize This argument is only needed when +\emph on +typenum +\emph default + represents a flexible array. + Otherwise it should be 0. + +\end_layout + +\end_deeper +\begin_layout Note +The simulation of a C-style array is not complete for 2-d and 3-d arrays. + For example, the simulated arrays of pointers cannot be passed to subroutines + expecting specific, statically-defined 2-d and 3-d arrays. + To pass to functions requiring those kind of inputs, you must statically + define the required array and copy data. + +\end_layout + +\begin_layout Description +PyArray_Free ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +void* +\family default + ptr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Must be called with the same objects and memory locations returned from + +\family typewriter +PyArray_AsCArray +\family default +(...). + This function cleans up memory that otherwise would get leaked. +\end_layout + +\begin_layout Description +PyArray_Concatenate ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Join the sequence of objects in +\emph on +obj +\emph default + together along +\emph on +axis +\emph default + into a single array. + If the dimensions or types are not compatible an error is raised. +\end_layout + +\begin_layout Description +PyArray_InnerProduct ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj1, +\family typewriter +PyObject* +\family default + obj2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Compute a product-sum over the last dimensions of +\emph on +obj1 +\emph default + and +\emph on +obj2 +\emph default +. + Neither array is conjugated. + +\end_layout + +\begin_layout Description +PyArray_MatrixProduct ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj1, +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Compute a product-sum over the last dimension of +\emph on +obj1 +\emph default + and the second-to-last dimension of +\emph on +obj2 +\emph default +. + For 2-d arrays this is a matrix-product. + Neither array is conjugated. + +\end_layout + +\begin_layout Description +PyArray_CopyAndTranspose ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject +\family default +* op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A specialized copy and transpose function that works only for 2-d arrays. + The returned array is a transposed copy of +\emph on +op +\emph default +. +\end_layout + +\begin_layout Description +PyArray_Correlate ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + op1, +\family typewriter +PyObject* +\family default + op2, +\family typewriter +int +\family default + mode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Compute the 1-d correlation of the 1-d arrays +\emph on +op1 +\emph default + and +\emph on +op2 +\emph default +. + The correlation is computed at each output point by multiplying +\emph on +op1 +\emph default + by a shifted version of +\emph on +op2 +\emph default + and summing the result. + As a result of the shift, needed values outside of the defined range of + +\emph on +op1 +\emph default + and +\emph on +op2 +\emph default + are interpreted as zero. + The mode determines how many shifts to return: 0 - return only shifts that + did not need to assume zero-values; 1 - return an object that is the same + size as +\emph on +op1 +\emph default +, 2 - return all possible shifts (any overlap at all is accepted). + +\end_layout + +\begin_layout Description +PyArray_Where ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + condition, +\family typewriter +PyObject* +\family default + x, +\family typewriter +PyObject* +\family default + y) +\end_layout + +\begin_layout Description +\InsetSpace ~ + If both +\family typewriter +x +\family default + and +\family typewriter +y +\family default + are +\family typewriter +NULL +\family default +, then return +\family typewriter +PyArray_Nonzero +\family default +( +\family typewriter +\emph on +condition +\family default +\emph default +). + Otherwise, both +\emph on +x +\emph default + and +\emph on +y +\emph default + must be given and the object returned is shaped like +\emph on +condition +\emph default + and has elements of +\emph on +x +\emph default + and +\emph on +y +\emph default + where +\emph on +condition +\emph default + is respectively True or False. + +\end_layout + +\begin_layout Subsubsection +Other functions +\end_layout + +\begin_layout Description +PyArray_CheckStrides ( +\family typewriter +Bool +\family default +) ( +\family typewriter +int +\family default + elsize, +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp +\family default + numbytes, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +npy_intp* +\family default + newstrides) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Determine if +\emph on +newstrides +\emph default + is a strides array consistent with the memory of an +\emph on +nd +\emph default +-dimensional array with shape +\family typewriter +dims +\family default + and element-size, +\emph on +elsize +\emph default +. + The +\emph on +newstrides +\emph default + array is checked to see if jumping by the provided number of bytes in each + direction will ever mean jumping more than +\emph on +numbytes +\emph default + which is the assumed size of the available memory segment. + If +\emph on +numbytes +\emph default + is 0, then an equivalent +\emph on +numbytes +\emph default + is computed assuming +\emph on +nd +\emph default +, +\emph on +dims +\emph default +, and +\emph on +elsize +\emph default + refer to a single-segment array. + Return +\family typewriter +NPY_TRUE +\family default + if +\emph on +newstrides +\emph default + is acceptable, otherwise return +\family typewriter +NPY_FALSE +\family default +. +\end_layout + +\begin_layout Description +PyArray_MultiplyList ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +npy_intp* +\family default + seq, +\family typewriter +int +\family default + n) +\end_layout + +\begin_layout Description +PyArray_MultiplyIntList ( +\family typewriter +int +\family default +) ( +\family typewriter +int* +\family default + seq, +\family typewriter +int +\family default + n) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Both of these routines multiply an +\emph on +n +\emph default +-length array, +\emph on +seq +\emph default +, of integers and return the result. + No overflow checking is performed. +\end_layout + +\begin_layout Description +PyArray_CompareLists ( +\family typewriter +int +\family default +) ( +\family typewriter +npy_intp* +\family default + l1, +\family typewriter +npy_intp* +\family default + l2, +\family typewriter +int +\family default + n) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Given two +\emph on +n +\emph default +-length arrays of integers, +\emph on +l1 +\emph default +, and +\emph on +l2 +\emph default +, return 1 if the lists are identical; otherwise, return 0. + +\end_layout + +\begin_layout Subsection +Array Iterators +\end_layout + +\begin_layout Standard +An array iterator is a simple way to access the elements of an N-dimensional + array quickly and efficiently. + Section +\begin_inset LatexCommand ref +reference "sec:array_iterator" + +\end_inset + + provides more description and examples of this useful approach to looping + over an array. + +\end_layout + +\begin_layout Description +PyArray_IterNew ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an array iterator object from the array, +\emph on +arr +\emph default +. + This is equivalent to +\emph on +arr +\emph default +. +\series bold +flat +\series default +. + The array iterator object makes it easy to loop over an N-dimensional non-conti +guous array in C-style contiguous fashion. + +\end_layout + +\begin_layout Description +PyArray_IterAllButAxis ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +int +\family default + *axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an array iterator that will iterate over all axes but the one provided + in +\emph on +*axis +\emph default +. + The returned iterator cannot be used with +\family typewriter +PyArray_ITER_GOTO1D +\family default +. + This iterator could be used to write something similar to what ufuncs do + wherein the loop over the largest axis is done by a separate sub-routine. + If +\emph on +*axis +\emph default + is negative then +\emph on +*axis +\emph default + will be set to the axis having the smallest stride and that axis will be + used. + +\end_layout + +\begin_layout Description +PyArray_BroadcastToShape ( +\family typewriter +PyObject* +\family default +)( +\family typewriter +PyObject* +\family default + arr, +\family typewriter +npy_intp +\family default + *dimensions, +\family typewriter +int +\family default + nd) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an array iterator that is broadcast to iterate as an array of the + shape provided by +\emph on +dimensions +\emph default + and +\emph on +nd +\emph default +. + +\end_layout + +\begin_layout Description +PyArrayIter_Check ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates true if +\emph on +op +\emph default + is an array iterator (or instance of a subclass of the array iterator type). + +\end_layout + +\begin_layout Description +PyArray_ITER_RESET ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + iterator) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Reset an +\emph on +iterator +\emph default + to the beginning of the array. +\end_layout + +\begin_layout Description +PyArray_ITER_NEXT ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + iterator) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Incremement the index and the dataptr members of the +\emph on +iterator +\emph default + to point to the next element of the array. + If the array is not (C-style) contiguous, also increment the N-dimensional + coordinates array. +\end_layout + +\begin_layout Description +PyArray_ITER_DATA ( +\family typewriter +void* +\family default +)( +\family typewriter +PyObject* +\family default + iterator) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A pointer to the current element of the array. + +\end_layout + +\begin_layout Description +PyArray_ITER_GOTO ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + iterator, +\family typewriter +npy_intp* +\family default + destination) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Set the +\emph on +iterator +\emph default + index, dataptr, and coordinates members to the location in the array indicated + by the N-dimensional c-array, +\emph on +destination +\emph default +, which must have size at least +\emph on +iterator +\emph default +->nd_m1+1. +\end_layout + +\begin_layout Description +PyArray_ITER_GOTO1D ( +\family typewriter +PyObject* +\family default + iterator, +\family typewriter +npy_intp +\family default + index) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Set the +\emph on +iterator +\emph default + index and dataptr to the location in the array indicated by the integer + +\emph on +index +\emph default + which points to an element in the C-styled flattened array. + +\end_layout + +\begin_layout Description +PyArray_ITER_NOTDONE ( +\family typewriter +int +\family default +)( +\family typewriter +PyObject* +\family default + iterator) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates TRUE as long as the iterator has not looped through all of the + elements, otherwise it evaluates FALSE. + +\end_layout + +\begin_layout Subsection +Broadcasting (multi-iterators) +\end_layout + +\begin_layout Description +PyArray_MultiIterNew ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + num, ...) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A simplified interface to broadcasting. + This function takes the number of arrays to broadcast and then +\emph on +num +\emph default + extra ( +\family typewriter +PyObject* +\family default +) arguments. + These arguments are converted to arrays and iterators are created. + +\family typewriter +PyArray_Broadcast +\family default + is then called on the resulting multi-iterator object. + The resulting, broadcasted mult-iterator object is then returned. + A broadcasted operation can then be performed using a single loop and using + +\family typewriter +PyArray_MultiIter_NEXT +\family default +(..) +\end_layout + +\begin_layout Description +PyArray_MultiIter_RESET ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + multi) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Reset all the iterators to the beginning in a multi-iterator object, +\emph on +multi +\emph default +. +\end_layout + +\begin_layout Description +PyArray_MultiIter_NEXT ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + multi) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Advance each iterator in a multi-iterator object, +\emph on +multi +\emph default +, to its next (broadcasted) element. +\end_layout + +\begin_layout Description +PyArray_MultiIter_DATA ( +\family typewriter +void* +\family default +)( +\family typewriter +PyObject* +\family default + multi, +\family typewriter +int +\family default + i) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the data-pointer of the +\emph on +i +\emph default + +\begin_inset Formula $^{\textrm{th}}$ +\end_inset + + iterator in a multi-iterator object. + +\end_layout + +\begin_layout Description +PyArray_MultiIter_NEXTi ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + multi, +\family typewriter +int +\family default + i) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Advance the pointer of only the +\emph on +i +\emph default + +\begin_inset Formula $^{\textrm{th}}$ +\end_inset + + iterator. +\end_layout + +\begin_layout Description +PyArray_MultiIter_GOTO ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + multi, +\family typewriter +npy_intp* +\family default + destination) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Advance each iterator in a multi-iterator object, +\emph on +multi +\emph default +, to the given +\begin_inset Formula $N$ +\end_inset + +-dimensional +\emph on +destination +\emph default + where +\begin_inset Formula $N$ +\end_inset + + is the number of dimensions in the broadcasted array. + +\end_layout + +\begin_layout Description +PyArray_MultiIter_GOTO1D ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + multi, +\family typewriter +npy_intp +\family default + index) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Advance each iterator in a multi-iterator object, +\emph on +multi +\emph default +, to the corresponding location of the +\emph on +index +\emph default + into the flattened broadcasted array. + +\end_layout + +\begin_layout Description +PyArray_MultiIter_NOTDONE ( +\family typewriter +int +\family default +)( +\family typewriter +PyObject* +\family default + multi) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates TRUE as long as the multi-iterator has not looped through all + of the elements (of the broadcasted result), otherwise it evaluates FALSE. + +\end_layout + +\begin_layout Description +PyArray_Broadcast ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayMultiIterObject* +\family default + mit) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function encapsulates the broadcasting rules. + The +\emph on +mit +\emph default + container should already contain iterators for all the arrays that need + to be broadcast. + On return, these iterators will be adjusted so that iteration over each + simultaneously will accomplish the broadcasting. + A negative number is returned if an error occurs. + +\end_layout + +\begin_layout Description +PyArray_RemoveSmallest ( +\family typewriter +int +\family default +) ( +\family typewriter +PyArrayMultiIterObject* +\family default + mit) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function takes a multi-iterator object that has been previously +\begin_inset Quotes eld +\end_inset + +broadcasted, +\begin_inset Quotes erd +\end_inset + + finds the dimension with the smallest +\begin_inset Quotes eld +\end_inset + +sum of strides +\begin_inset Quotes erd +\end_inset + + in the broadcasted result and adapts all the iterators so as not to iterate + over that dimension (by effectively making them of length-1 in that dimension). + The corresponding dimension is returned unless +\emph on +mit +\emph default +->nd is 0, then -1 is returned. + This function is useful for constructing ufunc-like routines that broadcast + their inputs correctly and then call a strided 1-d version of the routine + as the inner-loop. + This 1-d version is usually optimized for speed and for this reason the + loop should be performed over the axis that won't require large stride + jumps. + +\end_layout + +\begin_layout Subsection +Array Scalars +\end_layout + +\begin_layout Description +PyArray_Return ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyArrayObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function checks to see if +\emph on +arr +\emph default + is a 0-dimensional array and, if so, returns the appropriate array scalar. + It should be used whenever 0-dimensional arrays could be returned to Python. +\end_layout + +\begin_layout Description +PyArray_Scalar ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +PyArray_Descr* +\family default + dtype, +\family typewriter +PyObject* +\family default + itemsize) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an array scalar object of the given enumerated +\emph on +typenum +\emph default + and +\emph on +itemsize +\emph default + by +\series bold +copying +\series default + from memory pointed to by +\emph on +data +\emph default +. + If +\emph on +swap +\emph default + is nonzero then this function will byteswap the data if appropriate to + the data-type because array scalars are always in correct machine-byte + order. +\end_layout + +\begin_layout Description +PyArray_ToScalar ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +void* +\family default + data, +\family typewriter +PyArrayObject* +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an array scalar object of the type and itemsize indicated by the + array object +\emph on +arr +\emph default + copied from the memory pointed to by +\emph on +data +\emph default + and swapping if the data in +\emph on +arr +\emph default + is not in machine byte-order. +\end_layout + +\begin_layout Description +PyArray_FromScalar ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + scalar, +\family typewriter +PyArray_Descr* +\family default + outcode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a 0-dimensional array of type determined by +\emph on +outcode +\emph default + from +\emph on +scalar +\emph default + which should be an array-scalar object. + If +\emph on +outcode +\emph default + is NULL, then the type is determined from +\family typewriter +\emph on +scalar +\family default +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_ScalarAsCtype ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + scalar, +\family typewriter +void* +\family default + ctypeptr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return in +\emph on +ctypeptr +\emph default + a pointer to the actual value in an array scalar. + There is no error checking so +\emph on +scalar +\emph default + must be an array-scalar object, and ctypeptr must have enough space to + hold the correct type. + For flexible-sized types, a pointer to the data is copied into the memory + of +\emph on +ctypeptr +\emph default +, for all other types, the actual data is copied into the address pointed + to by +\emph on +ctypeptr +\emph default +. + +\end_layout + +\begin_layout Description +PyArray_CastScalarToCtype ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + scalar, +\family typewriter +void* +\family default + ctypeptr, +\family typewriter +PyArray_Descr* +\family default + outcode) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the data (cast to the data type indicated by +\emph on +outcode +\emph default +) from the array-scalar, +\emph on +scalar +\emph default +, into the memory pointed to by +\emph on +ctypeptr +\emph default + (which must be large enough to handle the incoming memory). + +\end_layout + +\begin_layout Description +PyArray_TypeObjectFromType ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + type) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns a scalar type-object from a type-number, +\emph on +type +\emph default +. + Equivalent to +\family typewriter +PyArray_DescrFromType +\family default +( +\emph on +type +\emph default +)->typeobj except for reference counting and error-checking. + Returns a new reference to the typeobject on success or +\family typewriter +NULL +\family default + on failure. +\end_layout + +\begin_layout Description +PyArray_ScalarKind ( +\family typewriter +NPY_SCALARKIND +\family default +) ( +\family typewriter +int +\family default + typenum, +\family typewriter +PyArrayObject** +\family default + arr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the kind of scalar represented by +\emph on +typenum +\emph default + and the array in +\emph on +*arr +\emph default + (if +\emph on +arr +\emph default + is not +\family typewriter +NULL +\family default +). + The array is assumed to be rank-0 and only used if +\emph on +typenum +\emph default + represents a signed integer. + If +\emph on +arr +\emph default + is not +\family typewriter +NULL +\family default + and the first element is negative then +\family typewriter +NPY_INTNEG_SCALAR +\family default + is returned, otherwise +\family typewriter +NPY_INTPOS_SCALAR +\family default + is returned. + The possible return values are +\family typewriter +NPY_ +\family default +<kind> +\family typewriter +_SCALAR +\family default + where <kind> can be +\series bold +INTPOS +\series default +, +\series bold +INTNEG +\series default +, +\series bold +FLOAT +\series default +, +\series bold +COMPLEX +\series default +, +\series bold +BOOL +\series default +, or +\series bold +OBJECT +\series default +. + +\family typewriter +NPY_NOSCALAR +\family default + is also an enumerated value +\family typewriter +NPY_SCALARKIND +\family default + variables can take on. + +\end_layout + +\begin_layout Description +PyArray_CanCoerceScalar ( +\family typewriter +int +\family default +) ( +\family typewriter +char +\family default + thistype, +\family typewriter +char +\family default + neededtype, +\family typewriter +NPY_SCALARKIND +\family default + scalar) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Implements the rules for scalar coercion. + Scalars are only silently coerced from thistype to neededtype if this function + returns nonzero. + If scalar is +\family typewriter +NPY_NOSCALAR +\family default +, then this function is equivalent to +\family typewriter +PyArray_CanCastSafely +\family default +. + The rule is that scalars of the same KIND can be coerced into arrays of + the same KIND. + This rule means that high-precision scalars will never cause low-precision + arrays of the same KIND to be upcast. + +\end_layout + +\begin_layout Subsection +Data-type descriptors +\end_layout + +\begin_layout Warning +Data-type objects must be reference counted so be aware of the action on + the data-type reference of different C-API calls. + The standard rule is that when a data-type object is returned it is a new + reference. + Functions that take +\family typewriter +PyArray_Descr* +\family default + objects and return arrays steal references to the data-type their inputs + unless otherwise noted. + Therefore, you must own a reference to any data-type object used as input + to such a function. + +\end_layout + +\begin_layout Description +PyArrayDescr_Check ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates as true if +\emph on +obj +\emph default + is a data-type object ( +\family typewriter +PyArray_Descr* +\family default +). +\end_layout + +\begin_layout Description +PyArray_DescrNew ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a new data-type object copied from +\emph on +obj +\emph default + (the fields reference is just updated so that the new object points to + the same fields dictionary if any). + +\end_layout + +\begin_layout Description +PyArray_DescrNewFromType ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create a new data-type object from the built-in (or user-registered) data-type + indicated by +\emph on +typenum +\emph default +. + All builtin types should not have any of their fields changed. + This creates a new copy of the +\family typewriter +PyArray_Descr +\family default + structure so that you can fill it in as appropriate. + This function is especially needed for flexible data-types which need to + have a new elsize member in order to be meaningful in array construction. + +\end_layout + +\begin_layout Description +PyArray_DescrNewByteorder ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +PyArray_Descr* +\family default + obj, +\family typewriter +char +\family default + newendian) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create a new data-type object with the byteorder set according to +\emph on +newendian +\emph default +. + All referenced data-type objects (in subdescr and fields members of the + data-type object) are also changed (recursively). + If a byteorder of +\family typewriter +NPY_IGNORE +\family default + is encountered it is left alone. + If newendian is +\family typewriter +NPY_SWAP +\family default +, then all byte-orders are swapped. + Other valid newendian values are +\family typewriter +NPY_NATIVE +\family default +, +\family typewriter +NPY_LITTLE +\family default +, and +\family typewriter +NPY_BIG +\family default + which all cause the returned data-typed descriptor (and all it's referenced + data-type descriptors) to have the corresponding byte-order. +\end_layout + +\begin_layout Description +PyArray_DescrFromObject ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +PyArray_Descr* +\family default + mintype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Determine an appropriate data-type object from the object +\emph on +op +\emph default + (which should be a +\begin_inset Quotes eld +\end_inset + +nested +\begin_inset Quotes erd +\end_inset + + sequence object) and the minimum data-type descriptor mintype (which can + be +\family typewriter +NULL +\family default +). + Similar in behavior to array( +\emph on +op +\emph default +).dtype. + Don't confuse this function with +\family typewriter +PyArray_DescrConverter +\family default +. + This function essentially looks at all the objects in the (nested) sequence + and determines the data-type from the elements it finds. + +\end_layout + +\begin_layout Description +PyArray_DescrFromScalar ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +PyObject* +\family default + scalar) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a data-type object from an array-scalar object. + No checking is done to be sure that +\emph on +scalar +\emph default + is an array scalar. + If no suitable data-type can be determined, then a data-type of NPY_OBJECT + is returned by default. + +\end_layout + +\begin_layout Description +PyArray_DescrFromType ( +\family typewriter +PyArray_Descr* +\family default +) ( +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns a data-type object corresponding to +\emph on +typenum +\emph default +. + The +\emph on +typenum +\emph default + can be one of the enumerated types, a character code for one of the enumerated + types, or a user-defined type. + +\end_layout + +\begin_layout Description +PyArray_DescrConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Descr** +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any compatible Python object, +\emph on +obj +\emph default +, to a data-type object in +\emph on +dtype +\emph default +. + A large number of Python objects can be converted to data-type objects. + See Chapter +\begin_inset LatexCommand ref +reference "cha:Data-descriptor-objects" + +\end_inset + + for a complete description. + This version of the converter converts None objects to a +\family typewriter +NPY_DEFAULT_TYPE +\family default + data-type object. + This function can be used with the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + character code in PyArg_ParseTuple processing. + +\end_layout + +\begin_layout Description +PyArray_DescrConverter2 ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Descr** +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any compatible Python object, +\emph on +obj +\emph default +, to a data-type object in +\emph on +dtype +\emph default +. + This version of the converter converts None objects so that the returned + data-type is +\family typewriter +NULL +\family default +. + This function can also be used with the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + character in PyArg_ParseTuple processing. +\end_layout + +\begin_layout Description +Pyarray_DescrAlignConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Descr** +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Like +\family typewriter +PyArray_DescrConverter +\family default + except it aligns C-struct-like objects on word-boundaries as the compiler + would. +\end_layout + +\begin_layout Description +Pyarray_DescrAlignConverter2 ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Descr** +\family default + dtype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Like +\family typewriter +PyArray_DescrConverter2 +\family default + except it aligns C-struct-like objects on word-boundaries as the compiler + would. +\end_layout + +\begin_layout Description +PyArray_FieldNames ( +\family typewriter +PyObject* +\family default +)( +\family typewriter +PyObject* +\family default + dict) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Take the fields dictionary, +\family typewriter +\emph on +dict +\family default +\emph default +, such as the one attached to a data-type object and construct an ordered-list + of field names such as is stored in the names field of the +\family typewriter +PyArray_Descr +\family default + object. + +\end_layout + +\begin_layout Subsection +Conversion Utilities +\end_layout + +\begin_layout Subsubsection +For use with +\family typewriter +PyArg_ParseTuple +\end_layout + +\begin_layout Standard +All of these functions can be used in +\family typewriter +PyArg_ParseTuple +\family default +(...) with the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + format specifier to automatically convert any Python object to the required + C-object. + All of these functions return +\family typewriter +NPY_SUCCEED +\family default + if successful and +\family typewriter +NPY_FAIL +\family default + if not. + The first argument to all of these function is a Python object. + The second argument is the +\series bold +address +\series default + of the C-type to convert the Python object to. + +\end_layout + +\begin_layout Warning +Be sure to understand what steps you should take to manage the memory when + using these conversion functions. + These functions can require freeing memory, and/or altering the reference + counts of specific objects based on your use. +\end_layout + +\begin_layout Description +PyArray_Converter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyObject** +\family default + address) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any Python object to a +\family typewriter +PyArrayObject +\family default +. + If +\family typewriter +PyArray_Check +\family default +( +\family typewriter +\emph on +obj +\family default +\emph default +) is TRUE then its reference count is incremented and a reference placed + in +\emph on +address +\emph default +. + If +\emph on +obj +\emph default + is not an array, then convert it to an array using +\family typewriter +PyArray_FromAny +\family default +. + No matter what is returned, you must DECREF the object returned by this + routine in +\emph on +address +\emph default + when you are done with it. + +\end_layout + +\begin_layout Description +PyArray_OutputConverter ( +\family typewriter +int +\family default +)( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArrayObject** +\family default + address) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is a default converter for output arrays given to functions. + If +\emph on +obj +\emph default + is +\family typewriter +Py_None +\family default + or +\family typewriter +NULL +\family default +, then +\emph on +*address +\emph default + will be +\family typewriter +NULL +\family default + but the call will succeed. + If +\family typewriter +PyArray_Check +\family default +( +\emph on +obj +\emph default +) is TRUE then it is returned in +\emph on +*address +\emph default + without incrementing its reference count. + +\end_layout + +\begin_layout Description +PyArray_IntpConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Dims* +\family default + seq) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any Python sequence, +\emph on +obj +\emph default +, smaller than +\family typewriter +NPY_MAXDIMS +\family default + to a C-array of +\family typewriter +npy_intp +\family default +. + The Python object could also be a single number. + The +\emph on +seq +\emph default + variable is a pointer to a structure with members ptr and len. + On successful return, +\emph on +seq +\emph default +->ptr contains a pointer to memory that must be freed to avoid a memory + leak. + The restriction on memory size allows this converter to be conveniently + used for sequences intended to be interpreted as array shapes. + +\end_layout + +\begin_layout Description +PyArray_BufferConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +PyArray_Chunk* +\family default + buf) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any Python object, +\emph on +obj +\emph default +, with a (single-segment) buffer interface to a variable with members that + detail the object's use of its chunk of memory. + The +\emph on +buf +\emph default + variable is a pointer to a structure with base, ptr, len, and flags members. + The +\family typewriter +PyArray_Chunk +\family default + structure is binary compatibile with the Python's buffer object (through + its len member on 32-bit platforms and its ptr member on 64-bit platforms + or in Python 2.5). + On return, the base member is set to +\emph on +obj +\emph default + (or its base if +\emph on +obj +\emph default + is already a buffer object pointing to another object). + If you need to hold on to the memory be sure to INCREF the base member. + The chunk of memory is pointed to by +\emph on +buf +\emph default +->ptr member and has length +\emph on +buf +\emph default +->len. + The flags member of +\emph on +buf +\emph default + is +\family typewriter +NPY_BEHAVED_RO +\family default + with the +\family typewriter +NPY_WRITEABLE +\family default + flag set if +\emph on +obj +\emph default + has a writeable buffer interface. + +\end_layout + +\begin_layout Description +PyArray_AxisConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject +\family default +* obj, +\family typewriter +int* +\family default + axis) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert a Python object, +\emph on +obj +\emph default +, representing an axis argument to the proper value for passing to the functions + that take an integer axis. + Specifically, if +\emph on +obj +\emph default + is None, +\emph on +axis +\emph default + is set to +\family typewriter +NPY_MAXDIMS +\family default + which is interpreted correctly by the C-API functions that take axis arguments. +\end_layout + +\begin_layout Description +PyArray_BoolConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +Bool* +\family default + value) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any Python object, +\emph on +obj +\emph default +, to +\family typewriter +NPY_TRUE +\family default + or +\family typewriter +NPY_FALSE +\family default +, and place the result in +\emph on +value +\emph default +. +\end_layout + +\begin_layout Description +PyArray_ByteorderConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +char* +\family default + endian) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert Python strings into the corresponding byte-order character: '>', + '<', 's', '=', or '|'. + +\end_layout + +\begin_layout Description +PyArray_SortkindConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +NPY_SORTKIND* +\family default + sort) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert Python strings into one of +\family typewriter +NPY_QUICKSORT +\family default + (starts with 'q' or 'Q') , +\family typewriter +NPY_HEAPSORT +\family default + (starts with 'h' or 'H'), or +\family typewriter +NPY_MERGESORT +\family default + (starts with 'm' or 'M'). + +\end_layout + +\begin_layout Description +PyArray_SearchsideConverter ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +NPY_SEARCHSIDE* +\family default + side) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert Python strings into one of +\family typewriter +NPY_SEARCHLEFT +\family default + (starts with 'l' or 'L'), or +\family typewriter +NPY_SEARCHRIGHT +\family default + (starts with 'r' or 'R'). + +\end_layout + +\begin_layout Subsubsection +Other conversions +\end_layout + +\begin_layout Description +PyArray_PyIntAsInt ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert all kinds of Python objects (including arrays and array scalars) + to a standard integer. + On error, -1 is returned and an exception set. + You may find useful the macro: +\end_layout + +\begin_layout LyX-Code +#define error_converting(x) (((x) == -1) && PyErr_Occurred() +\end_layout + +\begin_layout Description +PyArray_PyIntAsIntp ( +\family typewriter +npy_intp +\family default +) ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert all kinds of Python objects (including arrays and array scalars) + to a (platform-pointer-sized) integer. + On error, -1 is returned and an exception set. + +\end_layout + +\begin_layout Description +PyArray_IntpFromSequence ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + seq, +\family typewriter +npy_intp* +\family default + vals, +\family typewriter +int +\family default + maxvals) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert any Python sequence (or single Python number) passed in as +\emph on +seq +\emph default + to (up to) +\emph on +maxvals +\emph default + pointer-sized integers and place them in the +\emph on +vals +\emph default + array. + The sequence can be smaller then +\emph on +maxvals +\emph default + as the number of converted objects is returned. + +\end_layout + +\begin_layout Description +PyArray_TypestrConvert ( +\family typewriter +int +\family default +) ( +\family typewriter +int +\family default + itemsize, +\family typewriter +int +\family default + gentype) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Convert typestring characters (with +\emph on +itemsize +\emph default +) to basic enumerated data types. + The typestring character corresponding to signed and unsigned integers, + floating point numbers, and complex-floating point numbers are recognized + and converted. + Other values of gentype are returned. + This function can be used to convert, for example, the string 'f4' to +\family typewriter +NPY_FLOAT32 +\family default +. + +\end_layout + +\begin_layout Subsection +Miscellaneous +\end_layout + +\begin_layout Subsubsection +Importing the API +\end_layout + +\begin_layout Standard +In order to make use of the C-API from another extension module, the +\family typewriter +import_array +\family default +() command must be used. + If the extension module is self-contained in a single .c file, then that + is all that needs to be done. + If, however, the extension module involves multiple files where the C-API + is needed then some additional steps must be taken. +\end_layout + +\begin_layout Description +import_array (void) (void) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function must be called in the initialization section of a module + that will make use of the C-API. + It imports the module where the function-pointer table is stored and points + the correct variable to it. + +\end_layout + +\begin_layout Description +PY_ARRAY_UNIQUE_SYMBOL +\end_layout + +\begin_layout Description +NO_IMPORT_ARRAY +\end_layout + +\begin_layout Description +\InsetSpace ~ + Using these #defines you can use the C-API in multiple files for a single + extension module. + In each file you must define +\family typewriter +PY_ARRAY_UNIQUE_SYMBOL +\family default + to some name that will hold the C-API ( +\emph on +e.g. + +\emph default + myextension_ARRAY_API). + This must be done +\series bold +before +\series default + including the numpy/arrayobject.h file. + In the module intialization routine you call +\family typewriter +import_array +\family default +(). + In addition, in the files that do not have the module initialization sub_routin +e define +\family typewriter +NO_IMPORT_ARRAY +\family default + prior to including numpy/arrayobject.h. +\end_layout + +\begin_layout Description +\InsetSpace ~ + Suppose I have two files coolmodule.c and coolhelper.c which need to be compiled + and linked into a single extension module. + Suppose coolmodule.c contains the required initcool module initialization + function (with the import_array() function called). + Then, coolmodule.c would have at the top: +\end_layout + +\begin_layout LyX-Code +#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API +\end_layout + +\begin_layout LyX-Code +#include numpy/arrayobject.h +\end_layout + +\begin_layout Description +\InsetSpace ~ + On the other hand, coolhelper.c would contain at the top: +\end_layout + +\begin_layout LyX-Code +#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API +\end_layout + +\begin_layout LyX-Code +#define NO_IMPORT_ARRAY +\end_layout + +\begin_layout LyX-Code +#include numpy/arrayobject.h +\end_layout + +\begin_layout Description +PyArray_GetNDArrayCVersion ( +\family typewriter +unsigned +\family default + +\family typewriter +int +\family default +) ( +\family typewriter +void +\family default +) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This just returns the value +\family typewriter +NPY_VERSION +\family default +. + Because it is in the C-API, however, comparing the output of this function + from the value defined in the current header gives a way to test if the + C-API has changed thus requiring a re-compilation of extension modules + that use the C-API. + +\end_layout + +\begin_layout Subsubsection +Internal Flexibility +\end_layout + +\begin_layout Description +PyArray_SetNumericOps ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + dict) +\end_layout + +\begin_layout Description +\InsetSpace ~ + NumPy stores an internal table of Python callable objects that are used + to implement arithmetic operations for arrays as well as certain array + calculation methods. + This function allows the user to replace any or all of these Python objects + with their own versions. + The keys of the dictionary, +\emph on +dict +\emph default +, are the named functions to replace and the paired value is the Python + callable object to use. + Care should be taken that the function used to replace an internal array + operation does not itself call back to that internal array operation (unless + you have designed the function to handle that), or an unchecked infinite + recursion can result (possibly causing program crash). + The key names that represent operations that can be replaced are: +\end_layout + +\begin_layout Quote + +\series bold +add +\series default +, +\series bold +subtract +\series default +, +\series bold +multiply +\series default +, +\series bold +divide +\series default +, +\series bold +remainder +\series default +, +\series bold +power +\series default +, +\series bold +square, reciprocal, ones_like, sqrt +\series default +, +\series bold +negative +\series default +, +\series bold +absolute +\series default +, +\series bold +invert +\series default +, +\series bold +left_shift +\series default +, +\series bold +right_shift +\series default +, +\series bold +bitwise_and +\series default +, +\series bold +bitwise_xor +\series default +, +\series bold +bitwise_or +\series default +, +\series bold +less +\series default +, +\series bold +less_equal +\series default +, +\series bold +equal +\series default +, +\series bold +not_equal +\series default +, +\series bold +greater +\series default +, +\series bold +greater_equal +\series default +, +\series bold +floor_divide +\series default +, +\series bold +true_divide +\series default +, +\series bold +logical_or +\series default +, +\series bold +logical_and +\series default +, +\series bold +floor +\series default +, +\series bold +ceil +\series default +, +\series bold +maximum +\series default +, +\series bold +minimum +\series default +, +\series bold +rint +\series default +. +\end_layout + +\begin_layout Description +\InsetSpace ~ + These functions are included here because they are used at least once in + the array object's methods. + The function returns -1 (without setting a Python Error) if one of the + objects being assigned is not callable. +\end_layout + +\begin_layout Description +PyArray_GetNumericOps ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +void +\family default +) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return a Python dictionary containing the callable Python objects stored + in the the internal arithmetic operation table. + The keys of this dictionary are given in the explanation for +\family typewriter +PyArray_SetNumericOps +\family default +. +\end_layout + +\begin_layout Description +PyArray_SetStringFunction ( +\family typewriter +void +\family default +) ( +\family typewriter +PyObject* +\family default + op, +\family typewriter +int +\family default + repr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function allows you to alter the tp_str and tp_repr methods of the + array object to any Python function. + Thus you can alter what happens for all arrays when str(arr) or repr(arr) + is called from Python. + The function to be called is passed in as +\emph on +op +\emph default +. + If +\emph on +repr +\emph default + is non-zero, then this function will be called in response to repr(arr), + otherwise the function will be called in response to str(arr). + No check on whether or not +\emph on +op +\emph default + is callable is performed. + The callable passed in to +\emph on +op +\emph default + should expect an array argument and should return a string to be printed. +\end_layout + +\begin_layout Subsubsection +Memory management +\end_layout + +\begin_layout Description +PyDataMem_NEW ( +\family typewriter +char* +\family default +) ( +\family typewriter +size_t +\family default + nbytes) +\end_layout + +\begin_layout Description +PyDataMem_FREE ( +\family typewriter +char* +\family default + ptr) +\end_layout + +\begin_layout Description +PyDataMem_RENEW ( +\family typewriter +char* +\family default +) ( +\family typewriter +void * +\family default + ptr, +\family typewriter +size_t +\family default + newbytes) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Macros to allocate, free, and reallocate memory. + These macros are used internally to create arrays. +\end_layout + +\begin_layout Description +PyDimMem_NEW ( +\family typewriter +npy_intp* +\family default +) (nd) +\end_layout + +\begin_layout Description +PyDimMem_FREE ( +\family typewriter +npy_intp* +\family default + ptr) +\end_layout + +\begin_layout Description +PyDimMem_RENEW ( +\family typewriter +npy_intp* +\family default +) ( +\family typewriter +npy_intp* +\family default + ptr, +\family typewriter +npy_intp +\family default + newnd) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Macros to allocate, free, and reallocate dimension and strides memory. +\end_layout + +\begin_layout Description +PyArray_malloc (nbytes) +\end_layout + +\begin_layout Description +PyArray_free (ptr) +\end_layout + +\begin_layout Description +PyArray_realloc (ptr, nbytes) +\end_layout + +\begin_layout Description +\InsetSpace ~ + These macros use different memory allocators, depending on the constant + +\family typewriter +NPY_USE_PYMEM +\family default +. + The system malloc is used when NPY_USE_PYMEM is 0, if NPY_USE_PYMEM is + 1, then the Python memory allocator is used. + +\end_layout + +\begin_layout Subsubsection +Threading support +\end_layout + +\begin_layout Standard +These macros are only meaningful if +\family typewriter +NPY_ALLOW_THREADS +\family default + evaluates True during compilation of the extension module. + Otherwise, these macros are equivalent to whitespace. + Python uses a single Global Interpreter Lock (GIL) for each Python process + so that only a single thread may excecute at a time (even on multi-cpu + machines). + When calling out to a compiled function that may take time to compute (and + does not have side-effects for other threads like updated global variables), + the GIL should be released so that other Python threads can run while the + time-consuming calculations are performed. + This can be accomplished using two groups of macros. + Typically, if one macro in a group is used in a code block, all of them + must be used in the same code block. + Currently, +\family typewriter +NPY_ALLOW_THREADS +\family default + is defined to the python-defined +\family typewriter +WITH_THREADS +\family default + constant unless the environment variable +\family typewriter +NPY_NOSMP +\family default + is set in which case +\family typewriter +NPY_ALLOW_THREADS +\family default + is defined to be 0. + +\end_layout + +\begin_layout Description +Group\InsetSpace ~ +1 This group is used to call code that may take some time but does + not use any Python C-API calls. + Thus, the GIL should be released during its calculation. +\end_layout + +\begin_deeper +\begin_layout Description +NPY_BEGIN_ALLOW_THREADS Equivalent to +\family typewriter +Py_BEGIN_ALLOW_THREADS +\family default + except it uses +\family typewriter +NPY_ALLOW_THREADS +\family default + to determine if the macro if replaced with white-space or not. + +\end_layout + +\begin_layout Description +NPY_END_ALLOW_THREADS Equivalent to +\family typewriter +Py_END_ALLOW_THREADS +\family default + except it uses +\family typewriter +NPY_ALLOW_THREADS +\family default + to determine if the macro if replaced with white-space or not. + +\end_layout + +\begin_layout Description +NPY_BEGIN_THREADS_DEF Place in the variable declaration area. + This macro sets up the variable needed for storing the Python state. +\end_layout + +\begin_layout Description +NPY_BEGIN_THREADS Place right before code that does not need the Python + interpreter (no Python C-API calls). + This macro saves the Python state and releases the GIL. +\end_layout + +\begin_layout Description +NPY_END_THREADS Place right after code that does not need the Python interpreter. + This macro acquires the GIL and restores the Python state from the saved + variable. +\end_layout + +\begin_layout Description +NPY_BEGIN_THREADS_DESCR ( +\family typewriter +PyArray_Descr* +\family default + dtype) Useful to release the GIL only if +\emph on +dtype +\emph default + does not contain arbitrary Python objects which may need the Python interpreter + during execution of the loop. + Equivalent to +\end_layout + +\begin_layout Description +NPY_END_THREADS_DESCR ( +\family typewriter +PyArray_Descr* +\family default + dtype) Useful to regain the GIL in situations where it was released using + the BEGIN form of this macro. + +\end_layout + +\end_deeper +\begin_layout Description +Group\InsetSpace ~ +2 This group is used to re-acquire the Python GIL after it has been + released. + For example, suppose the GIL has been released (using the previous calls), + and then some path in the code (perhaps in a different subroutine) requires + use of the Python C-API, then these macros are useful to acquire the GIL. + These macros accomplish essentially a reverse of the previous three (acquire + the LOCK saving what state it had) and then re-release it with the saved + state. +\end_layout + +\begin_deeper +\begin_layout Description +NPY_ALLOW_C_API_DEF Place in the variable declaration area to set up the + necessary variable. + +\end_layout + +\begin_layout Description +NPY_ALLOW_C_API Place before code that needs to call the Python C-API (when + it is known that the GIL has already been released). + +\end_layout + +\begin_layout Description +NPY_DISABLE_C_API Place after code that needs to call the Python C-API (to + re-release the GIL). + +\end_layout + +\end_deeper +\begin_layout Tip +Never use semicolons after the threading support macros. +\end_layout + +\begin_layout Subsubsection +Priority +\end_layout + +\begin_layout Description +NPY_PRIOIRTY Default priority for arrays. +\end_layout + +\begin_layout Description +NPY_SUBTYPE_PRIORITY Default subtype priority. +\end_layout + +\begin_layout Description +NPY_SCALAR_PRIORITY Default scalar priority (very small) +\end_layout + +\begin_layout Description +PyArray_GetPriority ( +\family typewriter +double +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +double +\family default + def) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return the +\series bold +__array_priority__ +\series default + attribute (converted to a double) of +\emph on +obj +\emph default + or +\emph on +def +\emph default + if no attribute of that name exists. + Fast returns that avoid the attribute lookup are provided for objects of + type +\family typewriter +PyArray_Type +\family default +. + +\end_layout + +\begin_layout Subsubsection +Default buffers +\end_layout + +\begin_layout Description +NPY_BUFSIZE Default size of the user-settable internal buffers. +\end_layout + +\begin_layout Description +NPY_MIN_BUFSIZE Smallest size of user-settable internal buffers. +\end_layout + +\begin_layout Description +NPY_MAX_BUFSIZE Largest size allowed for the user-settable buffers. +\end_layout + +\begin_layout Subsubsection +Other constants +\end_layout + +\begin_layout Description +NPY_NUM_FLOATTYPE The number of floating-point types +\end_layout + +\begin_layout Description +NPY_MAXDIMS The maximum number of dimensions allowed in arrays. +\end_layout + +\begin_layout Description +NPY_VERSION The current version of the ndarray object (check to see if this + variable is defined to guarantee the numpy/arrayobject.h header is being + used). + +\end_layout + +\begin_layout Description +NPY_FALSE Defined as 0 for use with Bool. +\end_layout + +\begin_layout Description +NPY_TRUE Defined as 1 for use with Bool. +\end_layout + +\begin_layout Description +NPY_FAIL The return value of failed converter functions which are called + using the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + syntax in PyArg_ParseTuple-like functions. +\end_layout + +\begin_layout Description +NPY_SUCCEED The return value of successful converter functions which are + called using the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + syntax in PyArg_ParseTuple-like functions. +\end_layout + +\begin_layout Subsubsection +Miscellaneous Macros +\end_layout + +\begin_layout Description +PyArray_SAMESHAPE (a1, a2) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Evaluates as True if arrays +\emph on +a1 +\emph default + and +\emph on +a2 +\emph default + have the same shape. + +\end_layout + +\begin_layout Description +PyArray_MAX (a,b) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns the maximum of +\emph on +a +\emph default + and +\emph on +b +\emph default +. + If ( +\emph on +a +\emph default +) or ( +\emph on +b +\emph default +) are expressions they are evaluated twice. +\end_layout + +\begin_layout Description +PyArray_MIN (a,b) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns the minimum of +\emph on +a +\emph default + and +\emph on +b +\emph default +. + If ( +\emph on +a +\emph default +) or ( +\emph on +b +\emph default +) are expressions they are evaluated twice. +\end_layout + +\begin_layout Description +PyArray_CLT (a,b) +\end_layout + +\begin_layout Description +PyArray_CGT (a,b) +\end_layout + +\begin_layout Description +PyArray_CLE (a,b) +\end_layout + +\begin_layout Description +PyArray_CGE (a,b) +\end_layout + +\begin_layout Description +PyArray_CEQ (a,b) +\end_layout + +\begin_layout Description +PyArray_CNE (a,b) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Implements the complex comparisons between two complex numbers (structures + with a real and imag member) using NumPy's definition of the ordering which + is lexicographic: comparing the real parts first and then the complex parts + if the real parts are equal. + +\end_layout + +\begin_layout Description +PyArray_REFCOUNT ( +\family typewriter +PyObject* +\family default + op) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Returns the reference count of any Python object. + +\end_layout + +\begin_layout Description +PyArray_XDECREF_ERR (PyObject *obj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + DECREF's an array object which may have the +\family typewriter +NPY_UPDATEIFCOPY +\family default + flag set without causing the contents to be copied back into the original + array. + Resets the +\family typewriter +NPY_WRITEABLE +\family default + flag on the base object. + This is useful for recovering from an error condition when +\family typewriter +NPY_UPDATEIFCOPY +\family default + is used. + +\end_layout + +\begin_layout Subsubsection +Enumerated Types +\end_layout + +\begin_layout Description +NPY_SORTKIND A special variable-type which can take on the values +\series bold +NPY_ +\series default +<KIND> where <KIND> is +\end_layout + +\begin_layout Quote + +\series bold +QUICKSORT +\series default +, +\series bold +HEAPSORT +\series default +, +\series bold +MERGESORT +\end_layout + +\begin_layout Description +\InsetSpace ~ + +\series bold +NPY_NSORTS +\series default + is defined to be the number of sorts. +\end_layout + +\begin_layout Description +NPY_SCALARKIND A special variable type indicating the number of +\begin_inset Quotes eld +\end_inset + +kinds +\begin_inset Quotes erd +\end_inset + + of scalars distinguished in determining scalar-coercion rules. + This variable can take on the values NPY_<KIND> where <KIND> can be +\end_layout + +\begin_layout Quote + +\series bold +NOSCALAR +\series default +, +\series bold +BOOL_SCALAR +\series default +, +\series bold +INTPOS_SCALAR +\series default +, +\series bold +INTNEG_SCALAR +\series default +, +\series bold +FLOAT_SCALAR +\series default +, +\series bold +COMPLEX_SCALAR +\series default +, +\series bold +OBJECT_SCALAR +\end_layout + +\begin_layout Description +\InsetSpace ~ + +\series bold +NPY_NSCALARKINDS +\series default + is defined to be the number of scalar kinds (not including +\family typewriter +NPY_NOSCALAR +\family default +). + +\end_layout + +\begin_layout Description +NPY_ORDER A variable type indicating the order that an array should be interpret +ed in. + The value of a variable of this type can be +\series bold +NPY_ +\series default +<ORDER> where <ORDER> is +\end_layout + +\begin_layout Quote + +\series bold +ANYORDER +\series default +, +\series bold +CORDER +\series default +, +\series bold +FORTRANORDER +\end_layout + +\begin_layout Description +NPY_CLIPMODE A variable type indicating the kind of clipping that should + be applied in certain functions. + The value of a variable of this type can be +\series bold +NPY_ +\series default +<MODE> where <MODE> is +\end_layout + +\begin_layout Quote + +\series bold +CLIP +\series default +, +\series bold +WRAP +\series default +, +\series bold +RAISE +\begin_inset LatexCommand index +name "ndarray!C-API|)" + +\end_inset + + +\begin_inset LatexCommand index +name "C-API!array|)" + +\end_inset + + +\end_layout + +\begin_layout Section +UFunc API +\begin_inset LatexCommand index +name "ufunc!C-API|(" + +\end_inset + + +\begin_inset LatexCommand index +name "C-API!ufunc|(" + +\end_inset + + +\end_layout + +\begin_layout Subsection +Constants +\end_layout + +\begin_layout Description +UFUNC_ERR_<HANDLER> +\end_layout + +\begin_layout Description +\InsetSpace ~ + <HANDLER> can be +\series bold +IGNORE +\series default +, +\series bold +WARN +\series default +, +\series bold +RAISE +\series default +, or +\series bold +CALL +\end_layout + +\begin_layout Description +UFUNC_<THING>_<ERR> +\end_layout + +\begin_layout Description +\InsetSpace ~ + <THING> can be +\series bold +MASK +\series default +, +\series bold +SHIFT +\series default +, or +\series bold +FPE +\series default +, and <ERR> can be +\series bold +DIVIDEBYZERO +\series default +, +\series bold +OVERFLOW +\series default +, +\series bold +UNDERFLOW +\series default +, and +\series bold +INVALID +\series default +. +\end_layout + +\begin_layout Description +PyUFunc_<VALUE> <VALUE> can be +\series bold +One +\series default + (1), +\series bold +Zero +\series default + (0), or +\series bold +None +\series default + (-1) +\end_layout + +\begin_layout Subsection +Macros +\end_layout + +\begin_layout Description +NPY_LOOP_BEGIN_THREADS +\end_layout + +\begin_layout Description +\InsetSpace ~ + Used in universal function code to only release the Python GIL if loop->obj + is not true ( +\emph on +i.e. + +\emph default + this is not an OBJECT array loop). + Requires use of +\family typewriter +NPY_BEGIN_THREADS_DEF +\family default + in variable declaration area. +\end_layout + +\begin_layout Description +NPY_LOOP_END_THREADS +\end_layout + +\begin_layout Description +\InsetSpace ~ + Used in universal function code to re-acquire the Python GIL if it was + released (because loop->obj was not true). + +\end_layout + +\begin_layout Description +UFUNC_CHECK_ERROR (loop) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A macro used internally to check for errors and goto fail if found. + This macro requires a fail label in the current code block. + The +\emph on +loop +\emph default + variable must have at least members (obj, errormask, and errorobj). + If +\emph on +loop +\emph default +->obj is nonzero, then +\family typewriter +PyErr_Occurred +\family default +() is called (meaning the GIL must be held). + If +\emph on +loop +\emph default +->obj is zero, then if +\emph on +loop +\emph default +->errormask is nonzero, +\family typewriter +PyUFunc_checkfperr +\family default + is called with arguments +\emph on +loop +\emph default +->errormask and +\emph on +loop +\emph default +->errobj. + If the result of this check of the IEEE floating point registers is true + then the code redirects to the fail label which must be defined. +\end_layout + +\begin_layout Description +UFUNC_CHECK_STATUS ( +\emph on +ret +\emph default +) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A macro that expands to platform-dependent code. + The +\emph on +ret +\emph default + variable can can be any integer. + The +\family typewriter +UFUNC_FPE_ +\family default +<ERR> bits are set in +\emph on +ret +\emph default + according to the status of the corresponding error flags of the floating + point processor. + +\end_layout + +\begin_layout Subsection +Functions +\end_layout + +\begin_layout Description +PyUFunc_FromFuncAndData ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyUFuncGenericFunction* +\family default + func, +\family typewriter +void** +\family default + data, +\family typewriter +char* +\family default + types, +\family typewriter +int +\family default + ntypes, +\family typewriter +int +\family default + nin, +\family typewriter +int +\family default + nout, +\family typewriter +int +\family default + identity, +\family typewriter +char* +\family default + name, +\family typewriter +char* +\family default + doc, +\family typewriter +int +\family default + check_return) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Create a new broadcasting universal function from required variables. + Each ufunc builds around the notion of an element-by-element operation. + Each ufunc object contains pointers to 1-d loops implementing the basic + functionality for each supported type. + +\end_layout + +\begin_layout Description +nin The number of inputs to this operation. +\end_layout + +\begin_layout Description +nout The number of outputs +\end_layout + +\begin_layout Description +ntypes How many different data-type +\begin_inset Quotes eld +\end_inset + +signatures +\begin_inset Quotes erd +\end_inset + + the ufunc has implemented. + +\end_layout + +\begin_layout Description +func Must to an array of length +\emph on +ntypes +\emph default + containing +\family typewriter +PyUFuncGenericFunction +\family default + items. + These items are pointers to functions that acutally implement the underlying + (element-by-element) function +\begin_inset Formula $N$ +\end_inset + + times. + T +\end_layout + +\begin_layout Description +types Must be of length ( +\emph on +nin +\emph default ++ +\emph on +nout +\emph default +) +\emph on +*ntypes +\emph default +, and it contains the data-types (built-in only) that the corresponding + function in the +\emph on +func +\emph default + array can deal with. + +\end_layout + +\begin_layout Description +data Should be +\family typewriter +NULL +\family default + or a pointer to an array of size +\emph on +ntypes +\emph default +. + This array may contain arbitrary extra-data to be passed to the corresponding + 1-d loop function in the func array. + +\end_layout + +\begin_layout Description +name The name for the ufunc. + +\end_layout + +\begin_layout Description +doc Allows passing in a documentation string to be stored with the ufunc. + The documentation string should not contain the name of the function or + the calling signature as that will be dynamically determined from the object + and available when accessing the +\series bold +__doc__ +\series default + attribute of the ufunc. + +\end_layout + +\begin_layout Description +check_return Unused and present for backwards compatibility of the C-API. + A corresponding +\emph on +check_return +\emph default + integer does exist in the ufunc structure and it does get set with this + value when the ufunc object is created. + +\end_layout + +\begin_layout Description +PyUFunc_RegisterLoopForType ( +\family typewriter +int +\family default +) ( +\family typewriter +PyUFuncObject* +\family default + ufunc, +\family typewriter +int +\family default + usertype, +\family typewriter +PyUFuncGenericFunction +\family default + function, +\family typewriter +int* +\family default + arg_types, +\family typewriter +void* +\family default + data) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function allows the user to register a 1-d loop with an already-created + ufunc to be used whenever the ufunc is called with any of its input arguments + as the user-defined data-type. + This is needed in order to make ufuncs work with built-in data-types. + The data-type must have been previously registered with the numpy system. + The loop is passed in as +\emph on +function +\emph default +. + This loop can take arbitrary data which should be passed in as +\emph on +data +\emph default +. + The data-types the loop requires are passed in as +\emph on +arg_types +\emph default + which must be a pointer to memory at least as large as ufunc->nargs. +\end_layout + +\begin_layout Description +PyUFunc_ReplaceLoopBySignature ( +\family typewriter +int +\family default +) ( +\family typewriter +PyUFuncObject* +\family default + ufunc, +\family typewriter +PyUFuncGenericFunction +\family default + newfunc, +\family typewriter +int* +\family default + signature, +\family typewriter +PyUFuncGenericFunction* +\family default + oldfunc) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Replace a 1-d loop matching the given +\emph on +signature +\emph default + in the already-created +\emph on +ufunc +\emph default + with the new 1-d loop newfunc. + Return the old 1-d loop function in +\emph on +oldfunc +\emph default +. + Return 0 on success and -1 on failure. + This function works only with built-in types (use +\family typewriter +PyUFunc_RegisterLoopForType +\family default + for user-defined types). + A signature is an array of data-type numbers indicating the inputs followed + by the outputs assumed by the 1-d loop. + +\end_layout + +\begin_layout Description +PyUFunc_GenericFunction ( +\family typewriter +int +\family default +) ( +\family typewriter +PyUFuncObject* +\family default + self, +\family typewriter +PyObject* +\family default + args, +\family typewriter +PyArrayObject** +\family default + mps) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A generic ufunc call. + The ufunc is passed in as +\emph on +self +\emph default +, the arguments to the ufunc as +\emph on +args +\emph default +. + The +\emph on +mps +\emph default + argument is an array of +\family typewriter +PyArrayObject +\family default + pointers containing the converted input arguments as well as the ufunc + outputs on return. + The user is responsible for managing this array and receives a new reference + for each array in +\emph on +mps +\emph default +. + The total number of arrays in +\emph on +mps +\emph default + is given by +\emph on +self +\emph default +->nin + +\emph on +self +\emph default +->nout. +\end_layout + +\begin_layout Description +PyUFunc_checkfperr ( +\family typewriter +int +\family default +) ( +\family typewriter +int +\family default + errmask, +\family typewriter +PyObject* +\family default + errobj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + A simple interface to the IEEE error-flag checking support. + The +\emph on +errmask +\emph default + argument is a mask of +\family typewriter +UFUNC_MASK_<ERR> +\family default + bitmasks indicating which errors to check for (and how to check for them). + The +\emph on +errobj +\emph default + must be a Python tuple with two elements: a string containing the name + which will be used in any communication of error and either a callable + Python object (call-back function) or +\family typewriter +Py_None +\family default +. + The callable object will only be used if +\family typewriter +UFUNC_ERR_CALL +\family default + is set as the desired error checking method. + This routine manages the GIL and is safe to call even after releasing the + GIL. + If an error in the IEEE-compatibile hardware is determined a -1 is returned, + otherwise a 0 is returned. + +\end_layout + +\begin_layout Description +PyUFunc_clearfperr ( +\family typewriter +void +\family default +) () +\end_layout + +\begin_layout Description +\InsetSpace ~ + Clear the IEEE error flags. + +\end_layout + +\begin_layout Description +PyUFunc_GetPyValues ( +\family typewriter +void +\family default +) ( +\family typewriter +char* +\family default + name, +\family typewriter +int* +\family default + bufsize, +\family typewriter +int* +\family default + errmask, +\family typewriter +PyObject** +\family default + errobj) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Get the Python values used for ufunc processing from the thread-local storage + area unless the defaults have been set in which case the name lookup is + bypassed. + The name is placed as a string in the first element of +\emph on +*errobj +\emph default +. + The second element is the looked-up function to call on error callback. + The value of the looked-up buffer-size to use is passed into +\emph on +bufsize +\emph default +, and the value of the error mask is placed into +\emph on +errmask +\emph default +. + +\end_layout + +\begin_layout Subsection +Generic functions +\end_layout + +\begin_layout Standard +At the core of every ufunc is a collection of type-specific functions that + defines the basic functionality for each of the supported types. + These functions must evaluate the underlying function +\begin_inset Formula $N\geq1$ +\end_inset + + times. + Extra-data may be passed in that may be used during the calculation. + This feature allows some general functions to be used as these basic looping + functions. + The general function has all the code needed to point variables to the + right place and set up a function call. + The general function assumes that the actual function to call is passed + in as the extra data and calls it with the correct values. + All of these functions are suitable for placing directly in the array of + functions stored in the functions member of the PyUFuncObject structure. + +\end_layout + +\begin_layout Description +PyUFunc_f_f_As_d_d ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_d_d ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_f_f ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_g_g ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_F_F_As_D_D ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_F_F ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_D_D ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_G_G ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type specific, core 1-d functions for ufuncs where each calculation is + obtained by calling a function taking one input argument and returning + one output. + This function is passed in +\family typewriter +func +\family default +. + The letters correspond to dtypechar's of the supported data types ( +\family typewriter +f +\family default + - float, +\family typewriter +d +\family default + - double, +\family typewriter +g +\family default + - long double, +\family typewriter +F +\family default + - cfloat, +\family typewriter +D +\family default + - cdouble, +\family typewriter +G +\family default + - clongdouble). + The argument +\emph on +func +\emph default + must support the same signature. + The _As_X_X variants assume ndarray's of one data type but cast the values + to use an underlying function that takes a different data type. + Thus, +\family typewriter +PyUFunc_f_f_As_d_d +\family default + uses ndarrays of data type +\family typewriter +NPY_FLOAT +\family default + but calls out to a C-function that takes double and returns double. + +\end_layout + +\begin_layout Description +PyUFunc_ff_f_As_dd_d ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_ff_f ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_dd_d ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_gg_g ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_FF_F_As_DD_D ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_DD_D ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_FF_F ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_GG_G ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Type specific, core 1-d functions for ufuncs where each calculation is + obtained by calling a function taking two input arguments and returning + one output. + The underlying function to call is passed in as +\emph on +func +\emph default +. + The letters correspond to dtypechar's of the specific data type supported + by the general-purpose function. + The argument +\family typewriter +func +\family default + must support the corresponding signature. + The +\family typewriter +_As_XX_X +\family default + variants assume ndarrays of one data type but cast the values at each iteration + of the loop to use the underlying function that takes a different data + type. + +\end_layout + +\begin_layout Description +PyUFunc_O_O ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +PyUFunc_OO_O ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + One-input, one-output, and two-input, one-output core 1-d functions for + the +\family typewriter +NPY_OBJECT +\family default + data type. + These functions handle reference count issues and return early on error. + The actual function to call is +\emph on +func +\emph default + and it must accept calls with the signature ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default +) for +\family typewriter +PyUFunc_O_O +\family default + or ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject +\family default + *, +\family typewriter +PyObject +\family default + *) for +\family typewriter +PyUFunc_OO_O +\family default +. +\end_layout + +\begin_layout Description +PyUFunc_O_O_method ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This general purpose 1-d core function assumes that +\emph on +func +\emph default + is a string representing a method of the input object. + For each iteration of the loop, the Python obejct is extracted from the + array and its +\emph on +func +\emph default + method is called returning the result to the output array. + +\end_layout + +\begin_layout Description +PyUFunc_OO_O_method ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This general purpose 1-d core function assumes that +\emph on +func +\emph default + is a string representing a method of the input object that takes one argument. + The first argument in +\emph on +args +\emph default + is the method whose function is called, the second argument in +\emph on +args +\emph default + is the argument passed to the function. + The output of the function is stored in the third entry of +\emph on +args +\emph default +. + +\end_layout + +\begin_layout Description +PyUFunc_On_Om ( +\family typewriter +void +\family default +) ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + func) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This is the 1-d core function used by the dynamic ufuncs created by umath.frompy +func(function, nin, nout). + In this case +\emph on +func +\emph default + is a pointer to a +\family typewriter +PyUFunc_PyFuncData +\family default + structure which has definition { +\family typewriter +int +\family default + nin; +\family typewriter +int +\family default + nout; +\family typewriter +PyObject* +\family default + callable}. + At each iteration of the loop, the +\emph on +nin +\emph default + input objects are exctracted from their object arrays and placed into an + argument tuple, the Python +\emph on +callable +\emph default + is called with the input arguments, and the nout outputs are placed into + their object arrays. + +\end_layout + +\begin_layout Section +Importing the API +\end_layout + +\begin_layout Description +PY_UFUNC_UNIQUE_SYMBOL +\end_layout + +\begin_layout Description +NO_IMPORT_UFUNC +\end_layout + +\begin_layout Description +import_ufunc ( +\family typewriter +void +\family default +) ( +\family typewriter +void +\family default +) +\end_layout + +\begin_layout Description +\InsetSpace ~ + These are the constants and functions for accessing the ufunc C-API from + extension modules in precisely the same way as the array C-API can be accessed. + The +\family typewriter +import_ufunc +\family default +() function must always be called (in the initialization subroutine of the + extension module). + If your extension module is in one file then that is all that is required. + The other two constants are useful if your extension module makes use of + multiple files. + In that case, define +\family typewriter +PY_UFUNC_UNIQUE_SYMBOL +\family default + to something unique to your code and then in source files that do not contain + the module initialization function but still need access to the UFUNC API, + define +\family typewriter +PY_UFUNC_UNIQUE_SYMBOL +\family default + to the same name used previously and also define +\family typewriter +NO_IMPORT_UFUNC +\family default +. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + The C-API is actually an array of function pointers. + This array is created (and pointed to by a global variable) by import_ufunc. + The global variable is either statically defined or allowed to be seen + by other files depending on the state of +\family typewriter +Py_UFUNC_UNIQUE_SYMBOL +\family default + and +\family typewriter +NO_IMPORT_UFUNC +\family default +. + +\begin_inset LatexCommand index +name "ufunc!C-API|)" + +\end_inset + + +\begin_inset LatexCommand index +name "C-API!ufunc|)" + +\end_inset + + +\end_layout + +\begin_layout Chapter +How to extend NumPy +\end_layout + +\begin_layout Quotation +That which is static and repetitive is boring. + That which is dynamic and random is confusing. + In between lies art. +\end_layout + +\begin_layout Right Address +--- +\emph on +John A. + Locke +\end_layout + +\begin_layout Quotation +Science is a differential equation. + Religion is a boundary condition. +\end_layout + +\begin_layout Right Address +--- +\emph on +Alan Turing +\end_layout + +\begin_layout Section +Writing an extension module +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand label +name "sec:Writing-an-extension" + +\end_inset + + +\begin_inset LatexCommand index +name "extension module|(" + +\end_inset + +While the ndarray object is designed to allow rapid computation in Python, + it is also designed to be general-purpose and satisfy a wide-variety of + computational needs. + As a result, if absolute speed is essential, there is no replacement for + a well-crafted, compiled loop specific to your application and hardware. + This is one of the reasons that numpy includes f2py so that an easy-to-use + mechanisms for linking (simple) C/C++ and (arbitrary) Fortran code directly + into Python are available. + You are encouraged to use and improve this mechanism. + The purpose of this section is not to document this tool but to document + the more basic steps to writing an extension module that this tool depends + on. + +\end_layout + +\begin_layout Standard +When an extension module is written, compiled, and installed to somewhere + in the Python path (sys.path), the code can then be imported into Python + as if it were a standard python file. + It will contain objects and methods that have been defined and compiled + in C code. + The basic steps for doing this in Python are well-documented and you can + find more information in the documentation for Python itself available + online at +\begin_inset LatexCommand url +name "www.python.org" +target "http://www.python.org" + +\end_inset + +. + +\end_layout + +\begin_layout Standard +In addition to the Python C-API, there is a full and rich C-API for NumPy + allowing sophisticated manipulations on a C-level. + However, for most applications, only a few API calls will typically be + used. + If all you need to do is extract a pointer to memory along with some shape + information to pass to another calculation routine, then you will use very + different calls, then if you are trying to create a new array-like type + or add a new data type for ndarrays. + This chapter documents the API calls and macros that are most commonly + used. +\end_layout + +\begin_layout Section +Required subroutine +\end_layout + +\begin_layout Standard +There is exactly one function that must be defined in your C-code in order + for Python to use it as an extension module. + The function must be called init<name> where <name> is the name of the + module from Python. + This function must be declared so that it is visible to code outside of + the routine. + Besides adding the methods and constants you desire, this subroutine must + also contain calls to import_array() and/or import_ufunc() depending on + which C-API is needed. + Forgetting to place these commands will show itself as an ugly segmentation + fault (crash) as soon as any C-API subroutine is actually called. + It is actually possible to have multiple init<name> functions in a single + file in which case multiple modules will be defined by that file. + However, there are some tricks to get that to work correctly and it is + not covered here. +\end_layout + +\begin_layout Standard +A minimal init<name> method looks like +\end_layout + +\begin_layout LyX-Code +PyMODINIT_FUNC +\newline +init<name>(void) +\newline +{ +\newline + (void)Py_InitModule( +\begin_inset Quotes erd +\end_inset + +<name> +\begin_inset Quotes erd +\end_inset + +, mymethods); +\newline + import_array(); +\newline +} +\end_layout + +\begin_layout Standard +The mymethods must be an array (usually statically declared) of PyMethodDef + structures which contain method names, actual C-functions, a variable indicatin +g whether the method uses keyword arguments or not, and docstrings. + These are explained in the next section. + If you want to add constants to the module, then you store the returned + value from Py_InitModule which is a module object. + The most general way to add itmes to the module is to get the module dictionary + using PyModule_GetDict(module). + With the module dictionary, you can add whatever you like to the module + manually. + An easier way to add objects to the module is to use one of three additional + Python C-API calls that do not require a separate extraction of the module + dictionary. + These are documented in the Python documentation, but repeated here for + convenience: +\end_layout + +\begin_layout Description +PyModule_AddObject ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + module, +\family typewriter +char* +\family default + name, +\family typewriter +PyObject* +\family default + value) +\end_layout + +\begin_layout Description +PyModule_AddIntConstant ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + module, +\family typewriter +char* +\family default + name, +\family typewriter +long +\family default + value) +\end_layout + +\begin_layout Description +PyModule_AddStringConstant ( +\family typewriter +int +\family default +) ( +\family typewriter +PyObject* +\family default + module, +\family typewriter +char* +\family default + name, +\family typewriter +char* +\family default + value) +\end_layout + +\begin_layout Description +\InsetSpace ~ + All three of these functions require the +\family typewriter +module +\family default + object (the return value of Py_InitModule). + The +\family typewriter +name +\family default + is a string that labels the value in the module. + Depending on which function is called, the +\family typewriter +value +\family default + argument is either a general object (PyModule_AddObject steals a reference + to it), an integer constant, or a string constant. +\end_layout + +\begin_layout Section +Defining functions +\end_layout + +\begin_layout Standard +The second argument passed in to the Py_InitModule function is a structure + that makes it easy to to define functions in the module. + In the example given above, the mymethods structure would have been defined + earlier in the file (usually right before the init<name> subroutine) to + +\end_layout + +\begin_layout LyX-Code +static PyMethodDef mymethods[] = { +\newline +{ +\begin_inset Quotes erd +\end_inset + +nokeywordfunc +\begin_inset Quotes erd +\end_inset + +,nokeyword_cfunc, +\newline +METH_VARARGS, +\newline + +\begin_inset Quotes erd +\end_inset + +Doc string +\begin_inset Quotes erd +\end_inset + +}, +\newline +{ +\begin_inset Quotes erd +\end_inset + +keywordfunc +\begin_inset Quotes erd +\end_inset + +, keyword_cfunc, +\end_layout + +\begin_layout LyX-Code +METH_VARARGS|METH_KEYWORDS, +\newline + +\begin_inset Quotes erd +\end_inset + +Doc string +\begin_inset Quotes erd +\end_inset + +}, +\newline +{NULL, NULL, 0, NULL} /* Sentinel */ +\newline +} +\end_layout + +\begin_layout Standard +Each entry in the mymethods array is a PyMethodDef structure containing + 1) the Python name, 2) the C-function that implements the function, 3) + flags indicating whether or not keywords are accepted for this function, + and 4) The docstring for the function. + Any number of functions may be defined for a single module by adding more + entries to this table. + The last entry must be all NULL as shown to act as a sentinel. + Python looks for this entry to know that all of the functions for the module + have been defined. + +\end_layout + +\begin_layout Standard +The last thing that must be done to finish the extension module is to actually + write the code that performs the desired functions. + There are two kinds of functions: those that don't accept keyword arguments, + and those that do. +\end_layout + +\begin_layout Subsection +Functions without keyword arguments +\end_layout + +\begin_layout Standard +Functions that don't accept keyword arguments should be written as +\end_layout + +\begin_layout LyX-Code +static PyObject* +\newline +nokeyword_cfunc (PyObject *dummy, PyObject *args) +\newline +{ +\newline + /* + convert Python arguments */ +\newline + /* do function */ +\end_layout + +\begin_layout LyX-Code + /* return something */ +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Standard +The dummy argument is not used in this context and can be safely ignored. + The +\emph on +args +\emph default + argument contains all of the arguments passed in to the function as a tuple. + You can do anything you want at this point, but usually the easiest way + to manage the input arguments is to call +\family typewriter +PyArg_ParseTuple +\family default + (args, format_string, addresses_to_C_variables...) or +\family typewriter +PyArg_UnpackTuple +\family default + (tuple, +\begin_inset Quotes eld +\end_inset + +name +\begin_inset Quotes erd +\end_inset + +, min, max, ...). + A good description of how to use the first function is contained in the + Python C-API reference manual under section 5.5 (Parsing arguments and building + values). + You should pay particular attention to the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + format which uses converter functions to go between the Python object and + the C object. + All of the other format functions can be (mostly) thought of as special + cases of this general rule. + There are several converter functions defined in the NumPy C-API that may + be of use. + In particular, the +\family typewriter +PyArray_DescrConverter +\family default + function is very useful to support arbitrary data-type specification. + This function transforms any valid data-type Python object into a +\family typewriter +PyArray_Descr* +\family default + object. + Remember to pass in the address of the C-variables that should be filled + in. +\end_layout + +\begin_layout Standard +There are lots of examples of how to use +\family typewriter +PyArg_ParseTuple +\family default + throughout the NumPy source code. + The standard usage is like this: +\end_layout + +\begin_layout LyX-Code +PyObject *input; +\end_layout + +\begin_layout LyX-Code +PyArray_Descr *dtype; +\end_layout + +\begin_layout LyX-Code +if (!PyArg_ParseTuple(args, "OO&", &input, +\newline + PyArray_DescrCon +verter, +\newline + &dtype)) return NULL; +\end_layout + +\begin_layout Standard +It is important to keep in mind that you get a +\emph on +borrowed +\emph default + reference to the object when using the +\begin_inset Quotes eld +\end_inset + +O +\begin_inset Quotes erd +\end_inset + + format string. + However, the converter functions usually require some form of memory handling. + In this example, if the conversion is successful, +\emph on +dtype +\emph default + will hold a new reference to a +\family typewriter +PyArray_Descr* +\family default + object, while +\emph on +input +\emph default + will hold a borrowed reference. + Therefore, if this conversion were mixed with another conversion (say to + an integer) and the data-type conversion was successful but the integer + conversion failed, then you would need to release the reference count to + the data-type object before returning. + A typical way to do this is to set +\emph on +dtype +\emph default + to +\family typewriter +NULL +\family default + before calling PyArg_ParseTuple and then use +\family typewriter +Py_XDECREF +\family default + on +\emph on +dtype +\emph default + before returning. + +\end_layout + +\begin_layout Standard +After the input arguments are processed, the code that actually does the + work is written (likely calling other functions as needed). + The final step of the C-function is to return something. + If an error is encountered then +\family typewriter +NULL +\family default + should be returned (making sure an error has actually been set). + If nothing should be returned then increment +\family typewriter +Py_None +\family default + and return it. + If a single object should be returned then it is returned (ensuring that + you own a reference to it first). + If multiple objects should be returned then you need to return a tuple. + The +\family typewriter +Py_BuildValue +\family default + (format_string, c_variables...) function makes it easy to build tuples of + Python objects from C variables. + Pay special attention to the difference between 'N' and 'O' in the format + string or you can easily create memory leaks. + The 'O' format string increments the reference count of the +\family typewriter +PyObject* +\family default + C-variable it corresponds to, while the 'N' format string steals a reference + to the corresponding +\family typewriter +PyObject* +\family default + C-variable. + You should use 'N' if you ave already created a reference for the object + and just want to give that reference to the tuple. + You should use 'O' if you only have a borrowed reference to an object and + need to create one to provide for the tuple. + +\end_layout + +\begin_layout Subsection +Functions with keyword arguments +\end_layout + +\begin_layout Standard +These functions are very similar to functions without keyword arguments. + The only difference is that the function signature is +\end_layout + +\begin_layout LyX-Code +static PyObject* +\newline +keyword_cfunc (PyObject *dummy, PyObject *args, PyObject + *kwds) +\newline +{ +\newline +... +\newline +} +\end_layout + +\begin_layout Standard +The kwds argument holds a Python dictionary whose keys are the names of + the keyword arguments and whose values are the corresponding keyword-argument + values. + This dictionary can be processed however you see fit. + The easiest way to handle it, however, is to replace the +\family typewriter +PyArg_ParseTuple +\family default + (args, format_string, addresses...) function with a call to +\family typewriter +PyArg_ParseTupleAndKeywords +\family default + (args, kwds, format_string, char *kwlist[], addresses...). + The kwlist parameter to this function is a +\family typewriter +NULL +\family default +-terminated array of strings providing the expected keyword arguments. + There should be one string for each entry in the format_string. + Using this function will raise a TypeError if invalid keyword arguments + are passed in. + +\end_layout + +\begin_layout Standard +For more help on this function please see section 1.8 (Keyword Paramters + for Extension Functions) of the Extending and Embedding tutorial in the + Python documentation. +\end_layout + +\begin_layout Subsection +Reference counting +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "reference counting|(" + +\end_inset + +The biggest difficulty when writing extension modules is reference counting. + It is an important reason for the popularity of f2py, weave, pyrex, ctypes, + etc.... + If you mis-handle reference counts you can get problems from memory-leaks + to segmentation faults. + The only strategy I know of to handle reference counts correctly is blood, + sweat, and tears. + First, you force it into your head that every Python variable has a reference + count. + Then, you understand exactly what each function does to the reference count + of your objects, so that you can properly use DECREF and INCREF when you + need them. + Reference counting can really test the amount of patience and diligence + you have towards your programming craft. + Despite the grim depiction, most cases of reference counting are quite + straightforward with the most common difficulty being not using DECREF + on objects before exiting early from a routine due to some error. + In second place, is the common error of not owning the reference on an + object that is passed to a function or macro that is going to steal the + reference ( +\emph on +e.g. + +\emph default + +\family typewriter +PyTuple_SET_ITEM +\family default +, and most functions that take +\family typewriter +PyArray_Descr +\family default + objects). + +\end_layout + +\begin_layout Standard +Typically you get a new reference to a variable when it is created or is + the return value of some function (there are some prominent exceptions, + however --- such as getting an item out of a tuple or a dictionary). + When you own the reference, you are responsible to make sure that +\family typewriter +Py_DECREF +\family default +(var) is called when the variable is no longer necessary (and no other function + has +\begin_inset Quotes eld +\end_inset + +stolen +\begin_inset Quotes erd +\end_inset + + its reference). + Also, if you are passing a Python object to a function that will +\begin_inset Quotes eld +\end_inset + +steal +\begin_inset Quotes erd +\end_inset + + the reference, then you need to make sure you own it (or use +\family typewriter +Py_INCREF +\family default + to get your own reference). + You will also encounter the notion of borrowing a reference. + A function that borrows a reference does not alter the reference count + of the object and does not expect to +\begin_inset Quotes eld +\end_inset + +hold on +\begin_inset Quotes erd +\end_inset + + to the reference. + It's just going to use the object temporarily. + When you use +\family typewriter +PyArg_ParseTuple +\family default + or +\family typewriter +PyArg_UnpackTuple +\family default + you receive a borrowed reference to the objects in the tuple and should + not alter their reference count inside your function. + With practice, you can learn to get reference counting right, but it can + be frustrating at first. + +\end_layout + +\begin_layout Standard +One common source of reference-count errors is the +\family typewriter +Py_BuildValue +\family default + function. + Pay careful attention to the difference between the 'N' format character + and the 'O' format character. + If you create a new object in your subroutine (such as an output array), + and you are passing it back in a tuple of return values, then you should + most-likely use the 'N' format character in +\family typewriter +Py_BuildValue +\family default +. + The 'O' character will increase the reference count by one. + This will leave the caller with two reference counts for a brand-new array. + When the variable is deleted and the reference count decremented by one, + there will still be that extra reference count, and the array will never + be deallocated. + You will have a reference-counting induced memory leak. + Using the 'N' character will avoid this situation as it will return to + the caller an object (inside the tuple) with a single reference count. + +\begin_inset LatexCommand index +name "reference counting|)" + +\end_inset + + +\end_layout + +\begin_layout Section +Dealing with array objects +\end_layout + +\begin_layout Standard +Most extension modules for NumPy will need to access the memory for an ndarray + object (or one of it's sub-classes). + The easiest way to do this doesn't require you to know much about the internals + of NumPy. + The method is to +\end_layout + +\begin_layout Enumerate +Ensure you are dealing with a well-behaved array (aligned, in machine byte-order + and single-segment) of the correct type and number of dimensions. + +\end_layout + +\begin_deeper +\begin_layout Enumerate +By converting it from some Python object using +\family typewriter +PyArray_FromAny +\family default + or a macro built on it. + +\end_layout + +\begin_layout Enumerate +By constructing a new ndarray of your desired shape and type using +\family typewriter +PyArray_NewFromDescr +\family default + or a simpler macro or function based on it. + +\end_layout + +\end_deeper +\begin_layout Enumerate +Get the shape of the array and a pointer to its actual data. + +\end_layout + +\begin_layout Enumerate +Pass the data and shape information on to a subroutine or other section + of code that actually performs the computation. + +\end_layout + +\begin_layout Enumerate +If you are writing the algorithm, then I recommend that you use the stride + information contained in the array to access the elements of the array + (the +\family typewriter +PyArray_GETPTR +\family default + macros make this painless). + Then, you can relax your requirements so as not to force a single-segment + array and the data-copying that might result. + +\end_layout + +\begin_layout Standard +Each of these sub-topics is covered in the following sub-sections. +\end_layout + +\begin_layout Subsection +Converting an arbitrary sequence object +\end_layout + +\begin_layout Standard +The main routine for obtaining an array from any Python object that can + be converted to an array is +\family typewriter +PyArray_FromAny +\family default +. + This function is very flexible with many input arguments. + Several macros make it easier to use the basic function. + +\family typewriter +PyArray_FROM_OTF +\family default + is arguably the most useful of these macros for the most common uses. + It allows you to convert an arbitrary Python object to an array of a specific + builtin data-type ( +\emph on +e.g. + +\emph default + float), while specifying a particular set of requirements ( +\emph on +e.g. + +\emph default + contiguous, aligned, and writeable). + The syntax is +\end_layout + +\begin_layout Description +PyArray_FROM_OTF ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyObject* +\family default + obj, +\family typewriter +int +\family default + typenum, +\family typewriter +int +\family default + requirements) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Return an ndarray from any Python object, +\emph on +obj +\emph default +, that can be converted to an array. + The number of dimensions in the returned array is determined by the object. + The desired data-type of the returned array is provided in +\emph on +typenum +\emph default + which should be one of the enumerated types. + The +\emph on +requirements +\emph default + for the returned array can be any combination of standard array flags. + Each of these arguments is explained in more detail below. + You receive a new reference to the array on success. + On failure, +\family typewriter +NULL +\family default + is returned and an exception is set. + +\end_layout + +\begin_deeper +\begin_layout Description +obj The object can be any Python object convertable to an ndarray. + If the object is already (a subclass of) the ndarray that satisfies the + requirements then a new reference is returned. + Otherwise, a new array is constructed. + The contents of +\emph on +obj +\emph default + are copied to the new array unless the array interface is used so that + data does not have to be copied. + Objects that can be converted to an array include: 1) any nested sequence + object, 2) any object exposing the array interface, 3) any object with + an +\series bold +__array__ +\series default + method (which should return an ndarray), and 4) any scalar object (becomes + a zero-dimensional array). + Sub-classes of the ndarray that otherwise fit the requirements will be + passed through. + If you want to ensure a base-class ndarray, then use +\family typewriter +NPY_ENSUREARRAY +\family default + in the requirements flag. + A copy is made only if necessary. + If you want to guarantee a copy, then pass in +\family typewriter +NPY_ENSURECOPY +\family default + to the requirements flag. + +\end_layout + +\begin_layout Description +typenum One of the enumerated types or +\family typewriter +NPY_NOTYPE +\family default + if the data-type should be determined from the object itself. + The C-based names can be used: +\end_layout + +\begin_deeper +\begin_layout Quote + +\family typewriter +NPY_BOOL +\family default +, +\family typewriter +NPY_BYTE +\family default +, +\family typewriter +NPY_UBYTE +\family default +, +\family typewriter +NPY_SHORT +\family default +, +\family typewriter +NPY_USHORT +\family default +, +\family typewriter +NPY_INT +\family default +, +\family typewriter +NPY_UINT +\family default +, +\family typewriter +NPY_LONG +\family default +, +\family typewriter +NPY_ULONG +\family default +, +\family typewriter +NPY_LONGLONG +\family default +, +\family typewriter +NPY_ULONGLONG +\family default +, +\family typewriter +NPY_DOUBLE +\family default +, +\family typewriter +NPY_LONGDOUBLE +\family default +, +\family typewriter +NPY_CFLOAT +\family default +, +\family typewriter +NPY_CDOUBLE +\family default +, +\family typewriter +NPY_CLONGDOUBLE +\family default +, +\family typewriter +NPY_OBJECT +\family default +. + +\end_layout + +\end_deeper +\begin_layout Description +\InsetSpace ~ + Alternatively, the bit-width names can be used as supported on the platform. + For example: +\end_layout + +\begin_deeper +\begin_layout Quote + +\family typewriter +NPY_INT8 +\family default +, +\family typewriter +NPY_INT16 +\family default +, +\family typewriter +NPY_INT32 +\family default +, +\family typewriter +NPY_INT64 +\family default +, +\family typewriter +NPY_UINT8 +\family default +, +\family typewriter +NPY_UINT16 +\family default +, +\family typewriter +NPY_UINT32 +\family default +, +\family typewriter +NPY_UINT64 +\family default +, +\family typewriter +NPY_FLOAT32 +\family default +, +\family typewriter +NPY_FLOAT64 +\family default +, +\family typewriter +NPY_COMPLEX64 +\family default +, +\family typewriter +NPY_COMPLEX128 +\family default +. + +\end_layout + +\end_deeper +\begin_layout Description +\InsetSpace ~ + The object will be converted to the desired type only if it can be done + without losing precision. + Otherwise +\family typewriter +NULL +\family default + will be returned and an error raised. + Use +\family typewriter +NPY_FORCECAST +\family default + in the requirements flag to override this behavior. + +\end_layout + +\begin_layout Description +requirements The memory model for an ndarray admits arbitrary strides in + each dimension to advance to the next element of the array. + Often, however, you need to interface with code that expects a C-contiguous + or a Fortran-contiguous memory layout. + In addition, an ndarray can be misaligned (the address of an element is + not at an integral multiple of the size of the element) which can cause + your program to crash (or at least work more slowly) if you try and dereference + a pointer into the array data. + Both of these problems can be solved by converting the Python object into + an array that is more +\begin_inset Quotes eld +\end_inset + +well-behaved +\begin_inset Quotes erd +\end_inset + + for your specific usage. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + The requirements flag allows specification of what kind of array is acceptable. + If the object passed in does not satisfy this requirements then a copy + is made so that thre returned object will satisfy the requirements. + these ndarray can use a very generic pointer to memory. + This flag allows specification of the desired properties of the returned + array object. + All of the flags are explained in the detailed API chapter. + The flags most commonly needed are NPY_IN_ARRAY, NPY_OUT_ARRAY, and NPY_INOUT_A +RRAY: +\end_layout + +\begin_deeper +\begin_layout Description +NPY_IN_ARRAY Equivalent to NPY_CONTIGUOUS | NPY_ALIGNED. + This combination of flags is useful for arrays that must be in C-contiguous + order and aligned. + These kinds of arrays are usually input arrays for some algorithm. +\end_layout + +\begin_layout Description +NPY_OUT_ARRAY Equivalent to NPY_CONTIGUOUS | NPY_ALIGNED | NPY_WRITEABLE. + This combination of flags is useful to specify an array that is in C-contiguous + order, is aligned, and can be written to as well. + Such an array is usually returned as output (although normally such output + arrays are created from scratch). + +\end_layout + +\begin_layout Description +NPY_INOUT_ARRAY Equivalent to NPY_CONTIGUOUS | NPY_ALIGNED | NPY_WRITEABLE + | NPY_UPDATEIFCOPY. + This combination of flags is useful to specify an array that will be used + for both input and output. + If a copy is needed, then when the temporary is deleted (by your use of + Py_DECREF at the end of the interface routine), the temporary array will + be copied back into the original array passed in. + Use of the UPDATEIFCOPY flag requires that the input object is already + an array (because other objects cannot be automatically updated in this + fashion). + If an error occurs use +\series bold +PyArray_DECREF_ERR +\series default +(obj) on an array with the NPY_UPDATEIFCOPY flag set. + This will delete the array without causing the contents to be copied back + into the original array. + +\end_layout + +\end_deeper +\begin_layout Description +\InsetSpace ~ + Other useful flags that can be OR'd as additional requirements are: +\end_layout + +\begin_deeper +\begin_layout Description +NPY_FORCECAST Cast to the desired type, even if it can't be done without + losing information. +\end_layout + +\begin_layout Description +NPY_ENSURECOPY Make sure the resulting array is a copy of the original. +\end_layout + +\begin_layout Description +NPY_ENSUREARRAY Make sure the resulting object is an actual ndarray and + not a sub-class. +\end_layout + +\end_deeper +\end_deeper +\begin_layout Note +Whether or not an array is byte-swapped is determined by the data-type of + the array. + Native byte-order arrays are always requested by PyArray_FROM_OTF and so + there is no need for a NPY_NOTSWAPPED flag in the requirements argument. + There is also no way to get a byte-swapped array from this routine. +\end_layout + +\begin_layout Subsection +Creating a brand-new ndarray +\end_layout + +\begin_layout Standard +Quite often new arrays must be created from within extension-module code. + Perhaps an output array is needed and you don't want the caller to have + to supply it. + Perhaps only a temporary array is needed to hold an intermediate calculation. + Whatever the need there are simple ways to get an ndarray object of whatever + data-type is needed. + The most general function for doing this is PyArray_NewFromDescr. + All array creation functions go through this heavily re-used code. + Because of its flexibility, it can be somewhat confusing to use. + As a result, simpler forms exist that are easier to use. + +\end_layout + +\begin_layout Description +PyArray_SimpleNew ( +\family typewriter +PyObject* +\family default +)( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + typenum) +\end_layout + +\begin_layout Description +\InsetSpace ~ + This function allocates new memory and places it in an ndarray with +\family typewriter +nd +\family default + dimensions whose shape is determined by the array of at least +\family typewriter +nd +\family default + items pointed to by +\family typewriter +dims +\family default +. + The memory for the array is uninitialized (unless typenum is +\series bold +PyArray_OBJECT +\series default + in which case each element in the array is set to NULL). + The +\family typewriter +typenum +\family default + argument allows specification of any of the builtin data-types such as + +\series bold +PyArray_FLOAT +\series default + or +\series bold +PyArray_LONG +\series default +. + The memory for the array can be set to zero if desired using +\series bold +PyArray_FILLWBYTE +\series default +(return_object, 0). + +\end_layout + +\begin_layout Description +PyArray_SimpleNewFromData ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +int +\family default + nd, +\family typewriter +npy_intp* +\family default + dims, +\family typewriter +int +\family default + typenum, +\family typewriter +void* +\family default + data) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Sometimes, you want to wrap memory allocated elsewhere into an ndarray + object for downstream use. + This routine makes it straightforward to do that. + The first three arguments are the same as in +\series bold +PyArray_SimpleNew +\series default +, the final argument is a pointer to a block of contiguous memory that the + ndarray should use as it's data-buffer which will be interpreted in C-style + contiguous fashion. + A new reference to an ndarray is returned, but the ndarray will not own + its data. + When this ndarray is deallocated, the pointer will not be freed. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + You should ensure that the provided memory is not freed while the returned + array is in existence. + The easiest way to handle this is if data comes from another reference-counted + Python object. + The reference count on this object should be increased after the pointer + is passed in, and the base member of the returned ndarray should point + to the Python object that owns the data. + Then, when the ndarray is deallocated, the base-member will be DECREF'd + appropriately. + If you want the memory to be freed as soon as the ndarray is deallocated + then simply set the OWNDATA flag on the returned ndarray. + +\end_layout + +\begin_layout Subsection +Getting at ndarray memory and accessing elements of the ndarray +\end_layout + +\begin_layout Standard +If obj is an ndarray (PyArrayObject *), then the data-area of the ndarray + is pointed to by the void* pointer +\series bold +PyArray_DATA +\series default +(obj) or the char* pointer +\series bold +PyArray_BYTES +\series default +(obj). + Remember that (in general) this data-area may not be aligned according + to the data-type, it may represent byte-swapped data, and/or it may not + be writeable. + If the data area is aligned and in native byte-order, then how to get at + a specific element of the array is determined only by the array of npy_intp + variables, +\series bold +PyArray_STRIDES +\series default +(obj). + In particular, this c-array of integers shows how many +\series bold +bytes +\series default + must be added to the current element pointer to get to the next element + in each dimension. + For arrays less than 4-dimensions there are +\series bold +PyArray_GETPTR<k> +\series default +(obj, ...) macros where <k> is the integer 1, 2, 3, or 4 that make using the + array strides easier. + The arguments .... + represent <k> non-negative integer indices into the array. + For example, suppose +\family typewriter +E +\family default + is a 3-dimensional ndarray. + A (void*) pointer to the element +\family typewriter +E[i,j,k] +\family default + is obtained as PyArray_GETPTR3(E, i, j, k). + +\end_layout + +\begin_layout Standard +As explained previously, C-style contiguous arrays and Fortran-style contiguous + arrays have particular striding patterns. + Two array flags (NPY_C_CONTIGUOUS and NPY_F_CONTIGUOUS) indicate whether + or not the striding pattern of a particular array matches the C-style contiguou +s or Fortran-style contiguous or neither. + Whether or not the striding pattern matches a standard C or Fortran one + can be tested Using +\family typewriter +PyArray_ISCONTIGUOUS +\family default +(obj) and +\family typewriter +PyArray_ISFORTRAN +\family default +(obj) respectively. + Most third-party libraries expect contiguous arrays. + But, often it is not difficult to support general-purpose striding. + I encourage you to use the striding information in your own code whenever + possible, and reserve single-segment requirements for wrapping third-party + code. + Using the striding information provided with the ndarray rather than requiring + a contiguous striding reduces copying that otherwise must be made. + +\end_layout + +\begin_layout Section +Example +\end_layout + +\begin_layout Standard +The following example shows how you might write a wrapper that accepts two + input arguments (that will be converted to an array) and an output argument + (that must be an array). + The function returns None and updates the output array. + +\begin_inset LatexCommand index +name "extension module|)" + +\end_inset + + +\end_layout + +\begin_layout LyX-Code +static PyObject * +\end_layout + +\begin_layout LyX-Code +example_wrapper(PyObject *dummy, PyObject *args) +\end_layout + +\begin_layout LyX-Code +{ +\end_layout + +\begin_layout LyX-Code + PyObject *arg1=NULL, *arg2=NULL, *out=NULL; +\end_layout + +\begin_layout LyX-Code + PyObject *arr1=NULL, *arr2=NULL, *oarr=NULL; +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + if (!PyArg_ParseTuple(args, +\begin_inset Quotes eld +\end_inset + +OOO& +\begin_inset Quotes erd +\end_inset + +, &arg1, *arg2, +\end_layout + +\begin_layout LyX-Code + &PyArrayType, *out)) return NULL; +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + arr1 = PyArray_FROM_OTF(arg1, NPY_DOUBLE, NPY_IN_ARRAY); +\end_layout + +\begin_layout LyX-Code + if (arr1 == NULL) return NULL; +\end_layout + +\begin_layout LyX-Code + arr2 = PyArray_FROM_OTF(arg2, NPY_DOUBLE, NPY_IN_ARRAY); +\end_layout + +\begin_layout LyX-Code + if (arr2 == NULL) goto fail; +\end_layout + +\begin_layout LyX-Code + oarr = PyArray_FROM_OTF(out, NPY_DOUBLE, NPY_INOUT_ARRAY); +\end_layout + +\begin_layout LyX-Code + if (oarr == NULL) goto fail; +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + /* code that makes use of arguments */ +\end_layout + +\begin_layout LyX-Code + /* You will probably need at least +\end_layout + +\begin_layout LyX-Code + nd = PyArray_NDIM(<..>) -- number of dimensions +\end_layout + +\begin_layout LyX-Code + dims = PyArray_DIMS(<..>) -- npy_intp array of length nd +\end_layout + +\begin_layout LyX-Code + showing length in each dim. +\end_layout + +\begin_layout LyX-Code + dptr = (double *)PyArray_DATA(<..>) -- pointer to data. +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + If an error occurs goto fail. +\end_layout + +\begin_layout LyX-Code + */ +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + Py_DECREF(arr1); +\end_layout + +\begin_layout LyX-Code + Py_DECREF(arr2); +\end_layout + +\begin_layout LyX-Code + Py_DECREF(oarr); +\end_layout + +\begin_layout LyX-Code + Py_INCREF(Py_None); +\end_layout + +\begin_layout LyX-Code + return Py_None; +\end_layout + +\begin_layout LyX-Code + +\end_layout + +\begin_layout LyX-Code + fail: +\end_layout + +\begin_layout LyX-Code + Py_XDECREF(arr1); +\end_layout + +\begin_layout LyX-Code + Py_XDECREF(arr2); +\end_layout + +\begin_layout LyX-Code + PyArray_XDECREF_ERR(oarr); +\end_layout + +\begin_layout LyX-Code + return NULL; +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Chapter +Beyond the Basics +\end_layout + +\begin_layout Quotation +The voyage of discovery is not in seeking new landscapes but in having new + eyes. +\end_layout + +\begin_layout Right Address +--- +\emph on +Marcel Proust +\end_layout + +\begin_layout Quotation +Discovery is seeing what everyone else has seen and thinking what no one + else has thought. +\end_layout + +\begin_layout Right Address +--- +\emph on +Albert Szent-Gyorgi +\end_layout + +\begin_layout Section +Iterating over elements in the array +\end_layout + +\begin_layout Subsection +Basic Iteration +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand label +name "sec:array_iterator" + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "array iterator|(" + +\end_inset + +One common algorithmic requirement is to be able to walk over all elements + in a multidimensional array. + The array iterator object makes this easy to do in a generic way that works + for arrays of any dimension. + Naturally, if you know the number of dimensions you will be using, then + you can always write nested for loops to accomplish the iteration. + If, however, you want to write code that works with any number of dimensions, + then you can make use of the array iterator. + An array iterator object is returned when accessing the .flat attribute + of an array. + +\end_layout + +\begin_layout Standard +Basic usage is to call +\series bold +PyArray_IterNew +\series default + ( +\family typewriter +array +\family default +) where array is an ndarray object (or one of its sub-classes). + The returned object is an array-iterator object (the same object returned + by the .flat attribute of the ndarray). + This object is usually cast to PyArrayIterObject* so that its members can + be accessed. + The only members that are needed are +\family typewriter +iter->size +\family default + which contains the total size of the array, +\family typewriter +iter->index +\family default +, which contains the current 1-d index into the array, and +\family typewriter +iter->dataptr +\family default + which is a pointer to the data for the current element of the array. + Sometimes it is also useful to access +\family typewriter +iter->ao +\family default + which is a pointer to the underlying ndarray object. + +\end_layout + +\begin_layout Standard +After processing data at the current element of the array, the next element + of the array can be obtained using the macro +\series bold +PyArray_ITER_NEXT +\series default +( +\family typewriter +iter +\family default +). + The iteration always proceeds in a C-style contiguous fashion (last index + varying the fastest). + The +\series bold +PyArray_ITER_GOTO +\series default +( +\family typewriter +iter +\family default +, +\family typewriter +destination +\family default +) can be used to jump to a particular point in the array, where +\family typewriter +destination +\family default + is an array of npy_intp data-type with space to handle at least the number + of dimensions in the underlying array. + Occasionally it is useful to use +\series bold +PyArray_ITER_GOTO1D +\series default +( +\family typewriter +iter +\family default +, +\family typewriter +index +\family default +) which will jump to the 1-d index given by the value of +\family typewriter +index +\family default +. + The most common usage, however, is given in the following example. + +\end_layout + +\begin_layout LyX-Code +PyObject *obj; /* assumed to be some ndarray object */ +\end_layout + +\begin_layout LyX-Code +PyArrayIterObject *iter; +\end_layout + +\begin_layout LyX-Code +... +\end_layout + +\begin_layout LyX-Code +iter = (PyArrayIterObject *)PyArray_IterNew(obj); +\end_layout + +\begin_layout LyX-Code +if (iter == NULL) goto fail; /* Assume fail has clean-up code */ +\end_layout + +\begin_layout LyX-Code +while (iter->index < iter->size) { +\end_layout + +\begin_layout LyX-Code + /* do something with the data at it->dataptr */ +\end_layout + +\begin_layout LyX-Code + PyArray_ITER_NEXT(it); +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout LyX-Code +... +\end_layout + +\begin_layout Standard +You can also use +\series bold +PyArrayIter_Check +\series default +( +\family typewriter +obj +\family default +) to ensure you have an iterator object and +\series bold +PyArray_ITER_RESET +\series default +( +\family typewriter +iter +\family default +) to reset an iterator object back to the beginning of the array. + +\end_layout + +\begin_layout Standard +It should be emphasized at this point that you may not need the array iterator + if your array is already contiguous (using an array iterator will work + but will be slower than the fastest code you could write). + The major purpose of array iterators is to encapsulate iteration over N-dimensi +onal arrays with arbitrary strides. + They are used in many, many places in the NumPy source code itself. + If you already know your array is contiguous (Fortran or C), then simply + adding the element-size to a running pointer variable will step you through + the array very efficiently. + In other words, code like this will probably be faster for you in the contiguou +s case (assuming doubles). + +\end_layout + +\begin_layout LyX-Code +npy_intp size; +\end_layout + +\begin_layout LyX-Code +double *dptr; /* could make this any variable type */ +\end_layout + +\begin_layout LyX-Code +size = PyArray_SIZE(obj); +\end_layout + +\begin_layout LyX-Code +dptr = PyArray_DATA(obj); +\end_layout + +\begin_layout LyX-Code +while(size--) { +\end_layout + +\begin_layout LyX-Code + /* do something with the data at dptr */ +\end_layout + +\begin_layout LyX-Code + dptr++; +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Subsection +Iterating over all but one axis +\end_layout + +\begin_layout Standard +A common algorithm is to loop over all elements of an array and perform + some function with each element by issuing a function call. + As function calls can be time consuming, one way to speed up this kind + of algorithm is to write the function so it takes a vector of data and + then write the iteration so the function call is performed for an entire + dimension of data at a time. + This increases the amount of work done per function call, thereby reducing + the function-call over-head to a small(er) fraction of the total time. + Even if the interior of the loop is performed without a function call it + can be advantageous to perform the inner loop over the dimension with the + highest number of elements to take advantage of speed enhancements available + on micro-processors that use pipelining to enhance fundmental operations. + +\end_layout + +\begin_layout Standard +The +\series bold +PyArray_IterAllButAxis +\series default +( +\family typewriter +array +\family default +, +\family typewriter +&dim +\family default +) constructs an iterator object that is modified so that it will not iterate + over the dimension indicated by dim. + The only restriction on this iterator object, is that the +\series bold +PyArray_Iter_GOTO1D +\series default +( +\family typewriter +it +\family default +, +\family typewriter +ind +\family default +) macro cannot be used (thus flat indexing won't work either if you pass + this object back to Python --- so you shouldn't do this). + Note that the returned object from this routine is still usually cast to + PyArrayIterObject *. + All that's been done is to modify the strides and dimensions of the returned + iterator to simulate iterating over array[...,0,...] where 0 is placed on the + +\begin_inset Formula $\textrm{dim}^{\textrm{th}}$ +\end_inset + + dimension. + If dim is negative, then the dimension with the largest axis is found and + used. + +\end_layout + +\begin_layout Subsection +Iterating over multiple arrays +\end_layout + +\begin_layout Standard +Very often, it is desireable to iterate over several arrays at the same + time. + The universal functions are an example of this kind of behavior. + If all you want to do is iterate over arrays with the same shape, then + simply creating several iterator objects is the standard procedure. + For example, the following code iterates over two arrays assumed to be + the same shape and size (actually obj1 just has to have at least as many + total elements as does obj2): +\end_layout + +\begin_layout LyX-Code +/* It is already assumed that obj1 and obj2 +\end_layout + +\begin_layout LyX-Code + are ndarrays of the same shape and size. +\end_layout + +\begin_layout LyX-Code +*/ +\end_layout + +\begin_layout LyX-Code +iter1 = (PyArrayIterObject *)PyArray_IterNew(obj1); +\end_layout + +\begin_layout LyX-Code +if (iter1 == NULL) goto fail; +\end_layout + +\begin_layout LyX-Code +iter2 = (PyArrayIterObject *)PyArray_IterNew(obj2); +\end_layout + +\begin_layout LyX-Code +if (iter2 == NULL) goto fail; /* assume iter1 is DECREF'd at fail */ +\end_layout + +\begin_layout LyX-Code +while (iter2->index < iter2->size) { +\end_layout + +\begin_layout LyX-Code + /* process with iter1->dataptr and iter2->dataptr */ +\end_layout + +\begin_layout LyX-Code + PyArray_ITER_NEXT(iter1); +\end_layout + +\begin_layout LyX-Code + PyArray_ITER_NEXT(iter2); +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Subsection +Broadcasting over multiple arrays +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "broadcasting" + +\end_inset + +When multiple arrays are involved in an operation, you may want to use the + same broadcasting rules that the math operations ( +\emph on +i.e. + +\emph default + the ufuncs) use. + This can be done easily using the PyArrayMultiIterObject. + This is the object returned from the Python command numpy.broadcast and + it is almost as easy to use from C. + The function +\series bold +PyArray_MultiIterNew +\series default + ( +\family typewriter +n +\family default +, +\family typewriter +... +\family default +) is used (with +\family typewriter +n +\family default + input objects in place of +\family typewriter +... +\family default +). + The input objects can be arrays or anything that can be converted into + an array. + A pointer to a PyArrayMultiIterObject is returned. + Broadcasting has already been accomplished which adjusts the iterators + so that all that needs to be done to advance to the next element in each + array is for PyArray_ITER_NEXT to be called for each of the inputs. + This incrementing is automatically performed by +\series bold +PyArray_MultiIter_NEXT +\series default +( +\family typewriter +obj +\family default +) macro (which can handle a multiterator +\family typewriter +obj +\family default + as either a PyArrayMultiObject* or a PyObject*). + The data from input number +\family typewriter +i +\family default + is available using +\series bold +PyArray_MultiIter_DATA +\series default +( +\family typewriter +obj +\family default +, +\family typewriter +i +\family default +) and the total (broadcasted) size as +\series bold +PyArray_MultiIter_SIZE +\series default +( +\family typewriter +obj +\family default +). + An example of using this feature follows. +\end_layout + +\begin_layout LyX-Code +mobj = PyArray_MultiIterNew(2, obj1, obj2); +\end_layout + +\begin_layout LyX-Code +size = PyArray_MultiIter_SIZE(obj); +\end_layout + +\begin_layout LyX-Code +while(size--) { +\end_layout + +\begin_layout LyX-Code + ptr1 = PyArray_MultiIter_DATA(mobj, 0); +\end_layout + +\begin_layout LyX-Code + ptr2 = PyArray_MultiIter_DATA(mobj, 1); +\end_layout + +\begin_layout LyX-Code + /* code using contents of ptr1 and ptr2 */ +\end_layout + +\begin_layout LyX-Code + PyArray_MultiIter_NEXT(mobj); +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Standard +The function +\series bold +PyArray_RemoveLargest +\series default +( +\family typewriter +multi +\family default +) can be used to take a multi-iterator object and adjust all the iterators + so that iteration does not take place over the largest dimension (it makes + that dimension of size 1). + The code being looped over that makes use of the pointers will very-likely + also need the strides data for each of the iterators. + This information is stored in multi->iters[i]->strides. +\end_layout + +\begin_layout Standard +There are several examples of using the multi-iterator in the NumPy source + code as it makes N-dimensional broadcasting-code very simple to write. + Browse the source for more examples. + +\begin_inset LatexCommand index +name "array iterator|)" + +\end_inset + + +\end_layout + +\begin_layout Section +Creating a new universal function +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand label +name "sec:Creating-a-new" + +\end_inset + + +\begin_inset LatexCommand index +name "ufunc!adding new|(" + +\end_inset + +The umath module is a computer-generated C-module that creates many ufuncs. + It provides a great many examples of how to create a universal function. + Creating your own ufunc that will make use of the ufunc machinery is not + difficult either. + Suppose you have a function that you want to operate element-by-element + over its inputs. + By creating a new ufunc you will obtain a function that handles +\end_layout + +\begin_layout Itemize +broadcasting +\end_layout + +\begin_layout Itemize +N-dimensional looping +\end_layout + +\begin_layout Itemize +automatic type-conversions with minimal memory usage +\end_layout + +\begin_layout Itemize +optional output arrays +\end_layout + +\begin_layout Standard +It is not difficult to create your own ufunc. + All that is required is a 1-d loop for each data-type you want to support. + Each 1-d loop must have a specific signature, and only ufuncs for fixed-size + data-types can be used. + The function call used to create a new ufunc to work on built-in data-types + is given below. + A different mechanism is used to register ufuncs for user-defined data-types. +\end_layout + +\begin_layout Description +PyUFunc_FromFuncAndData ( +\family typewriter +PyObject* +\family default +) ( +\family typewriter +PyUFuncGenericFunction* +\family default + func, +\family typewriter +void** +\family default + data, +\family typewriter +char* +\family default + types, +\family typewriter +int +\family default + ntypes, +\family typewriter +int +\family default + nin, +\family typewriter +int +\family default + nout, +\family typewriter +int +\family default + identity, +\family typewriter +char* +\family default + name, +\family typewriter +char* +\family default + doc, +\family typewriter +int +\family default + check_return) +\end_layout + +\begin_deeper +\begin_layout Description +func A pointer to an array of 1-d functions to use. + This array must be at least ntypes long. + Each entry in the array must be a +\family typewriter +PyUFuncGenericFunction +\family default + function. + This function has the following signature. + An example of a valid 1d loop function is also given. + +\end_layout + +\begin_layout Description +\InsetSpace ~ + +\family typewriter +void +\family default + loop1d ( +\family typewriter +char** +\family default + args, +\family typewriter +npy_intp* +\family default + dimensions, +\family typewriter +npy_intp* +\family default + steps, +\family typewriter +void* +\family default + data) +\end_layout + +\begin_deeper +\begin_layout Description +args An array of pointers to the actual data for the input and output arrays. + The input arguments are given first followed by the output arguments. +\end_layout + +\begin_layout Description +dimensions A pointer to the size of the dimension over which this function + is looping. + +\end_layout + +\begin_layout Description +steps A pointer to the number of bytes to jump to get to the next element + in this dimension for each of the input and output arguments. + +\end_layout + +\begin_layout Description +data Arbitrary data (extra arguments, function names, +\emph on +etc. +\emph default +) that can be stored with the ufunc and will be passed in when it is called. + +\end_layout + +\end_deeper +\begin_layout LyX-Code +static void +\newline +double_add(char *args, npy_intp *dimensions, npy_intp *steps, + void *extra) +\newline +{ +\newline + npy_intp i; +\newline + npy_intp is1=steps[0], is2=steps[1]; +\newline + + npy_intp os=steps[2], n=dimensions[0]; +\newline + char *i1=args[0], *i2=args[1], + *op=args[2]; +\newline + for (i=0; i<n; i++) { +\newline + *((double *)op) = *((double + *)i1) + +\backslash + +\newline + *((double *)i2); +\newline + i1 += is1; i2 += is2; + op += os; +\newline + } +\newline +} +\end_layout + +\begin_layout Description +data An array of data. + There should be ntypes entries (or NULL) --- one for every loop function + defined for this ufunc. + This data will be passed in to the 1-d loop. + One common use of this data variable is to pass in an actual function to + call to compute the result when a generic 1-d loop (e.g. + PyUFunc_d_d) is being used. + +\end_layout + +\begin_layout Description +types An array of type-number signatures (type +\family typewriter +char +\family default +). + This array should be of size (nin+nout)*ntypes and contain the data-types + for the corresponding 1-d loop. + The inputs should be first followed by the outputs. + For example, suppose I have a ufunc that supports 1 integer and 1 double + 1-d loop (length-2 func and data arrays) that takes 2 inputs and returns + 1 output that is always a complex double, then the types array would be +\end_layout + +\begin_layout LyX-Code +char my_sigs[] = +\backslash + +\newline +{NPY_INT, NPY_INT, NPY_CDOUBLE, +\newline +NPY_DOUBLE, NPY_DOUBLE, NPY_CDOUBLE}; +\end_layout + +\begin_layout Description +\InsetSpace ~ + The bit-width names can also be used (e.g. + +\family typewriter +NPY_INT32 +\family default +, +\family typewriter +NPY_COMPLEX128 +\family default +) if desired. + +\end_layout + +\begin_layout Description +ntypes The number of data-types supported. + This is equal to the number of 1-d loops provided. + +\end_layout + +\begin_layout Description +nin The number of input arguments. +\end_layout + +\begin_layout Description +nout The number of output arguments. +\end_layout + +\begin_layout Description +identity Either +\series bold +PyUFunc_One +\series default +, +\series bold +PyUFunc_Zero +\series default +, +\series bold +PyUFunc_None +\series default +. + This specifies what should be returned when an empty array is passed to + the reduce method of the ufunc. + +\end_layout + +\begin_layout Description +name A +\family typewriter +NULL +\family default +-terminated string providing the name of this ufunc (should be the Python + name it will be called). + +\end_layout + +\begin_layout Description +doc A documentation string for this ufunc (will be used in generating the + response to <ufunc_name>.__doc__). + Do not include the function signature or the name as this is generated + automatically. + +\end_layout + +\begin_layout Description +check_return Not presently used, but this integer value does get set in + the structure-member of similar name. + +\end_layout + +\end_deeper +\begin_layout Standard +The returned ufunc object is a callable Python object. + It should be placed in a (module) dictionary under the same name as was + used in the name argument to the ufunc-creation routine. + The following example is adapted from the umath module: +\begin_inset LatexCommand index +name "ufunc!adding new|)" + +\end_inset + + +\end_layout + +\begin_layout LyX-Code +static PyUFuncGenericFunction atan2_functions[]= +\backslash + +\newline + {PyUFunc_ff_f, PyUFunc_dd_d, +\newline + PyUFunc_gg_g, PyUFunc_OO_O_method}; +\newline +static + void* atan2_data[]= +\backslash + +\newline + {(void *)atan2f,(void *) atan2, +\newline + (void *)atan2l,(void *)"arctan2"}; +\newline +stati +c char atan2_signatures[]= +\backslash + +\newline + {NPY_FLOAT, NPY_FLOAT, NPY_FLOAT, +\newline + NPY_DOUBLE, NPY_DOUBLE, +\newline + NPY_DOUBLE +, NPY_LONGDOUBLE, +\newline + NPY_LONGDOUBLE, NPY_LONGDOUBLE +\newline + NPY_OBJECT, NPY_OBJECT, + +\newline + NPY_OBJECT}; +\newline +... +\newline +/* in the module initialization code */ +\newline +PyObject *f, *dict, + *module; +\newline +... +\newline +dict = PyModule_GetDict(module); +\newline +... +\newline +f = PyUFunc_FromFuncAndData(atan2_funct +ions, +\newline + atan2_data, atan2_signatures, 4, 2, 1, +\newline + PyUFunc_None, "arctan2", + +\newline + "a safe and correct arctan(x1/x2)", 0); +\newline +PyDict_SetItemString(dict, "arctan2" +, f); +\newline +Py_DECREF(f); +\newline +... +\end_layout + +\begin_layout Section +User-defined data-types +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "dtype!adding new|(" + +\end_inset + +NumPy comes with 21 builtin data-types. + While this covers a large majority of possible use cases, it is conceivable + that a user may have a need for an additional data-type. + There is some support for adding an additional data-type into the NumPy + system. + This additional data-type will behave much like a regular data-type except + ufuncs must have 1-d loops registered to handle it separately. + Also checking for whether or not other data-types can be cast +\begin_inset Quotes eld +\end_inset + +safely +\begin_inset Quotes erd +\end_inset + + to and from this new type or not will always return +\begin_inset Quotes eld +\end_inset + +can cast +\begin_inset Quotes erd +\end_inset + + unless you also register which types your new data-type can be cast to + and from. + Adding data-types is one of the less well-tested areas for NumPy 1.0, so + there may be bugs remaining in the approach. + Only add a new data-type if you can't do what you want to do using the + OBJECT or VOID data-types that are already available. + As an example of what I consider a useful application of the ability to + add data-types is the possibility of adding a data-type of arbitrary precision + floats to NumPy. + +\end_layout + +\begin_layout Subsection +Adding the new data-type +\end_layout + +\begin_layout Standard +To begin to make use of the new data-type, you need to first define a new + Python type to hold the scalars of your new data-type. + It should be acceptable to inherit from one of the array scalars if your + new type has a binary compatible layout. + This will allow your new data type to have the methods and attributes of + array scalars. + New data-types must have a fixed memory size (if you want to define a data-type + that needs a flexible representation, like a variable-precision number, + then use a pointer to the object as the data-type). + The memory layout of the object structure for the new Python type must + be PyObject_HEAD followed by the fixed-size memory needed for the data-type. + For example, a suitable structure for the new Python type is: +\end_layout + +\begin_layout LyX-Code +typedef struct { +\end_layout + +\begin_layout LyX-Code + PyObject_HEAD; +\end_layout + +\begin_layout LyX-Code + some_data_type obval; +\end_layout + +\begin_layout LyX-Code + /* the name can be whatever you want */ +\end_layout + +\begin_layout LyX-Code +} PySomeDataTypeObject; +\end_layout + +\begin_layout Standard +After you have defined a new Python type object, you must then define a + new PyArray_Descr structure whose typeobject member will contain a pointer + to the data-type you've just defined. + In addition, the required functions in the +\begin_inset Quotes eld +\end_inset + +.f +\begin_inset Quotes erd +\end_inset + + member must be defined: nonzero, copyswap, copyswapn, setitem, getitem, + and cast. + The more functions in the +\begin_inset Quotes eld +\end_inset + +.f +\begin_inset Quotes erd +\end_inset + + member you define, however, the more useful the new data-type will be. + It is very important to intialize unused functions to NULL. + This can be achieved using +\series bold +PyArray_InitArrFuncs +\series default +(f). +\end_layout + +\begin_layout Standard +Once a new PyArray_Descr structure is created and filled with the needed + information and useful functions you call +\series bold +PyArray_RegisterDataType +\series default +(new_descr). + The return value from this call is an integer providing you with a unique + type_number that specifies your data-type. + This type number should be stored and made available by your module so + that other modules can use it to recognize your data-type (the other mechanism + for finding a user-defined data-type number is to search based on the name + of the type-object associated with the data-type using +\series bold +PyArray_TypeNumFromName +\series default +). + +\end_layout + +\begin_layout Subsection +Registering a casting function +\end_layout + +\begin_layout Standard +You may want to allow builtin (and other user-defined) data-types to be + cast automatically to your data-type. + In order to make this possible, you must register a casting function with + the data-type you want to be able to cast from. + This requires writing low-level casting functions for each conversion you + want to support and then registering these functions with the data-type + descriptor. + A low-level casting function has the signature. + +\end_layout + +\begin_layout Description +castfunc ( +\family typewriter +void +\family default +) ( +\family typewriter +void* +\family default + from, +\family typewriter +void* +\family default + to, +\family typewriter +npy_intp +\family default + n, +\family typewriter +void* +\family default + fromarr, +\family typewriter +void* +\family default + toarr) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Cast +\family typewriter +n +\family default + elements +\family typewriter +from +\family default + one type +\family typewriter +to +\family default + another. + The data to cast from is in a contiguous, correctly-swapped and aligned + chunk of memory pointed to by from. + The buffer to cast to is also contiguous, correctly-swapped and aligned. + The fromarr and toarr arguments should only be used for flexible-element-sized + arrays (string, unicode, void). + +\end_layout + +\begin_layout Standard +An example castfunc is +\end_layout + +\begin_layout LyX-Code +static void +\end_layout + +\begin_layout LyX-Code +double_to_float(double *from, float* to, npy_intp n, +\newline + void* ig1, void* + ig2); +\newline +while (n--) { +\newline + (*to++) = (double) *(from++); +\newline +} +\end_layout + +\begin_layout Standard +This could then be registered to convert doubles to floats using the code +\end_layout + +\begin_layout LyX-Code +doub = PyArray_DescrFromType(NPY_DOUBLE); +\newline +PyArray_RegisterCastFunc(doub, + NPY_FLOAT, +\newline + (PyArray_VectorUnaryFunc *)double_to_float); +\newline +Py_DECREF(doub); +\end_layout + +\begin_layout Subsection +Registering coercion rules +\end_layout + +\begin_layout Standard +By default, all user-defined data-types are not presumed to be safely castable + to any builtin data-types. + In addition builtin data-types are not presumed to be safely castable to + user-defined data-types. + This situation limits the ability of user-defined data-types to participate + in the coercion system used by ufuncs and other times when automatic coercion + takes place in NumPy. + This can be changed by registering data-types as safely castable from a + particlar data-type object. + The function +\series bold +PyArray_RegisterCanCast +\series default + (from_descr, totype_number, scalarkind) should be used to specify that + the data-type object from_descr can be cast to the data-type with type + number totype_number. + If you are not trying to alter scalar coercion rules, then use +\series bold +PyArray_NOSCALAR +\series default + for the scalarkind argument. +\end_layout + +\begin_layout Standard +If you want to allow your new data-type to also be able to share in the + scalar coercion rules, then you need to specify the scalarkind function + in the data-type object's +\begin_inset Quotes eld +\end_inset + +.f +\begin_inset Quotes erd +\end_inset + + member to return the kind of scalar the new data-type should be seen as + (the value of the scalar is available to that function). + Then, you can register data-types that can be cast to separately for each + scalar kind that may be returned from your user-defined data-type. + If you don't register scalar coercion handling, then all of your user-defined + data-types will be seen as +\series bold +PyArray_NOSCALAR +\series default +. + +\end_layout + +\begin_layout Subsection +Registering a ufunc loop +\end_layout + +\begin_layout Standard +You may also want to register low-level ufunc loops for your data-type so + that an ndarray of your data-type can have math applied to it seamlessly. + Registering a new loop with exactly the same arg_types signature, silently + replaces any previously registered loops for that data-type. + +\end_layout + +\begin_layout Standard +Before you can register a 1-d loop for a ufunc, the ufunc must be previously + created. + Then you call +\series bold +PyUFunc_RegisterLoopForType +\series default +(...) with the information needed for the loop. + The return value of this function is +\family typewriter +0 +\family default + if the process was successful and +\family typewriter +-1 +\family default + with an error condition set if it was not successful. + +\end_layout + +\begin_layout Description +PyUFunc_RegisterLoopForType ( +\family typewriter +int +\family default +) ( +\family typewriter +PyUFuncObject* +\family default + ufunc, +\family typewriter +int +\family default + usertype, +\family typewriter +PyUFuncGenericFunction +\family default + function, +\family typewriter +int* +\family default + arg_types, +\family typewriter +void* +\family default + data) +\end_layout + +\begin_layout Description +ufunc The ufunc to attach this loop to. +\end_layout + +\begin_layout Description +usertype The user-defined type this loop should be indexed under. + This number must be a user-defined type or an error occurs. + +\end_layout + +\begin_layout Description +function The ufunc inner 1-d loop. + This function must have the signature as explained in Section +\begin_inset LatexCommand ref +reference "sec:Creating-a-new" + +\end_inset + +. +\end_layout + +\begin_layout Description +arg_types (optional) If given, this should contain an array of integers + of at least size ufunc.nargs containing the data-types expected by the loop + function. + The data will be copied into a NumPy-managed structure so the memory for + this argument should be deleted after calling this function. + If this is NULL, then it will be assumed that all data-types are of type + usertype. +\end_layout + +\begin_layout Description +data (optional) Specify any optional data needed by the function which will + be passed when the function is called. + +\begin_inset LatexCommand index +name "dtype!adding new|)" + +\end_inset + + +\end_layout + +\begin_layout Section +Subtyping the ndarray in C +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ndarray!subtyping|(" + +\end_inset + +One of the lesser-used features that has been lurking in Python since 2.2 + is the ability to sub-class types in C. + This facility is one of the important reasons for basing NumPy off of the + Numeric code-base which was already in C. + A sub-type in C allows much more flexibility with regards to memory management. + Sub-typing in C is not difficult even if you have only a rudimentary understand +ing of how to create new types for Python. + While it is easiest to sub-type from a single parent type, sub-typing from + multiple parent types is also possible. + Multiple inheritence in C is generally less useful than it is in Python + because a restriction on Python sub-types is that they have a binary compatible + memory layout. + Perhaps for this reason, it is somewhat easier to sub-type from a single + parent type. + +\end_layout + +\begin_layout Standard +All C-structures corresponding to Python objects must begin with PyObject_HEAD + (or PyObject_VAR_HEAD). + In the same way, any sub-type must have a C-structure that begins with + exactly the same memory layout as the parent type (or all of the parent + types in the case of multiple-inheritance). + The reason for this is that Python may attempt to access a member of the + sub-type structure as if it had the parent structure ( +\emph on +i.e. + +\emph default + it will cast a given pointer to a pointer to the parent structure and then + dereference one of it's members). + If the memory layouts are not compatible, then this attempt will cause + unpredictable behavior (eventually leading to a memory violation and program + crash). + +\end_layout + +\begin_layout Standard +One of the elements in PyObject_HEAD is a pointer to a type-object structure. + A new Python type is created by creating a new type-object structure and + populating it with functions and pointers to describe the desired behavior + of the type. + Typically, a new C-structure is also created to contain the instance-specific + information needed for each object of the type as well. + For example, &PyArray_Type is a pointer to the type-object table for the + ndarray while a PyArrayObject* variable is a pointer to a particular instance + of an ndarray (one of the members of the ndarray structure is, in turn, + a pointer to the type-object table &PyArray_Type). + Finally +\series bold +PyType_Ready +\series default +(<pointer_to_type_object>) must be called for every new Python type. + +\end_layout + +\begin_layout Subsection +Creating sub-types +\end_layout + +\begin_layout Standard +To create a sub-type, a similar proceedure must be followed except only + behaviors that are different require new entries in the type-object structure. + All other entires can be NULL and will be filled in by +\series bold +PyType_Ready +\series default + with appropriate functions from the parent type(s). + In particular, to create a sub-type in C follow these steps: +\end_layout + +\begin_layout Enumerate +If needed create a new C-structure to handle each instance of your type. + A typical C-structure would be +\end_layout + +\begin_deeper +\begin_layout LyX-Code +typedef _new_struct { +\newline + PyArrayObject base; +\newline + /* new things here */ +\newline +} NewArrayO +bject; +\end_layout + +\begin_layout Standard +Notice that the full PyArrayObject is used as the first entry in order to + ensure that the binary layout of instances of the new type is identical + to the PyArrayObject. + +\end_layout + +\end_deeper +\begin_layout Enumerate +Fill in a new Python type-object structure with pointers to new functions + that will over-ride the default behavior while leaving any function that + should remain the same unfilled (or NULL). + The tp_name element should be different. +\end_layout + +\begin_layout Enumerate +Fill in the tp_base member of the new type-object structure with a pointer + to the (main) parent type object. + For multiple-inheritance, also fill in the tp_bases member with a tuple + containing all of the parent objects in the order they should be used to + define inheritance. + Remember, all parent-types must have the same C-structure for multiple + inheritance to work properly. + +\end_layout + +\begin_layout Enumerate +Call +\series bold +PyType_Ready +\series default +(<pointer_to_new_type>). + If this function returns a negative number, a failure occurred and the + type is not initialized. + Otherwise, the type is ready to be used. + It is generally important to place a reference to the new type into the + module dictionary so it can be accessed from Python. + +\end_layout + +\begin_layout Standard +More information on creating sub-types in C can be learned by reading PEP + 253 (available at http://www.python.org/dev/peps/pep-0253). +\end_layout + +\begin_layout Subsection +Specific features of ndarray sub-typing +\end_layout + +\begin_layout Standard +Some special methods and attributes are used by arrays in order to facilitate + the interoperation of sub-types with the base ndarray type. + +\end_layout + +\begin_layout Subsubsection +The __array_finalize__ method +\end_layout + +\begin_layout Standard +Several array-creation functions of the ndarray allow specification of a + particular sub-type to be created. + This allows sub-types to be handled seamlessly in many routines. + When a sub-type is created in such a fashion, however, neither the __new__ + method nor the __init__ method gets called. + Instead, the sub-type is allocated and the appropriate instance-structure + members are filled in. + Finally, the +\series bold +__array_finalize__ +\series default + attribute is looked-up in the object dictionary. + If it is present and not None, then it can be either a CObject containing + a pointer to a +\series bold +PyArray_FinalizeFunc +\series default + or it can be a method taking a single argument (which could be None). + +\end_layout + +\begin_layout Standard +If the +\series bold +__array_finalize__ +\series default + attribute is a CObject, then the pointer must be a pointer to a function + with the signature: +\end_layout + +\begin_layout Description +\InsetSpace ~ + (int) (PyArrayObject *, PyObject *) +\end_layout + +\begin_layout Standard +The first argument is the newly created sub-type. + The second argument (if not NULL) is the +\begin_inset Quotes eld +\end_inset + +parent +\begin_inset Quotes erd +\end_inset + + array (if the array was created using slicing or some other operation where + a clearly-distinguishable parent is present). + This routine can do anything it wants to. + It should return a -1 on error and 0 otherwise. + +\end_layout + +\begin_layout Standard +If the +\series bold +__array_finalize__ +\series default + attribute is not None nor a CObject, then it must be a Python method that + takes the parent array as an argument (which could be None if there is + no parent), and returns nothing. + Errors in this method will be caught and handled. + +\end_layout + +\begin_layout Subsubsection +The __array_priority__ attribute +\end_layout + +\begin_layout Standard +This attribute allows simple but flexible determination of which sub-type + should be considered +\begin_inset Quotes eld +\end_inset + +primary +\begin_inset Quotes erd +\end_inset + + when an operation involving two or more sub-types arises. + In operations where different sub-types are being used, the sub-type with + the largest +\series bold +__array_priority__ +\series default + attribute will determine the sub-type of the output(s). + If two sub-types have the same +\series bold +__array_prioirty__ +\series default + then the sub-type of the first argument determines the output. + The default +\series bold +__array_priority__ +\series default + attribute returns a value of 0.0 for the base ndarray type and 1.0 for a + sub-type. + This attribute can also be defined by objects that are not sub-types of + the ndarray and can be used to determine which +\series bold +__array_wrap__ +\series default + method should be called for the return output. + +\end_layout + +\begin_layout Subsubsection +The __array_wrap__ method +\end_layout + +\begin_layout Standard +Any class or type can define this method which should take an ndarray argument + and return an instance of the type. + It can be seen as the opposite of the +\series bold +__array__ +\series default + method. + This method is used by the ufuncs (and other NumPy functions) to allow + other objects to pass through. + For Python >2.4, it can also be used to write a decorator that converts + a function that works only with ndarrays to one that works with any type + with +\series bold +__array__ +\series default + and +\series bold +__array_wrap__ +\series default + methods. + +\begin_inset LatexCommand index +name "ndarray!subtyping|)" + +\end_inset + + +\end_layout + +\begin_layout Chapter +Using Python as glue +\end_layout + +\begin_layout Quotation +There is no conversation more boring than the one where everybody agrees. +\end_layout + +\begin_layout Right Address +--- +\emph on +Michel de Montaigne +\end_layout + +\begin_layout Quotation +Duct tape is like the force. + It has a light side, and a dark side, and it holds the universe together. +\end_layout + +\begin_layout Right Address +--- +\emph on +Carl Zwanzig +\end_layout + +\begin_layout Standard +Many people like to say that Python is a fantastic glue language. + Hopefully, this Chapter will convince you that this is true. + The first adopters of Python for science were typically people who used + it to glue together large applicaton codes running on super-computers. + Not only was it much nicer to code in Python than in a shell script or + Perl, in addition, the ability to easily extend Python made it relatively + easy to create new classes and types specifically adapted to the problems + being solved. + From the interactions of these early contributors, Numeric emerged as an + array-like object that could be used to pass data between these applications. +\end_layout + +\begin_layout Standard +As Numeric has matured and developed into NumPy, people have been able to + write more code directly in NumPy. + Often this code is fast-enough for production use, but there are still + times that there is a need to access compiled code. + Either to get that last bit of efficiency out of the algorithm or to make + it easier to access widely-available codes written in C/C++ or Fortran. + +\end_layout + +\begin_layout Standard +This chapter will review many of the tools that are available for the purpose + of accessing code written in other compiled languages. + There are many resources available for learning to call other compiled + libraries from Python and the purpose of this Chapter is not to make you + an expert. + The main goal is to make you aware of some of the possibilities so that + you will know what to +\begin_inset Quotes eld +\end_inset + +Google +\begin_inset Quotes erd +\end_inset + + in order to learn more. + +\end_layout + +\begin_layout Standard +The http://www.scipy.org website also contains a great deal of useful information + about many of these tools. + For example, there is a nice description of using several of the tools + explained in this chapter at http://www.scipy.org/PerformancePython. + This link provides several ways to solve the same problem showing how to + use and connect with compiled code to get the best performance. + In the process you can get a taste for several of the approaches that will + be discussed in this chapter. + +\end_layout + +\begin_layout Section +Calling other compiled libraries from Python +\end_layout + +\begin_layout Standard +While Python is a great language and a pleasure to code in, its dynamic + nature results in overhead that can cause some code ( +\emph on +i.e. + +\emph default + raw computations inside of for loops) to be up 10-100 times slower than + equivalent code written in a static compiled language. + In addition, it can cause memory usage to be larger than necessary as temporary + arrays are created and destroyed during computation. + For many types of computing needs the extra slow-down and memory consumption + can often not be spared (at least for time- or memory-critical portions + of your code). + Therefore one of the most common needs is to call out from Python code + to a fast, machine-code routine (e.g. + compiled using C/C++ or Fortran). + The fact that this is relatively easy to do is a big reason why Python + is such an excellent high-level language for scientific and engineering + programming. + +\end_layout + +\begin_layout Standard +Their are two basic approaches to calling compiled code: writing an extension + module that is then imported to Python using the import command, or calling + a shared-library subroutine directly from Python using the ctypes module + (included in the standard distribution with Python 2.5). + The first method is the most common (but with the inclusion of ctypes into + Python 2.5 this status may change). +\end_layout + +\begin_layout Warning +Calling C-code from Python can result in Python crashes if you are not careful. + None of the approaches in this chapter are immune. + You have to know something about the way data is handled by both NumPy + and by the third-party library being used. + +\end_layout + +\begin_layout Section +Hand-generated wrappers +\end_layout + +\begin_layout Standard +Extension modules were discussed in Chapter +\begin_inset LatexCommand ref +reference "sec:Writing-an-extension" + +\end_inset + +. + The most basic way to interface with compiled code is to write an extension + module and construct a module method that calls the compiled code. + For improved readability, your method should take advantage of the PyArg_ParseT +uple call to convert between Python objects and C data-types. + For standard C data-types there is probably already a built-in converter. + For others you may need to write your own converter and use the +\begin_inset Quotes eld +\end_inset + +O& +\begin_inset Quotes erd +\end_inset + + format string which allows you to specify a function that will be used + to perform the conversion from the Python object to whatever C-structures + are needed. + +\end_layout + +\begin_layout Standard +Once the conversions to the appropriate C-structures and C data-types have + been performed, the next step in the wrapper is to call the underlying + function. + This is straightforward if the underlying function is in C or C++. + However, in order to call Fortran code you must be familiar with how Fortran + subroutines are called from C/C++ using your compiler and platform. + This can vary somewhat platforms and compilers (which is another reason + f2py makes life much simpler for interfacing Fortran code) but generally + involves underscore mangling of the name and the fact that all variables + are passed by reference (i.e. + all arguments are pointers). + +\end_layout + +\begin_layout Standard +The advantage of the hand-generated wrapper is that you have complete control + over how the C-library gets used and called which can lead to a lean and + tight interface with minimal over-head. + The disadvantage is that you have to write, debug, and maintain C-code, + although most of it can be adapted using the time-honored technique of + +\begin_inset Quotes eld +\end_inset + +cutting-pasting-and-modifying +\begin_inset Quotes erd +\end_inset + + from other extension modules. + Because, the procedure of calling out to additional C-code is fairly regimented +, code-generation procedures have been developed to make this process easier. + One of these code-generation techniques is distributed with NumPy and allows + easy integration with Fortran and (simple) C code. + This package, f2py, will be covered briefly in the next session. + +\end_layout + +\begin_layout Section +f2py +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "f2py|(" + +\end_inset + +F2py allows you to automatically construct an extension module that interfaces + to routines in Fortran 77/90/95 code. + It has the ability to parse Fortran 77/90/95 code and automatically generate + Python signatures for the subroutines it encounters, or you can guide how + the subroutine interfaces with Python by constructing an interface-defintion-fi +le (or modifying the f2py-produced one). + +\end_layout + +\begin_layout Subsection +Creating source for a basic extension module +\end_layout + +\begin_layout Standard +Probably the easiest way to introduce f2py is to offer a simple example. + Here is one of the subroutines contained in a file named add.f +\end_layout + +\begin_layout LyX-Code +C +\newline + SUBROUTINE ZADD(A,B,C,N) +\newline +C +\newline + DOUBLE COMPLEX A(*) +\newline + DOUBLE COMPLEX + B(*) +\newline + DOUBLE COMPLEX C(*) +\newline + INTEGER N +\newline + DO 20 J = 1, N +\newline + + C(J) = A(J)+B(J) +\newline + 20 CONTINUE +\newline + END +\end_layout + +\begin_layout Standard +This routine simply adds the elements in two contiguous arrays and places + the result in a third. + The memory for all three arrays must be provided by the calling routine. + A very basic interface to this routine can be automatically generated by + f2py: +\end_layout + +\begin_layout LyX-Code +f2py -m add add.f +\end_layout + +\begin_layout Standard +You should be able to run this command assuming your search-path is set-up + properly. + This command will produce an extension module named addmodule.c in the current + directory. + This extension module can now be compiled and used from Python just like + any other extension module. + +\end_layout + +\begin_layout Subsection +Creating a compiled extension module +\end_layout + +\begin_layout Standard +You can also get f2py to compile add.f and also compile its produced extension + module leaving only a shared-library extension file that can be imported + from Python: +\end_layout + +\begin_layout LyX-Code +f2py -c -m add add.f +\end_layout + +\begin_layout Standard +This command leaves a file named add.<ext> in the current directory (where + <ext> is the appropriate extension for a python extension module on your + platform --- so, pyd, +\emph on +etc. +\emph default +). + This module may then be imported from Python. + It will contain a method for each subroutin in add (zadd, cadd, dadd, sadd). + The docstring of each method contains information about how the module + method may be called: +\end_layout + +\begin_layout LyX-Code +>>> import add +\newline +>>> print add.zadd.__doc__ +\newline +zadd - Function signature: +\newline + zadd(a,b,c,n) +\newline + +Required arguments: +\newline + a : input rank-1 array('D') with bounds (*) +\newline + b : input + rank-1 array('D') with bounds (*) +\newline + c : input rank-1 array('D') with bounds + (*) +\newline + n : input int +\end_layout + +\begin_layout Subsection +Improving the basic interface +\end_layout + +\begin_layout Standard +The default interface is a very literal translation of the fortran code + into Python. + The Fortran array arguments must now be NumPy arrays and the integer argument + should be an integer. + The interface will attempt to convert all arguments to their required types + (and shapes) and issue an error if unsuccessful. + However, because it knows nothing about the semantics of the arguments + (such that C is an output and n should really match the array sizes), it + is possible to abuse this function in ways that can cause Python to crash. + For example +\end_layout + +\begin_layout LyX-Code +>>> add.zadd([1,2,3],[1,2],[3,4],1000) +\end_layout + +\begin_layout Standard +will cause a program crash on most systems. + Under the covers, the lists are being converted to proper arrays but then + the underlying add loop is told to cycle way beyond the borders of the + allocated memory. + +\end_layout + +\begin_layout Standard +In order to improve the interface, directives should be provided. + This is accomplished by constructing an interface definition file. + It is usually best to start from the interface file that f2py can produce + (where it gets its default behavior from). + To get f2py to generate the interface file use the -h option: +\end_layout + +\begin_layout LyX-Code +f2py -h add.pyf -m add add.f +\end_layout + +\begin_layout Standard +This command leaves the file add.pyf in the current directory. + The section of this file corresponding to zadd is: +\end_layout + +\begin_layout LyX-Code +subroutine zadd(a,b,c,n) ! in :add:add.f +\newline + double complex dimension(*) :: + a +\newline + double complex dimension(*) :: b +\newline + double complex dimension(*) :: + c +\newline + integer :: n +\newline +end subroutine zadd +\end_layout + +\begin_layout Standard +By placing intent directives and checking code, the interface can be cleaned + up quite a bit until the Python module method is both easier to use and + more robust. + +\end_layout + +\begin_layout LyX-Code +subroutine zadd(a,b,c,n) ! in :add:add.f +\newline + double complex dimension(n) :: + a +\newline + double complex dimension(n) :: b +\newline + double complex intent(out),dimension(n +) :: c +\newline + integer intent(hide),depend(a) :: n=len(a) +\newline +end subroutine zadd +\end_layout + +\begin_layout Standard +The intent directive, intent(out) is used to tell f2py that +\family typewriter +c +\family default + is an output variable and should be created by the interface before being + passed to the underlying code. + The intent(hide) directive tells f2py to not allow the user to specify + the variable, +\family typewriter +n +\family default +, but instead to get it from the size of +\family typewriter +a +\family default +. + The depend( +\family typewriter +a +\family default +) directive is necessary to tell f2py that the value of n depends on the + input a (so that it won't try to create the variable n until the variable + a is created). + +\end_layout + +\begin_layout Standard +The new interface has docstring: +\end_layout + +\begin_layout LyX-Code +>>> print add.zadd.__doc__ +\newline +zadd - Function signature: +\newline + c = zadd(a,b) +\newline +Required + arguments: +\newline + a : input rank-1 array('D') with bounds (n) +\newline + b : input rank-1 + array('D') with bounds (n) +\newline +Return objects: +\newline + c : rank-1 array('D') with + bounds (n) +\end_layout + +\begin_layout Standard +Now, the function can be called in a much more robust way: +\end_layout + +\begin_layout LyX-Code +>>> add.zadd([1,2,3],[4,5,6]) +\newline +array([ 5.+0.j, 7.+0.j, 9.+0.j]) +\end_layout + +\begin_layout Standard +Notice the automatic conversion to the correct format that occurred. + +\end_layout + +\begin_layout Subsection +Inserting directives in Fortran source +\end_layout + +\begin_layout Standard +The nice interface can also be generated automatically by placing the variable + directives as special comments in the original fortran code. + Thus, if I modify the source code to contain: +\end_layout + +\begin_layout LyX-Code +C +\newline + SUBROUTINE ZADD(A,B,C,N) +\newline +C +\newline +CF2PY INTENT(OUT) :: C +\newline +CF2PY INTENT(HIDE) + :: N +\newline +CF2PY DOUBLE COMPLEX :: A(N) +\newline +CF2PY DOUBLE COMPLEX :: B(N) +\newline +CF2PY DOUBLE + COMPLEX :: C(N) +\newline + DOUBLE COMPLEX A(*) +\newline + DOUBLE COMPLEX B(*) +\newline + + DOUBLE COMPLEX C(*) +\newline + INTEGER N +\newline + DO 20 J = 1, N +\newline + C(J) = A(J) + + B(J) +\newline + 20 CONTINUE +\newline + END +\end_layout + +\begin_layout Standard +Then, I can compile the extension module using +\end_layout + +\begin_layout LyX-Code +f2py -c -m add add.f +\end_layout + +\begin_layout Standard +The resulting signature for the function add.zadd is exactly the same one + that was created previously. + If the original source code had contained A(N) instead of A(*) and so forth + with B and C, then I could obtain (nearly) the same interface simply by + placing the INTENT(OUT) :: C comment line in the source code. + The only difference is that N would be an optional input that would default + to the length of A. + +\end_layout + +\begin_layout Subsection +A filtering example +\end_layout + +\begin_layout Standard +For comparison with the other methods to be discussed. + Here is another example of a function that filters a two-dimensional array + of double precision floating-point numbers using a fixed averaging filter. + The advantage of using Fortran to index into multi-dimensional arrays should + be clear from this example. + +\end_layout + +\begin_layout LyX-Code + SUBROUTINE DFILTER2D(A,B,M,N) +\newline +C +\newline + DOUBLE PRECISION A(M,N) +\newline + DOUBLE + PRECISION B(M,N) +\newline + INTEGER N, M +\newline +CF2PY INTENT(OUT) :: B +\newline +CF2PY INTENT(HIDE) + :: N +\newline +CF2PY INTENT(HIDE) :: M +\newline + DO 20 I = 2,M-1 +\newline + DO 40 J=2,N-1 +\newline + + B(I,J) = A(I,J) + +\newline + $ (A(I-1,J)+A(I+1,J) + +\newline + + $ A(I,J-1)+A(I,J+1) )*0.5D0 + +\newline + $ (A(I-1,J-1) + A(I-1,J+1 +) + +\newline + $ A(I+1,J-1) + A(I+1,J+1))*0.25D0 +\newline + 40 CONTINUE +\newline + 20 + CONTINUE +\newline + END +\end_layout + +\begin_layout Standard +This code can be compiled and linked into an extension module named filter + using +\end_layout + +\begin_layout LyX-Code +f2py -c -m filter filter.f +\end_layout + +\begin_layout Standard +This will produce an extension module named filter.so in the current directory + with a method named dfilter2d that returns a filtered version of the input. + +\end_layout + +\begin_layout Subsection +Calling f2py from Python +\end_layout + +\begin_layout Standard +The f2py program is written in Python and can be run from inside your module. + This provides a facility that is somewhat similar to the use of weave.ext_tools + described below. + An example of the final interface executed using Python code is +\end_layout + +\begin_layout LyX-Code +import numpy.f2py as f2py +\end_layout + +\begin_layout LyX-Code +fid = open('add.f') +\end_layout + +\begin_layout LyX-Code +source = fid.read() +\end_layout + +\begin_layout LyX-Code +fid.close() +\end_layout + +\begin_layout LyX-Code +f2py.compile(source, modulename='add') +\end_layout + +\begin_layout LyX-Code +import add +\end_layout + +\begin_layout Standard +The source string can be any valid Fortran code. + If you want to save the extension-module source code then a suitable file-name + can be provided by the source_fn keyword to the compile function. + +\end_layout + +\begin_layout Subsection +Automatic extension module generation +\end_layout + +\begin_layout Standard +If you want to distribute your f2py extension module, then you only need + to include the .pyf file and the Fortran code. + The distutils extensions in NumPy allow you to define an extension module + entirely in terms of this interface file. + A valid setup.py file allowing distribution of the add.f module (as part + of the package f2py_examples so that it would be loaded as f2py_examples.add) + is +\end_layout + +\begin_layout LyX-Code +def configuration(parent_package='', top_path=None) +\newline + from numpy.distutils.misc_u +til import Configuration +\newline + config = Configuration('f2py_examples',parent_packag +e, top_path) +\newline + config.add_extension('add', sources=['add.pyf','add.f']) +\newline + + return config +\newline + +\newline +if __name__ == '__main__': +\newline + from numpy.distutils.core import + setup +\newline + setup(**configuration(top_path='').todict()) +\end_layout + +\begin_layout Standard +Installation of the new package is easy using +\end_layout + +\begin_layout LyX-Code +python setup.py install +\end_layout + +\begin_layout Standard +assuming you have the proper permissions to write to the main site-packages + directory for the version of Python you are using. + For the resulting package to work, you need to create a file named __init__.py + (in the same directory as add.pyf). + Notice the extension module is defined entirely in terms of the +\begin_inset Quotes eld +\end_inset + +add.pyf +\begin_inset Quotes erd +\end_inset + + and +\begin_inset Quotes eld +\end_inset + +add.f +\begin_inset Quotes erd +\end_inset + + files. + The conversion of the .pyf file to a .c file is handled by numpy.disutils. + +\end_layout + +\begin_layout Subsection +Conclusion +\end_layout + +\begin_layout Standard +The interface definition file (.pyf) is how you can fine-tune the interface + between Python and Fortran. + There is decent documentation for f2py found in the numpy/f2py/docs directory + where-ever NumPy is installed on your system (usually under site-packages). + There is also more information on using f2py (including how to use it to + wrap C codes) at http://www.scipy.org/Cookbook under the +\begin_inset Quotes eld +\end_inset + +Using NumPy with Other Languages +\begin_inset Quotes erd +\end_inset + + heading. + +\end_layout + +\begin_layout Standard +The f2py method of linking compiled code is currently the most sophisticated + and integrated approach. + It allows clean separation of Python with compiled code while still allowing + for separate distribution of the extension module. + The only draw-back is that it requires the existence of a Fortran compiler + in order for a user to install the code. + However, with the existence of the free-compilers g77, gfortran, and g95, + as well as high-quality commerical compilers, this restriction is not particula +rly onerous. + In my opinion, Fortran is still the easiest way to write fast and clear + code for scientific computing. + It handles complex numbers, and multi-dimensional indexing in the most + straightforward way. + Be aware, however, that some Fortran compilers will not be able to optimize + code as well as good hand-written C-code. + +\begin_inset LatexCommand index +name "f2py|)" + +\end_inset + + +\end_layout + +\begin_layout Section +weave +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "weave|(" + +\end_inset + +Weave is a scipy package that can be used to automate the process of extending + Python with C/C++ code. + It can be used to speed up evaluation of an array expression that would + otherwise create temporary variables, to directly +\begin_inset Quotes eld +\end_inset + +inline +\begin_inset Quotes erd +\end_inset + + C/C++ code into Python, or to create a fully-named extension module. + You must either install scipy or get the weave package separately and install + it using the standard python setup.py install. + You must also have a C/C++-compiler installed and useable by Python distutils + in order to use weave. +\end_layout + +\begin_layout Standard +Somewhat dated, but still useful documentation for weave can be found at + the link http://www.scipy/Weave. + There are also many examples found in the examples directory which is installed + under the weave directory in the place where weave is installed on your + system. +\end_layout + +\begin_layout Subsection +Speed up code involving arrays (also see scipy.numexpr) +\end_layout + +\begin_layout Standard +This is the easiest way to use weave and requires minimal changes to your + Python code. + It involves placing quotes around the expression of interest and calling + weave.blitz. + Weave will parse the code and generate C++ code using Blitz C++ arrays. + It will then compile the code and catalog the shared library so that the + next time this exact string is asked for (and the array types are the same), + the already-compiled shared library will be loaded and used. + Because Blitz makes extensive use of C++ templating, it can take a long + time to compile the first time. + After that, however, the code should evaluate more quickly than the equivalent + NumPy expression. + This is especially true if your array sizes are large and the expression + would require NumPy to create several temporaries. + Only expressions involving basic arithmetic operations and basic array + slicing can be converted to Blitz C++ code. + +\end_layout + +\begin_layout Standard +For example, consider the expression +\end_layout + +\begin_layout LyX-Code +d = 4*a + 5*a*b + 6*b*c +\end_layout + +\begin_layout Standard +where a, b, and c are all arrays of the same type and shape. + When the data-type is double-precision and the size is 1000x1000, this + expression takes about 0.5 seconds to compute on an 1.1Ghz AMD Athlon machine. + When this expression is executed instead using blitz: +\end_layout + +\begin_layout LyX-Code +d = empty(a.shape, 'd'); weave.blitz(expr) +\end_layout + +\begin_layout Standard +execution time is only about 0.20 seconds (about 0.14 seconds spent in weave + and the rest in allocating space for d). + Thus, we've sped up the code by a factor of 2 using only a simnple command + (weave.blitz). + Your mileage may vary, but factors of 2-8 speed-ups are possible with this + very simple technique. + +\end_layout + +\begin_layout Standard +If you are interested in using weave in this way, then you should also look + at scipy.numexpr which is another similar way to speed up expressions by + eliminating the need for temporary variables. + Using numexpr does not require a C/C++ compiler. + +\end_layout + +\begin_layout Subsection +Inline C-code +\end_layout + +\begin_layout Standard +Probably the most widely-used method of employing weave is to +\begin_inset Quotes eld +\end_inset + +in-line +\begin_inset Quotes erd +\end_inset + + C/C++ code into Python in order to speed up a time-critical section of + Python code. + In this method of using weave, you define a string containing useful C-code + and then pass it to the function +\series bold +weave.inline +\series default +( +\family typewriter +code_string +\family default +, +\family typewriter +variables +\family default +), where code_string is a string of valid C/C++ code and variables is a + list of variables that should be passed in from Python. + The C/C++ code should refer to the variables with the same names as they + are defined with in Python. + If weave.line should return anything the the special value return_val should + be set to whatever object should be returned. + The following example shows how to use weave on basic Python objects +\end_layout + +\begin_layout LyX-Code +code = r""" +\newline +int i; +\newline +py::tuple results(2); +\newline +for (i=0; i<a.length(); i++) { +\newline + + a[i] = i; +\newline +} +\newline +results[0] = 3.0; +\newline +results[1] = 4.0; +\newline +return_val = results; +\newline +""" + +\newline +a = [None]*10 +\newline +res = weave.inline(code,['a']) +\end_layout + +\begin_layout Standard +The C++ code shown in the code string uses the name 'a' to refer to the + Python list that is passed in. + Because the Python List is a mutable type, the elements of the list itself + are modified by the C++ code. + A set of C++ classes are used to access Python objects using simple syntax. + +\end_layout + +\begin_layout Standard +The main advantage of using C-code, however, is to speed up processing on + an array of data. + Accessing a NumPy array in C++ code using weave, depends on what kind of + type converter is chosen in going from NumPy arrays to C++ code. + The default converter creates 5 variables for the C-code for every NumPy + array passed in to weave.inline. + The following table shows these variables which can all be used in the + C++ code. + The table assumes that +\family typewriter +myvar +\family default + is the name of the array in Python with data-type <dtype> (i.e. + float64, float32, int8, etc.) +\end_layout + +\begin_layout Standard +\align center +\begin_inset Tabular +<lyxtabular version="3" rows="6" columns="3"> +<features> +<column alignment="center" valignment="top" leftline="true" width="0"> +<column alignment="center" valignment="top" leftline="true" width="0"> +<column alignment="center" valignment="top" leftline="true" rightline="true" width="0"> +<row topline="true" bottomline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Variable +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Type +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Contents +\end_layout + +\end_inset +</cell> +</row> +<row topline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +myvar +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +<dtype>* +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Pointer to the first element of the array +\end_layout + +\end_inset +</cell> +</row> +<row topline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Nmyvar +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +npy_intp* +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +A pointer to the dimensions array +\end_layout + +\end_inset +</cell> +</row> +<row topline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Smyvar +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +npy_intp* +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +A pointer to the strides array +\end_layout + +\end_inset +</cell> +</row> +<row topline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +Dmyvar +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +int +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +The number of dimensions +\end_layout + +\end_inset +</cell> +</row> +<row topline="true" bottomline="true"> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +myvar_array +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +PyArrayObject* +\end_layout + +\end_inset +</cell> +<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> +\begin_inset Text + +\begin_layout Standard +The entire structure for the array +\end_layout + +\end_inset +</cell> +</row> +</lyxtabular> + +\end_inset + + +\end_layout + +\begin_layout Standard +The in-lined code can contain references to any of these variables as well + as to the standard macros MYVAR1(i), MYVAR2(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. +\end_layout + +\begin_layout LyX-Code +int i,j; +\newline +for(i=1;i<Na[0]-1;i++) { +\newline + for(j=1;j<Na[1]-1;j++) { +\newline + B2(i,j) + = A2(i,j) + (A2(i-1,j) + +\newline + A2(i+1,j)+A2(i,j-1) +\newline + + + A2(i,j+1))*0.5 +\newline + + (A2(i-1,j-1) +\newline + + + A2(i-1,j+1) +\newline + + A2(i+1,j-1) +\newline + + A2(i+1,j+1))*0.25 +\newline + + } +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout Standard +The above code doesn't have any error checking and so could fail with a + Python crash if, +\family typewriter +a +\family default + had the wrong number of dimensions, or +\family typewriter +b +\family default + did not have the same shape as +\family typewriter +a +\family default +. + However, it could be placed inside a standard Python function with the + necessary error checking to produce a robust but fast subroutine. +\end_layout + +\begin_layout Standard +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 statments, etc. + you can pass this code in as a string using the keyword support_code: +\family typewriter +weave.inline(code, variables, support_code=support) +\family default +. + 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_dir +s, libraries, and/or runtime_library_dirs which point to the appropriate + libraries and directories. + +\end_layout + +\begin_layout Subsection +Simplify creation of an extension module +\end_layout + +\begin_layout Standard +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. + +\end_layout + +\begin_layout Standard +The approach is to: +\end_layout + +\begin_layout Enumerate +construct a extension module object using ext_tools.ext_module( +\family typewriter +module_name +\family default +); +\end_layout + +\begin_layout Enumerate +create function objects using ext_tools.ext_function( +\family typewriter +func_name +\family default +, +\family typewriter +code +\family default +, +\family typewriter +variables +\family default +); +\end_layout + +\begin_layout Enumerate +(optional) add support code to the function using the .customize.add_support_code( +\family typewriter +support_code +\family default +) method of the function object; +\end_layout + +\begin_layout Enumerate +add the functions to the extension module object using the .add_function( +\family typewriter +func +\family default +) method; +\end_layout + +\begin_layout Enumerate +when all the functions are added, compile the extension with its .compile() + method. +\end_layout + +\begin_layout Standard +Several examples are available in the examples directory where weave is + installed on your system. + Look particularly at ramp2.py, increment_example.py and fibonacii.py +\end_layout + +\begin_layout Subsection +Conclusion +\end_layout + +\begin_layout Standard +Weave is a useful tool for quickly routines in C/C++ and linking them into + Python. + It's caching-mechanism allows for on-the-fly compilation which makes it + particularly attractive for in-house code. + Because of the requirement that the user have a C++-compiler, it can be + difficult (but not impossible) to distribute a package that uses weave + to other users who don't have a compiler installed. + Of course, weave could be used to construct an extension module which is + then distributed in the normal way +\emph on +( +\emph default +using a setup.py file). + While you can use weave to build larger extension modules with many methods, + creating methods with a variable-number of arguments is not possible. + Thus, for a more sophisticated module, you will still probably want a Python-la +yer that calls the weave-produced extension. + +\begin_inset LatexCommand index +name "weave|)" + +\end_inset + + +\end_layout + +\begin_layout Section +Pyrex +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "pyrex|(" + +\end_inset + +Pyrex is a way to write C-extension modules using Python-like syntax. + It is an interesting way to generate extension modules that is growing + in popularity, particularly among people who have rusty or non-existent + C-skills. + It does require the user to write the +\begin_inset Quotes eld +\end_inset + +interface +\begin_inset Quotes erd +\end_inset + + code and so is more time-consuming than SWIG or f2py if you are trying + to interface to a large library of code. + However, if you are writing an extension module that will include quite + a bit of your own algorithmic code, as well, then Pyrex is a good match. + A big weakness perhaps is the inability to easily and quickly access the + elements of a multidimensional array. + +\end_layout + +\begin_layout Standard +Notice that Pyrex is an extension-module generator only. + Unlike weave or f2py, it includes no automatic facility for compiling and + linking the extension module (which must be done in the usual fashion). + It does provide a modified distutils class called build_ext which lets + you build an extension module from a .pyx source. + Thus, you could write in a setup.py file +\end_layout + +\begin_layout LyX-Code +from Pyrex.Distutils import build_ext +\newline +from distutils.extension import Extension +\newline +from + distutils.core import setup +\newline + +\newline +import numpy +\newline +py_ext = Extension('mine', ['mine.pyx'], +\newline + + include_dirs=[numpy.get_include()]) +\newline + +\newline +setup(name='mine', description='Nothi +ng', +\newline + ext_modules=[pyx_ext], +\newline + cmdclass = {'build_ext':build_ext}) +\end_layout + +\begin_layout Standard +Adding the NumPy include directory is, of course, only necessary if you + are using NumPy arrays in the extension module (which is what I assume + you are using Pyrex for). + The distutils extensions in NumPy also include support for automatically + producing the extension-module and linking it from a +\family typewriter +.pyx +\family default + file. + It works so that if the user does not have Pyrex installed, then it looks + for a file with the same file-name but a +\family typewriter +.c +\family default + extension which it then uses instead of trying to produce the +\family typewriter +.c +\family default + file again. + +\end_layout + +\begin_layout Standard +Pyrex does not natively understand NumPy arrays. + However, it is not difficult to include information that lets Pyrex deal + with them usefully. + In fact, the numpy.random.mtrand module was written using Pyrex so an example + of Pyrex usage is already included in the NumPy source distribution. + That experience led to the creation of a standard c_numpy.pxd file that + you can use to simplify interacting with NumPy array objects in a Pyrex-written + extension. + The file may not be complete (it wasn't at the time of this writing). + If you have additions you'd like to contribute, please send them. + The file is located in the .../site-packages/numpy/doc/pyrex directory where + you have Python installed. + There is also an example in that directory of using Pyrex to construct + a simple extension module. + It shows that Pyrex looks a lot like Python but also contains some new + syntax that is necessary in order to get C-like speed. + +\end_layout + +\begin_layout Standard +If you just use Pyrex to compile a standard Python module, then you will + get a C-extension module that runs either as fast or, possibly, more slowly + than the equivalent Python module. + Speed increases are possible only when you use cdef to statically define + C variables and use a special construct to create for loops: +\end_layout + +\begin_layout LyX-Code +cdef int i +\newline +for i from start <= i < stop +\end_layout + +\begin_layout Standard +Let's look at two examples we've seen before to see how they might be implemente +d using Pyrex. + These examples were compiled into extension modules using Pyrex-0.9.3.1. +\end_layout + +\begin_layout Subsection +Pyrex-add +\end_layout + +\begin_layout Standard +Here is part of a Pyrex-file I named add.pyx which implements the add functions + we previously implemented using f2py: +\end_layout + +\begin_layout LyX-Code +cimport c_numpy +\newline +from c_numpy cimport import_array, ndarray, npy_intp, npy_cdouble +, +\backslash + +\newline + npy_cfloat, NPY_DOUBLE, NPY_CDOUBLE, NPY_FLOAT, +\backslash + +\newline + NPY_CFLOAT +\newline + +\newline +#We need to initialize NumPy +\newline +import_array() +\newline + +\newline +def zadd(object + ao, object bo): +\newline + cdef ndarray c, a, b +\newline + cdef npy_intp i +\newline + a = c_numpy.PyArra +y_ContiguousFromAny(ao, +\newline + NPY_CDOUBLE, 1, 1) +\newline + b = c_numpy.PyArr +ay_ContiguousFromAny(bo, +\newline + NPY_CDOUBLE, 1, 1) +\newline + c = c_numpy.PyAr +ray_SimpleNew(a.nd, a.dimensions, +\newline + a.descr.type_num) +\newline + for i + from 0 <= i < a.dimensions[0]: +\newline + (<npy_cdouble *>c.data)[i].real = +\backslash + +\newline + (<npy_cdouble *>a.data)[i].real + +\backslash + +\newline + (<npy_cdouble *>b.data)[i].real +\newline + (<npy_cdouble *>c.data)[i].imag + = +\backslash + +\newline + (<npy_cdouble *>a.data)[i].imag + +\backslash + +\newline + (<npy_cdouble *>b.data)[i].imag +\newline + return c +\end_layout + +\begin_layout Standard +This module shows use of the +\family typewriter +cimport +\family default + statement to load the definitions from the c_numpy.pxd file. + As shown, both versions of the import statement are supported. + It also shows use of the NumPy C-API to construct NumPy arrays from arbitrary + input objects. + The array c is created using PyArray_SimpleNew. + Then the c-array is filled by addition. + Casting to a particiular data-type is accomplished using <cast *>. + Pointers are de-referenced with bracket notation and members of structures + are accessed using '.' notation even if the object is techinically a pointer + to a structure. + The use of the special for loop construct ensures that the underlying code + will have a similar C-loop so the addition calculation will proceed quickly. + Notice that we have not checked for NULL after calling to the C-API --- + a cardinal sin when writing C-code. + For routines that return Python objects, Pyrex inserts the checks for NULL + into the C-code for you and returns with failure if need be. + There is also a way to get Pyrex to automatically check for exceptions + when you call functions that don't return Python objects. + See the documentation of Pyrex for details. + +\end_layout + +\begin_layout Subsection +Pyrex-filter +\end_layout + +\begin_layout Standard +The two-dimensional example we created using weave is a bit uglierto implement + in Pyrex because two-dimensional indexing using Pyrex is not as simple. + But, it is straightforward (and possibly faster because of pre-computed + indices). + Here is the Pyrex-file I named image.pyx. +\end_layout + +\begin_layout LyX-Code +cimport c_numpy +\newline +from c_numpy cimport import_array, ndarray, npy_intp, +\backslash + +\newline + NPY_DOUBLE, NPY_CDOUBLE, +\backslash + +\newline + NPY_FLOAT, NPY_CFLOAT, NPY_ALIGNED +\backslash + +\newline + +\newline +#We need to initialize NumPy +\newline +import_array() +\newline +def filter(object ao): +\newline + cdef + ndarray a, b +\newline + cdef npy_intp i, j, M, N, oS +\newline + cdef npy_intp r,rm1,rp1,c,cm1,c +p1 +\newline + cdef double value +\newline + # Require an ALIGNED array +\newline + # (but not necessarily + contiguous) +\newline + # We will use strides to access the elements. +\newline + a = c_numpy.PyAr +ray_FROMANY(ao, NPY_DOUBLE, +\backslash + +\newline + 2, 2, NPY_ALIGNED) +\newline + b = c_numpy.PyArray_SimpleNew(a.nd,a.dimensio +ns, +\backslash + +\newline + a.descr.type_num) +\newline + M = a.dimensions[0] +\newline + + N = a.dimensions[1] +\newline + S0 = a.strides[0] +\newline + S1 = a.strides[1] +\newline + for i + from 1 <= i < M-1: +\newline + r = i*S0 +\newline + rm1 = r-S0 +\newline + rp1 = r+S0 +\newline + + oS = i*N +\newline + for j from 1 <= j < N-1: +\newline + c = j*S1 +\newline + + cm1 = c-S1 +\newline + cp1 = c+S1 +\newline + (<double *>b.data)[oS+j] + = +\backslash + +\newline + (<double *>(a.data+r+c))[0] + +\backslash + +\newline + ((<double *>(a.data+rm1+c))[0] + +\backslash + +\newline + (<double *>(a.data+rp1+c))[0] + +\backslash + +\newline + (<double *>(a.data+r+cm1))[0] + +\backslash + +\newline + (<double *>(a.data+r+cp1))[0])*0.5 + +\backslash + +\newline + ((<double *>(a.data+rm1+cm1))[0] + +\backslash + +\newline + (<double *>(a.data+rp1+cm1))[0] + +\backslash + +\newline + (<double *>(a.data+rp1+cp1))[0] + +\backslash + +\newline + (<double *>(a.data+rm1+cp1))[0])*0.25 +\newline + return b +\end_layout + +\begin_layout Standard +This 2-d averaging filter runs quickly because the loop is in C and the + pointer computations are done only as needed. + However, it is not particularly easy to understand what is happening. + A 2-d image, +\family typewriter +in +\family default +, can be filtered using this code very quickly using +\end_layout + +\begin_layout LyX-Code +import image +\end_layout + +\begin_layout LyX-Code +out = image.filter(in) +\end_layout + +\begin_layout Subsection +Conclusion +\end_layout + +\begin_layout Standard +There are several disadvantages of using Pyrex: +\end_layout + +\begin_layout Enumerate +The syntax for Pyrex can get a bit bulky, and it can be confusing at first + to understand what kind of objects you are getting and how to interface + them with C-like constructs. + +\end_layout + +\begin_layout Enumerate +Inappropriate Pyrex syntax or incorrect calls to C-code or type-mismatches + can result in failures such as +\end_layout + +\begin_deeper +\begin_layout Enumerate +Pyrex failing to generate the extension module source code, +\end_layout + +\begin_layout Enumerate +Compiler failure while generating the extension module binary due to incorrect + C syntax, +\end_layout + +\begin_layout Enumerate +Python failure when trying to use the module. + +\end_layout + +\end_deeper +\begin_layout Enumerate +It is easy to lose a clean separation between Python and C which makes re-using + your C-code for other non-Python-related projects more difficult. +\end_layout + +\begin_layout Enumerate +Multi-dimensional arrays are +\begin_inset Quotes eld +\end_inset + +bulky +\begin_inset Quotes erd +\end_inset + + to index (appropriate macros may be able to fix this). + +\end_layout + +\begin_layout Enumerate +The C-code generated by Prex is hard to read and modify (and typically compiles + with annoying but harmless warnings). + +\end_layout + +\begin_layout Standard +Writing a good Pyrex extension module still takes a bit of effort because + not only does it require (a little) familiarity with C, but also with Pyrex's + brand of Python-mixed-with C. + One big advantage of Pyrex-generated extension modules is that they are + easy to distribute using distutils. + In summary, Pyrex is a very capable tool for either gluing C-code or generating + an extension module quickly and should not be over-looked. + It is especially useful for people that can't or won't write C-code or + Fortran code. + But, if you are already able to write simple subroutines in C or Fortran, + then I would use one of the other approaches such as f2py (for Fortran), + ctypes (for C shared-libraries), or weave (for inline C-code). +\begin_inset LatexCommand index +name "pyrex|)" + +\end_inset + + +\end_layout + +\begin_layout Section +ctypes +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ctypes|(" + +\end_inset + +Ctypes is a python extension module (downloaded separately for Python <2.5 + and included with Python 2.5) that allows you to call an arbitrary function + in a shared library directly from Python. + This approach allows you to interface with C-code directly from Python. + This opens up an enormous number of libraries for use from Python. + The drawback, however, is that coding mistakes can lead to ugly program + crashes very easily (just as can happen in C) because there is little type + or bounds checking done on the parameters. + This is especially true when array data is passed in as a pointer to a + raw memory location. + The responsibility is then on you that the subroutine will not access memory + outside the actual array area. + But, if you don't mind living a little dangerously ctypes can be an effective + tool for quickly taking advantage of a large shared library (or writing + extended functionality in your own shared library). +\end_layout + +\begin_layout Standard +Because the ctypes approach exposes a raw interface to the compiled code + it is not always tolerant of user mistakes. + Robust use of the ctypes module typically involves an additional layer + of Python code in order to check the data types and array bounds of objects + passed to the underlying subroutine. + This additional layer of checking (not to mention the conversion from ctypes + objects to C-data-types that ctypes itself performs), will make the interface + slower than a hand-written extension-module interface. + However, this overhead should be neglible if the C-routine being called + is doing any significant amount of work. + If you are a great Python programmer with weak C-skills, ctypes is an easy + way to write a useful interface to a (shared) library of compiled code. + +\end_layout + +\begin_layout Standard +To use c-types you must +\end_layout + +\begin_layout Enumerate +Have a shared library. +\end_layout + +\begin_layout Enumerate +Load the shared library. +\end_layout + +\begin_layout Enumerate +Convert the python objects to ctypes-understood arguments. +\end_layout + +\begin_layout Enumerate +Call the function from the library with the ctypes arguments. +\end_layout + +\begin_layout Subsection +Having a shared library +\end_layout + +\begin_layout Standard +There are several requirements for a shared library that can be used with + c-types that are platform specific. + This guide assumes you have some familiarity with making a shared library + on your system (or simply have a shared library available to you). + Items to remember are: +\end_layout + +\begin_layout Itemize +A shared library must be compiled in a special way ( +\emph on +e.g. + +\emph default + using the -shared flag with gcc). +\end_layout + +\begin_layout Itemize +On some platforms ( +\emph on +e.g. + +\emph default + Windows) , a shared library requires a .def file that specifies the functions + to be exported. + For example a mylib.def file might contain. + +\end_layout + +\begin_deeper +\begin_layout LyX-Code +LIBRARY mylib.dll +\newline +EXPORTS +\newline +cool_function1 +\newline +cool_function2 +\end_layout + +\begin_layout Standard +Alternatively, you may be able to use the storage-class specifier __declspec(dll +export) in the C-definition of the function to avoid the need for this .def + file. + +\end_layout + +\end_deeper +\begin_layout Standard +There is no standard way in Python distutils to create a standard shared + library (an extension module is a +\begin_inset Quotes eld +\end_inset + +special +\begin_inset Quotes erd +\end_inset + + shared library Python understands) in a cross-platform manner. + Thus, a big disadvantage of ctypes at the time of writing this book is + that it is difficult to distribute in a cross-platform manner a Python + extension that uses c-types and includes your own code which should be + compiled as a shared library on the users system. + +\end_layout + +\begin_layout Subsection +Loading the shared library +\end_layout + +\begin_layout Standard +A simple, but robust way to load the shared library is to get the absolute + path name and load it using the cdll object of ctypes. + +\end_layout + +\begin_layout LyX-Code +lib = ctypes.cdll[<full_path_name>] +\end_layout + +\begin_layout Standard +However, on Windows accessing an attribute of the cdll method will load + the first DLL by that name found in the current directory or on the PATH. + Loading the absolute path name requires a little finesse for cross-platform + work since the extension of shared libraries varies. + There is a +\family typewriter +ctypes.util.find_library +\family default + utility available that can simplify the process of finding the library + to load but it is not foolproof. + Complicating matters, different platforms have different default extensions + used by shared libraries (e.g. + .dll -- Windows, .so -- Linux, .dylib -- Mac OS X). + This must also be taken into account if you are using c-types to wrap code + that needs to work on several platforms. + +\end_layout + +\begin_layout Standard +NumPy provides a convenience function called +\series bold +ctypeslib.load_library +\series default +(name, path). + This function takes the name of the shared library (including any prefix + like 'lib' but excluding the extension) and a path where the shared library + can be located. + It returns a ctypes library object or raises an OSError if the library + cannot be found or raises an ImportError if the ctypes module is not available. + (Windows users: the ctypes library object loaded using +\series bold +load_library +\series default + is always loaded assuming cdecl calling convention. + See the ctypes documentation under ctypes.windll and/or ctypes.oledll for + ways to load libraries under other calling conventions). + +\end_layout + +\begin_layout Standard +The functions in the shared library are available as attributes of the ctypes + library object (returned from +\series bold +ctypeslib.load_library +\series default +) or as items using lib['func_name'] syntax. + The latter method for retrieving a function name is particularly useful + if the function name contains characters that are not allowable in Python + variable names. + +\end_layout + +\begin_layout Subsection +Converting arguments +\end_layout + +\begin_layout Standard +Python ints/longs, strings, and unicode objects are automatically converted + as needed to equivalent c-types arguments The None object is also converted + automatically to a NULL pointer. + All other Python objects must be converted to ctypes-specific types. + There are two ways around this restriction that allow c-types to integrate + with other objects. + +\end_layout + +\begin_layout Enumerate +Don't set the argtypes attribute of the function object and define an _as_parame +ter_ method for the object you want to pass in. + The _as_parameter_ method must return a Python int which will be passed + directly to the function. + +\end_layout + +\begin_layout Enumerate +Set the argtypes attribute to a list whose entries contain objects with + a classmethod named from_param that knows how to convert your object to + an object that ctypes can understand (an int/long, string, unicode, or + object with the _as_parameter_ attribute). + +\end_layout + +\begin_layout Standard +NumPy uses both methods with a preference for the second method because + it can be safer. + The ctypes attribute of the ndarray returns an object that has an _as_parameter +_ attribute which returns an integer representing the address of the ndarray + to which it is associated. + As a result, one can pass this ctypes attribute object directly to a function + expecting a pointer to the data in your ndarray. + The caller must be sure that the ndarray object is of the correct type, + shape, and has the correct flags set or risk nasty crashes if the data-pointer + to inappropriate arrays are passsed in. + +\end_layout + +\begin_layout Standard +To implement the second method, NumPy provides the class-factory function + +\series bold +ndpointer +\series default + in the +\series bold +ctypeslib +\series default + module. + This class-factory function produces an appropriate class that can be placed + in an argtypes attribute entry of a ctypes function. + The class will contain a from_param method which ctypes will use to convert + any ndarray passed in to the function to a ctypes-recognized object. + In the process, the conversion will perform checking on any properties + of the ndarray that were specified by the user in the call to ndpointer. + Aspects of the ndarray that can be checked include the data-type, the number-of +-dimensions, the shape, and/or the state of the flags on any array passed. + The return value of the from_param method is the ctypes attribute of the + array which (because it contains the _as_parameter_ attribute pointing + to the array data area) can be used by ctypes directly. + +\end_layout + +\begin_layout Standard +The ctypes attribute of an ndarray is also endowed with additional attributes + that may be convenient when passing additional information about the array + into a ctypes function. + The attributes +\series bold +data +\series default +, +\series bold +shape +\series default +, and +\series bold +strides +\series default + can provide c-types compatible types corresponding to the data-area, the + shape, and the strides of the array. + The data attribute reutrns a +\family typewriter +c_void_p +\family default + representing a pointer to the data area. + The shape and strides attributes each return an array of ctypes integers + (or None representing a NULL pointer, if a 0-d array). + The base ctype of the array is a ctype integer of the same size as a pointer + on the platform. + There are also methods data_as(<ctype>), shape_as(<base ctype>), and strides_as +(<base ctype>). + These return the data as a ctype object of your choice and the shape/strides + arrays using an underlying base type of your choice. + For convenience, the +\series bold +ctypeslib +\series default + module also contains +\series bold +c_intp +\series default + as a ctypes integer data-type whose size is the same as the size of +\family typewriter +c_void_p +\family default + on the platform (it's value is None if ctypes is not installed). + +\end_layout + +\begin_layout Subsection +Calling the function +\end_layout + +\begin_layout Standard +The function is accessed as an attribute of or an item from the loaded shared-li +brary. + Thus, if +\begin_inset Quotes eld +\end_inset + +./mylib.so +\begin_inset Quotes erd +\end_inset + + has a function named +\begin_inset Quotes eld +\end_inset + +cool_function1 +\begin_inset Quotes erd +\end_inset + +, I could access this function either as +\end_layout + +\begin_layout LyX-Code +lib = numpy.ctypeslib.load_library('mylib','.') +\newline +func1 = lib.cool_function1 # + or equivalently +\newline +func1 = lib['cool_function1'] +\end_layout + +\begin_layout Standard +In ctypes, the return-value of a function is set to be 'int' by default. + This behavior can be changed by setting the restype attribute of the function. + Use None for the restype if the function has no return value ('void'): +\end_layout + +\begin_layout LyX-Code +func1.restype = None +\end_layout + +\begin_layout Standard +As previously discussed, you can also set the argtypes attribute of the + function in order to have ctypes check the types of the input arguments + when the function is called. + Use the ndpointer factory function to generate a ready-made class for data-type +, shape, and flags checking on your new function. + The ndpointer function has the signature +\end_layout + +\begin_layout Description +ndpointer (dtype=None, ndim=None, shape=None, flags=None) +\end_layout + +\begin_layout Description +\InsetSpace ~ + Keyword arguments with the value +\family typewriter +None +\family default + are not checked. + Specifying a keyword enforces checking of that aspect of the ndarray on + conversion to a ctypes-compatible object. + The dtype keyword can be any object understood as a data-type object. + The ndim keyword should be an integer, and the shape keyword should be + an integer or a sequence of integers. + The flags keyword specifies the minimal flags that are required on any + array passed in. + This can be specified as a string of comma separated requirements, an integer + indicating the requirement bits OR'd together, or a flags object returned + from the flags attribute of an array with the necessary requirements. + +\end_layout + +\begin_layout Standard +Using an ndpointer class in the argtypes method can make it significantly + safer to call a C-function using ctypes and the data-area of an ndarray. + You may still want to wrap the function in an additional Python wrapper + to make it user-friendly (hiding some obvious arguments and making some + arguments output arguments). + In this process, the +\series bold +requires +\series default + function in NumPy may be useful to return the right kind of array from + a given input. + +\end_layout + +\begin_layout Subsection +Complete example +\end_layout + +\begin_layout Standard +In this example, I will show how the addition function and the filter function + implemented previously using the other approaches can be implemented using + ctypes. + First, the C-code which implements the algorithms contains the functions + zadd, dadd, sadd, cadd, and dfilter2d. + The zadd function is +\end_layout + +\begin_layout LyX-Code +/* Add arrays of contiguous data */ +\newline +typedef struct {double real; double imag;} + cdouble; +\newline +typedef struct {float real; float imag;} cfloat; +\newline +void zadd(cdouble + *a, cdouble *b, cdouble *c, long n) +\newline +{ +\newline + while (n--) { +\newline + c->real = + a->real + b->real; +\newline + c->imag = a->imag + b->imag; +\newline + a++; b++; + c++; +\newline + } +\newline +} +\end_layout + +\begin_layout Standard +with similar code for cadd, dadd, and sadd that handles complex float, double, + and float data-types, respectively: +\end_layout + +\begin_layout LyX-Code +void cadd(cfloat *a, cfloat *b, cfloat *c, long n) +\newline +{ +\newline + while (n--) { +\newline + + c->real = a->real + b->real; +\newline + c->imag = a->imag + + b->imag; +\newline + a++; b++; c++; +\newline + } +\newline +} +\newline +void dadd(double + *a, double *b, double *c, long n) +\newline +{ +\newline + while (n--) { +\newline + + *c++ = *a++ + *b++; +\newline + } +\newline +} +\newline +void sadd(float *a, float *b, float + *c, long n) +\newline +{ +\newline + while (n--) { +\newline + *c++ = *a++ + *b++; +\newline + + } +\newline +} +\end_layout + +\begin_layout Standard +The code.c file also contains the function dfilter2d: +\end_layout + +\begin_layout LyX-Code +/* Assumes b is contiguous and +\newline + a has strides that are multiples of sizeof(dou +ble) +\newline +*/ +\newline +void +\newline +dfilter2d(double *a, double *b, int *astrides, int *dims) +\newline +{ +\newline + + int i, j, M, N, S0, S1; +\newline + int r, c, rm1, rp1, cp1, cm1; +\newline + +\newline + M = dims[0]; + N = dims[1]; +\newline + S0 = astrides[0]/sizeof(double); +\newline + S1=astrides[1]/sizeof(doub +le); +\newline + for (i=1; i<M-1; i++) { +\newline + r = i*S0; rp1 = r+S0; rm1 = r-S0; +\newline + + for (j=1; j<N-1; j++) { +\newline + c = j*S1; cp1 = j+S1; cm1 = j-S1; +\newline + + b[i*N+j] = a[r+c] + +\backslash + +\newline + (a[rp1+c] + a[rm1+c] + +\backslash + +\newline + a[r+cp1] + a[r+cm1])*0.5 + +\backslash + +\newline + (a[rp1+cp1] + a[rp1+cm1] + +\backslash + +\newline + a[rm1+cp1] + a[rm1+cp1])*0.25; +\newline + } +\newline + } +\newline +} +\end_layout + +\begin_layout Standard +A possible advantage this code has over the Fortran-equivalent code is that + it takes arbitrarily strided (i.e. + non-contiguous arrays) and may also run faster depending on the optimization + capability of your compiler. + But, it is a obviously more complicated than the simple code in filter.f. + This code must be compiled into a shared library. + On my Linux system this is accomplished using +\end_layout + +\begin_layout LyX-Code +gcc -o code.so -shared code.c +\end_layout + +\begin_layout Standard +Which creates a shared_library named code.so in the current directory. + On Windows don't forget to either add __declspec(dllexport) in front of + void on the line preceeding each function definition, or write a code.def + file that lists the names of the functions to be exported. + +\end_layout + +\begin_layout Standard +A suitable Python interface to this shared library should be constructed. + To do this create a file named interface.py with the following lines at + the top: +\end_layout + +\begin_layout LyX-Code +__all__ = ['add', 'filter2d'] +\newline + +\newline +import numpy as N +\newline +import os +\newline + +\newline +_path = os.path.dirname('__ +file__') +\newline +lib = N.ctypeslib.load_library('code', _path) +\newline +_typedict = {'zadd' : + complex, 'sadd' : N.single, +\newline + 'cadd' : N.csingle, 'dadd' : float} +\newline +for + name in _typedict.keys(): +\newline + val = getattr(lib, name) +\newline + val.restype = None +\newline + + _type = _typedict[name] +\newline + val.argtypes = [N.ctypeslib.ndpointer(_type, + +\newline + flags='aligned, contiguous'), +\newline + + N.ctypeslib.ndpointer(_type, +\newline + flags='aligned, contiguous'), +\newline + + N.ctypeslib.ndpointer(_type, +\newline + flags='alig +ned, contiguous,' +\backslash + +\newline + 'writeable'), +\newline + N.ctypeslib.c_intp] +\end_layout + +\begin_layout Standard +This code loads the shared library named code.<ext> located in the same path + as this file. + It then adds a return type of void to the functions contained in the library. + It also adds argument checking to the functions in the library so that + ndarrays can be passed as the first three arguments along with an integer + (large enough to hold a pointer on the platform) as the fourth argument. + +\end_layout + +\begin_layout Standard +Setting up the filtering function is similar and allows the filtering function + to be called with ndarray arguments as the first two arguments and with + pointers to integers (large enough to handle the strides and shape of an + ndarray) as the last two arguments. + +\end_layout + +\begin_layout LyX-Code +lib.dfilter2d.restype=None +\newline +lib.dfilter2d.argtypes = [N.ctypeslib.ndpointer(float, + ndim=2, +\newline + flags='aligned'), +\newline + + N.ctypeslib.ndpointer(float, ndim=2, +\newline + + flags='aligned, contiguous,' +\backslash + +\newline + 'writeable'), +\newline + + ctypes.POINTER(N.ctypeslib.c_intp), +\newline + ctypes.POINTER +(N.ctypeslib.c_intp)] +\end_layout + +\begin_layout Standard +Next, define a simple selection function that chooses which addition function + to call in the shared library based on the data-type: +\end_layout + +\begin_layout LyX-Code +def select(dtype): +\newline + if dtype.char in ['?bBhHf']: +\newline + return lib.sadd, + single +\newline + elif dtype.char in ['F']: +\newline + return lib.cadd, csingle +\newline + elif + dtype.char in ['DG']: +\newline + return lib.zadd, complex +\newline + else: +\newline + return + lib.dadd, float +\newline + return func, ntype +\end_layout + +\begin_layout Standard +Finally, the two functions to be exported by the interface can be written + simply as +\end_layout + +\begin_layout LyX-Code +def add(a, b): +\newline + requires = ['CONTIGUOUS', 'ALIGNED'] +\newline + a = N.asanyarray(a) +\newline + + func, dtype = select(a.dtype) +\newline + a = N.require(a, dtype, requires) +\newline + + b = N.require(b, dtype, requires) +\newline + c = N.empty_like(a) +\newline + func(a,b,c,a.size) +\newline + + return c +\end_layout + +\begin_layout Standard +and +\end_layout + +\begin_layout LyX-Code +def filter2d(a): +\newline + a = N.require(a, float, ['ALIGNED']) +\newline + b = N.zeros_like(a) +\newline + + lib.dfilter2d(a, b, a.ctypes.strides, a.ctypes.shape) +\newline + return b +\end_layout + +\begin_layout Subsection +Conclusion +\end_layout + +\begin_layout Standard +Using ctypes is a powerful way to connect Python with arbitrary C-code. + It's advantages for extending Python include +\end_layout + +\begin_layout Itemize +clean separation of C-code from Python code +\end_layout + +\begin_deeper +\begin_layout Itemize +no need to learn a new syntax except Python and C +\end_layout + +\begin_layout Itemize +allows re-use of C-code +\end_layout + +\begin_layout Itemize +functionality in shared libraries written for other purposes can be obtained + with a simple Python wrapper and search for the library. + +\end_layout + +\end_deeper +\begin_layout Itemize +easy integration with NumPy through the ctypes attribute +\end_layout + +\begin_layout Itemize +full argument checking with the ndpointer class factory +\end_layout + +\begin_layout Standard +It's disadvantages include +\end_layout + +\begin_layout Itemize +It is difficult to distribute an extension module made using ctypes because + of a lack of support for building shared libraries in distutils (but I + suspect this will change in time). + +\end_layout + +\begin_layout Itemize +You must have shared-libraries of your code (no static libraries). + +\end_layout + +\begin_layout Itemize +Very little support for C++ code and it's different library-calling conventions. + You will probably need a C-wrapper around C++ code to use with ctypes (or + just use Boost.Python instead). +\end_layout + +\begin_layout Standard +Because of the difficulty in distributing an extension module made using + ctypes, f2py is still the easiest way to extend Python for package creation. + However, ctypes is a close second and will probably be growing in popularity + now that it is part of the Python distribution. + This should bring more features to ctypes that should eliminate the difficulty + in extending Python and distributing the extension using ctypes. + +\begin_inset LatexCommand index +name "ctypes|)" + +\end_inset + + +\end_layout + +\begin_layout Section +Additional tools you may find useful +\end_layout + +\begin_layout Standard +These tools have been found useful by others using Python and so are included + here. + They are discussed separately because I see them as either older ways to + do things more modernly handled by f2py, weave, Pyrex, or ctypes (SWIG, + PyFort, PyInline) or because I don't know much about them (SIP, Boost, + Instant). + I have not added links to these methods because my experience is that you + can find the most relevant link faster using Google or some other search + engine, and any links provided here would be quickly dated. + Do not assume that just because it is included in this list, I don't think + the package deserves your attention. + I'm including information about these packages because many people have + found them useful and I'd like to give you as many options as possible + for tackling the problem of easily integrating your code. + +\end_layout + +\begin_layout Subsection +SWIG +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "swig" + +\end_inset + +Simplified Wrapper and Interface Generator (SWIG) is an old and fairly stable + method for wrapping C/C++-libraries to a large variety of other languages. + It does not specifically understand NumPy arrays but can be made useable + with NumPy through the use of typemaps. + There are some sample typemaps in the numpy/doc/swig directory under numpy.i + along with an example module that makes use of them. + SWIG excels at wrapping large C/C++ libraries because it can (almost) parse + their headers and auto-produce an interface. + Technically, you need to generate a +\family typewriter +.i +\family default + file that defines the interface. + Often, however, this +\family typewriter +.i +\family default + file can be parts of the header itself. + The interface usually needs a bit of tweaking to be very useful. + This ability to parse C/C++ headers and auto-generate the interface still + makes SWIG a useful approach to adding functionalilty from C/C++ into Python, + despite the other methods that have emerged that are more targeted to Python. + SWIG can actually target extensions for several languages, but the typemaps + usually have to be language-specific. + Nonetheless, with modifications to the Python-specific typemaps, SWIG can + be used to interface a library with other languages such as Perl, Tcl, + and Ruby. + +\end_layout + +\begin_layout Standard +My experience with SWIG has been generally positive in that it is relatively + easy to use and quite powerful. + I used to use it quite often before becoming more proficient at writing + C-extensions. + However, I struggled writing custom interfaces with SWIG because it must + be done using the concept of typemaps which are not Python specific and + are written in a C-like syntax. + Therefore, I tend to prefer other gluing strategies and would only attempt + to use SWIG to wrap a very-large C/C++ library. + Nonetheless, there are others who use SWIG quite happily. + +\end_layout + +\begin_layout Subsection +SIP +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "SIP" + +\end_inset + +SIP is another tool for wrapping C/C++ libraries that is Python specific + and appears to have very good support for C++. + Riverbank Computing developed SIP in order to create Python bindings to + the QT library. + An interface file must be written to generate the binding, but the interface + file looks a lot like a C/C++ header file. + While SIP is not a full C++ parser, it understands quite a bit of C++ syntax + as well as its own special directives that allow modification of how the + Python binding is accomplished. + It also allows the user to define mappings between Python types and C/C++ + structrues and classes. + +\end_layout + +\begin_layout Subsection +Boost Python +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "Boost.Python" + +\end_inset + +Boost is a repository of C++ libraries and Boost.Python is one of those libraries + which provides a concise interface for binding C++ classes and functions + to Python. + The amazing part of the Boost.Python approach is that it works entirely + in pure C++ without introducing a new syntax. + Many users of C++ report that Boost.Python makes it possible to combine + the best of both worlds in a seamless fashion. + I have not used Boost.Python because I am not a big user of C++ and using + Boost to wrap simple C-subroutines is usually over-kill. + It's primary purpose is to make C++ classes available in Python. + So, if you have a set of C++ classes that need to be integrated cleanly + into Python, consider learning about and using Boost.Python. +\end_layout + +\begin_layout Subsection +Instant +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "Instant" + +\end_inset + +This is a relatively new package (called pyinstant at sourceforge) that + builds on top of SWIG to make it easy to inline C and C++ code in Python + very much like weave. + However, Instant builds extension modules on the fly with specific module + names and specific method names. + In this repsect it is more more like f2py in its behavior. + The extension modules are built on-the fly (as long as the SWIG is installed). + They can then be imported. + Here is an example of using Instant with NumPy arrays (adapted from the + test2 included in the Instant distribution): +\end_layout + +\begin_layout LyX-Code +code=""" +\end_layout + +\begin_layout LyX-Code +PyObject* add(PyObject* a_, PyObject* b_){ +\end_layout + +\begin_layout LyX-Code + /* +\end_layout + +\begin_layout LyX-Code + various checks +\end_layout + +\begin_layout LyX-Code + */ +\end_layout + +\begin_layout LyX-Code + PyArrayObject* a=(PyArrayObject*) a_; +\end_layout + +\begin_layout LyX-Code + PyArrayObject* b=(PyArrayObject*) b_; +\end_layout + +\begin_layout LyX-Code + int n = a->dimensions[0]; +\end_layout + +\begin_layout LyX-Code + int dims[1]; +\end_layout + +\begin_layout LyX-Code + dims[0] = n; +\end_layout + +\begin_layout LyX-Code + PyArrayObject* ret; +\end_layout + +\begin_layout LyX-Code + ret = (PyArrayObject*) PyArray_FromDims(1, dims, NPY_DOUBLE); +\end_layout + +\begin_layout LyX-Code + int i; +\end_layout + +\begin_layout LyX-Code + char *aj=a->data; +\end_layout + +\begin_layout LyX-Code + char *bj=b->data; +\end_layout + +\begin_layout LyX-Code + double *retj = (double *)ret->data; +\end_layout + +\begin_layout LyX-Code + for (i=0; i < n; i++) { +\end_layout + +\begin_layout LyX-Code + *retj++ = *((double *)aj) + *((double *)bj); +\end_layout + +\begin_layout LyX-Code + aj += a->strides[0]; +\end_layout + +\begin_layout LyX-Code + bj += b->strides[0]; +\end_layout + +\begin_layout LyX-Code + } +\end_layout + +\begin_layout LyX-Code +return (PyObject *)ret; +\end_layout + +\begin_layout LyX-Code +} +\end_layout + +\begin_layout LyX-Code +""" +\end_layout + +\begin_layout LyX-Code +import Instant, numpy +\end_layout + +\begin_layout LyX-Code +ext = Instant.Instant() +\end_layout + +\begin_layout LyX-Code +ext.create_extension(code=s, headers=["numpy/arrayobject.h"], + include_dirs=[numpy.get_include()], + init_code='import_array();', module="test2b_ext +") +\end_layout + +\begin_layout LyX-Code +import test2b_ext +\end_layout + +\begin_layout LyX-Code +a = numpy.arange(1000) +\end_layout + +\begin_layout LyX-Code +b = numpy.arange(1000) +\end_layout + +\begin_layout LyX-Code +d = test2b_ext.add(a,b) +\end_layout + +\begin_layout Standard +Except perhaps for the dependence on SWIG, Instant is a straightforward + utility for writing extension modules. + +\end_layout + +\begin_layout Subsection +PyInline +\end_layout + +\begin_layout Standard +This is a much older module that allows automatic building of extension + modules so that C-code can be included with Python code. + It's latest release (version 0.03) was in 2001, and it appears that it is + not being updated. + +\end_layout + +\begin_layout Subsection +PyFort +\end_layout + +\begin_layout Standard +PyFort is a nice tool for wrapping Fortran and Fortran-like C-code into + Python with support for Numeric arrays. + It was written by Paul Dubois, a distinguished computer scientist and the + very first maintainer of Numeric (now retired). + It is worth mentioning in the hopes that somebody will update PyFort to + work with NumPy arrays as well which now support either Fortran or C-style + contiguous arrays. + +\end_layout + +\begin_layout Chapter +Code Explanations +\end_layout + +\begin_layout Quotation +Fanaticism consists of redoubling your efforts when you have forgotten your + aim. +\end_layout + +\begin_layout Right Address +--- +\emph on +George Santayana +\end_layout + +\begin_layout Quotation +An authority is a person who can tell you more about something than you + really care to know. +\end_layout + +\begin_layout Right Address +--- +\emph on +Unknown +\end_layout + +\begin_layout Standard +This Chapter attempts to explain the logic behind some of the new pieces + of code. + The purpose behind these explanations is to enable somebody to be able + to understand the ideas behind the implementation somewhat more easily + than just staring at the code. + Perhaps in this way, the algorithms can be improved on, borrowed from, + and/or optimized. + +\end_layout + +\begin_layout Section +Memory model +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ndarray!memory model" + +\end_inset + +One fundamental aspect of the ndarray is that an array is seen as a +\begin_inset Quotes eld +\end_inset + +chunk +\begin_inset Quotes erd +\end_inset + + of memory starting at some location. + The interpretation of this memory depends on the stride information. + For each dimension in an +\begin_inset Formula $N$ +\end_inset + +-dimensional array, an integer (stride) dictates how many bytes must be + skipped to get to the next element in that dimension. + Unless you have a single-segment array, this stride information must be + consulted when traversing through an array. + It is not difficult to write code that accepts strides, you just have to + use (char *) pointers because strides are in units of bytes. + Keep in mind also that strides do not have to be unit-multiples of the + element size. + Also, remember that if the number of dimensions of the array is 0 (sometimes + called a rank-0 array), then the strides and dimensions variables are NULL. + +\end_layout + +\begin_layout Standard +Besides the structural information contained in the strides and dimensions + members of the PyArrayObject, the flags contain important information about + how the data may be accessed. + In particular, the NPY_ALIGNED flag is set when the memory is on a suitable + boundary according to the data-type array. + Even if you have a contiguous chunk of memory, you cannot just assume it + is safe to dereference a data-type-specific pointer to an element. + Only if the NPY_ALIGNED flag is set is this a safe operation (on some platforms + it will work but on others, like Solaris, it will cause a bus error). + The NPY_WRITEABLE should also be ensured if you plan on writing to the + memory area of the array. + It is also possible to obtain a pointer to an unwriteable memory area. + Sometimes, writing to the memory area when the NPY_WRITEABLE flag is not + set will just be rude. + Other times it can cause program crashes ( +\emph on +e.g. + +\emph default + a data-area that is a read-only memory-mapped file). +\end_layout + +\begin_layout Section +Data-type encapsulation +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "dtype" + +\end_inset + +The data-type is an important abstraction of the ndarray. + Operations will look to the data-type to provide the key functionality + that is needed to operate on the array. + This functionality is provided in the list of function pointers pointed + to by the 'f' member of the PyArray_Descr structure. + In this way, the number of data-types can be extended simply by providing + a PyArray_Descr structure with suitable function pointers in the 'f' member. + For built-in types there are some optimizations that by-pass this mechanism, + but the point of the data-type abstraction is to allow new data-types to + be added. +\end_layout + +\begin_layout Standard +One of the built-in data-types, the void data-type allows for arbitrary + records containing 1 or more fields as elements of the array. + A field is simply another data-type object along with an offset into the + current record. + In order to support arbitrarily nested fields, several recursive implementation +s of data-type access are implemented for the void type. + A common idiom is to cycle through the elements of the dictionary and perform + a specific operation based on the data-type object stored at the given + offset. + These offsets can be arbitrary numbers. + Therefore, the possibility of encountering mis-aligned data must be recognized + and taken into account if necessary. + +\end_layout + +\begin_layout Section +N-D Iterators +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "array iterator" + +\end_inset + +A very common operation in much of NumPy code is the need to iterate over + all the elements of a general, strided, N-dimensional array. + This operation of a general-purpose N-dimensional loop is abstracted in + the notion of an iterator object. + To write an N-dimensional loop, you only have to create an iterator object + from an ndarray, work with the dataptr member of the iterator object structure + and call the macro PyArray_ITER_NEXT(it) on the iterator object to move + to the next element. + The +\begin_inset Quotes eld +\end_inset + +next +\begin_inset Quotes erd +\end_inset + + element is always in C-contiguous order. + The macro works by first special casing the C-contiguous, 1-d, and 2-d + cases which work very simply. + +\end_layout + +\begin_layout Standard +For the general case, the iteration works by keeping track of a list of + coordinate counters in the iterator object. + At each iteration, the last coordinate counter is increased (starting from + 0). + If this counter is smaller then one less than the size of the array in + that dimension (a pre-computed and stored value), then the counter is increased + and the dataptr member is increased by the strides in that dimension and + the macro ends. + If the end of a dimension is reached, the counter for the last dimension + is reset to zero and the dataptr is moved back to the beginning of that + dimension by subtracting the strides value times one less than the number + of elements in that dimension (this is also pre-computed and stored in + the backstrides member of the iterator object). + In this case, the macro does not end, but a local dimension counter is + decremented so that the next-to-last dimension replaces the role that the + last dimension played and the previously-described tests are executed again + on the next-to-last dimension. + In this way, the dataptr is adjusted appropriately for arbitrary striding. + +\end_layout + +\begin_layout Standard +The coordinates member of the PyArrayIterObject structure maintains the + current N-d counter unless the underlying array is C-contiguous in which + case the coordinate counting is by-passed. + The index member of the PyArrayIterObject keeps track of the current flat + index of the iterator. + It is updated by the PyArray_ITER_NEXT macro. + +\end_layout + +\begin_layout Section +Broadcasting +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "broadcasting" + +\end_inset + +In Numeric, broadcasting was implemented in several lines of code buried + deep in ufuncobject.c. + In NumPy, the notion of broadcasting has been abstracted so that it can + be performed in multiple places. + Broadcasting is handled by the function PyArray_Broadcast. + This function requires a PyArrayMultiIterObject (or something that is a + binary equivalent) to be passed in. + The PyArrayMultiIterObject keeps track of the broadcasted number of dimensions + and size in each dimension along with the total size of the broadcasted + result. + It also keeps track of the number of arrays being broadcast and a pointer + to an iterator for each of the arrays being broadcasted. + +\end_layout + +\begin_layout Standard +The PyArray_Broadcast function takes the iterators that have already been + defined and uses them to determine the broadcast shape in each dimension + (to create the iterators at the same time that broadcasting occurs then + use the PyMuliIter_New function). + Then, the iterators are adjusted so that each iterator thinks it is iterating + over an array with the broadcasted size. + This is done by adjusting the iterators number of dimensions, and the shape + in each dimension. + This works because the iterator strides are also adjusted. + Broadcasting only adjusts (or adds) length-1 dimensions. + For these dimensions, the strides variable is simply set to 0 so that the + data-pointer for the iterator over that array doesn't move as the broadcasting + operation operates over the extended dimension. + +\end_layout + +\begin_layout Standard +Broadcasting was always implemented in Numeric using 0-valued strides for + the extended dimensions. + It is done in exactly the same way in NumPy. + The big difference is that now the array of strides is kept track of in + a PyArrayIterObject, the iterators involved in a broadcasted result are + kept track of in a PyArrayMultiIterObject, and the PyArray_BroadCast call + implements the broad-casting rules. + +\end_layout + +\begin_layout Section +Array Scalars +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "array scalars" + +\end_inset + +The array scalars offer a hierarchy of Python types that allow a one-to-one + correspondence between the data-type stored in an array and the Python-type + that is returned when an element is extracted from the array. + An exception to this rule was made with object arrays. + Object arrays are heterogeneous collections of arbitrary Python objects. + When you select an item from an object array, you get back the original + Python object (and not an object array scalar which does exist but is rarely + used for practical purposes). +\end_layout + +\begin_layout Standard +The array scalars also offer the same methods and attributes as arrays with + the intent that the same code can be used to support arbitrary dimensions + (including 0-dimensions). + The array scalars are read-only (immutable) with the exception of the void + scalar which can also be written to so that record-array field setting + works more naturally (a[0]['f1'] = +\family typewriter +value +\family default +). +\end_layout + +\begin_layout Section +Advanced ( +\begin_inset Quotes eld +\end_inset + +Fancy +\begin_inset Quotes erd +\end_inset + +) Indexing +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "indexing" + +\end_inset + +The implementation of advanced indexing represents some of the most difficult + code to write and explain. + In fact, there are two implementations of advanced indexing. + The first works only with 1-d arrays and is implemented to handle expressions + involving a.flat[obj]. + The second is general-purpose that works for arrays of +\begin_inset Quotes eld +\end_inset + +arbitrary dimension +\begin_inset Quotes erd +\end_inset + + (up to a fixed maximum). + The one-dimensional indexing approaches were implemented in a rather straightfo +rward fashion, and so it is the general-purpose indexing code that will + be the focus of this section. + +\end_layout + +\begin_layout Standard +There is a multi-layer approach to indexing because the indexing code can + at times return an array scalar and at other times return an array. + The functions with +\begin_inset Quotes eld +\end_inset + +_nice +\begin_inset Quotes erd +\end_inset + + appended to their name do this special handling while the function without + the _nice appendage always return an array (perhaps a 0-dimensional array). + Some special-case optimizations (the index being an integer scalar, and + the index being a tuple with as many dimensions as the array) are handled + in array_subscript_nice function which is what Python calls when presented + with the code +\begin_inset Quotes eld +\end_inset + +a[obj]. +\begin_inset Quotes erd +\end_inset + + These optimizations allow fast single-integer indexing, and also ensure + that a 0-dimensional array is not created only to be discarded as the array + scalar is returned instead. + This provides significant speed-up for code that is selecting many scalars + out of an array (such as in a loop). + However, it is still not faster than simply using a list to store standard + Python scalars, because that is optimized by the Python interpreter itself. + +\end_layout + +\begin_layout Standard +After these optimizations, the array_subscript function itself is called. + This function first checks for field selection which occurs when a string + is passed as the indexing object. + Then, 0-d arrays are given special-case consideration. + Finally, the code determines whether or not advanced, or fancy, indexing + needs to be performed. + If fancy indexing is not needed, then standard view-based indexing is performed + using code borrowed from Numeric which parses the indexing object and returns + the offset into the data-buffer and the dimensions necessary to create + a new view of the array. + The strides are also changed by multiplying each stride by the step-size + requested along the corresponding dimension. + +\end_layout + +\begin_layout Subsection +Fancy-indexing check +\end_layout + +\begin_layout Standard +The fancy_indexing_check routine determines whether or not to use standard + view-based indexing or new copy-based indexing. + If the indexing object is a tuple, then view-based indexing is assumed + by default. + Only if the tuple contains an array object or a sequence object is fancy-indexi +ng assumed. + If the indexing object is an array, then fancy indexing is automatically + assumed. + If the indexing object is any other kind of sequence, then fancy-indexing + is assumed by default. + This is over-ridden to simple indexing if the sequence contains any slice, + newaxis, or Ellipsis objects, and no arrays or additional sequences are + also contained in the sequence. + The purpose of this is to allow the construction of +\begin_inset Quotes eld +\end_inset + +slicing +\begin_inset Quotes erd +\end_inset + + sequences which is a common technique for building up code that works in + arbitrary numbers of dimensions. + +\end_layout + +\begin_layout Subsection +Fancy-indexing implementation +\end_layout + +\begin_layout Standard +The concept of indexing was also abstracted using the idea of an iterator. + If fancy indexing is performed, then a PyArrayMapIterObject is created. + This internal object is not exposed to Python. + It is created in order to handle the fancy-indexing at a high-level. + Both get and set fancy-indexing operations are implemented using this object. + Fancy indexing is abstracted into three separate operations: (1) creating + the PyArrayMapIterObject from the indexing object, (2) binding the PyArrayMapIt +erObject to the array being indexed, and (3) getting (or setting) the items + determined by the indexing object. + There is an optimization implemented so that the PyArrayIterObject (which + has it's own less complicated fancy-indexing) is used for indexing when + possible. + +\end_layout + +\begin_layout Subsubsection +Creating the mapping object +\end_layout + +\begin_layout Standard +The first step is to convert the indexing objects into a standard form where + iterators are created for all of the index array inputs and all Boolean + arrays are converted to equivalent integer index arrays (as if nonzero(arr) + had been called). + Finally, all integer arrays are replaced with the integer 0 in the indexing + object and all of the index-array iterators are +\begin_inset Quotes eld +\end_inset + +broadcast +\begin_inset Quotes erd +\end_inset + + to the same shape. + +\end_layout + +\begin_layout Subsubsection +Binding the mapping object +\end_layout + +\begin_layout Standard +When the mapping object is created it does not know which array it will + be used with so once the index iterators are constructed during mapping-object + creation, the next step is to associate these iterators with a particular + ndarray. + This process interprets any ellipsis and slice objects so that the index + arrays are associated with the appropriate axis (the axis indicated by + the iteraxis entry corresponding to the iterator for the integer index + array). + This information is then used to check the indices to be sure they are + within range of the shape of the array being indexed. + The presence of ellipsis and/or slice objects implies a sub-space iteration + that is accomplished by extracting a sub-space view of the array (using + the index object resulting from replacing all the integer index arrays + with 0) and storing the information about where this sub-space starts in + the mapping object. + This is used later during mapping-object iteration to select the correct + elements from the underlying array. + +\end_layout + +\begin_layout Subsubsection +Getting (or Setting) +\end_layout + +\begin_layout Standard +After the mapping object is successfully bound to a particular array, the + mapping object contains the shape of the resulting item as well as iterator + objects that will walk through the currently-bound array and either get + or set its elements as needed. + The walk is implemented using the PyArray_MapIterNext function. + This function sets the coordinates of an iterator object into the current + array to be the next coordinate location indicated by all of the indexing-objec +t iterators while adjusting, if necessary, for the presence of a sub-space. + The result of this function is that the dataptr member of the mapping object + structure is pointed to the next position in the array that needs to be + copied out or set to some value. + +\end_layout + +\begin_layout Standard +When advanced indexing is used to extract an array, an iterator for the + new array is constructed and advanced in phase with the mapping object + iterator. + When advanced indexing is used to place values in an array, a special +\begin_inset Quotes eld +\end_inset + +broadcasted +\begin_inset Quotes erd +\end_inset + + iterator is constructed from the object being placed into the array so + that it will only work if the values used for setting have a shape that + is +\begin_inset Quotes eld +\end_inset + +broadcastable +\begin_inset Quotes erd +\end_inset + + to the shape implied by the indexing object. + +\end_layout + +\begin_layout Section +Universal Functions +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ufunc|(" + +\end_inset + +Universal functions are callable objects that take +\begin_inset Formula $N$ +\end_inset + + inputs and produce +\begin_inset Formula $M$ +\end_inset + + outputs by wrapping basic 1-d loops that work element-by-element into full + easy-to use functions that seamlessly implement broadcasting, type-checking + and buffered coercion, and output-argument handling. + New universal functions are normally created in C, although there is a + mechanism for creating ufuncs from Python functions ( +\series bold +frompyfunc +\series default +). + The user must supply a 1-d loop that implements the basic function taking + the input scalar values and placing the resulting scalars into the appropriate + output slots as explaine n implementation. + +\end_layout + +\begin_layout Subsection +Setup +\end_layout + +\begin_layout Standard +Every ufunc calculation involves some overhead related to setting up the + calculation. + The practical significance of this overhead is that even though the actual + calculation of the ufunc is very fast, you will be able to write array + and type-specific code that will work faster for small arrays than the + ufunc. + In particular, using ufuncs to perform many calculations on 0-d arrays + will be slower than other Python-based solutions (the silently-imported + scalarmath module exists precisely to give array scalars the look-and-feel + of ufunc-based calculations with significantly reduced overhead). + +\end_layout + +\begin_layout Standard +When a ufunc is called, many things must be done. + The information collected from these setup operations is stored in a loop-objec +t. + This loop object is a C-structure (that could become a Python object but + is not initialized as such because it is only used internally). + This loop object has the layout needed to be used with PyArray_Broadcast + so that the broadcasting can be handled in the same way as it is handled + in other sections of code. + +\end_layout + +\begin_layout Standard +The first thing done is to look-up in the thread-specific global dictionary + the current values for the buffer-size, the error mask, and the associated + error object. + The state of the error mask controls what happens when an error-condiction + is found. + It should be noted that checking of the hardware error flags is only performed + after each 1-d loop is executed. + This means that if the input and output arrays are contiguous and of the + correct type so that a single 1-d loop is performed, then the flags may + not be checked until all elements of the array have been calcluated. + Looking up these values in a thread-specific dictionary takes time which + is easily ignored for all but very small arrays. + +\end_layout + +\begin_layout Standard +After checking, the thread-specific global variables, the inputs are evaluated + to determine how the ufunc should proceed and the input and output arrays + are constructed if necessary. + Any inputs which are not arrays are converted to arrays (using context + if necessary). + Which of the inputs are scalars (and therefore converted to 0-d arrays) + is noted. + +\end_layout + +\begin_layout Standard +Next, an appropriate 1-d loop is selected from the 1-d loops available to + the ufunc based on the input array types. + This 1-d loop is selected by trying to match the signature of the data-types + of the inputs against the available signatures. + The signatures corresponding to built-in types are stored in the types + member of the ufunc structure. + The signatures corresponding to user-defined types are stored in a linked-list + of function-information with the head element stored as a +\family typewriter +CObject +\family default + in the userloops dictionary keyed by the data-type number (the first user-defin +ed type in the argument list is used as the key). + The signatures are searched until a signature is found to which the input + arrays can all be cast safely (ignoring any scalar arguments which are + not allowed to determine the type of the result). + The implication of this search procedure is that +\begin_inset Quotes eld +\end_inset + +lesser types +\begin_inset Quotes erd +\end_inset + + should be placed below +\begin_inset Quotes eld +\end_inset + +larger types +\begin_inset Quotes erd +\end_inset + + when the signatures are stored. + If no 1-d loop is found, then an error is reported. + Otherwise, the argument_list is updated with the stored signature --- in + case casting is necessary and to fix the output types assumed by the 1-d + loop. +\end_layout + +\begin_layout Standard +If the ufunc has 2 inputs and 1 output and the second input is an Object + array then a special-case check is performed so that NotImplemented is + returned if the second input is not an ndarray, has the __array_priority__ + attribute, and has an __r<op>__ special method. + In this way, Python is signaled to give the other object a chance to complete + the operation instead of using generic object-array calculations. + This allows (for example) sparse matrices to override the multiplication + operator 1-d loop. + +\end_layout + +\begin_layout Standard +For input arrays that are smaller than the specified buffer size, copies + are made of all non-contiguous, mis-aligned, or out-of-byteorder arrays + to ensure that for small arrays, a single-loop is used. + Then, array iterators are created for all the input arrays and the resulting + collection of iterators is broadcast to a single shape. + +\end_layout + +\begin_layout Standard +The output arguments (if any) are then processed and any missing return + arrays are constructed. + If any provided output array doesn't have the correct type (or is mis-aligned) + and is smaller than the buffer size, then a new output array is constructed + with the special UPDATEIFCOPY flag set so that when it is DECREF'd on completio +n of the function, it's contents will be copied back into the output array. + Iterators for the output arguments are then processed. + +\end_layout + +\begin_layout Standard +Finally, the decision is made about how to execute the looping mechanism + to ensure that all elements of the input arrays are combined to produce + the output arrays of the correct type. + The options for loop execution are one-loop (for contiguous, aligned, and + correct data-type), strided-loop (for non-contiguous but still aligned + and correct data-type), and a buffered loop (for mis-aligned or incorrect + data-type situations). + Depending on which execution method is called for, the loop is then setup + and computed. + +\end_layout + +\begin_layout Subsection +Function call +\end_layout + +\begin_layout Standard +This section describes how the basic universal function computation loop + is setup and executed for each of the three different kinds of execution + possibilities. + If NPY_ALLOW_THREADS is defined during compilation, then the Python Global + Interpreter Lock (GIL) is released prior to calling all of these loops + (as long as they don't involve object arrays). + It is re-acquired if necessary to handle error conditions. + The hardware error flags are checked only after the 1-d loop is calcluated. + +\end_layout + +\begin_layout Subsubsection +One Loop +\end_layout + +\begin_layout Standard +This is the simplest case of all. + The ufunc is executed by calling the underlying 1-d loop exactly once. + This is possible only when we have aligned data of the correct type (including + byte-order) for both input and output and all arrays have uniform strides + (either contiguous, 0-d, or 1-d). + In this case, the 1-d computational loop is called once to compute the + calculation for the entire array. + Note that the hardware error flags are only checked after the entire calculatio +n is complete. + +\end_layout + +\begin_layout Subsubsection +Strided Loop +\end_layout + +\begin_layout Standard +When the input and output arrays are aligned and of the correct type, but + the striding is not uniform (non-contiguous and 2-d or larger), then a + second looping structure is employed for the calculation. + This approach converts all of the iterators for the input and output arguments + to iterate over all but the largest dimension. + The inner loop is then handled by the underlying 1-d computational loop. + The outer loop is a standard iterator loop on the converted iterators. + The hardware error flags are checked after each 1-d loop is completed. + +\end_layout + +\begin_layout Subsubsection +Buffered Loop +\end_layout + +\begin_layout Standard +This is the code that handles the situation whenever the input and/or output + arrays are either misaligned or of the wrong data-type (including being + byte-swapped) from what the underlying 1-d loop expects. + The arrays are also assumed to be non-contiguous. + The code works very much like the strided loop except for the inner 1-d + loop is modified so that pre-processing is performed on the inputs and + post-processing is performed on the outputs in bufsize chunks (where bufsize + is a user-settable parameter). + The underlying 1-d computational loop is called on data that is copied + over (if it needs to be). + The setup code and the loop code is considerably more complicated in this + case because it has to handle: +\end_layout + +\begin_layout Itemize +memory allocation of the temporary buffers +\end_layout + +\begin_layout Itemize +deciding whether or not to use buffers on the input and output data (mis-aligned + and/or wrong data-type) +\end_layout + +\begin_layout Itemize +copying and possibly casting data for any inputs or outputs for which buffers + are necessary. +\end_layout + +\begin_layout Itemize +special-casing Object arrays so that reference counts are properly handled + when copies and/or casts are necessary. + +\end_layout + +\begin_layout Itemize +breaking up the inner 1-d loop into bufsize chunks (with a possible remainder). + +\end_layout + +\begin_layout Standard +Again, the hardware error flags are checked at the end of each 1-d loop. +\end_layout + +\begin_layout Subsection +Final output manipulation +\end_layout + +\begin_layout Standard +Ufuncs allow other array-like classes to be passed seamlessly through the + interface in that inputs of a particular class will induce the outputs + to be of that same class. + The mechanism by which this works is the following. + If any of the inputs are not ndarrays and define the +\series bold +__array_wrap__ +\series default + method, then the class with the largest +\series bold +__array_priority__ +\series default + attribute determines the type of all the outputs (with the exception of + any output arrays passed in). + The +\series bold +__array_wrap__ +\series default + method of the input array will be called with the ndarray being returned + from the ufunc as it's input. + There are two calling styles of the +\series bold +__array_wrap__ +\series default + function supported. + The first takes the ndarray as the first argument and a tuple of +\begin_inset Quotes eld +\end_inset + +context +\begin_inset Quotes erd +\end_inset + + as the second argument. + The context is (ufunc, arguments, output argument number). + This is the first call tried. + If a TypeError occurs, then the function is called with just the ndarray + as the first argument. + +\end_layout + +\begin_layout Subsection +Methods +\end_layout + +\begin_layout Standard +Their are three methods of ufuncs that require calculation similar to the + general-purpose ufuncs. + These are reduce, accumulate, and reduceat. + Each of these methods requires a setup command followed by a loop. + There are four loop styles possible for the methods corresponding to no-element +s, one-element, strided-loop, and buffered-loop. + These are the same basic loop styles as implemented for the general purpose + function call except for the no-element and one-element cases which are + special-cases occurring when the input array objects have 0 and 1 elements + respectively. + +\end_layout + +\begin_layout Subsubsection +Setup +\end_layout + +\begin_layout Standard +The setup function for all three methods is +\family typewriter +construct_reduce +\family default +. + This function creates a reducing loop object and fills it with parameters + needed to complete the loop. + All of the methods only work on ufuncs that take 2-inputs and return 1 + output. + Therefore, the underlying 1-d loop is selected assuming a signature of + [ +\family typewriter +otype +\family default +, +\family typewriter +otype +\family default +, +\family typewriter +otype +\family default +] where +\family typewriter +otype +\family default + is the requested reduction data-type. + The buffer size and error handling is then retrieved from (per-thread) + global storage. + For small arrays that are mis-aligned or have incorrect data-type, a copy + is made so that the un-buffered section of code is used. + Then, the looping strategy is selected. + If there is 1 element or 0 elements in the array, then a simple looping + method is selected. + If the array is not mis-aligned and has the correct data-type, then strided + looping is selected. + Otherwise, buffered looping must be performed. + Looping parameters are then established, and the return array is constructed. + The output array is of a different shape depending on whether the method + is reduce, accumulate, or reduceat. + If an output array is already provided, then it's shape is checked. + If the output array is not C-contiguous, aligned, and of the correct data + type, then a temporary copy is made with the UPDATEIFCOPY flag set. + In this way, the methods will be able to work with a well-behaved output + array but the result will be copied back into the true output array when + the method computation is complete. + Finally, iterators are set up to loop over the correct axis (depending + on the value of axis provided to the method) and the setup routine returns + to the actual computation routine. + +\end_layout + +\begin_layout Subsubsection +Reduce +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ufunc!methods!reduce" + +\end_inset + +All of the ufunc methods use the same underlying 1-d computational loops + with input and output arguments adjusted so that the appropriate reduction + takes place. + For example, the key to the functioning of reduce is that the 1-d loop + is called with the output and the second input pointing to the same position + in memory and both having a step-size of 0. + The first input is pointing to the input array with a step-size given by + the appropriate stride for the selected axis. + In this way, the operation performed is +\begin_inset Formula \begin{eqnarray*} +o & = & i[0]\\ +o & = & i[k]\textrm{ <op> }o\quad k=1\ldots N\end{eqnarray*} + +\end_inset + + where +\begin_inset Formula $N+1$ +\end_inset + + is the number of elements in the input, +\begin_inset Formula $i$ +\end_inset + +, +\begin_inset Formula $o$ +\end_inset + + is the output, and +\begin_inset Formula $i[k]$ +\end_inset + + is the +\begin_inset Formula $k^{\textrm{th}}$ +\end_inset + + element of +\begin_inset Formula $i$ +\end_inset + + along the selected axis. + This basic operations is repeated for arrays with greater than 1 dimension + so that the reduction takes place for every 1-d sub-array along the selected + axis. + An iterator with the selected dimension removed handles this looping. + +\end_layout + +\begin_layout Standard +For buffered loops, care must be taken to copy and cast data before the + loop function is called because the underlying loop expects aligned data + of the correct data-type (including byte-order). + The buffered loop must handle this copying and casting prior to calling + the loop function on chunks no greater than the user-specified bufsize. + +\end_layout + +\begin_layout Subsubsection +Accumulate +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ufunc!methods!accumulate" + +\end_inset + +The accumulate function is very similar to the reduce function in that the + output and the second input both point to the output. + The difference is that the second input points to memory one stride behind + the current output pointer. + Thus, the operation performed is +\end_layout + +\begin_layout Standard +\begin_inset Formula \begin{eqnarray*} +o[0] & = & i[0]\\ +o[k] & = & i[k]\textrm{ <op> }o[k-1]\quad k=1\ldots N.\end{eqnarray*} + +\end_inset + + The output has the same shape as the input and each 1-d loop operates over + +\begin_inset Formula $N$ +\end_inset + + elements when the shape in the selected axis is +\begin_inset Formula $N+1$ +\end_inset + +. + Again, buffered loops take care to copy and cast the data before calling + the underlying 1-d computational loop. + +\end_layout + +\begin_layout Subsubsection +Reduceat +\end_layout + +\begin_layout Standard +\begin_inset LatexCommand index +name "ufunc!methods!reduceat" + +\end_inset + +The reduceat function is a generalization of both the reduce and accumulate + functions. + It implements a reduce over ranges of the input array specified by indices. + The extra indices argument is checked to be sure that every input is not + too large for the input array along the selected dimension before the loop + calculations take place. + The loop implementation is handled using code that is very similar to the + reduce code repeated as many times as there are elements in the indices + input. + In particular: the first input pointer passed to the underlying 1-d computation +al loop points to the input array at the correct location indicated by the + index array. + In addition, the output pointer and the second input pointer passed to + the underlying 1-d loop point to the same position in memory. + The size of the 1-d computational loop is fixed to be the difference between + the current index and the next index (when the current index is the last + index, then the next index is assumed to be the length of the array along + the selected dimension). + In this way, the 1-d loop will implement a reduce over the specified indices. + +\end_layout + +\begin_layout Standard +Mis-aligned or a loop data-type that does not match the input and/or output + data-type is handled using buffered code where-in data is copied to a temporary + buffer and cast to the correct data-type if necessary prior to calling + the underlying 1-d function. + The temporary buffers are created in (element) sizes no bigger than the + user settable buffer-size value. + Thus, the loop must be flexible enough to call the underlying 1-d computational + loop enough times to complete the total calculation in chunks no bigger + than the buffer-size. + +\begin_inset LatexCommand index +name "ufunc|)" + +\end_inset + + +\end_layout + +\end_body +\end_document |