diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.classes.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/arrays.indexing.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/arrays.ndarray.rst | 44 | ||||
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 44 | ||||
| -rw-r--r-- | doc/source/reference/c-api.iterator.rst | 11 | ||||
| -rw-r--r-- | doc/source/reference/c-api.types-and-structures.rst | 10 | ||||
| -rw-r--r-- | doc/source/reference/c-api.ufunc.rst | 10 | ||||
| -rw-r--r-- | doc/source/reference/routines.linalg.rst | 18 | ||||
| -rw-r--r-- | doc/source/reference/routines.math.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/routines.polynomials.classes.rst | 34 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 10 |
11 files changed, 146 insertions, 43 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index b35e36545..5cdadd40e 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -340,7 +340,7 @@ The default iterator of an ndarray object is the default Python iterator of a sequence type. Thus, when the array object itself is used as an iterator. The default behavior is equivalent to:: - for i in xrange(arr.shape[0]): + for i in range(arr.shape[0]): val = arr[i] This default iterator selects a sub-array of dimension :math:`N-1` diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst index f8966f5c1..e759b6ff8 100644 --- a/doc/source/reference/arrays.indexing.rst +++ b/doc/source/reference/arrays.indexing.rst @@ -170,8 +170,8 @@ concepts to remember include: .. data:: newaxis - The :const:`newaxis` object can be used in the basic slicing syntax - discussed above. :const:`None` can also be used instead of + The :const:`newaxis` object can be used in all slicing operations + as discussed above. :const:`None` can also be used instead of :const:`newaxis`. diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 535ce8faa..5a528cbf6 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -115,7 +115,7 @@ 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) schemes are just specific kinds of -strided scheme, and correspond to the strides: +strided scheme, and correspond to memory that can be *addressed* by the strides: .. math:: @@ -124,12 +124,51 @@ strided scheme, and correspond to the strides: .. index:: single-segment, contiguous, non-contiguous -where :math:`d_j` = `self.itemsize * self.shape[j]`. +where :math:`d_j` `= self.itemsize * self.shape[j]`. 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. +While a C-style and Fortran-style contiguous array, which has the corresponding +flags set, can be addressed with the above strides, the actual strides may be +different. This can happen in two cases: + 1. If ``self.shape[k] == 1`` then for any legal index ``index[k] == 0``. + This means that in the formula for the offset + :math:`n_k = 0` and thus :math:`s_k n_k = 0` and the value of + :math:`s_k` `= self.strides[k]` is arbitrary. + 2. If an array has no elements (``self.size == 0``) there is no legal index + and the strides are never used. Any array with no elements may be + considered C-style and Fortran-style contiguous. + +Point 1. means that ``self``and ``self.squeeze()`` always have the same +contiguity and :term:`aligned` flags value. This also means that even a high +dimensional array could be C-style and Fortran-style contiguous at the same +time. + +.. index:: aligned + +An array is considered aligned if the memory offsets for all elements and the +base offset itself is a multiple of `self.itemsize`. + +.. note:: + + Points (1) and (2) are not yet applied by default. Beginning with + Numpy 1.8.0, they are applied consistently only if the environment + variable ``NPY_RELAXED_STRIDES_CHECKING=1`` was defined when NumPy + was built. Eventually this will become the default. + + You can check whether this option was enabled when your NumPy was + built by looking at the value of ``np.ones((10,1), + order='C').flags.f_contiguous``. If this is ``True``, then your + NumPy has relaxed strides checking enabled. + +.. warning:: + + It does *not* generally hold that ``self.strides[-1] == self.itemsize`` + for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for + Fortran-style contiguous arrays is true. + Data in new :class:`ndarrays <ndarray>` is in the :term:`row-major` (C) order, unless otherwise specified, but, for example, :ref:`basic array slicing <arrays.indexing>` often produces :term:`views <view>` @@ -144,7 +183,6 @@ in a different scheme. irregularly strided array is passed in to such algorithms, a copy is automatically made. - .. _arrays.ndarray.attributes: Array attributes diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 85cf3c317..cef400fad 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -165,13 +165,13 @@ with misaligned data. at least *aobj* ->nd in size). You may want to typecast the returned pointer to the data type of the ndarray. -.. cfunction:: void* PyArray_GETPTR1(PyObject* obj, <npy_intp> i) +.. cfunction:: void* PyArray_GETPTR1(PyArrayObject* obj, npy_intp i) -.. cfunction:: void* PyArray_GETPTR2(PyObject* obj, <npy_intp> i, <npy_intp> j) +.. cfunction:: void* PyArray_GETPTR2(PyArrayObject* obj, npy_intp i, npy_intp j) -.. cfunction:: void* PyArray_GETPTR3(PyObject* obj, <npy_intp> i, <npy_intp> j, <npy_intp> k) +.. cfunction:: void* PyArray_GETPTR3(PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k) -.. cfunction:: void* PyArray_GETPTR4(PyObject* obj, <npy_intp> i, <npy_intp> j, <npy_intp> k, <npy_intp> l) +.. cfunction:: void* PyArray_GETPTR4(PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k, npy_intp l) Quick, inline access to the element at the given coordinates in the ndarray, *obj*, which must have respectively 1, 2, 3, or 4 @@ -1062,7 +1062,7 @@ Converting data types *arr* is an array scalar (has 0 dimensions), it finds the data type of smallest size to which the value may be converted without overflow or truncation to an integer. - + This function will not demote complex to float or anything to boolean, but will demote a signed integer to an unsigned integer when the scalar value is positive. @@ -1088,7 +1088,7 @@ Converting data types Categories are determined by first checking which of boolean, integer (int/uint), or floating point (float/complex) the maximum kind of all the arrays and the scalars are. - + If there are only scalars or the maximum category of the scalars is higher than the maximum category of the arrays, the data types are combined with :cfunc:`PyArray_PromoteTypes` @@ -1310,11 +1310,21 @@ of the constant names is deprecated in 1.7. The data area is in Fortran-style contiguous order (first index varies the fastest). -Notice that contiguous 1-d arrays are always both Fortran contiguous -and C contiguous. Both of these flags can be checked and are convenience -flags only as whether or not an array is :cdata:`NPY_ARRAY_C_CONTIGUOUS` -or :cdata:`NPY_ARRAY_F_CONTIGUOUS` can be determined by the ``strides``, -``dimensions``, and ``itemsize`` attributes. +.. note:: + + Arrays can be both C-style and Fortran-style contiguous simultaneously. + This is clear for 1-dimensional arrays, but can also be true for higher + dimensional arrays. + + Even for contiguous arrays a stride for a given dimension + ``arr.strides[dim]`` may be *arbitrary* if ``arr.shape[dim] == 1`` + or the array has no elements. + It does *not* generally hold that ``self.strides[-1] == self.itemsize`` + for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for + Fortran-style contiguous arrays is true. The correct way to access the + ``itemsize`` of an array from the C API is ``PyArray_ITEMSIZE(arr)``. + + .. seealso:: :ref:`Internal memory layout of an ndarray <arrays.ndarray>` .. cvar:: NPY_ARRAY_OWNDATA @@ -1322,7 +1332,7 @@ or :cdata:`NPY_ARRAY_F_CONTIGUOUS` can be determined by the ``strides``, .. cvar:: NPY_ARRAY_ALIGNED - The data area is aligned appropriately (for all strides). + The data area and all array elements are aligned appropriately. .. cvar:: NPY_ARRAY_WRITEABLE @@ -1432,14 +1442,20 @@ For all of these macros *arr* must be an instance of a (subclass of) :cdata:`NPY_ARRAY_OWNDATA`, :cdata:`NPY_ARRAY_ALIGNED`, :cdata:`NPY_ARRAY_WRITEABLE`, :cdata:`NPY_ARRAY_UPDATEIFCOPY`. -.. cfunction:: PyArray_ISCONTIGUOUS(arr) +.. cfunction:: PyArray_IS_C_CONTIGUOUS(arr) Evaluates true if *arr* is C-style contiguous. -.. cfunction:: PyArray_ISFORTRAN(arr) +.. cfunction:: PyArray_IS_F_CONTIGUOUS(arr) Evaluates true if *arr* is Fortran-style contiguous. +.. cfunction:: PyArray_ISFORTRAN(arr) + + Evaluates true if *arr* is Fortran-style contiguous and *not* + C-style contiguous. :cfunc:`PyArray_IS_F_CONTIGUOUS` + is the correct way to test for Fortran-style contiguity. + .. cfunction:: PyArray_ISWRITEABLE(arr) Evaluates true if the data area of *arr* can be written to diff --git a/doc/source/reference/c-api.iterator.rst b/doc/source/reference/c-api.iterator.rst index 7e2900bcc..1e3565bc1 100644 --- a/doc/source/reference/c-api.iterator.rst +++ b/doc/source/reference/c-api.iterator.rst @@ -634,12 +634,12 @@ Construction and Destruction Extends :cfunc:`NpyIter_MultiNew` with several advanced options providing more control over broadcasting and buffering. - If 0/NULL values are passed to ``oa_ndim``, ``op_axes``, ``itershape``, + If -1/NULL values are passed to ``oa_ndim``, ``op_axes``, ``itershape``, and ``buffersize``, it is equivalent to :cfunc:`NpyIter_MultiNew`. - The parameter ``oa_ndim``, when non-zero, specifies the number of + The parameter ``oa_ndim``, when not zero or -1, specifies the number of dimensions that will be iterated with customized broadcasting. - If it is provided, ``op_axes`` and/or ``itershape`` must also be provided. + If it is provided, ``op_axes`` must and ``itershape`` can also be provided. The ``op_axes`` parameter let you control in detail how the axes of the operand arrays get matched together and iterated. In ``op_axes``, you must provide an array of ``nop`` pointers @@ -649,6 +649,11 @@ Construction and Destruction -1 which means ``newaxis``. Within each ``op_axes[j]`` array, axes may not be repeated. The following example is how normal broadcasting applies to a 3-D array, a 2-D array, a 1-D array and a scalar. + + **Note**: Before NumPy 1.8 ``oa_ndim == 0` was used for signalling that + that ``op_axes`` and ``itershape`` are unused. This is deprecated and + should be replaced with -1. Better backward compatibility may be + achieved by using :cfunc:`NpyIter_MultiNew` for this case. .. code-block:: c diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index 07c7e07be..79a888912 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -652,6 +652,8 @@ PyUFunc_Type void *ptr; PyObject *obj; PyObject *userloops; + npy_uint32 *op_flags; + npy_uint32 *iter_flags; } PyUFuncObject; .. cmacro:: PyUFuncObject.PyObject_HEAD @@ -755,6 +757,14 @@ PyUFunc_Type numbers are always larger than :cdata:`NPY_USERDEF`. + .. cmember:: npy_uint32 PyUFuncObject.op_flags + + Override the default operand flags for each ufunc operand. + + .. cmember:: npy_uint32 PyUFuncObject.iter_flags + + Override the default nditer flags for the ufunc. + PyArrayIter_Type ---------------- diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index 45268b261..d4de28188 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -140,6 +140,16 @@ Functions in as *arg_types* which must be a pointer to memory at least as large as ufunc->nargs. +.. cfunction:: int PyUFunc_RegisterLoopForDescr(PyUFuncObject* ufunc, + PyArray_Descr* userdtype, PyUFuncGenericFunction function, + PyArray_Descr** arg_dtypes, void* data) + + This function behaves like PyUFunc_RegisterLoopForType above, except + that it allows the user to register a 1-d loop using PyArray_Descr + objects instead of dtype type num values. This allows a 1-d loop to be + registered for structured array data-dtypes and custom data-types + instead of scalar data-types. + .. cfunction:: int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, PyUFuncGenericFunction newfunc, int* signature, PyUFuncGenericFunction* oldfunc) diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst index 173a6ad53..00620347a 100644 --- a/doc/source/reference/routines.linalg.rst +++ b/doc/source/reference/routines.linalg.rst @@ -67,3 +67,21 @@ Exceptions :toctree: generated/ linalg.LinAlgError + +Linear algebra on several matrices at once +------------------------------------------ + +Several of the linear algebra routines listed above are able to +compute results for several matrices at once, if they are stacked into +the same array. + +This is indicated in the documentation via input parameter +specifications such as ``a : (..., M, M) array_like``. This means that +if for instance given an input array ``a.shape == (N, M, M)``, it is +interpreted as a "stack" of N matrices, each of size M-by-M. Similar +specification applies to return values, for instance the determinant +has ``det : (...)`` and will in this case return an array of shape +``det(a).shape == (N,)``. This generalizes to linear algebra +operations on higher-dimensional arrays: the last 1 or 2 dimensions of +a multidimensional array are interpreted as vectors or matrices, as +appropriate for each operation. diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst index 7ce77c24d..0e7a60b76 100644 --- a/doc/source/reference/routines.math.rst +++ b/doc/source/reference/routines.math.rst @@ -143,6 +143,8 @@ Miscellaneous sign maximum minimum + fmax + fmin nan_to_num real_if_close diff --git a/doc/source/reference/routines.polynomials.classes.rst b/doc/source/reference/routines.polynomials.classes.rst index 9294728c8..14729f08b 100644 --- a/doc/source/reference/routines.polynomials.classes.rst +++ b/doc/source/reference/routines.polynomials.classes.rst @@ -30,10 +30,10 @@ and more generally .. math:: p(x) = \sum_{i=0}^n c_i T_i(x) -where in this case the :math:`T_n` are the Chebyshev functions of degree -`n`, but could just as easily be the basis functions of any of the other -classes. The convention for all the classes is that the coefficient -c[i] goes with the basis function of degree i. +where in this case the :math:`T_n` are the Chebyshev functions of +degree :math:`n`, but could just as easily be the basis functions of +any of the other classes. The convention for all the classes is that +the coefficient :math:`c[i]` goes with the basis function of degree i. All of the classes have the same methods, and especially they implement the Python numeric operators +, -, \*, //, %, divmod, \*\*, ==, @@ -47,7 +47,7 @@ Basics First we need a polynomial class and a polynomial instance to play with. The classes can be imported directly from the polynomial package or from the module of the relevant type. Here we import from the package and use -the conventional Polynomial class because of its familiarity.:: +the conventional Polynomial class because of its familiarity:: >>> from numpy.polynomial import Polynomial as P >>> p = P([1,2,3]) @@ -93,7 +93,7 @@ Powers:: Division: -Floor_division, '//', is the division operator for the polynomial classes, +Floor division, '//', is the division operator for the polynomial classes, polynomials are treated like integers in this regard. For Python versions < 3.x the '/' operator maps to '//', as it does for Python, for later versions the '/' will only work for division by scalars. At some point it @@ -182,7 +182,7 @@ and window casting:: >>> p(T([0, 1])) Chebyshev([ 2.5, 2. , 1.5], [-1., 1.], [-1., 1.]) -Which gives the polynomial 'p' in Chebyshev form. This works because +Which gives the polynomial `p` in Chebyshev form. This works because :math:`T_1(x) = x` and substituting :math:`x` for :math:`x` doesn't change the original polynomial. However, all the multiplications and divisions will be done using Chebyshev series, hence the type of the result. @@ -199,7 +199,7 @@ Polynomial instances can be integrated and differentiated.:: >>> p.integ(2) Polynomial([ 0., 0., 1., 1.], [-1., 1.], [-1., 1.]) -The first example integrates 'p' once, the second example integrates it +The first example integrates `p` once, the second example integrates it twice. By default, the lower bound of the integration and the integration constant are 0, but both can be specified.:: @@ -227,7 +227,7 @@ Constructing polynomials by specifying coefficients is just one way of obtaining a polynomial instance, they may also be created by specifying their roots, by conversion from other polynomial types, and by least squares fits. Fitting is discussed in its own section, the other methods -are demonstrated below.:: +are demonstrated below:: >>> from numpy.polynomial import Polynomial as P >>> from numpy.polynomial import Chebyshev as T @@ -244,9 +244,9 @@ The convert method can also convert domain and window:: >>> p.convert(kind=P, domain=[0, 1]) Polynomial([-1.875, 2.875, -1.125, 0.125], [ 0., 1.], [-1., 1.]) -In numpy versions >= 1.7.0 the 'basis' and 'cast' class methods are also +In numpy versions >= 1.7.0 the `basis` and `cast` class methods are also available. The cast method works like the convert method while the basis -method returns the basis polynomial of given degree.:: +method returns the basis polynomial of given degree:: >>> P.basis(3) Polynomial([ 0., 0., 0., 1.], [-1., 1.], [-1., 1.]) @@ -276,8 +276,8 @@ polynomials up to degree 5 are plotted below. <matplotlib.legend.Legend object at 0x3b3ee10> >>> plt.show() -In the range -1 <= x <= 1 they are nice, equiripple functions lying between +/- 1. -The same plots over the range -2 <= x <= 2 look very different: +In the range -1 <= `x` <= 1 they are nice, equiripple functions lying between +/- 1. +The same plots over the range -2 <= `x` <= 2 look very different: .. plot:: @@ -291,17 +291,17 @@ The same plots over the range -2 <= x <= 2 look very different: >>> plt.show() As can be seen, the "good" parts have shrunk to insignificance. In using -Chebyshev polynomials for fitting we want to use the region where x is -between -1 and 1 and that is what the 'window' specifies. However, it is +Chebyshev polynomials for fitting we want to use the region where `x` is +between -1 and 1 and that is what the `window` specifies. However, it is unlikely that the data to be fit has all its data points in that interval, -so we use 'domain' to specify the interval where the data points lie. When +so we use `domain` to specify the interval where the data points lie. When the fit is done, the domain is first mapped to the window by a linear transformation and the usual least squares fit is done using the mapped data points. The window and domain of the fit are part of the returned series and are automatically used when computing values, derivatives, and such. If they aren't specified in the call the fitting routine will use the default window and the smallest domain that holds all the data points. This is -illustrated below for a fit to a noisy sin curve. +illustrated below for a fit to a noisy sine curve. .. plot:: diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index afcb1302b..2154bca37 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -321,9 +321,9 @@ advanced usage and will not typically be used. Specifies the calculation iteration order/memory layout of the output array. Defaults to 'K'. 'C' means the output should be C-contiguous, 'F' means - F-contiguous, 'A' means F-contiguous if the inputs are F-contiguous, C-contiguous - otherwise, and 'K' means to match the element ordering of the inputs - as closely as possible. + F-contiguous, 'A' means F-contiguous if the inputs are F-contiguous and + not also not C-contiguous, C-contiguous otherwise, and 'K' means to match + the element ordering of the inputs as closely as possible. *dtype* @@ -604,6 +604,10 @@ Comparison functions ``a > b`` and uses it to return either `a` or `b` (as a whole). A similar difference exists between ``minimum(a, b)`` and ``min(a, b)``. +.. autosummary:: + + fmax + fmin Floating functions ------------------ |