diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.datetime.rst | 3 | ||||
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 44 | ||||
| -rw-r--r-- | doc/source/reference/internals.code-explanations.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/maskedarray.generic.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/routines.linalg.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.logic.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.math.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.polynomials.classes.rst | 48 | ||||
| -rw-r--r-- | doc/source/reference/routines.testing.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 18 |
10 files changed, 77 insertions, 51 deletions
diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst index 139f23f11..e64d0c17e 100644 --- a/doc/source/reference/arrays.datetime.rst +++ b/doc/source/reference/arrays.datetime.rst @@ -363,7 +363,8 @@ As a corollary to this change, we no longer prohibit casting between datetimes with date units and datetimes with timeunits. With timezone naive datetimes, the rule for casting from dates to times is no longer ambiguous. -pandas_: http://pandas.pydata.org +.. _pandas: http://pandas.pydata.org + Differences Between 1.6 and 1.7 Datetimes ========================================= diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 35df42daa..90bb56b2d 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -137,7 +137,7 @@ sub-types). .. c:function:: npy_intp PyArray_Size(PyArrayObject* obj) - Returns 0 if *obj* is not a sub-class of bigndarray. Otherwise, + Returns 0 if *obj* is not a sub-class of ndarray. Otherwise, returns the total number of elements in the array. Safer version of :c:func:`PyArray_SIZE` (*obj*). @@ -257,7 +257,7 @@ From scratch PyTypeObject* subtype, int nd, npy_intp* dims, int type_num, \ npy_intp* strides, void* data, int itemsize, int flags, PyObject* obj) - This is similar to :c:func:`PyArray_DescrNew` (...) except you + This is similar to :c:func:`PyArray_NewFromDescr` (...) except you specify the data-type descriptor with *type_num* and *itemsize*, where *type_num* corresponds to a builtin (or user-defined) type. If the type always has the same number of bytes, then @@ -303,7 +303,7 @@ From scratch .. c:function:: PyArray_FILLWBYTE(PyObject* obj, int val) Fill the array pointed to by *obj* ---which must be a (subclass - of) bigndarray---with the contents of *val* (evaluated as a byte). + of) ndarray---with the contents of *val* (evaluated as a byte). This macro calls memset, so obj must be contiguous. .. c:function:: PyObject* PyArray_Zeros( \ @@ -433,9 +433,9 @@ From other objects .. c:var:: NPY_ARRAY_ENSUREARRAY - Make sure the result is a base-class ndarray or bigndarray. By - default, if *op* is an instance of a subclass of the - bigndarray, an instance of that same subclass is returned. If + Make sure the result is a base-class ndarray. By + default, if *op* is an instance of a subclass of + ndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead. .. c:var:: NPY_ARRAY_FORCECAST @@ -455,8 +455,7 @@ From other objects is deleted (presumably after your calculations are complete), its contents will be copied back into *op* and the *op* array will be made writeable again. If *op* is not writeable to begin - with, then an error is raised. If *op* is not already an array, - then this flag has no effect. + with, or if it is not already an array, then an error is raised. .. c:var:: NPY_ARRAY_BEHAVED @@ -1483,8 +1482,7 @@ specify desired properties of the new array. .. c:var:: NPY_ARRAY_ENSUREARRAY - Make sure the resulting object is an actual ndarray (or bigndarray), - and not a sub-class. + Make sure the resulting object is an actual ndarray, and not a sub-class. .. c:var:: NPY_ARRAY_NOTSWAPPED @@ -2888,10 +2886,10 @@ to. to a C-array of :c:type:`npy_intp`. The Python object could also be a single number. The *seq* variable is a pointer to a structure with members ptr and len. On successful return, *seq* ->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. + pointer to memory that must be freed, by calling :c:func:`PyDimMem_FREE`, + 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. .. c:function:: int PyArray_BufferConverter(PyObject* obj, PyArray_Chunk* buf) @@ -3064,6 +3062,24 @@ the C-API is needed then some additional steps must be taken. header file as long as you make sure that NO_IMPORT_ARRAY is #defined before #including that file. + Internally, these #defines work as follows: + + * If neither is defined, the C-API is declared to be + :c:type:`static void**`, so it is only visible within the + compilation unit that #includes numpy/arrayobject.h. + * If :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, but + :c:macro:`NO_IMPORT_ARRAY` is not, the C-API is declared to + be :c:type:`void**`, so that it will also be visible to other + compilation units. + * If :c:macro:`NO_IMPORT_ARRAY` is #defined, regardless of + whether :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is, the C-API is + declared to be :c:type:`extern void**`, so it is expected to + be defined in another compilation unit. + * Whenever :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, it + also changes the name of the variable holding the C-API, which + defaults to :c:data:`PyArray_API`, to whatever the macro is + #defined to. + Checking the API Version ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/reference/internals.code-explanations.rst b/doc/source/reference/internals.code-explanations.rst index af34d716f..94e827429 100644 --- a/doc/source/reference/internals.code-explanations.rst +++ b/doc/source/reference/internals.code-explanations.rst @@ -105,7 +105,7 @@ which work very simply. 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 +counter is smaller than 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, @@ -369,7 +369,7 @@ 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 completion of the -function, it's contents will be copied back into the output array. +function, its contents will be copied back into the output array. Iterators for the output arguments are then processed. Finally, the decision is made about how to execute the looping @@ -475,7 +475,7 @@ function is called with just the ndarray as the first argument. Methods ------- -Their are three methods of ufuncs that require calculation similar to +There 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 diff --git a/doc/source/reference/maskedarray.generic.rst b/doc/source/reference/maskedarray.generic.rst index adb51416a..1fee9a74a 100644 --- a/doc/source/reference/maskedarray.generic.rst +++ b/doc/source/reference/maskedarray.generic.rst @@ -379,8 +379,8 @@ is masked. When accessing a slice, the output is a masked array whose :attr:`~MaskedArray.data` attribute is a view of the original data, and whose mask is either :attr:`nomask` (if there was no invalid entries in the original -array) or a copy of the corresponding slice of the original mask. The copy is -required to avoid propagation of any modification of the mask to the original. +array) or a view of the corresponding slice of the original mask. The view is +required to ensure propagation of any modification of the mask to the original. >>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1]) >>> mx = x[:3] diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst index 09c7d9b4e..4715f636e 100644 --- a/doc/source/reference/routines.linalg.rst +++ b/doc/source/reference/routines.linalg.rst @@ -18,6 +18,7 @@ Matrix and vector products matmul tensordot einsum + einsum_path linalg.matrix_power kron diff --git a/doc/source/reference/routines.logic.rst b/doc/source/reference/routines.logic.rst index 88edde855..7fa0cd1de 100644 --- a/doc/source/reference/routines.logic.rst +++ b/doc/source/reference/routines.logic.rst @@ -19,6 +19,7 @@ Array contents isfinite isinf isnan + isnat isneginf isposinf diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst index a2fb06958..4c2f2800a 100644 --- a/doc/source/reference/routines.math.rst +++ b/doc/source/reference/routines.math.rst @@ -108,6 +108,7 @@ Arithmetic operations add reciprocal + positive negative multiply divide diff --git a/doc/source/reference/routines.polynomials.classes.rst b/doc/source/reference/routines.polynomials.classes.rst index 0db77eb7c..f44ddd46c 100644 --- a/doc/source/reference/routines.polynomials.classes.rst +++ b/doc/source/reference/routines.polynomials.classes.rst @@ -52,7 +52,7 @@ the conventional Polynomial class because of its familiarity:: >>> from numpy.polynomial import Polynomial as P >>> p = P([1,2,3]) >>> p - Polynomial([ 1., 2., 3.], [-1., 1.], [-1., 1.]) + Polynomial([ 1., 2., 3.], domain=[-1, 1], window=[-1, 1]) Note that there are three parts to the long version of the printout. The first is the coefficients, the second is the domain, and the third is the @@ -77,19 +77,19 @@ we ignore them and run through the basic algebraic and arithmetic operations. Addition and Subtraction:: >>> p + p - Polynomial([ 2., 4., 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 2., 4., 6.], domain=[-1, 1], window=[-1, 1]) >>> p - p - Polynomial([ 0.], [-1., 1.], [-1., 1.]) + Polynomial([ 0.], domain=[-1, 1], window=[-1, 1]) Multiplication:: >>> p * p - Polynomial([ 1., 4., 10., 12., 9.], [-1., 1.], [-1., 1.]) + Polynomial([ 1., 4., 10., 12., 9.], domain=[-1, 1], window=[-1, 1]) Powers:: >>> p**2 - Polynomial([ 1., 4., 10., 12., 9.], [-1., 1.], [-1., 1.]) + Polynomial([ 1., 4., 10., 12., 9.], domain=[-1, 1], window=[-1, 1]) Division: @@ -100,20 +100,20 @@ versions the '/' will only work for division by scalars. At some point it will be deprecated:: >>> p // P([-1, 1]) - Polynomial([ 5., 3.], [-1., 1.], [-1., 1.]) + Polynomial([ 5., 3.], domain=[-1, 1], window=[-1, 1]) Remainder:: >>> p % P([-1, 1]) - Polynomial([ 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 6.], domain=[-1, 1], window=[-1, 1]) Divmod:: >>> quo, rem = divmod(p, P([-1, 1])) >>> quo - Polynomial([ 5., 3.], [-1., 1.], [-1., 1.]) + Polynomial([ 5., 3.], domain=[-1, 1], window=[-1, 1]) >>> rem - Polynomial([ 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 6.], domain=[-1, 1], window=[-1, 1]) Evaluation:: @@ -134,7 +134,7 @@ the polynomials are regarded as functions this is composition of functions:: >>> p(p) - Polynomial([ 6., 16., 36., 36., 27.], [-1., 1.], [-1., 1.]) + Polynomial([ 6., 16., 36., 36., 27.], domain=[-1, 1], window=[-1, 1]) Roots:: @@ -148,11 +148,11 @@ tuples, lists, arrays, and scalars are automatically cast in the arithmetic operations:: >>> p + [1, 2, 3] - Polynomial([ 2., 4., 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 2., 4., 6.], domain=[-1, 1], window=[-1, 1]) >>> [1, 2, 3] * p - Polynomial([ 1., 4., 10., 12., 9.], [-1., 1.], [-1., 1.]) + Polynomial([ 1., 4., 10., 12., 9.], domain=[-1, 1], window=[-1, 1]) >>> p / 2 - Polynomial([ 0.5, 1. , 1.5], [-1., 1.], [-1., 1.]) + Polynomial([ 0.5, 1. , 1.5], domain=[-1, 1], window=[-1, 1]) Polynomials that differ in domain, window, or class can't be mixed in arithmetic:: @@ -180,7 +180,7 @@ conversion of Polynomial classes among themselves is done for type, domain, and window casting:: >>> p(T([0, 1])) - Chebyshev([ 2.5, 2. , 1.5], [-1., 1.], [-1., 1.]) + Chebyshev([ 2.5, 2. , 1.5], domain=[-1, 1], window=[-1, 1]) 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 @@ -195,18 +195,18 @@ Polynomial instances can be integrated and differentiated.:: >>> from numpy.polynomial import Polynomial as P >>> p = P([2, 6]) >>> p.integ() - Polynomial([ 0., 2., 3.], [-1., 1.], [-1., 1.]) + Polynomial([ 0., 2., 3.], domain=[-1, 1], window=[-1, 1]) >>> p.integ(2) - Polynomial([ 0., 0., 1., 1.], [-1., 1.], [-1., 1.]) + Polynomial([ 0., 0., 1., 1.], domain=[-1, 1], window=[-1, 1]) 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.:: >>> p.integ(lbnd=-1) - Polynomial([-1., 2., 3.], [-1., 1.], [-1., 1.]) + Polynomial([-1., 2., 3.], domain=[-1, 1], window=[-1, 1]) >>> p.integ(lbnd=-1, k=1) - Polynomial([ 0., 2., 3.], [-1., 1.], [-1., 1.]) + Polynomial([ 0., 2., 3.], domain=[-1, 1], window=[-1, 1]) In the first case the lower bound of the integration is set to -1 and the integration constant is 0. In the second the constant of integration is set @@ -215,9 +215,9 @@ number of times the polynomial is differentiated:: >>> p = P([1, 2, 3]) >>> p.deriv(1) - Polynomial([ 2., 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 2., 6.], domain=[-1, 1], window=[-1, 1]) >>> p.deriv(2) - Polynomial([ 6.], [-1., 1.], [-1., 1.]) + Polynomial([ 6.], domain=[-1, 1], window=[-1, 1]) Other Polynomial Constructors @@ -233,9 +233,9 @@ are demonstrated below:: >>> from numpy.polynomial import Chebyshev as T >>> p = P.fromroots([1, 2, 3]) >>> p - Polynomial([ -6., 11., -6., 1.], [-1., 1.], [-1., 1.]) + Polynomial([ -6., 11., -6., 1.], domain=[-1, 1], window=[-1, 1]) >>> p.convert(kind=T) - Chebyshev([ -9. , 11.75, -3. , 0.25], [-1., 1.], [-1., 1.]) + Chebyshev([ -9. , 11.75, -3. , 0.25], domain=[-1, 1], window=[-1, 1]) The convert method can also convert domain and window:: @@ -249,9 +249,9 @@ available. The cast method works like the convert method while the basis method returns the basis polynomial of given degree:: >>> P.basis(3) - Polynomial([ 0., 0., 0., 1.], [-1., 1.], [-1., 1.]) + Polynomial([ 0., 0., 0., 1.], domain=[-1, 1], window=[-1, 1]) >>> T.cast(p) - Chebyshev([ -9. , 11.75, -3. , 0.25], [-1., 1.], [-1., 1.]) + Chebyshev([ -9. , 11.75, -3. , 0.25], domain=[-1, 1], window=[-1, 1]) Conversions between types can be useful, but it is *not* recommended for routine use. The loss of numerical precision in passing from a diff --git a/doc/source/reference/routines.testing.rst b/doc/source/reference/routines.testing.rst index c43aeeed9..ad95bb399 100644 --- a/doc/source/reference/routines.testing.rst +++ b/doc/source/reference/routines.testing.rst @@ -41,7 +41,6 @@ Decorators decorators.slow decorate_methods - Test Running ------------ .. autosummary:: @@ -50,3 +49,4 @@ Test Running Tester run_module_suite rundocs + suppress_warnings diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index b3fb4d384..e28496cf6 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -426,12 +426,14 @@ Methods All ufuncs have four methods. However, these methods only make sense on ufuncs that take two input arguments and return one output argument. Attempting to call these methods on other ufuncs will cause a -:exc:`ValueError`. The reduce-like methods all take an *axis* keyword -and a *dtype* keyword, and the arrays must all have dimension >= 1. +:exc:`ValueError`. The reduce-like methods all take an *axis* keyword, a *dtype* +keyword, and an *out* keyword, and the arrays must all have dimension >= 1. The *axis* keyword specifies the axis of the array over which the reduction -will take place and may be negative, but must be an integer. The -*dtype* keyword allows you to manage a very common problem that arises -when naively using :ref:`{op}.reduce <ufunc.reduce>`. Sometimes you may +will take place (with negative values counting backwards). Generally, it is an +integer, though for :meth:`ufunc.reduce`, it can also be a tuple of `int` to +reduce over several axes at once, or `None`, to reduce over all axes. +The *dtype* keyword allows you to manage a very common problem that arises +when naively using :meth:`ufunc.reduce`. Sometimes you may have an array of a certain data type and wish to add up all of its elements, but the result does not fit into the data type of the array. This commonly happens if you have an array of single-byte @@ -443,7 +445,10 @@ mostly up to you. There is one exception: if no *dtype* is given for a reduction on the "add" or "multiply" operations, then if the input type is an integer (or Boolean) data-type and smaller than the size of the :class:`int_` data type, it will be internally upcast to the :class:`int_` -(or :class:`uint`) data-type. +(or :class:`uint`) data-type. Finally, the *out* keyword allows you to provide +an output array (for single-output ufuncs, which are currently the only ones +supported; for future extension, however, a tuple with a single argument +can be passed in). If *out* is given, the *dtype* argument is ignored. Ufuncs also have a fifth method that allows in place operations to be performed using fancy indexing. No buffering is used on the dimensions where @@ -660,6 +665,7 @@ single operation. isfinite isinf isnan + isnat fabs signbit copysign |