diff options
Diffstat (limited to 'doc/numpybook/capi.lyx')
| -rw-r--r-- | doc/numpybook/capi.lyx | 24240 |
1 files changed, 0 insertions, 24240 deletions
diff --git a/doc/numpybook/capi.lyx b/doc/numpybook/capi.lyx deleted file mode 100644 index b14d5c4f5..000000000 --- a/doc/numpybook/capi.lyx +++ /dev/null @@ -1,24240 +0,0 @@ -#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 - unused; -\end_layout - -\begin_layout LyX-Code - -\emph on -int -\emph default - flags; -\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 -flags -\family default - member. -\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 -flags 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[NPY_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[NPY_NSORTS]; -\end_layout - -\begin_layout LyX-Code - -\emph on -PyArray_ArgSortFunc -\emph default - *argsort[NPY_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 -NPY_QUICKSORT -\family default -, -\family typewriter -NPY_HEAPSORT -\family default -, and -\family typewriter -NPY_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 -NPY_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 -NPY_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 -NPY_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 -NPY_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 -NPY_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 -NPY_INTP -\series default - and -\series bold -NPY_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 -NPY_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 -NPY_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 -NPY_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 -NPY_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 NPY_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 -NPY_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 -tobytes -\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 -NPY_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 -PyArray_DescrCheck ( -\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 -NPY_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 -NPY_FLOAT -\series default - or -\series bold -NPY_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_RemoveSmallest -\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 -NPY_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 -NPY_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 |