diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.classes.rst | 31 | ||||
| -rw-r--r-- | doc/source/reference/arrays.ndarray.rst | 37 | ||||
| -rw-r--r-- | doc/source/reference/arrays.scalars.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 166 | ||||
| -rw-r--r-- | doc/source/reference/c-api.config.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/c-api.coremath.rst | 27 | ||||
| -rw-r--r-- | doc/source/reference/c-api.generalized-ufuncs.rst (renamed from doc/source/reference/generalized_ufuncs.rst) | 10 | ||||
| -rw-r--r-- | doc/source/reference/c-api.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/c-api.types-and-structures.rst | 12 | ||||
| -rw-r--r-- | doc/source/reference/c-api.ufunc.rst | 43 | ||||
| -rw-r--r-- | doc/source/reference/distutils.rst | 295 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 7 | ||||
| -rw-r--r-- | doc/source/reference/routines.indexing.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/routines.set.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/routines.statistics.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.testing.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 22 |
17 files changed, 402 insertions, 272 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 671c95bbf..f9abfbafa 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -47,14 +47,29 @@ customize: update meta-information from the "parent." Subclasses inherit a default implementation of this method that does nothing. -.. function:: __array_wrap__(array) - - This method should return an instance of the subclass from the - :class:`ndarray` object passed in. For example, this is called - after every :ref:`ufunc <ufuncs.output-type>` for the object with - the highest array priority. The ufunc-computed array object is - passed in and whatever is returned is passed to the - user. Subclasses inherit a default implementation of this method. +.. function:: __array_prepare__(array, context=None) + + At the beginning of every :ref:`ufunc <ufuncs.output-type>`, this + method is called on the input object with the highest array + priority, or the output object if one was specified. The output + array is passed in and whatever is returned is passed to the ufunc. + Subclasses inherit a default implementation of this method which + simply returns the output array unmodified. Subclasses may opt to + use this method to transform the output array into an instance of + the subclass and update metadata before returning the array to the + ufunc for computation. + +.. function:: __array_wrap__(array, context=None) + + At the end of every :ref:`ufunc <ufuncs.output-type>`, this method + is called on the input object with the highest array priority, or + the output object if one was specified. The ufunc-computed array + is passed in and whatever is returned is passed to the user. + Subclasses inherit a default implementation of this method, which + transforms the array into a new instance of the object's class. Subclasses + may opt to use this method to transform the output array into an + instance of the subclass and update metadata before returning the + array to the user. .. data:: __array_priority__ diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 0def05ced..1bf7d1ac8 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -9,14 +9,14 @@ The N-dimensional array (:class:`ndarray`) An :class:`ndarray` is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its :attr:`shape <ndarray.shape>`, -which is a :class:`tuple` of *N* integers that specify the sizes of +which is a :class:`tuple` of *N* positive integers that specify the sizes of each dimension. The type of items in the array is specified by a separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which is associated with each ndarray. -As with other container objects in Python, the contents of a +As with other container objects in Python, the contents of an :class:`ndarray` can be accessed and modified by :ref:`indexing or -slicing <arrays.indexing>` the array (using for example *N* integers), +slicing <arrays.indexing>` the array (using, for example, *N* integers), and via the methods and attributes of the :class:`ndarray`. .. index:: view, base @@ -42,15 +42,19 @@ objects implementing the :class:`buffer` or :ref:`array >>> x.dtype dtype('int32') - The array can be indexed using a Python container-like syntax: + The array can be indexed using Python container-like syntax: - >>> x[1,2] + >>> x[1,2] # i.e., the element of x in the *second* row, *third* column 6 For example :ref:`slicing <arrays.indexing>` can produce views of the array: >>> y = x[:,1] - >>> y[0] = 9 + >>> y + array([2, 5]) + >>> y[0] = 9 # this also changes the corresponding element in x + >>> y + array([9, 5]) >>> x array([[1, 9, 3], [4, 5, 6]]) @@ -95,7 +99,7 @@ the bytes are interpreted is defined by the :ref:`data-type object .. index:: C-order, Fortran-order, row-major, column-major, stride, offset A segment of memory is inherently 1-dimensional, and there are many -different schemes of arranging the items of an *N*-dimensional array to +different schemes for arranging the items of an *N*-dimensional array in a 1-dimensional block. Numpy is flexible, and :class:`ndarray` objects can accommodate any *strided indexing scheme*. In a strided scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})` corresponds @@ -105,10 +109,10 @@ to the offset (in bytes) from the beginning of the memory block associated with the array. Here, :math:`s_k` are integers which specify the :obj:`strides -<ndarray.strides>` of the array. The :term:`column-major` order (used -for example in the Fortran language and in *Matlab*) and -:term:`row-major` order (used in C) are special cases of the strided -scheme, and correspond to the strides: +<ndarray.strides>` of the array. The :term:`column-major` order (used, +for example, in the Fortran language and in *Matlab*) and +:term:`row-major` order (used in C) schemes are just specific kinds of +strided scheme, and correspond to the strides: .. math:: @@ -116,12 +120,12 @@ scheme, and correspond to the strides: .. index:: single-segment, contiguous, non-contiguous -Both the C and Fortran orders are :term:`contiguous`, *i.e.* +Both the C and Fortran orders are :term:`contiguous`, *i.e.,* :term:`single-segment`, memory layouts, in which every part of the memory block can be accessed by some combination of the indices. Data in new :class:`ndarrays <ndarray>` is in the :term:`row-major` -(C) order, unless otherwise specified, but for example :ref:`basic +(C) order, unless otherwise specified, but, for example, :ref:`basic array slicing <arrays.indexing>` often produces :term:`views <view>` in a different scheme. @@ -227,7 +231,8 @@ Array methods An :class:`ndarray` object has many methods which operate on or with the array in some fashion, typically returning an array result. These -methods are explained below. +methods are briefly explained below. (Each method's doc string has a +more complete description.) For the following methods there are also corresponding functions in :mod:`numpy`: :func:`all`, :func:`any`, :func:`argmax`, @@ -433,7 +438,7 @@ Arithmetic: .. note:: - Any third argument to :func:`pow()` is silently ignored, - as the underlying :func:`ufunc <power>` only takes two arguments. + as the underlying :func:`ufunc <power>` takes only two arguments. - The three division operators are all defined; :obj:`div` is active by default, :obj:`truediv` is active when @@ -472,7 +477,7 @@ Arithmetic, in-place: the array. Therefore, for mixed precision calculations, ``A {op}= B`` can be different than ``A = A {op} B``. For example, suppose ``a = ones((3,3))``. Then, ``a += 3j`` is different than ``a = a + - 3j``: While they both perform the same computation, ``a += 3`` + 3j``: while they both perform the same computation, ``a += 3`` casts the result to fit back in ``a``, whereas ``a = a + 3j`` re-binds the name ``a`` to the result. diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst index 33d5ceff6..75daf2a08 100644 --- a/doc/source/reference/arrays.scalars.rst +++ b/doc/source/reference/arrays.scalars.rst @@ -204,8 +204,6 @@ elements the data type consists of.) :mod:`struct` module. -.. note:: XXX: what to put in the type docstrings, and where to put them? - Attributes ========== @@ -235,7 +233,6 @@ attribute. Otherwise, they share the same attributes as arrays: generic.__array_priority__ generic.__array_wrap__ -.. note:: XXX: import the documentation into the docstrings? Indexing ======== @@ -273,7 +270,6 @@ The exceptions to the above rules are given below: generic.__setstate__ generic.setflags -.. note:: XXX: import the documentation into the docstrings? Defining new types ================== diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 654201d73..8ce362079 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -251,14 +251,16 @@ From other objects .. cfunction:: PyObject* PyArray_FromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context) This is the main function used to obtain an array from any nested - sequence, or object that exposes the array interface, ``op``. The - parameters allow specification of the required *type*, the + sequence, or object that exposes the array interface, *op*. The + parameters allow specification of the required *dtype*, the minimum (*min_depth*) and maximum (*max_depth*) number of dimensions acceptable, and other *requirements* for the array. The *dtype* argument needs to be a :ctype:`PyArray_Descr` structure indicating the desired data-type (including required byteorder). The *dtype* argument may be NULL, indicating that any - data-type (and byteorder) is acceptable. If you want to use + data-type (and byteorder) is acceptable. Unless ``FORCECAST`` is + present in ``flags``, this call will generate an error if the data + type cannot be safely obtained from the object. If you want to use ``NULL`` for the *dtype* and ensure the array is notswapped then use :cfunc:`PyArray_CheckFromAny`. A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the @@ -270,7 +272,8 @@ From other objects filled from *op* using the sequence protocol). The new array will have :cdata:`NPY_DEFAULT` as its flags member. The *context* argument is passed to the :obj:`__array__` method of *op* and is only used if - the array is constructed that way. + the array is constructed that way. Almost always this + parameter is ``NULL``. .. cvar:: NPY_C_CONTIGUOUS @@ -1001,6 +1004,24 @@ Special functions for PyArray_OBJECT Array flags ----------- +The ``flags`` attribute of the ``PyArrayObject`` structure contains +important information about the memory used by the array (pointed to +by the data member) This flag information must be kept accurate or +strange results and even segfaults may result. + +There are 6 (binary) flags that describe the memory area used by the +data buffer. These constants are defined in ``arrayobject.h`` and +determine the bit-position of the flag. Python exposes a nice +attribute- based interface as well as a dictionary-like interface for +getting (and, if appropriate, setting) these flags. + +Memory areas of all kinds can be pointed to by an ndarray, +necessitating these flags. If you get an arbitrary ``PyArrayObject`` +in C-code, you need to be aware of the flags that are set. If you +need to guarantee a certain kind of array (like ``NPY_CONTIGUOUS`` and +``NPY_BEHAVED``), then pass these requirements into the +PyArray_FromAny function. + Basic Array Flags ^^^^^^^^^^^^^^^^^ @@ -1023,6 +1044,12 @@ associated with an array. The data area is in Fortran-style contiguous order (first index varies the fastest). +Notice that contiguous 1-d arrays are always both ``NPY_FORTRAN`` +contiguous and C contiguous. Both of these flags can be checked and +are convenience flags only as whether or not an array is +``NPY_CONTIGUOUS`` or ``NPY_FORTRAN`` can be determined by the +``strides``, ``dimensions``, and ``itemsize`` attributes. + .. cvar:: NPY_OWNDATA The data area is owned by this array. @@ -1043,6 +1070,24 @@ associated with an array. The data area represents a (well-behaved) copy whose information should be transferred back to the original when this array is deleted. + This is a special flag that is set if this array represents a copy + made because a user required certain flags in + :cfunc:`PyArray_FromAny` and a copy had to be made of some other + array (and the user asked for this flag to be set in such a + situation). The base attribute then points to the "misbehaved" + array (which is set read_only). When the array with this flag set + is deallocated, it will copy its contents back to the "misbehaved" + array (casting if necessary) and will reset the "misbehaved" array + to :cdata:`NPY_WRITEABLE`. If the "misbehaved" array was not + :cdata:`NPY_WRITEABLE` to begin with then :cfunc:`PyArray_FromAny` + would have returned an error because :cdata:`NPY_UPDATEIFCOPY` + would not have been possible. + +:cfunc:`PyArray_UpdateFlags` (obj, flags) will update the +``obj->flags`` for ``flags`` which can be any of +:cdata:`NPY_CONTIGUOUS`, :cdata:`NPY_FORTRAN`, :cdata:`NPY_ALIGNED`, +or :cdata:`NPY_WRITEABLE`. + Combinations of array flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,6 +1766,29 @@ Array Functions *op1*, 2 - return all possible shifts (any overlap at all is accepted). + .. rubric:: Notes + + This does not compute the usual correlation: if op2 is larger than op1, the + arguments are swapped, and the conjugate is never taken for complex arrays. + See PyArray_Correlate2 for the usual signal processing correlation. + +.. cfunction:: PyObject* PyArray_Correlate2(PyObject* op1, PyObject* op2, int mode) + + Updated version of PyArray_Correlate, which uses the usual definition of + correlation for 1d arrays. The correlation is computed at each output point + by multiplying *op1* by a shifted version of *op2* and summing the result. + As a result of the shift, needed values outside of the defined range of + *op1* and *op2* 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 *op1*, 2 - return all + possible shifts (any overlap at all is accepted). + + .. rubric:: Notes + + Compute z as follows:: + + z[k] = sum_n op1[n] * conj(op2[n+k]) + .. cfunction:: PyObject* PyArray_Where(PyObject* condition, PyObject* x, PyObject* y) If both ``x`` and ``y`` are ``NULL``, then return @@ -1901,6 +1969,96 @@ Broadcasting (multi-iterators) loop should be performed over the axis that won't require large stride jumps. +Neighborhood iterator +--------------------- + +.. versionadded:: 1.4.0 + +Neighborhood iterators are subclasses of the iterator object, and can be used +to iter over a neighborhood of a point. For example, you may want to iterate +over every voxel of a 3d image, and for every such voxel, iterate over an +hypercube. Neighborhood iterator automatically handle boundaries, thus making +this kind of code much easier to write than manual boundaries handling, at the +cost of a slight overhead. + +.. cfunction:: PyObject* PyArray_NeighborhoodIterNew(PyArrayIterObject* iter, npy_intp bounds, int mode, PyArrayObject* fill_value) + + This function creates a new neighborhood iterator from an existing + iterator. The neighborhood will be computed relatively to the position + currently pointed by *iter*, the bounds define the shape of the + neighborhood iterator, and the mode argument the boundaries handling mode. + + The *bounds* argument is expected to be a (2 * iter->ao->nd) arrays, such + as the range bound[2*i]->bounds[2*i+1] defines the range where to walk for + dimension i (both bounds are included in the walked coordinates). The + bounds should be ordered for each dimension (bounds[2*i] <= bounds[2*i+1]). + + The mode should be one of: + + * NPY_NEIGHBORHOOD_ITER_ZERO_PADDING: zero padding. Outside bounds values + will be 0. + * NPY_NEIGHBORHOOD_ITER_ONE_PADDING: one padding, Outside bounds values + will be 1. + * NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING: constant padding. Outside bounds + values will be the same as the first item in fill_value. + * NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING: mirror padding. Outside bounds + values will be as if the array items were mirrored. For example, for the + array [1, 2, 3, 4], x[-2] will be 2, x[-2] will be 1, x[4] will be 4, + x[5] will be 1, etc... + * NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: circular padding. Outside bounds + values will be as if the array was repeated. For example, for the + array [1, 2, 3, 4], x[-2] will be 3, x[-2] will be 4, x[4] will be 1, + x[5] will be 2, etc... + + If the mode is constant filling (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING), + fill_value should point to an array object which holds the filling value + (the first item will be the filling value if the array contains more than + one item). For other cases, fill_value may be NULL. + + - The iterator holds a reference to iter + - Return NULL on failure (in which case the reference count of iter is not + changed) + - iter itself can be a Neighborhood iterator: this can be useful for .e.g + automatic boundaries handling + - the object returned by this function should be safe to use as a normal + iterator + - If the position of iter is changed, any subsequent call to + PyArrayNeighborhoodIter_Next is undefined behavior, and + PyArrayNeighborhoodIter_Reset must be called. + + .. code-block:: c + + PyArrayIterObject \*iter; + PyArrayNeighborhoodIterObject \*neigh_iter; + iter = PyArray_IterNew(x); + + //For a 3x3 kernel + bounds = {-1, 1, -1, 1}; + neigh_iter = (PyArrayNeighborhoodIterObject*)PyArrayNeighborhoodIter_New( + iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL); + + for(i = 0; i < iter->size; ++i) { + for (j = 0; j < neigh_iter->size; ++j) { + // Walk around the item currently pointed by iter->dataptr + PyArrayNeighborhoodIter_Next(neigh_iter); + } + + // Move to the next point of iter + PyArrayIter_Next(iter); + PyArrayNeighborhoodIter_Reset(neigh_iter); + } + +.. cfunction:: int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter) + + Reset the iterator position to the first point of the neighborhood. This + should be called whenever the iter argument given at + PyArray_NeighborhoodIterObject is changed (see example) + +.. cfunction:: int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter) + + After this call, iter->dataptr points to the next point of the + neighborhood. Calling this function after every point of the + neighborhood has been visited is undefined. Array Scalars ------------- diff --git a/doc/source/reference/c-api.config.rst b/doc/source/reference/c-api.config.rst index 0c7f6b147..0989c53d7 100644 --- a/doc/source/reference/c-api.config.rst +++ b/doc/source/reference/c-api.config.rst @@ -89,8 +89,8 @@ Platform information .. versionadded:: 1.3.0 Portable alternatives to the ``endian.h`` macros of GNU Libc. - One of :cdata:`NPY_BIG_ENDIAN` :cdata:`NPY_LITTLE_ENDIAN` or - is defined, and :cdata:`NPY_BYTE_ORDER` is either 4321 or 1234. + If big endian, :cdata:`NPY_BYTE_ORDER` == :cdata:`NPY_BIG_ENDIAN`, and + similarly for little endian architectures. Defined in ``numpy/npy_endian.h``. diff --git a/doc/source/reference/c-api.coremath.rst b/doc/source/reference/c-api.coremath.rst index 8e6011603..b1a356551 100644 --- a/doc/source/reference/c-api.coremath.rst +++ b/doc/source/reference/c-api.coremath.rst @@ -69,6 +69,14 @@ Floating point classification and extended precision, and return a non 0 value is x has the signbit set (that is the number is negative). +.. cfunction:: double npy_copysign(double x, double y) + + This is a function equivalent to C99 copysign: return x with the same sign + as y. Works for any value, including inf and nan. Single and extended + precisions are available with suffix f and l. + + .. versionadded:: 1.4.0 + Useful math constants ~~~~~~~~~~~~~~~~~~~~~ @@ -114,3 +122,22 @@ precision are also available by adding the F and L suffixes respectively. .. cvar:: NPY_2_PI Two times the reciprocal of pi (:math:`\frac{2}{\pi}`) + +.. cvar:: NPY_EULER + + The Euler constant (:math:`\lim_{n\rightarrow \infty}{\sum_{k=1}^n{\frac{1}{k}} - \ln n}`) + +Linking against the core math library in an extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.4.0 + +To use the core math library in your own extension, you need to add the npymath +compile and link options to your extension in your setup.py: + + >>> from numpy.distutils.misc_utils import get_info + >>> info = get_info('npymath') + >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info) + +In other words, the usage of info is exactly the same as when using blas_info +and co. diff --git a/doc/source/reference/generalized_ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst index d9f3818b9..870e5dbc4 100644 --- a/doc/source/reference/generalized_ufuncs.rst +++ b/doc/source/reference/c-api.generalized-ufuncs.rst @@ -1,6 +1,6 @@ -=============================== -Generalized Universal Functions -=============================== +================================== +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), as explained on @@ -91,14 +91,14 @@ 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 + 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 (or broadcastable size) of the corresponding - dimensions. + dimensions. The formal syntax of signatures is as follows:: diff --git a/doc/source/reference/c-api.rst b/doc/source/reference/c-api.rst index 158e04a16..9bcc68b49 100644 --- a/doc/source/reference/c-api.rst +++ b/doc/source/reference/c-api.rst @@ -45,4 +45,5 @@ code. c-api.dtype c-api.array c-api.ufunc + c-api.generalized-ufuncs c-api.coremath diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index b99702e11..ece7f341b 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -917,6 +917,18 @@ PyArrayMultiIter_Type to be broadcast together. On return, the iterators are adjusted for broadcasting. +PyArrayNeighborhoodIter_Type +---------------------------- + +.. cvar:: PyArrayNeighborhoodIter_Type + + This is an iterator object that makes it easy to loop over an N-dimensional + neighborhood. + +.. ctype:: PyArrayNeighborhoodIterObject + + The C-structure corresponding to an object of :cdata:`PyArrayNeighborhoodIter_Type` is + the :ctype:`PyArrayNeighborhoodIterObject`. PyArrayFlags_Type ----------------- diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index bd0ee8e02..6a6a0dff0 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -70,43 +70,45 @@ Functions operation. Each ufunc object contains pointers to 1-d loops implementing the basic functionality for each supported type. - :param nin: - - The number of inputs to this operation. - - :param nout: - - The number of outputs - - :param ntypes: + .. note:: - How many different data-type "signatures" the ufunc has implemented. + The *func*, *data*, *types*, *name*, and *doc* arguments are not + copied by :cfunc:`PyUFunc_FromFuncAndData`. The caller must ensure + that the memory used by these arrays is not freed as long as the + ufunc object is alive. :param func: - Must to an array of length *ntypes* containing :ctype:`PyUFuncGenericFunction` items. These items are pointers to - functions that acutally implement the underlying - (element-by-element) function :math:`N` times. T + functions that actually implement the underlying + (element-by-element) function :math:`N` times. - :param types: + :param data: + Should be ``NULL`` or a pointer to an array of size *ntypes* + . This array may contain arbitrary extra-data to be passed to + the corresponding 1-d loop function in the func array. + :param types: Must be of length (*nin* + *nout*) \* *ntypes*, and it contains the data-types (built-in only) that the corresponding function in the *func* array can deal with. - :param data: + :param ntypes: + How many different data-type "signatures" the ufunc has implemented. - Should be ``NULL`` or a pointer to an array of size *ntypes* - . This array may contain arbitrary extra-data to be passed to - the corresponding 1-d loop function in the func array. + :param nin: + The number of inputs to this operation. - :param name: + :param nout: + The number of outputs + :param identity: + XXX: Undocumented + + :param name: The name for the ufunc. :param 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 @@ -114,7 +116,6 @@ Functions accessing the **__doc__** attribute of the ufunc. :param check_return: - Unused and present for backwards compatibility of the C-API. A corresponding *check_return* integer does exist in the ufunc structure and it does get set with this value when the ufunc diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst index 051a1c031..bb01a529a 100644 --- a/doc/source/reference/distutils.rst +++ b/doc/source/reference/distutils.rst @@ -67,223 +67,49 @@ misc_util files in the numpy distribution are good examples of how to use the :class:`Configuration` instance. - .. method:: todict() - - Return a dictionary compatible with the keyword arguments of distutils - setup function. Thus, this method may be used as - setup(\**config.todict()). - - .. method:: get_distribution() - - Return the distutils distribution object for self. - - .. method:: get_subpackage(subpackage_name, subpackage_path=None) - - Return a Configuration instance for the sub-package given. If - subpackage_path is None then the path is assumed to be the local path - plus the subpackage_name. If a setup.py file is not found in the - subpackage_path, then a default configuration is used. - - .. method:: add_subpackage(subpackage_name, subpackage_path=None) - - Add a sub-package to the current Configuration instance. This is - useful in a setup.py script for adding sub-packages to a package. The - sub-package is contained in subpackage_path / subpackage_name and this - directory may contain a setup.py script or else a default setup - (suitable for Python-code-only subpackages) is assumed. If the - subpackage_path is None, then it is assumed to be located in the local - path / subpackage_name. - - .. method:: self.add_data_files(*files) - - Add files to the list of data_files to be included with the package. - The form of each element of the files sequence is very flexible - allowing many combinations of where to get the files from the package - and where they should ultimately be installed on the system. The most - basic usage is for an element of the files argument sequence to be a - simple filename. This will cause that file from the local path to be - installed to the installation path of the self.name package (package - path). The file argument can also be a relative path in which case the - entire relative path will be installed into the package directory. - Finally, the file can be an absolute path name in which case the file - will be found at the absolute path name but installed to the package - path. - - This basic behavior can be augmented by passing a 2-tuple in as the - file argument. The first element of the tuple should specify the - relative path (under the package install directory) where the - remaining sequence of files should be installed to (it has nothing to - do with the file-names in the source distribution). The second element - of the tuple is the sequence of files that should be installed. The - files in this sequence can be filenames, relative paths, or absolute - paths. For absolute paths the file will be installed in the top-level - package installation directory (regardless of the first argument). - Filenames and relative path names will be installed in the package - install directory under the path name given as the first element of - the tuple. An example may clarify:: - - self.add_data_files('foo.dat', - ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']), - 'bar/cat.dat', - '/full/path/to/can.dat') - - will install these data files to:: - - <package install directory>/ - foo.dat - fun/ - gun.dat - nun/ - pun.dat - sun.dat - bar/ - car.dat - can.dat - - where <package install directory> is the package (or sub-package) - directory such as '/usr/lib/python2.4/site-packages/mypackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage') or '/usr/lib/python2.4/site- - packages/mypackage/mysubpackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage \\mysubpackage'). - - - An additional feature is that the path to a data-file can actually be - a function that takes no arguments and returns the actual path(s) to - the data-files. This is useful when the data files are generated while - building the package. - - .. method:: add_data_dir(data_path) - - Recursively add files under data_path to the list of data_files to be - installed (and distributed). The data_path can be either a relative - path-name, or an absolute path-name, or a 2-tuple where the first - argument shows where in the install directory the data directory - should be installed to. For example suppose the source directory - contains fun/foo.dat and fun/bar/car.dat:: - - self.add_data_dir('fun') - self.add_data_dir(('sun', 'fun')) - self.add_data_dir(('gun', '/full/path/to/fun')) - - Will install data-files to the locations:: - - <package install directory>/ - fun/ - foo.dat - bar/ - car.dat - sun/ - foo.dat - bar/ - car.dat - gun/ - foo.dat - car.dat - - .. method:: add_include_dirs(*paths) - - Add the given sequence of paths to the beginning of the include_dirs - list. This list will be visible to all extension modules of the - current package. - - .. method:: add_headers(*files) - - Add the given sequence of files to the beginning of the headers list. - By default, headers will be installed under <python- - include>/<self.name.replace('.','/')>/ directory. If an item of files - is a tuple, then its first argument specifies the actual installation - location relative to the <python-include> path. - - .. method:: add_extension(name, sources, **kw) - - Create and add an Extension instance to the ext_modules list. The - first argument defines the name of the extension module that will be - installed under the self.name package. The second argument is a list - of sources. This method also takes the following optional keyword - arguments that are passed on to the Extension constructor: - include_dirs, define_macros, undef_macros, library_dirs, libraries, - runtime_library_dirs, extra_objects, swig_opts, depends, language, - f2py_options, module_dirs, and extra_info. - - The self.paths(...) method is applied to all lists that may contain - paths. The extra_info is a dictionary or a list of dictionaries whose - content will be appended to the keyword arguments. The depends list - contains paths to files or directories that the sources of the - extension module depend on. If any path in the depends list is newer - than the extension module, then the module will be rebuilt. - - The list of sources may contain functions (called source generators) - which must take an extension instance and a build directory as inputs - and return a source file or list of source files or None. If None is - returned then no sources are generated. If the Extension instance has - no sources after processing all source generators, then no extension - module is built. + .. automethod:: todict - .. method:: add_library(name, sources, **build_info) + .. automethod:: get_distribution - Add a library to the list of libraries. Allowed keyword arguments are - depends, macros, include_dirs, extra_compiler_args, and f2py_options. - The name is the name of the library to be built and sources is a list - of sources (or source generating functions) to add to the library. + .. automethod:: get_subpackage - .. method:: add_scripts(*files) + .. automethod:: add_subpackage - Add the sequence of files to the beginning of the scripts list. - Scripts will be installed under the <prefix>/bin/ directory. + .. automethod:: add_data_files - .. method:: paths(*paths) + .. automethod:: add_data_dir - Applies glob.glob(...) to each path in the sequence (if needed) and - pre-pends the local_path if needed. Because this is called on all - source lists, this allows wildcard characters to be specified in lists - of sources for extension modules and libraries and scripts and allows - path-names be relative to the source directory. + .. automethod:: add_include_dirs - .. method:: get_config_cmd() + .. automethod:: add_headers - Returns the numpy.distutils config command instance. + .. automethod:: add_extension - .. method:: get_build_temp_dir() + .. automethod:: add_library - Return a path to a temporary directory where temporary files should be - placed. + .. automethod:: add_scripts - .. method:: have_f77c() + .. automethod:: add_installed_library - True if a Fortran 77 compiler is available (because a simple Fortran - 77 code was able to be compiled successfully). + .. automethod:: add_npy_pkg_config - .. method:: have_f90c() + .. automethod:: paths - True if a Fortran 90 compiler is available (because a simple Fortran - 90 code was able to be compiled successfully) + .. automethod:: get_config_cmd - .. method:: get_version() + .. automethod:: get_build_temp_dir - Return a version string of the current package or None if the version - information could not be detected. This method scans files named - __version__.py, <packagename>_version.py, version.py, and - __svn_version__.py for string variables version, __version\__, and - <packagename>_version, until a version number is found. + .. automethod:: have_f77c - .. method:: make_svn_version_py() + .. automethod:: have_f90c - Appends a data function to the data_files list that will generate - __svn_version__.py file to the current package directory. This file - will be removed from the source directory when Python exits (so that - it can be re-generated next time the package is built). This is - intended for working with source directories that are in an SVN - repository. + .. automethod:: get_version - .. method:: make_config_py() + .. automethod:: make_svn_version_py - Generate a package __config__.py file containing system information - used during the building of the package. This file is installed to the - package installation directory. - - .. method:: get_info(*names) - - Return information (from system_info.get_info) for all of the names in - the argument list in a single dictionary. + .. automethod:: make_config_py + .. automethod:: get_info Other modules ------------- @@ -299,6 +125,83 @@ Other modules log.set_verbosity exec_command +Building Installable C libraries +================================ + +Conventional C libraries (installed through add_library) are not installed, and +are just used during the build (they are statically linked). An installable C +library is a pure C library, which does not depend on the python C runtime, and +is installed such as it may be used by third-party packages. To build and +install the C library, you just use the method add_installed_library instead of +add_library, which takes the same arguments except for an additional +install_dir argument:: + + >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib') + +npy-pkg-config files +-------------------- + +To make the necessary build options available to third parties, you could use +the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is +based on an .ini file which contains all the options. A .ini file is very +similar to .pc files as used by the pkg-config unix utility:: + + [meta] + Name: foo + Version: 1.0 + Description: foo library + + [variables] + prefix = /home/user/local + libdir = ${prefix}/lib + includedir = ${prefix}/include + + [default] + cflags = -I${includedir} + libs = -L${libdir} -lfoo + +Generally, the file needs to be generated during the build, since it needs some +information known at build time only (e.g. prefix). This is mostly automatic if +one uses the Configuration method add_npy_pkg_config. Assuming we have a +template file foo.ini.in as follows:: + + [meta] + Name: foo + Version: @version@ + Description: foo library + + [variables] + prefix = @prefix@ + libdir = ${prefix}/lib + includedir = ${prefix}/include + + [default] + cflags = -I${includedir} + libs = -L${libdir} -lfoo + +and the following code in setup.py:: + + >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib') + >>> subst = {'version': '1.0'} + >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst) + +This will install the file foo.ini into the directory package_dir/lib, and the +foo.ini file will be generated from foo.ini.in, where each @version@ will be +replaced by subst_dict['version']. The dictionary has an additional prefix +substitution rule automatically added, which contains the install prefix (since +this is not easy to get from setup.py). npy-pkg-config files can also be +installed at the same location as used for numpy, using the path returned from +get_npy_pkg_dir function. + +Reusing a C library from another package +---------------------------------------- + +Info are easily retrieved from the get_info function in numpy.distutils.misc_util:: + + >>> info = get_info('npymath') + >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info) + +An additional list of paths to look for .ini files can be given to get_info. Conversion of ``.src`` files ============================ diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 0d83053ac..00317a18e 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -19,7 +19,6 @@ For learning how to use NumPy, see also :ref:`user`. arrays ufuncs - generalized_ufuncs routines ctypes distutils @@ -37,8 +36,6 @@ the functions are written by numerous contributors and developers of Numpy, both prior to and during the `Numpy Documentation Marathon <http://scipy.org/Developer_Zone/DocMarathon2008>`__. -The Documentation Marathon is still ongoing. Please help us write -better documentation for Numpy by joining it! Instructions on how to -join and what to do can be found +Please help to improve NumPy's documentation! Instructions on how to +join the ongoing documentation marathon can be found `on the scipy.org website <http://scipy.org/Developer_Zone/DocMarathon2008>`__ - diff --git a/doc/source/reference/routines.indexing.rst b/doc/source/reference/routines.indexing.rst index f618fa0a4..9d8fde882 100644 --- a/doc/source/reference/routines.indexing.rst +++ b/doc/source/reference/routines.indexing.rst @@ -21,6 +21,13 @@ Generating index arrays ix_ ogrid unravel_index + diag_indices + diag_indices_from + mask_indices + tril_indices + tril_indices_from + triu_indices + triu_indices_from Indexing-like operations ------------------------ @@ -42,6 +49,7 @@ Inserting data into arrays place put putmask + fill_diagonal Iterating over arrays --------------------- diff --git a/doc/source/reference/routines.set.rst b/doc/source/reference/routines.set.rst index 4c298e80f..27c6aeb89 100644 --- a/doc/source/reference/routines.set.rst +++ b/doc/source/reference/routines.set.rst @@ -8,16 +8,15 @@ Making proper sets .. autosummary:: :toctree: generated/ - unique1d + unique Boolean operations ------------------ .. autosummary:: :toctree: generated/ + in1d intersect1d - intersect1d_nu setdiff1d - setmember1d setxor1d union1d diff --git a/doc/source/reference/routines.statistics.rst b/doc/source/reference/routines.statistics.rst index b41b62839..578cbd09a 100644 --- a/doc/source/reference/routines.statistics.rst +++ b/doc/source/reference/routines.statistics.rst @@ -35,6 +35,7 @@ Correlating :toctree: generated/ corrcoef + acorrelate correlate cov diff --git a/doc/source/reference/routines.testing.rst b/doc/source/reference/routines.testing.rst index 5a5f4cb8c..075c1e3a9 100644 --- a/doc/source/reference/routines.testing.rst +++ b/doc/source/reference/routines.testing.rst @@ -29,6 +29,7 @@ Decorators .. autosummary:: :toctree: generated/ + decorators.deprecated decorators.knownfailureif decorators.setastest decorators.skipif diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index d63486342..8096e1497 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -102,19 +102,24 @@ Output type determination The output of the ufunc (and its methods) is not necessarily an :class:`ndarray`, if all input arguments are not :class:`ndarrays <ndarray>`. -All output arrays will be passed to the :obj:`__array_wrap__` -method of the input (besides :class:`ndarrays <ndarray>`, and scalars) -that defines it **and** has the highest :obj:`__array_priority__` of -any other input to the universal function. The default -:obj:`__array_priority__` of the ndarray is 0.0, and the default -:obj:`__array_priority__` of a subtype is 1.0. Matrices have -:obj:`__array_priority__` equal to 10.0. +All output arrays will be passed to the :obj:`__array_prepare__` and +:obj:`__array_wrap__` methods of the input (besides +:class:`ndarrays <ndarray>`, and scalars) that defines it **and** has +the highest :obj:`__array_priority__` of any other input to the +universal function. The default :obj:`__array_priority__` of the +ndarray is 0.0, and the default :obj:`__array_priority__` of a subtype +is 1.0. Matrices have :obj:`__array_priority__` equal to 10.0. The ufuncs can also all take output arguments. The output will be cast if necessary to the provided output array. If a class with an :obj:`__array__` method is used for the output, results will be written to the object returned by :obj:`__array__`. Then, if the class -also has an :obj:`__array_wrap__` method, the returned +also has an :obj:`__array_prepare__` method, it is called so metadata +may be determined based on the context of the ufunc (the context +consisting of the ufunc itself, the arguments passed to the ufunc, and +the ufunc domain.) The array object returned by +:obj:`__array_prepare__` is passed to the ufunc for computation. +Finally, if the class also has an :obj:`__array_wrap__` method, the returned :class:`ndarray` result will be passed to that method just before passing control back to the caller. @@ -549,6 +554,7 @@ single operation. isinf isnan signbit + copysign modf ldexp frexp |