numpy 1.9.2__zip → 1.10.0__zip

numpy-1.10.0.post2/doc/source/reference/c-api.dtype.rst

@@ -0,0 +1,376 @@
+Data Type API
+=============
+
+.. sectionauthor:: Travis E. Oliphant
+
+The standard array can have 24 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.
+
+.. 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, :c:data:`NPY_FLOAT` picks up a 32-bit float in
+    C, but :class:`numpy.float_` in Python corresponds to a 64-bit
+    double. The bit-width names can be used in both Python and C for
+    clarity.
+
+
+Enumerated Types
+----------------
+
+There is a list of enumerated types defined providing the basic 24
+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 :c:data:`NPY_{NAME}`:
+
+.. c:var:: NPY_BOOL
+
+    The enumeration value for the boolean type, stored as one byte.
+    It may only be set to the values 0 and 1.
+
+.. c:var:: NPY_BYTE
+.. c:var:: NPY_INT8
+
+    The enumeration value for an 8-bit/1-byte signed integer.
+
+.. c:var:: NPY_SHORT
+.. c:var:: NPY_INT16
+
+    The enumeration value for a 16-bit/2-byte signed integer.
+
+.. c:var:: NPY_INT
+.. c:var:: NPY_INT32
+
+    The enumeration value for a 32-bit/4-byte signed integer.
+
+.. c:var:: NPY_LONG
+
+    Equivalent to either NPY_INT or NPY_LONGLONG, depending on the
+    platform.
+
+.. c:var:: NPY_LONGLONG
+.. c:var:: NPY_INT64
+
+    The enumeration value for a 64-bit/8-byte signed integer.
+
+.. c:var:: NPY_UBYTE
+.. c:var:: NPY_UINT8
+
+    The enumeration value for an 8-bit/1-byte unsigned integer.
+
+.. c:var:: NPY_USHORT
+.. c:var:: NPY_UINT16
+
+    The enumeration value for a 16-bit/2-byte unsigned integer.
+
+.. c:var:: NPY_UINT
+.. c:var:: NPY_UINT32
+
+    The enumeration value for a 32-bit/4-byte unsigned integer.
+
+.. c:var:: NPY_ULONG
+
+    Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the
+    platform.
+
+.. c:var:: NPY_ULONGLONG
+.. c:var:: NPY_UINT64
+
+    The enumeration value for a 64-bit/8-byte unsigned integer.
+
+.. c:var:: NPY_HALF
+.. c:var:: NPY_FLOAT16
+
+    The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating
+    point type.
+
+.. c:var:: NPY_FLOAT
+.. c:var:: NPY_FLOAT32
+
+    The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating
+    point type.
+
+.. c:var:: NPY_DOUBLE
+.. c:var:: NPY_FLOAT64
+
+    The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating
+    point type.
+
+.. c:var:: NPY_LONGDOUBLE
+
+    The enumeration value for a platform-specific floating point type which is
+    at least as large as NPY_DOUBLE, but larger on many platforms.
+
+.. c:var:: NPY_CFLOAT
+.. c:var:: NPY_COMPLEX64
+
+    The enumeration value for a 64-bit/8-byte complex type made up of
+    two NPY_FLOAT values.
+
+.. c:var:: NPY_CDOUBLE
+.. c:var:: NPY_COMPLEX128
+
+    The enumeration value for a 128-bit/16-byte complex type made up of
+    two NPY_DOUBLE values.
+
+.. c:var:: NPY_CLONGDOUBLE
+
+    The enumeration value for a platform-specific complex floating point
+    type which is made up of two NPY_LONGDOUBLE values.
+
+.. c:var:: NPY_DATETIME
+
+    The enumeration value for a data type which holds dates or datetimes with
+    a precision based on selectable date or time units.
+
+.. c:var:: NPY_TIMEDELTA
+
+    The enumeration value for a data type which holds lengths of times in
+    integers of selectable date or time units.
+
+.. c:var:: NPY_STRING
+
+    The enumeration value for ASCII strings of a selectable size. The
+    strings have a fixed maximum size within a given array.
+
+.. c:var:: NPY_UNICODE
+
+    The enumeration value for UCS4 strings of a selectable size. The
+    strings have a fixed maximum size within a given array.
+
+.. c:var:: NPY_OBJECT
+
+    The enumeration value for references to arbitrary Python objects.
+
+.. c:var:: NPY_VOID
+
+    Primarily used to hold struct dtypes, but can contain arbitrary
+    binary data.
+
+Some useful aliases of the above types are
+
+.. c:var:: NPY_INTP
+
+    The enumeration value for a signed integer type which is the same
+    size as a (void \*) pointer. This is the type used by all
+    arrays of indices.
+
+.. c:var:: NPY_UINTP
+
+    The enumeration value for an unsigned integer type which is the
+    same size as a (void \*) pointer.
+
+.. c:var:: NPY_MASK
+
+    The enumeration value of the type used for masks, such as with
+    the :c:data:`NPY_ITER_ARRAYMASK` iterator flag. This is equivalent
+    to :c:data:`NPY_UINT8`.
+
+.. c:var:: NPY_DEFAULT_TYPE
+
+    The default type to use when no dtype is explicitly specified, for
+    example when calling np.zero(shape). This is equivalent to
+    :c:data:`NPY_DOUBLE`.
+
+Other useful related constants are
+
+.. c:var:: NPY_NTYPES
+
+    The total number of built-in NumPy types. The enumeration covers
+    the range from 0 to NPY_NTYPES-1.
+
+.. c:var:: NPY_NOTYPE
+
+    A signal value guaranteed not to be a valid type enumeration number.
+
+.. c:var:: NPY_USERDEF
+
+    The start of type numbers used for Custom Data types.
+
+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 :c:data:`NPY_{NAME}LTR` where ``{NAME}`` can be
+
+    **BOOL**, **BYTE**, **UBYTE**, **SHORT**, **USHORT**, **INT**,
+    **UINT**, **LONG**, **ULONG**, **LONGLONG**, **ULONGLONG**,
+    **HALF**, **FLOAT**, **DOUBLE**, **LONGDOUBLE**, **CFLOAT**,
+    **CDOUBLE**, **CLONGDOUBLE**, **DATETIME**, **TIMEDELTA**,
+    **OBJECT**, **STRING**, **VOID**
+
+    **INTP**, **UINTP**
+
+    **GENBOOL**, **SIGNED**, **UNSIGNED**, **FLOATING**, **COMPLEX**
+
+The latter group of ``{NAME}s`` corresponds to letters used in the array
+interface typestring specification.
+
+
+Defines
+-------
+
+Max and min values for integers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. c:var:: NPY_MAX_INT{bits}
+
+.. c:var:: NPY_MAX_UINT{bits}
+
+.. c:var:: NPY_MIN_INT{bits}
+
+    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).
+
+.. c:var:: NPY_MIN_{type}
+
+    This is defined for ``{type}`` = **BYTE**, **SHORT**, **INT**,
+    **LONG**, **LONGLONG**, **INTP**
+
+.. c:var:: NPY_MAX_{type}
+
+    This is defined for all defined for ``{type}`` = **BYTE**, **UBYTE**,
+    **SHORT**, **USHORT**, **INT**, **UINT**, **LONG**, **ULONG**,
+    **LONGLONG**, **ULONGLONG**, **INTP**, **UINTP**
+
+
+Number of bits in data types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All :c:data:`NPY_SIZEOF_{CTYPE}` constants have corresponding
+:c:data:`NPY_BITSOF_{CTYPE}` constants defined. The :c:data:`NPY_BITSOF_{CTYPE}`
+constants provide the number of bits in the data type.  Specifically,
+the available ``{CTYPE}s`` are
+
+    **BOOL**, **CHAR**, **SHORT**, **INT**, **LONG**,
+    **LONGLONG**, **FLOAT**, **DOUBLE**, **LONGDOUBLE**
+
+
+Bit-width references to enumerated typenums
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+:c:data:`PyArray_{NAME}{BITS}` where ``{NAME}`` is **INT**, **UINT**,
+**FLOAT**, **COMPLEX** 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.
+
+
+Integer that can hold a pointer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The constants **NPY_INTP** and **NPY_UINTP** refer to an
+enumerated integer type that is large enough to hold a pointer on the
+platform. Index arrays should always be converted to **NPY_INTP**
+, because the dimension of the array is of type npy_intp.
+
+
+C-type names
+------------
+
+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.
+
+
+Boolean
+^^^^^^^
+
+.. c:type:: npy_bool
+
+    unsigned char; The constants :c:data:`NPY_FALSE` and
+    :c:data:`NPY_TRUE` are also defined.
+
+
+(Un)Signed Integer
+^^^^^^^^^^^^^^^^^^
+
+Unsigned versions of the integers can be defined by pre-pending a 'u'
+to the front of the integer name.
+
+.. c:type:: npy_(u)byte
+
+    (unsigned) char
+
+.. c:type:: npy_(u)short
+
+    (unsigned) short
+
+.. c:type:: npy_(u)int
+
+    (unsigned) int
+
+.. c:type:: npy_(u)long
+
+    (unsigned) long int
+
+.. c:type:: npy_(u)longlong
+
+    (unsigned long long int)
+
+.. c:type:: npy_(u)intp
+
+    (unsigned) Py_intptr_t (an integer that is the size of a pointer on
+    the platform).
+
+
+(Complex) Floating point
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. c:type:: npy_(c)float
+
+    float
+
+.. c:type:: npy_(c)double
+
+    double
+
+.. c:type:: npy_(c)longdouble
+
+    long double
+
+complex types are structures with **.real** and **.imag** members (in
+that order).
+
+
+Bit-width names
+^^^^^^^^^^^^^^^
+
+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
+
+    :c:type:`npy_int{bits}`, :c:type:`npy_uint{bits}`, :c:type:`npy_float{bits}`,
+    and :c:type:`npy_complex{bits}`
+
+where ``{bits}`` is the number of bits in the type and can be **8**,
+**16**, **32**, **64**, 128, and 256 for integer types; 16, **32**
+, **64**, 80, 96, 128, and 256 for floating-point types; and 32,
+**64**, **128**, 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.
+
+
+Printf Formatting
+-----------------
+
+For help in printing, the following strings are defined as the correct
+format specifier in printf and related commands.
+
+    :c:data:`NPY_LONGLONG_FMT`, :c:data:`NPY_ULONGLONG_FMT`,
+    :c:data:`NPY_INTP_FMT`, :c:data:`NPY_UINTP_FMT`,
+    :c:data:`NPY_LONGDOUBLE_FMT`

numpy-1.10.0.post2/doc/source/reference/c-api.generalized-ufuncs.rst

@@ -0,0 +1,191 @@
+==================================
+Generalized Universal Function API
+==================================
+
+There is a general need for looping over not only functions on scalars
+but also over functions on vectors (or arrays).
+This concept is realized in Numpy by generalizing the universal functions
+(ufuncs).  In regular ufuncs, the elementary function is limited to
+element-by-element operations, whereas the generalized version (gufuncs)
+supports "sub-array" by "sub-array" operations.  The Perl vector library PDL
+provides a similar functionality and its terms are re-used in the following.
+
+Each generalized ufunc has information associated with it that states
+what the "core" dimensionality of the inputs is, as well as the
+corresponding dimensionality of the outputs (the element-wise ufuncs
+have zero core dimensions).  The list of the core dimensions for all
+arguments is called the "signature" of a ufunc.  For example, the
+ufunc numpy.add has signature ``(),()->()`` defining two scalar inputs
+and one scalar output.
+
+Another example is the function ``inner1d(a, b)`` with a signature of
+``(i),(i)->()``.  This applies the inner product along the last axis of
+each input, but keeps the remaining indices intact.
+For example, where ``a`` is of shape ``(3, 5, N)`` and ``b`` is of shape
+``(5, N)``, this will return an output of shape ``(3,5)``.
+The underlying elementary function is called ``3 * 5`` times.  In the
+signature, we specify one core dimension ``(i)`` for each input and zero core
+dimensions ``()`` for the output, since it takes two 1-d arrays and
+returns a scalar.  By using the same name ``i``, we specify that the two
+corresponding dimensions should be of the same size.
+
+The dimensions beyond the core dimensions are called "loop" dimensions.  In
+the above example, this corresponds to ``(3, 5)``.
+
+The signature determines how the dimensions of each input/output array are
+split into core and loop dimensions:
+
+#. Each dimension in the signature is matched to a dimension of the
+   corresponding passed-in array, starting from the end of the shape tuple.
+   These are the core dimensions, and they must be present in the arrays, or
+   an error will be raised.
+#. Core dimensions assigned to the same label in the signature (e.g. the
+   ``i`` in ``inner1d``'s ``(i),(i)->()``) must have exactly matching sizes,
+   no broadcasting is performed.
+#. The core dimensions are removed from all inputs and the remaining
+   dimensions are broadcast together, defining the loop dimensions.
+#. The shape of each output is determined from the loop dimensions plus the
+   output's core dimensions
+
+Typically, the size of all core dimensions in an output will be determined by
+the size of a core dimension with the same label in an input array. This is
+not a requirement, and it is possible to define a signature where a label
+comes up for the first time in an output, although some precautions must be
+taken when calling such a function. An example would be the function
+``euclidean_pdist(a)``, with signature ``(n,d)->(p)``, that given an array of
+``n`` ``d``-dimensional vectors, computes all unique pairwise Euclidean
+distances among them. The output dimension ``p`` must therefore be equal to
+``n * (n - 1) / 2``, but it is the caller's responsibility to pass in an
+output array of the right size. If the size of a core dimension of an output
+cannot be determined from a passed in input or output array, an error will be
+raised.
+
+Note: Prior to Numpy 1.10.0, less strict checks were in place: missing core
+dimensions were created by prepending 1's to the shape as necessary, core
+dimensions with the same label were broadcast together, and undetermined
+dimensions were created with size 1.
+
+
+Definitions
+-----------
+
+Elementary Function
+    Each ufunc consists of an elementary function that performs the
+    most basic operation on the smallest portion of array arguments
+    (e.g. adding two numbers is the most basic operation in adding two
+    arrays).  The ufunc applies the elementary function multiple times
+    on different parts of the arrays.  The input/output of elementary
+    functions can be vectors; e.g., the elementary function of inner1d
+    takes two vectors as input.
+
+Signature
+    A signature is a string describing the input/output dimensions of
+    the elementary function of a ufunc.  See section below for more
+    details.
+
+Core Dimension
+    The dimensionality of each input/output of an elementary function
+    is defined by its core dimensions (zero core dimensions correspond
+    to a scalar input/output).  The core dimensions are mapped to the
+    last dimensions of the input/output arrays.
+
+Dimension Name
+    A dimension name represents a core dimension in the signature.
+    Different dimensions may share a name, indicating that they are of
+    the same size.
+
+Dimension Index
+    A dimension index is an integer representing a dimension name. It
+    enumerates the dimension names according to the order of the first
+    occurrence of each name in the signature.
+
+
+Details of Signature
+--------------------
+
+The signature defines "core" dimensionality of input and output
+variables, and thereby also defines the contraction of the
+dimensions.  The signature is represented by a string of the
+following format:
+
+* Core dimensions of each input or output array are represented by a
+  list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar
+  input/output is denoted by ``()``.  Instead of ``i_1``, ``i_2``,
+  etc, one can use any valid Python variable name.
+* Dimension lists for different arguments are separated by ``","``.
+  Input/output arguments are separated by ``"->"``.
+* If one uses the same dimension name in multiple locations, this
+  enforces the same size of the corresponding dimensions.
+
+The formal syntax of signatures is as follows::
+
+    <Signature>            ::= <Input arguments> "->" <Output arguments>
+    <Input arguments>      ::= <Argument list>
+    <Output arguments>     ::= <Argument list>
+    <Argument list>        ::= nil | <Argument> | <Argument> "," <Argument list>
+    <Argument>             ::= "(" <Core dimension list> ")"
+    <Core dimension list>  ::= nil | <Dimension name> |
+                               <Dimension name> "," <Core dimension list>
+    <Dimension name>       ::= valid Python variable name
+
+
+Notes:
+
+#. All quotes are for clarity.
+#. Core dimensions that share the same name must have the exact same size.
+   Each dimension name typically corresponds to one level of looping in the
+   elementary function's implementation.
+#. White spaces are ignored.
+
+Here are some examples of signatures:
+
++-------------+------------------------+-----------------------------------+
+| add         | ``(),()->()``          |                                   |
++-------------+------------------------+-----------------------------------+
+| inner1d     | ``(i),(i)->()``        |                                   |
++-------------+------------------------+-----------------------------------+
+| sum1d       | ``(i)->()``            |                                   |
++-------------+------------------------+-----------------------------------+
+| dot2d       | ``(m,n),(n,p)->(m,p)`` | matrix multiplication             |
++-------------+------------------------+-----------------------------------+
+| outer_inner | ``(i,t),(j,t)->(i,j)`` | inner over the last dimension,    |
+|             |                        | outer over the second to last,    |
+|             |                        | and loop/broadcast over the rest. |
++-------------+------------------------+-----------------------------------+
+
+C-API for implementing Elementary Functions
+-------------------------------------------
+
+The current interface remains unchanged, and ``PyUFunc_FromFuncAndData``
+can still be used to implement (specialized) ufuncs, consisting of
+scalar elementary functions.
+
+One can use ``PyUFunc_FromFuncAndDataAndSignature`` to declare a more
+general ufunc.  The argument list is the same as
+``PyUFunc_FromFuncAndData``, with an additional argument specifying the
+signature as C string.
+
+Furthermore, the callback function is of the same type as before,
+``void (*foo)(char **args, intp *dimensions, intp *steps, void *func)``.
+When invoked, ``args`` is a list of length ``nargs`` containing
+the data of all input/output arguments.  For a scalar elementary
+function, ``steps`` is also of length ``nargs``, denoting the strides used
+for the arguments. ``dimensions`` is a pointer to a single integer
+defining the size of the axis to be looped over.
+
+For a non-trivial signature, ``dimensions`` will also contain the sizes
+of the core dimensions as well, starting at the second entry.  Only
+one size is provided for each unique dimension name and the sizes are
+given according to the first occurrence of a dimension name in the
+signature.
+
+The first ``nargs`` elements of ``steps`` remain the same as for scalar
+ufuncs.  The following elements contain the strides of all core
+dimensions for all arguments in order.
+
+For example, consider a ufunc with signature ``(i,j),(i)->()``.  In
+this case, ``args`` will contain three pointers to the data of the
+input/output arrays ``a``, ``b``, ``c``.  Furthermore, ``dimensions`` will be
+``[N, I, J]`` to define the size of ``N`` of the loop and the sizes ``I`` and ``J``
+for the core dimensions ``i`` and ``j``.  Finally, ``steps`` will be
+``[a_N, b_N, c_N, a_i, a_j, b_i]``, containing all necessary strides.