From f72c60510a225f242a36cdbbc3aacf1b36f05f22 Mon Sep 17 00:00:00 2001 From: David Warde-Farley Date: Fri, 7 Jan 2011 13:36:18 -0500 Subject: ENH: Add minlength keyword to bincount. Patch from ticket #1595. --- numpy/add_newdocs.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index baf5285f0..d7a8569fa 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -3796,12 +3796,15 @@ add_newdoc('numpy.lib._compiled_base', 'digitize', add_newdoc('numpy.lib._compiled_base', 'bincount', """ - bincount(x, weights=None) + bincount(x, weights=None, minlength=None) Count number of occurrences of each value in array of non-negative ints. The number of bins (of size 1) is one larger than the largest value in - `x`. Each bin gives the number of occurrences of its index value in `x`. + `x`. If `minlength` is specified, there will be at least this number + of bins in the output array (though it will be longer if necessary, + depending on the contents of `x`). + Each bin gives the number of occurrences of its index value in `x`. If `weights` is specified the input array is weighted by it, i.e. if a value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead of ``out[n] += 1``. @@ -3812,6 +3815,8 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', Input array. weights : array_like, optional Weights, array of the same shape as `x`. + minlength : integer, optional + A minimum number of bins for the output array. Returns ------- @@ -3823,7 +3828,7 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', ------ ValueError If the input is not 1-dimensional, or contains elements with negative - values. + values, or if `minlength` is non-positive. TypeError If the type of the input is float or complex. -- cgit v1.2.1 From 165d98d9a574aaba367f20b4fcd8dec7fda0bafb Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Sun, 16 Jan 2011 01:48:42 -0800 Subject: ENH: core: Switch nonzero to use the iterator as an example, add count_nonzero function --- numpy/add_newdocs.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index baf5285f0..2faf3ba16 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -481,6 +481,35 @@ add_newdoc('numpy.core.multiarray', 'zeros', """) +add_newdoc('numpy.core.multiarray', 'count_nonzero', + """ + count_nonzero(a) + + Counts the number of non-zero values in the array ``a``. + + Parameters + ---------- + a : array_like + The array for which to count non-zeros. + + Returns + ------- + count : int + Number of non-zero values in the array. + + See Also + -------- + nonzero : Return the coordinates of all the non-zero values. + + Examples + -------- + >>> np.count_nonzero(np.eye(4)) + 4 + + >>> np.count_nonzero([[0,1,7,0,0],[3,0,0,2,19]]) + 5 + """) + add_newdoc('numpy.core.multiarray','set_typeDict', """set_typeDict(dict) -- cgit v1.2.1 From e916b9e44c1732fba94393056f80093a0e775134 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Mon, 17 Jan 2011 17:06:54 -0800 Subject: ENH: core: Change PyArray_CopyAnyInto and PyArray_MoveAnyInto to use the new iterator I also found that the tricky case of CopyAnyInto wasn't being triggered by the test suite, so added a new function ndarray.setasflat, which calls CopyAnyInto. --- numpy/add_newdocs.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 2faf3ba16..5e6a07bb0 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -2642,6 +2642,37 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset', """)) +add_newdoc('numpy.core.multiarray', 'ndarray', ('setasflat', + """ + a.setasflat(arr) + + Equivalent to a.flat = arr.flat, but is generally more efficient. + This function does not check for overlap, so if ``arr`` and ``a`` + are viewing the same data with different strides, the results will + be unpredictable. + + Parameters + ---------- + arr : array_like + The array to copy into a. + + Examples + -------- + >>> a = np.arange(2*4).reshape(2,4)[:,:-1]; a + array([[0, 1, 2], + [4, 5, 6]]) + >>> b = np.arange(3*3, dtype='f4').reshape(3,3).T[::-1,:-1]; b + array([[ 2., 5.], + [ 1., 4.], + [ 0., 3.]], dtype=float32) + >>> a.setasflat(b) + >>> a + array([[2, 5, 1], + [4, 0, 3]]) + + """)) + + add_newdoc('numpy.core.multiarray', 'ndarray', ('max', """ a.max(axis=None, out=None) -- cgit v1.2.1 From ee06d183c407ea315b2eb3ef41ee422b0ea30251 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 18 Jan 2011 12:13:32 -0800 Subject: ENH: core: Start converting ufunc to new iterator, add PyArray_PromoteTypes --- numpy/add_newdocs.py | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 5e6a07bb0..92e438249 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1176,6 +1176,46 @@ add_newdoc('numpy.core.multiarray', 'can_cast', >>> np.can_cast('i4', 'S4') True + """) + +add_newdoc('numpy.core.multiarray', 'promote_types', + """ + promote_types(type1, type2) + + Returns the data type with the smallest size and smallest scalar + kind to which both ``type1`` and ``type2`` may be safely cast. + The returned data type is always in native byte order. Promotion of + string, unicode and void with numbers is disallowed. + + Parameters + ---------- + type1 : dtype or dtype specifier + First data type. + type2 : dtype or dtype specifier + Second data type. + + Returns + ------- + out : dtype + The promoted data type. + + Examples + -------- + >>> np.promote_types('f4', 'f8') + dtype('float64') + + >>> np.promote_types('i8', 'f4') + dtype('float64') + + >>> np.promote_types('>i8', '>> np.promote_types('i1', 'S8') + Traceback (most recent call last): + File "", line 1, in + TypeError: invalid type promotion + + """) add_newdoc('numpy.core.multiarray','newbuffer', -- cgit v1.2.1 From 81a28e7309e13f0a22464697b14c2c7d4c272ea5 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 18 Jan 2011 13:41:14 -0800 Subject: ENH: core: Add PyArray_MinScalarType and expose it to Python --- numpy/add_newdocs.py | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 92e438249..a3381d47e 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1214,7 +1214,44 @@ add_newdoc('numpy.core.multiarray', 'promote_types', Traceback (most recent call last): File "", line 1, in TypeError: invalid type promotion + """) + +add_newdoc('numpy.core.multiarray', 'min_scalar_type', + """ + min_scalar_type(a) + For scalar ``a``, returns the data type with the smallest size + and smallest scalar kind which can hold its value. For vector ``a``, + returns the vector's dtype unmodified. + + As a special case, floating point values are not reduced to integers. + + Parameters + ---------- + a : scalar or array_like + The value whose minimal data type is to be found. + + Returns + ------- + out : dtype + The minimal data type. + + Examples + -------- + >>> np.min_scalar_type(10) + dtype('uint8') + + >>> np.min_scalar_type(-260) + dtype('int16') + + >>> np.min_scalar_type(3.1) + dtype('float16') + + >>> np.min_scalar_type(1e50) + dtype('float64') + + >>> np.min_scalar_type(np.arange(4,dtype='f8')) + dtype('float64') """) -- cgit v1.2.1 From beba8f4e7c7071d0619558a66f0a096ca705c1c5 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 18 Jan 2011 17:52:42 -0800 Subject: ENH: core: Add functions PyArray_CanCastArrayTo and PyArray_ResultType They have also been exposed to Python. --- numpy/add_newdocs.py | 102 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 3 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index a3381d47e..0f58f66a2 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1144,9 +1144,12 @@ add_newdoc('numpy.core.multiarray', 'lexsort', add_newdoc('numpy.core.multiarray', 'can_cast', """ - can_cast(fromtype, totype) + can_cast(from, totype, casting = 'safe') - Returns True if cast between data types can occur without losing precision. + Returns True if cast between data types can occur according to the + casting rule. If from is a scalar or array scalar, also returns + True if the scalar value can be cast without overflow or truncation + to an integer. Parameters ---------- @@ -1154,14 +1157,19 @@ add_newdoc('numpy.core.multiarray', 'can_cast', Data type to cast from. totype : dtype or dtype specifier Data type to cast to. + casting : casting rule + May be any of 'no', 'equiv', 'safe', 'same_kind', or 'unsafe'. Returns ------- out : bool - True if cast can occur without losing precision. + True if cast can occur according to the casting rule. Examples -------- + + Basic examples + >>> np.can_cast(np.int32, np.int64) True >>> np.can_cast(np.float64, np.complex) @@ -1176,6 +1184,52 @@ add_newdoc('numpy.core.multiarray', 'can_cast', >>> np.can_cast('i4', 'S4') True + Casting scalars + + >>> np.can_cast(100, 'i1') + True + >>> np.can_cast(150, 'i1') + False + >>> np.can_cast(150, 'u1') + True + + >>> np.can_cast(3.5e100, np.float32) + False + >>> np.can_cast(1000.0, np.float32) + True + + Array scalar checks the value, array does not + + >>> np.can_cast(np.array(1000.0), np.float32) + True + >>> np.can_cast(np.array([1000.0]), np.float32) + False + + Using the casting rules + + >>> np.can_cast('i8', 'i8', 'no') + True + >>> np.can_cast('i8', 'no') + False + + >>> np.can_cast('i8', 'equiv') + True + >>> np.can_cast('i8', 'equiv') + False + + >>> np.can_cast('i8', 'safe') + True + >>> np.can_cast('i4', 'safe') + False + + >>> np.can_cast('i4', 'same_kind') + True + >>> np.can_cast('u4', 'same_kind') + False + + >>> np.can_cast('u4', 'unsafe') + True + """) add_newdoc('numpy.core.multiarray', 'promote_types', @@ -1255,6 +1309,48 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type', """) +add_newdoc('numpy.core.multiarray', 'result_type', + """ + result_type(*arrays_and_dtypes) + + Returns the type that results from applying the NumPy + type promotion rules to the arguments. + + Type promotion in NumPy works similarly to the rules in languages + like C++, with some slight differences. When both scalars and + arrays are used, the array's type takes precedence and the actual value + of the scalar is taken into account. + + For example, calculating 3*a, where a is an array of 32-bit floats, + intuitively should result in a 32-bit float output. If the 3 is a + 32-bit integer, the NumPy rules indicate it can't convert losslessly + into a 32-bit float, so a 64-bit float should be the result type. + By examining the value of the constant, '3', we see that it fits in + an 8-bit integer, which can be cast losslessly into the 32-bit float. + + Parameters + ---------- + arrays_and_dtypes : list of arrays and dtypes + The operands of some operation whose result type is needed. + + Returns + ------- + out : dtype + The result type. + + Examples + -------- + >>> np.result_type(3, np.arange(7, dtype='i1')) + dtype('int8') + + >>> np.result_type('i4', 'c8') + dtype('complex128') + + >>> np.result_type(3.0, -2) + dtype('float64') + + """) + add_newdoc('numpy.core.multiarray','newbuffer', """newbuffer(size) -- cgit v1.2.1 From fe08a916cf275ecd21c1b32b22aa3b8d2ca36b33 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 18 Jan 2011 20:14:07 -0800 Subject: ENH: iter: Switch the iterator to use PyArray_ResultType --- numpy/add_newdocs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 0f58f66a2..db84046cb 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1275,8 +1275,8 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type', min_scalar_type(a) For scalar ``a``, returns the data type with the smallest size - and smallest scalar kind which can hold its value. For vector ``a``, - returns the vector's dtype unmodified. + and smallest scalar kind which can hold its value. For non-scalar + array ``a``, returns the vector's dtype unmodified. As a special case, floating point values are not reduced to integers. -- cgit v1.2.1 From 5435bdc0a23b26455f6a47d93e39e02b394b0503 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Mon, 24 Jan 2011 17:08:06 -0800 Subject: DOC: core: Document the new einsum function --- numpy/add_newdocs.py | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index db84046cb..854338a9c 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -826,6 +826,7 @@ add_newdoc('numpy.core', 'inner', -------- tensordot : Sum products over arbitrary axes. dot : Generalised matrix product, using second last dimension of `b`. + einsum : Einstein summation convention. Notes ----- @@ -1429,6 +1430,7 @@ add_newdoc('numpy.core', 'dot', -------- vdot : Complex-conjugating dot product. tensordot : Sum products over arbitrary axes. + einsum : Einstein summation convention. Examples -------- @@ -1457,6 +1459,149 @@ add_newdoc('numpy.core', 'dot', """) +add_newdoc('numpy.core', 'einsum', + """ + einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe') + + Evaluates the Einstein summation convention on the operands. + + Using the Einstein summation convention, many common multi-dimensional + array operations can be represented in a simple fashion. This function + provides a way compute such summations. + + The best way to understand this function is to try the examples below, + which show how many common NumPy functions can be implemented as + calls to einsum. + + The subscripts string is a comma-separated list of subscript labels, + where each label refers to a dimension of the corresponding operand. + Repeated subscripts labels in one operand take the diagonal. For example, + ``np.einsum('ii', a)`` is equivalent to ``np.trace(a)``. + + Whenever a label is repeated, it is summed, so ``np.einsum('i,i', a, b)`` + is equivalent to ``np.inner(a,b)``. If a label appears only once, + it is not summed, so ``np.einsum('i', a)`` produces a view of ``a`` + with no changes. + + The order of labels in the output is by default alphabetical. This + means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while + ``np.einsum('ji', a)`` takes its transpose. + + The output can be controlled by specifying output subscript labels + as well. This specifies the label order, and allows summing to be + disallowed or forced when desired. The call ``np.einsum('i->', a)`` + is equivalent to ``np.sum(a, axis=-1)``, and + ``np.einsum('ii->i', a)`` is equivalent to ``np.diag(a)``. + + It is also possible to control how broadcasting occurs using + an ellipsis. To take the trace along the first and last axes, + you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix + product with the left-most indices instead of rightmost, you can do + ``np.einsum('ij...,jk...->ik...', a, b)``. + + When there is only one operand, no axes are summed, and no output + parameter is provided, a view into the operand is returned instead + of a new array. Thus, taking the diagonal as ``np.einsum('ii->i', a)`` + produces a view. + + Parameters + ---------- + subscripts : string + Specifies the subscripts for summation. + operands : list of array_like + These are the arrays for the operation. + out : None or array + If provided, the calculation is done into this array. + dtype : None or data type + If provided, forces the calculation to use the data type specified. + order : 'C', 'F', 'A', or 'K' + Controls the memory layout of the output. + casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe' + Controls what kind of data casting may occur. Setting this to + 'unsafe' is not recommended, as it can adversely affect accumulations. + + Returns + ------- + output : ndarray + The calculation based on the Einstein summation convention. + + See Also + -------- + dot, inner, outer, tensordot + + + Examples + -------- + + >>> a = np.arange(25).reshape(5,5) + >>> b = np.arange(5) + >>> c = np.arange(6).reshape(2,3) + + >>> np.einsum('ii', a) + 60 + >>> np.trace(a) + 60 + + >>> np.einsum('ii->i', a) + array([ 0, 6, 12, 18, 24]) + >>> np.diag(a) + array([ 0, 6, 12, 18, 24]) + + >>> np.einsum('ij,j', a, b) + array([ 30, 80, 130, 180, 230]) + >>> np.dot(a, b) + array([ 30, 80, 130, 180, 230]) + + >>> np.einsum('ji', c) + array([[0, 3], + [1, 4], + [2, 5]]) + >>> c.T + array([[0, 3], + [1, 4], + [2, 5]]) + + >>> np.einsum(',', 3, c) + array([[ 0, 3, 6], + [ 9, 12, 15]]) + >>> np.multiply(3, c) + array([[ 0, 3, 6], + [ 9, 12, 15]]) + + >>> np.einsum('i,i', b, b) + 30 + >>> np.inner(b,b) + 30 + + >>> np.einsum('i,j', np.arange(2)+1, b) + array([[0, 1, 2, 3, 4], + [0, 2, 4, 6, 8]]) + >>> np.outer(np.arange(2)+1, b) + array([[0, 1, 2, 3, 4], + [0, 2, 4, 6, 8]]) + + >>> np.einsum('i...->', a) + array([50, 55, 60, 65, 70]) + >>> np.sum(a, axis=0) + array([50, 55, 60, 65, 70]) + + >>> a = np.arange(60.).reshape(3,4,5) + >>> b = np.arange(24.).reshape(4,3,2) + >>> np.einsum('ijk,jil->kl', a, b) + array([[ 4400., 4730.], + [ 4532., 4874.], + [ 4664., 5018.], + [ 4796., 5162.], + [ 4928., 5306.]]) + >>> np.tensordot(a,b, axes=([1,0],[0,1])) + array([[ 4400., 4730.], + [ 4532., 4874.], + [ 4664., 5018.], + [ 4796., 5162.], + [ 4928., 5306.]]) + + """) + add_newdoc('numpy.core', 'alterdot', """ Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions. -- cgit v1.2.1 From 3e58b8db5d2ff4b850f63373e1b1d1c812454264 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 25 Jan 2011 23:23:30 -0800 Subject: ENH: core: Make NumPy trunk ABI-compatible with 1.5 --- numpy/add_newdocs.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 854338a9c..9bd714a8a 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1514,11 +1514,22 @@ add_newdoc('numpy.core', 'einsum', If provided, the calculation is done into this array. dtype : None or data type If provided, forces the calculation to use the data type specified. + Note that you may have to also give a more liberal ``casting`` + parameter to allow the conversions. order : 'C', 'F', 'A', or 'K' - Controls the memory layout of the output. + Controls the memory layout of the output. 'C' means it should + be Fortran contiguous. 'F' means it should be Fortran contiguous, + 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. + 'K' means it should be as close to the layout as the inputs as + is possible, including arbitrarily permuted axes. casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe' Controls what kind of data casting may occur. Setting this to 'unsafe' is not recommended, as it can adversely affect accumulations. + 'no' means the data types should not be cast at all. 'equiv' means + only byte-order changes are allowed. 'safe' means only casts + which can preserve values are allowed. 'same_kind' means only + safe casts or casts within a kind, like float64 to float32, are + allowed. 'unsafe' means any data conversions may be done. Returns ------- -- cgit v1.2.1 From 01c78669494a05a539cdbb83614b6c3312e5401e Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Wed, 26 Jan 2011 20:58:35 -0800 Subject: ENH: ufunc: Add new iterator version of generalized ufuncs --- numpy/add_newdocs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 9bd714a8a..c3876afb0 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1518,7 +1518,7 @@ add_newdoc('numpy.core', 'einsum', parameter to allow the conversions. order : 'C', 'F', 'A', or 'K' Controls the memory layout of the output. 'C' means it should - be Fortran contiguous. 'F' means it should be Fortran contiguous, + be C contiguous. 'F' means it should be Fortran contiguous, 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. 'K' means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. -- cgit v1.2.1 From 779b01b039e05150ec21047fc04061fab55e5f42 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Thu, 27 Jan 2011 11:00:07 -0800 Subject: WRN: iter: Fix half-float warnings, other small tweaks --- numpy/add_newdocs.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index c3876afb0..095eba15d 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1239,8 +1239,7 @@ add_newdoc('numpy.core.multiarray', 'promote_types', Returns the data type with the smallest size and smallest scalar kind to which both ``type1`` and ``type2`` may be safely cast. - The returned data type is always in native byte order. Promotion of - string, unicode and void with numbers is disallowed. + The returned data type is always in native byte order. Parameters ---------- @@ -1279,7 +1278,8 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type', and smallest scalar kind which can hold its value. For non-scalar array ``a``, returns the vector's dtype unmodified. - As a special case, floating point values are not reduced to integers. + As a special case, floating point values are not demoted to integers, + and complex values are not demoted to floats. Parameters ---------- -- cgit v1.2.1 From c9d1849332ae5bf73299ea1268f6a55f78624688 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Fri, 28 Jan 2011 12:43:22 -0800 Subject: ENH: core: Add dtype= and order= parameters to zeros_like, ones_like, and empty_like --- numpy/add_newdocs.py | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 095eba15d..28eead38c 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -413,6 +413,58 @@ add_newdoc('numpy.core.multiarray', 'empty', """) +add_newdoc('numpy.core.multiarray', 'empty_like', + """ + empty_like(a, dtype=None, order='K') + + Return a new array with the same shape and type as a given array. + + Parameters + ---------- + a : array_like + The shape and data-type of `a` define these same attributes of the + returned array. + dtype : data-type, optional + Overrides the data type of the result. + order : {'C', 'F', 'A', or 'K'}, optional + Overrides the memory layout of the result. 'C' means C-order, + 'F' means F-order, 'A' means 'F' if ``a`` is Fortran contiguous, + 'C' otherwise. 'K' means match the layout of ``a`` as closely + as possible. + + Returns + ------- + out : ndarray + Array of uninitialized (arbitrary) data with the same + shape and type as `a`. + + See Also + -------- + ones_like : Return an array of ones with shape and type of input. + zeros_like : Return an array of zeros with shape and type of input. + empty : Return a new uninitialized array. + ones : Return a new array setting values to one. + zeros : Return a new array setting values to zero. + + Notes + ----- + This function does *not* initialize the returned array; to do that use + `zeros_like` or `ones_like` instead. It may be marginally faster than + the functions that do set the array values. + + Examples + -------- + >>> a = ([1,2,3], [4,5,6]) # a is array-like + >>> np.empty_like(a) + array([[-1073741821, -1073741821, 3], #random + [ 0, 0, -1073741821]]) + >>> a = np.array([[1., 2., 3.],[4.,5.,6.]]) + >>> np.empty_like(a) + array([[ -2.00000715e+000, 1.48219694e-323, -2.00000572e+000],#random + [ 4.38791518e-305, -2.00000715e+000, 4.17269252e-309]]) + + """) + add_newdoc('numpy.core.multiarray', 'scalar', """ -- cgit v1.2.1 From abcdd9a62a1f83fa5d233477442cf0a34bde2143 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Mon, 31 Jan 2011 09:13:57 -0800 Subject: ENH: einsum: Disable broadcasting by default, allow spaces in subscripts string --- numpy/add_newdocs.py | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 51826c5ff..f51860240 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1540,13 +1540,16 @@ add_newdoc('numpy.core', 'einsum', ``np.einsum('ji', a)`` takes its transpose. The output can be controlled by specifying output subscript labels - as well. This specifies the label order, and allows summing to be - disallowed or forced when desired. The call ``np.einsum('i->', a)`` - is equivalent to ``np.sum(a, axis=-1)``, and - ``np.einsum('ii->i', a)`` is equivalent to ``np.diag(a)``. - - It is also possible to control how broadcasting occurs using - an ellipsis. To take the trace along the first and last axes, + as well. This specifies the label order, and allows summing to + be disallowed or forced when desired. The call ``np.einsum('i->', a)`` + is like ``np.sum(a, axis=-1)``, and ``np.einsum('ii->i', a)`` + is like ``np.diag(a)``. The difference is that ``einsum`` does not + allow broadcasting by default. + + To enable and control broadcasting, use an ellipsis. Default + NumPy-style broadcasting is done by adding an ellipsis + to the left of each term, like ``np.einsum('...ii->...i', a)``. + To take the trace along the first and last axes, you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix product with the left-most indices instead of rightmost, you can do ``np.einsum('ij...,jk...->ik...', a, b)``. @@ -1624,7 +1627,7 @@ add_newdoc('numpy.core', 'einsum', [1, 4], [2, 5]]) - >>> np.einsum(',', 3, c) + >>> np.einsum('..., ...', 3, c) array([[ 0, 3, 6], [ 9, 12, 15]]) >>> np.multiply(3, c) @@ -1643,7 +1646,7 @@ add_newdoc('numpy.core', 'einsum', array([[0, 1, 2, 3, 4], [0, 2, 4, 6, 8]]) - >>> np.einsum('i...->', a) + >>> np.einsum('i...->...', a) array([50, 55, 60, 65, 70]) >>> np.sum(a, axis=0) array([50, 55, 60, 65, 70]) -- cgit v1.2.1 From cdb0a56c8551182e566f0308fd9f4515d5e95d89 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Mon, 31 Jan 2011 12:22:39 -0800 Subject: ENH: einsum: Add alternative einsum parameter method This makes the following equivalent: einsum('ii', a) einsum(a, [0,0]) einsum('ii->i', a) einsum(a, [0,0], [0]) einsum('...i,...i->...', a, b) einsum(a, [Ellipsis,0], b, [Ellipsis,0], [Ellipsis]) --- numpy/add_newdocs.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index f51860240..e749784d5 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1517,6 +1517,10 @@ add_newdoc('numpy.core', 'einsum', Evaluates the Einstein summation convention on the operands. + An alternative way to provide the subscripts and operands is as + einsum(op0, sublist0, op1, sublist1, ..., [sublistout]). The examples + below have corresponding einsum calls with the two parameter methods. + Using the Einstein summation convention, many common multi-dimensional array operations can be represented in a simple fashion. This function provides a way compute such summations. @@ -1605,20 +1609,30 @@ add_newdoc('numpy.core', 'einsum', >>> np.einsum('ii', a) 60 + >>> np.einsum(a, [0,0]) + 60 >>> np.trace(a) 60 >>> np.einsum('ii->i', a) array([ 0, 6, 12, 18, 24]) + >>> np.einsum(a, [0,0], [0]) + array([ 0, 6, 12, 18, 24]) >>> np.diag(a) array([ 0, 6, 12, 18, 24]) >>> np.einsum('ij,j', a, b) array([ 30, 80, 130, 180, 230]) + >>> np.einsum(a, [0,1], b, [1]) + array([ 30, 80, 130, 180, 230]) >>> np.dot(a, b) array([ 30, 80, 130, 180, 230]) >>> np.einsum('ji', c) + array([[0, 3], + [1, 4], + [2, 5]]) + >>> np.einsum(c, [1,0]) array([[0, 3], [1, 4], [2, 5]]) @@ -1628,6 +1642,9 @@ add_newdoc('numpy.core', 'einsum', [2, 5]]) >>> np.einsum('..., ...', 3, c) + array([[ 0, 3, 6], + [ 9, 12, 15]]) + >>> np.einsum(3, [Ellipsis], c, [Ellipsis]) array([[ 0, 3, 6], [ 9, 12, 15]]) >>> np.multiply(3, c) @@ -1636,10 +1653,15 @@ add_newdoc('numpy.core', 'einsum', >>> np.einsum('i,i', b, b) 30 + >>> np.einsum(b, [0], b, [0]) + 30 >>> np.inner(b,b) 30 >>> np.einsum('i,j', np.arange(2)+1, b) + array([[0, 1, 2, 3, 4], + [0, 2, 4, 6, 8]]) + >>> np.einsum(np.arange(2)+1, [0], b, [1]) array([[0, 1, 2, 3, 4], [0, 2, 4, 6, 8]]) >>> np.outer(np.arange(2)+1, b) @@ -1648,12 +1670,20 @@ add_newdoc('numpy.core', 'einsum', >>> np.einsum('i...->...', a) array([50, 55, 60, 65, 70]) + >>> np.einsum(a, [0,Ellipsis], [Ellipsis]) + array([50, 55, 60, 65, 70]) >>> np.sum(a, axis=0) array([50, 55, 60, 65, 70]) >>> a = np.arange(60.).reshape(3,4,5) >>> b = np.arange(24.).reshape(4,3,2) >>> np.einsum('ijk,jil->kl', a, b) + array([[ 4400., 4730.], + [ 4532., 4874.], + [ 4664., 5018.], + [ 4796., 5162.], + [ 4928., 5306.]]) + >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3]) array([[ 4400., 4730.], [ 4532., 4874.], [ 4664., 5018.], -- cgit v1.2.1 From 24392c8a4d161000dd925904f302d77b0efed219 Mon Sep 17 00:00:00 2001 From: Charles Harris Date: Fri, 4 Feb 2011 22:35:46 -0700 Subject: DOC: Note version minlength was added to bincount. --- numpy/add_newdocs.py | 1 + 1 file changed, 1 insertion(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index e749784d5..a66eb6de3 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4290,6 +4290,7 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', weights : array_like, optional Weights, array of the same shape as `x`. minlength : integer, optional + .. versionadded:: 1.6.0 A minimum number of bins for the output array. Returns -- cgit v1.2.1 From bdf25de6bf7327460cfd7a7f6fbab41eb0655f18 Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Tue, 8 Feb 2011 00:50:38 -0800 Subject: ENH: index_tricks: Implement unravel_index and ravel_coords functions in C --- numpy/add_newdocs.py | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index a66eb6de3..487ffef00 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4337,6 +4337,100 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', """) +add_newdoc('numpy.lib._compiled_base', 'ravel_coords', + """ + ravel_coords(coords, dims, mode='raise', order='C') + + Converts a tuple of coordinate arrays into an array of flat + indices, applying boundary modes to the coordinates. + + Parameters + ---------- + coords : tuple of array_like + A tuple of integer arrays, one array for each dimension. + dims : tuple of ints + The shape of an array into which indices from `coords` are for. + mode : {'raise', 'wrap', 'clip'}, optional + Specifies how out-of-bounds indices will behave. Can specify + either one mode or a tuple of modes, with length matching that + of ``dims``. + + * 'raise' -- raise an error (default) + * 'wrap' -- wrap around + * 'clip' -- clip to the range + + Note that in 'clip' mode, a negative index which would normally + wrap will clip to 0 instead. + order : {'C', 'F'}, optional + Determines whether the coords should be viewed as indexing in + C (row-major) order or FORTRAN (column-major) order. + + Returns + ------- + raveled_indices : ndarray + This is a new array with the same shape as the broadcast shape + of the arrays in ``coords``. + + See Also + -------- + unravel_index + + Examples + -------- + >>> arr = np.array([[3,6,6],[4,5,1]]) + >>> np.ravel_coords(arr, (7,6)) + array([22, 41, 37]) + >>> np.ravel_coords(arr, (7,6), order='F') + array([31, 41, 13]) + >>> np.ravel_coords(arr, (4,6), mode='clip') + array([22, 23, 19]) + >>> np.ravel_coords(arr, (4,4), mode=('clip','wrap')) + array([12, 13, 13]) + + >>> np.ravel_coords((3,1,4,1), (6,7,8,9)) + 1621 + """) + +add_newdoc('numpy.lib._compiled_base', 'unravel_index', + """ + unravel_index(indices, dims, order='C') + + Converts a flat index or array of flat indices into a tuple + of coordinate arrays. + + Parameters + ---------- + indices : array_like + An integer type array whose elements are indices for a + flattened array with shape `dims`. + dims : tuple of ints + The shape of an array into which flattened indices from + ``indices`` are for. + order : {'C', 'F'}, optional + Determines whether the indices should be viewed as indexing in + C (row-major) order or FORTRAN (column-major) order. + + Returns + ------- + unraveled_coords : tuple of ndarray + Each array in the tuple is the same shape as the input ``indices`` + array. + + See Also + -------- + ravel_coords + + Examples + -------- + >>> np.unravel_index([22, 41, 37], (7,6)) + (array([3, 6, 6]), array([4, 5, 1])) + >>> np.unravel_index([31, 41, 13], (7,6), order='F') + (array([3, 6, 6]), array([4, 5, 1])) + + >>> np.unravel_index(1621, (6,7,8,9)) + (3, 1, 4, 1) + """) + add_newdoc('numpy.lib._compiled_base', 'add_docstring', """ docstring(obj, docstring) -- cgit v1.2.1 From f30000bd09a4886f6d5dd9e1cb0ab437dc6c3f2f Mon Sep 17 00:00:00 2001 From: Mark Wiebe Date: Wed, 9 Feb 2011 21:13:54 -0800 Subject: STY: index_tricks: Improve comments and documentation strings --- numpy/add_newdocs.py | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 487ffef00..1a55b6bc7 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4349,17 +4349,16 @@ add_newdoc('numpy.lib._compiled_base', 'ravel_coords', coords : tuple of array_like A tuple of integer arrays, one array for each dimension. dims : tuple of ints - The shape of an array into which indices from `coords` are for. + The shape of array into which the indices from ``coords`` apply. mode : {'raise', 'wrap', 'clip'}, optional - Specifies how out-of-bounds indices will behave. Can specify - either one mode or a tuple of modes, with length matching that - of ``dims``. + Specifies how out-of-bounds indices are handled. Can specify + either one mode or a tuple of modes, one mode per index. * 'raise' -- raise an error (default) * 'wrap' -- wrap around * 'clip' -- clip to the range - Note that in 'clip' mode, a negative index which would normally + In 'clip' mode, a negative index which would normally wrap will clip to 0 instead. order : {'C', 'F'}, optional Determines whether the coords should be viewed as indexing in @@ -4368,13 +4367,17 @@ add_newdoc('numpy.lib._compiled_base', 'ravel_coords', Returns ------- raveled_indices : ndarray - This is a new array with the same shape as the broadcast shape - of the arrays in ``coords``. + An array of indices into the flattened version of an array + of dimensions ``dims``. See Also -------- unravel_index + Notes + ----- + .. versionadded:: 1.6.0 + Examples -------- >>> arr = np.array([[3,6,6],[4,5,1]]) @@ -4401,19 +4404,20 @@ add_newdoc('numpy.lib._compiled_base', 'unravel_index', Parameters ---------- indices : array_like - An integer type array whose elements are indices for a - flattened array with shape `dims`. + An integer array whose elements are indices into the flattened + version of an array of dimensions ``dims``. Before version 1.6.0, + this function accepted just one index value. dims : tuple of ints - The shape of an array into which flattened indices from - ``indices`` are for. + The shape of the array to use for unravelling ``indices``. order : {'C', 'F'}, optional + .. versionadded:: 1.6.0 Determines whether the indices should be viewed as indexing in C (row-major) order or FORTRAN (column-major) order. Returns ------- unraveled_coords : tuple of ndarray - Each array in the tuple is the same shape as the input ``indices`` + Each array in the tuple has the same shape as the ``indices`` array. See Also -- cgit v1.2.1 From af1e833e49dafc6d96b20de90a44633f11450b3f Mon Sep 17 00:00:00 2001 From: Luis Pedro Coelho Date: Fri, 12 Nov 2010 10:52:19 -0500 Subject: ENH: core: Allow user to pass in output array for dot() This avoids the memory allocation. It is strict in checking that the types are correct, but since it is intended as an optimisation, it should only be used when the user knows what they are doing. The out parameter is added both to the BLAS and non-BLAS versions of dot(). Tests are included. --- numpy/add_newdocs.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 1a55b6bc7..5b65d9ce1 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1447,7 +1447,7 @@ add_newdoc('numpy.core.multiarray', 'getbuffer', add_newdoc('numpy.core', 'dot', """ - dot(a, b) + dot(a, b, out=None) Dot product of two arrays. @@ -1464,6 +1464,13 @@ add_newdoc('numpy.core', 'dot', First argument. b : array_like Second argument. + out : ndarray, optional + Output argument. This must have the exact kind that would be returned + if it was not used. In particular, it must have the right type, must be + C-contiguous, and its dtype must be the dtype that would be returned + for `dot(a,b)`. This is a performance feature. Therefore, if these + conditions are not met, an exception is raised, instead of attempting + to be flexible. Returns ------- @@ -1471,6 +1478,7 @@ add_newdoc('numpy.core', 'dot', Returns the dot product of `a` and `b`. If `a` and `b` are both scalars or both 1-D arrays then a scalar is returned; otherwise an array is returned. + If `out` is given, then it is returned. Raises ------ -- cgit v1.2.1 From 4ca2465fe169576b46dee783dd0279cfd536d9c4 Mon Sep 17 00:00:00 2001 From: rgommers Date: Wed, 2 Mar 2011 12:43:47 +0800 Subject: DOC: merge more doc wiki edits. --- numpy/add_newdocs.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 5b65d9ce1..62e656346 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -2605,9 +2605,15 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('astype', Parameters ---------- - t : string or dtype + t : str or dtype Typecode or data-type to which the array is cast. + Raises + ------ + ComplexWarning : + When casting from complex to float or int. To avoid this, + one should use ``a.real.astype(t)``. + Examples -------- >>> x = np.array([1, 2, 2.5]) @@ -4297,8 +4303,9 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', Input array. weights : array_like, optional Weights, array of the same shape as `x`. - minlength : integer, optional + minlength : int, optional .. versionadded:: 1.6.0 + A minimum number of bins for the output array. Returns @@ -4330,6 +4337,9 @@ add_newdoc('numpy.lib._compiled_base', 'bincount', >>> np.bincount(x).size == np.amax(x)+1 True + The input array needs to be of integer dtype, otherwise a + TypeError is raised: + >>> np.bincount(np.arange(5, dtype=np.float)) Traceback (most recent call last): File "", line 1, in -- cgit v1.2.1 From 68e33f93d49d39cfd3789d85224a65036f03ee11 Mon Sep 17 00:00:00 2001 From: rgommers Date: Wed, 2 Mar 2011 12:55:04 +0800 Subject: DOC: merge wiki edits for numpy.core. --- numpy/add_newdocs.py | 110 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 71 insertions(+), 39 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 62e656346..c631fe3d0 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -284,6 +284,36 @@ add_newdoc('numpy.core', 'broadcast', ('size', """)) +add_newdoc('numpy.core', 'broadcast', ('reset', + """ + reset() + + Reset the broadcasted result's iterator(s). + + Parameters + ---------- + None + + Returns + ------- + None + + Examples + -------- + >>> x = np.array([1, 2, 3]) + >>> y = np.array([[4], [5], [6]] + >>> b = np.broadcast(x, y) + >>> b.index + 0 + >>> b.next(), b.next(), b.next() + ((1, 4), (2, 4), (3, 4)) + >>> b.index + 3 + >>> b.reset() + >>> b.index + 0 + + """)) ############################################################################### # @@ -330,6 +360,15 @@ add_newdoc('numpy.core.multiarray', 'array', array should have. Ones will be pre-pended to the shape as needed to meet this requirement. + Returns + ------- + out : ndarray + An array object satisfying the specified requirements. + + See Also + -------- + empty, empty_like, zeros, zeros_like, ones, ones_like, fill + Examples -------- >>> np.array([1, 2, 3]) @@ -574,28 +613,29 @@ add_newdoc('numpy.core.multiarray', 'fromstring', """ fromstring(string, dtype=float, count=-1, sep='') - Return a new 1-D array initialized from raw binary or text data in string. + A new 1-D array initialized from raw binary or text data in a string. Parameters ---------- string : str A string containing the data. - dtype : dtype, optional - The data type of the array. For binary input data, the data must be - in exactly this format. + dtype : data-type, optional + The data type of the array; default: float. For binary input data, + the data must be in exactly this format. count : int, optional - Read this number of `dtype` elements from the data. If this is - negative, then the size will be determined from the length of the - data. + Read this number of `dtype` elements from the data. If this is + negative (the default), the count will be determined from the + length of the data. sep : str, optional - If provided and not empty, then the data will be interpreted as - ASCII text with decimal numbers. This argument is interpreted as the - string separating numbers in the data. Extra whitespace between - elements is also ignored. + If not provided or, equivalently, the empty string, the data will + be interpreted as binary data; otherwise, as ASCII text with + decimal numbers. Also in this latter case, this argument is + interpreted as the string separating numbers in the data; extra + whitespace between elements is also ignored. Returns ------- - arr : array + arr : ndarray The constructed array. Raises @@ -604,6 +644,10 @@ add_newdoc('numpy.core.multiarray', 'fromstring', If the string is not the correct size to satisfy the requested `dtype` and `count`. + See Also + -------- + frombuffer, fromfile, fromiter + Examples -------- >>> np.fromstring('\\x01\\x02', dtype=np.uint8) @@ -615,17 +659,6 @@ add_newdoc('numpy.core.multiarray', 'fromstring', >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3) array([1, 2, 3], dtype=uint8) - Invalid inputs: - - >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.int32) - Traceback (most recent call last): - File "", line 1, in - ValueError: string size must be a multiple of element size - >>> np.fromstring('\\x01\\x02', dtype=np.uint8, count=3) - Traceback (most recent call last): - File "", line 1, in - ValueError: string is smaller than requested size - """) add_newdoc('numpy.core.multiarray', 'fromiter', @@ -639,9 +672,9 @@ add_newdoc('numpy.core.multiarray', 'fromiter', iterable : iterable object An iterable object providing data for the array. dtype : data-type - The data type of the returned array. + The data-type of the returned array. count : int, optional - The number of items to read from iterable. The default is -1, + The number of items to read from *iterable*. The default is -1, which means all data is read. Returns @@ -651,9 +684,8 @@ add_newdoc('numpy.core.multiarray', 'fromiter', Notes ----- - Specify ``count`` to improve performance. It allows - ``fromiter`` to pre-allocate the output array, instead of - resizing it on demand. + Specify `count` to improve performance. It allows ``fromiter`` to + pre-allocate the output array, instead of resizing it on demand. Examples -------- @@ -746,26 +778,26 @@ add_newdoc('numpy.core.multiarray', 'frombuffer', Parameters ---------- - buffer + buffer : buffer_like An object that exposes the buffer interface. dtype : data-type, optional - Data type of the returned array. + Data-type of the returned array; default: float. count : int, optional Number of items to read. ``-1`` means all data in the buffer. offset : int, optional - Start reading the buffer from this offset. + Start reading the buffer from this offset; default: 0. Notes ----- - If the buffer has data that is not in machine byte-order, this - should be specified as part of the data-type, e.g.:: + If the buffer has data that is not in machine byte-order, this should + be specified as part of the data-type, e.g.:: >>> dt = np.dtype(int) >>> dt = dt.newbyteorder('>') >>> np.frombuffer(buf, dtype=dt) - The data of the resulting array will not be byteswapped, - but will be interpreted correctly. + The data of the resulting array will not be byteswapped, but will be + interpreted correctly. Examples -------- @@ -1373,7 +1405,7 @@ add_newdoc('numpy.core.multiarray', 'result_type', like C++, with some slight differences. When both scalars and arrays are used, the array's type takes precedence and the actual value of the scalar is taken into account. - + For example, calculating 3*a, where a is an array of 32-bit floats, intuitively should result in a 32-bit float output. If the 3 is a 32-bit integer, the NumPy rules indicate it can't convert losslessly @@ -1536,12 +1568,12 @@ add_newdoc('numpy.core', 'einsum', The best way to understand this function is to try the examples below, which show how many common NumPy functions can be implemented as calls to einsum. - + The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Repeated subscripts labels in one operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent to ``np.trace(a)``. - + Whenever a label is repeated, it is summed, so ``np.einsum('i,i', a, b)`` is equivalent to ``np.inner(a,b)``. If a label appears only once, it is not summed, so ``np.einsum('i', a)`` produces a view of ``a`` @@ -1607,7 +1639,7 @@ add_newdoc('numpy.core', 'einsum', -------- dot, inner, outer, tensordot - + Examples -------- -- cgit v1.2.1 From 821afc8f1376a634612e182903c06a0c9c556d94 Mon Sep 17 00:00:00 2001 From: rgommers Date: Thu, 3 Mar 2011 14:13:28 +0800 Subject: DOC: commit some more fixes from the doc wiki. --- numpy/add_newdocs.py | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index c631fe3d0..6f9435c5c 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1337,6 +1337,11 @@ add_newdoc('numpy.core.multiarray', 'promote_types', out : dtype The promoted data type. + See Also + -------- + issctype, issubsctype, issubdtype, obj2sctype, sctype2char, + maximum_sctype, min_scalar_type + Examples -------- >>> np.promote_types('f4', 'f8') @@ -1352,6 +1357,7 @@ add_newdoc('numpy.core.multiarray', 'promote_types', Traceback (most recent call last): File "", line 1, in TypeError: invalid type promotion + """) add_newdoc('numpy.core.multiarray', 'min_scalar_type', @@ -1375,6 +1381,12 @@ add_newdoc('numpy.core.multiarray', 'min_scalar_type', out : dtype The minimal data type. + + See Also + -------- + issctype, issubsctype, issubdtype, obj2sctype, sctype2char, + maximum_sctype, promote_types + Examples -------- >>> np.min_scalar_type(10) @@ -2854,6 +2866,35 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal', """)) +add_newdoc('numpy.core.multiarray', 'ndarray', ('dot', + """ + a.dot(b, out=None) + + Dot product of two arrays. + + Refer to `numpy.dot` for full documentation. + + See Also + -------- + numpy.dot : equivalent function + + Examples + -------- + >>> a = np.eye(2) + >>> b = np.ones((2, 2)) * 2 + >>> a.dot(b) + array([[ 2., 2.], + [ 2., 2.]]) + + This array method can be conveniently chained: + + >>> a.dot(b).dot(b) + array([[ 8., 8.], + [ 8., 8.]]) + + """)) + + add_newdoc('numpy.core.multiarray', 'ndarray', ('dump', """a.dump(file) @@ -4458,9 +4499,10 @@ add_newdoc('numpy.lib._compiled_base', 'unravel_index', version of an array of dimensions ``dims``. Before version 1.6.0, this function accepted just one index value. dims : tuple of ints - The shape of the array to use for unravelling ``indices``. + The shape of the array to use for unraveling ``indices``. order : {'C', 'F'}, optional .. versionadded:: 1.6.0 + Determines whether the indices should be viewed as indexing in C (row-major) order or FORTRAN (column-major) order. @@ -4483,6 +4525,7 @@ add_newdoc('numpy.lib._compiled_base', 'unravel_index', >>> np.unravel_index(1621, (6,7,8,9)) (3, 1, 4, 1) + """) add_newdoc('numpy.lib._compiled_base', 'add_docstring', -- cgit v1.2.1 From 4b8923f63439b14fd20720f51bb0551f8ec595bc Mon Sep 17 00:00:00 2001 From: rgommers Date: Thu, 3 Mar 2011 14:19:19 +0800 Subject: DOC: merge wiki edit for einsum docstring. --- numpy/add_newdocs.py | 93 ++++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 46 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 6f9435c5c..187180c5a 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1569,18 +1569,53 @@ add_newdoc('numpy.core', 'einsum', Evaluates the Einstein summation convention on the operands. - An alternative way to provide the subscripts and operands is as - einsum(op0, sublist0, op1, sublist1, ..., [sublistout]). The examples - below have corresponding einsum calls with the two parameter methods. - Using the Einstein summation convention, many common multi-dimensional array operations can be represented in a simple fashion. This function - provides a way compute such summations. + provides a way compute such summations. The best way to understand this + function is to try the examples below, which show how many common NumPy + functions can be implemented as calls to `einsum`. + + Parameters + ---------- + subscripts : str + Specifies the subscripts for summation. + operands : list of array_like + These are the arrays for the operation. + out : ndarray, optional + If provided, the calculation is done into this array. + dtype : data-type, optional + If provided, forces the calculation to use the data type specified. + Note that you may have to also give a more liberal `casting` + parameter to allow the conversions. + order : {'C', 'F', 'A', or 'K'}, optional + Controls the memory layout of the output. 'C' means it should + be C contiguous. 'F' means it should be Fortran contiguous, + 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. + 'K' means it should be as close to the layout as the inputs as + is possible, including arbitrarily permuted axes. + Default is 'K'. + casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional + Controls what kind of data casting may occur. Setting this to + 'unsafe' is not recommended, as it can adversely affect accumulations. - The best way to understand this function is to try the examples below, - which show how many common NumPy functions can be implemented as - calls to einsum. + * 'no' means the data types should not be cast at all. + * 'equiv' means only byte-order changes are allowed. + * 'safe' means only casts which can preserve values are allowed. + * 'unsafe' means any data conversions may be done. + * 'same_kind' means only safe casts or casts within a kind, + like float64 to float32, are allowed. + + Returns + ------- + output : ndarray + The calculation based on the Einstein summation convention. + + See Also + -------- + dot, inner, outer, tensordot + Notes + ----- The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Repeated subscripts labels in one operand take the diagonal. For example, @@ -1599,7 +1634,7 @@ add_newdoc('numpy.core', 'einsum', as well. This specifies the label order, and allows summing to be disallowed or forced when desired. The call ``np.einsum('i->', a)`` is like ``np.sum(a, axis=-1)``, and ``np.einsum('ii->i', a)`` - is like ``np.diag(a)``. The difference is that ``einsum`` does not + is like ``np.diag(a)``. The difference is that `einsum` does not allow broadcasting by default. To enable and control broadcasting, use an ellipsis. Default @@ -1615,46 +1650,12 @@ add_newdoc('numpy.core', 'einsum', of a new array. Thus, taking the diagonal as ``np.einsum('ii->i', a)`` produces a view. - Parameters - ---------- - subscripts : string - Specifies the subscripts for summation. - operands : list of array_like - These are the arrays for the operation. - out : None or array - If provided, the calculation is done into this array. - dtype : None or data type - If provided, forces the calculation to use the data type specified. - Note that you may have to also give a more liberal ``casting`` - parameter to allow the conversions. - order : 'C', 'F', 'A', or 'K' - Controls the memory layout of the output. 'C' means it should - be C contiguous. 'F' means it should be Fortran contiguous, - 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. - 'K' means it should be as close to the layout as the inputs as - is possible, including arbitrarily permuted axes. - casting : 'no', 'equiv', 'safe', 'same_kind', 'unsafe' - Controls what kind of data casting may occur. Setting this to - 'unsafe' is not recommended, as it can adversely affect accumulations. - 'no' means the data types should not be cast at all. 'equiv' means - only byte-order changes are allowed. 'safe' means only casts - which can preserve values are allowed. 'same_kind' means only - safe casts or casts within a kind, like float64 to float32, are - allowed. 'unsafe' means any data conversions may be done. - - Returns - ------- - output : ndarray - The calculation based on the Einstein summation convention. - - See Also - -------- - dot, inner, outer, tensordot - + An alternative way to provide the subscripts and operands is as + ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``. The examples + below have corresponding `einsum` calls with the two parameter methods. Examples -------- - >>> a = np.arange(25).reshape(5,5) >>> b = np.arange(5) >>> c = np.arange(6).reshape(2,3) -- cgit v1.2.1 From 51b5c585890967283aa6ddcdbb9ff624f0ee4866 Mon Sep 17 00:00:00 2001 From: rgommers Date: Mon, 7 Mar 2011 12:25:37 +0800 Subject: DOC: add a few more wiki edits, and move umath docs to correct place. --- numpy/add_newdocs.py | 247 --------------------------------------------------- 1 file changed, 247 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 187180c5a..1cbf27c7d 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4046,253 +4046,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view', """)) -############################################################################## -# -# umath functions -# -############################################################################## - -add_newdoc('numpy.core.umath', 'frexp', - """ - Return normalized fraction and exponent of 2 of input array, element-wise. - - Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``. - - Parameters - ---------- - x : array_like - Input array. - - Returns - ------- - (out1, out2) : tuple of ndarrays, (float, int) - `out1` is a float array with values between -1 and 1. - `out2` is an int array which represent the exponent of 2. - - See Also - -------- - ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - Examples - -------- - >>> x = np.arange(9) - >>> y1, y2 = np.frexp(x) - >>> y1 - array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, - 0.5 ]) - >>> y2 - array([0, 1, 2, 2, 3, 3, 3, 3, 4]) - >>> y1 * 2**y2 - array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.]) - - """) - -add_newdoc('numpy.core.umath', 'frompyfunc', - """ - frompyfunc(func, nin, nout) - - Takes an arbitrary Python function and returns a Numpy ufunc. - - Can be used, for example, to add broadcasting to a built-in Python - function (see Examples section). - - Parameters - ---------- - func : Python function object - An arbitrary Python function. - nin : int - The number of input arguments. - nout : int - The number of objects returned by `func`. - - Returns - ------- - out : ufunc - Returns a Numpy universal function (``ufunc``) object. - - Notes - ----- - The returned ufunc always returns PyObject arrays. - - Examples - -------- - Use frompyfunc to add broadcasting to the Python function ``oct``: - - >>> oct_array = np.frompyfunc(oct, 1, 1) - >>> oct_array(np.array((10, 30, 100))) - array([012, 036, 0144], dtype=object) - >>> np.array((oct(10), oct(30), oct(100))) # for comparison - array(['012', '036', '0144'], - dtype='|S4') - - """) - -add_newdoc('numpy.core.umath', 'ldexp', - """ - Compute y = x1 * 2**x2. - - Parameters - ---------- - x1 : array_like - The array of multipliers. - x2 : array_like - The array of exponents. - - Returns - ------- - y : array_like - The output array, the result of ``x1 * 2**x2``. - - See Also - -------- - frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - `ldexp` is useful as the inverse of `frexp`, if used by itself it is - more clear to simply use the expression ``x1 * 2**x2``. - - Examples - -------- - >>> np.ldexp(5, np.arange(4)) - array([ 5., 10., 20., 40.], dtype=float32) - - >>> x = np.arange(6) - >>> np.ldexp(*np.frexp(x)) - array([ 0., 1., 2., 3., 4., 5.]) - - """) - -add_newdoc('numpy.core.umath', 'geterrobj', - """ - geterrobj() - - Return the current object that defines floating-point error handling. - - The error object contains all information that defines the error handling - behavior in Numpy. `geterrobj` is used internally by the other - functions that get and set error handling behavior (`geterr`, `seterr`, - `geterrcall`, `seterrcall`). - - Returns - ------- - errobj : list - The error object, a list containing three elements: - [internal numpy buffer size, error mask, error callback function]. - - The error mask is a single integer that holds the treatment information - on all four floating point errors. The information for each error type - is contained in three bits of the integer. If we print it in base 8, we - can see what treatment is set for "invalid", "under", "over", and - "divide" (in that order). The printed string can be interpreted with - - * 0 : 'ignore' - * 1 : 'warn' - * 2 : 'raise' - * 3 : 'call' - * 4 : 'print' - * 5 : 'log' - - See Also - -------- - seterrobj, seterr, geterr, seterrcall, geterrcall - getbufsize, setbufsize - - Notes - ----- - For complete documentation of the types of floating-point exceptions and - treatment options, see `seterr`. - - Examples - -------- - >>> np.geterrobj() # first get the defaults - [10000, 0, None] - - >>> def err_handler(type, flag): - ... print "Floating point error (%s), with flag %s" % (type, flag) - ... - >>> old_bufsize = np.setbufsize(20000) - >>> old_err = np.seterr(divide='raise') - >>> old_handler = np.seterrcall(err_handler) - >>> np.geterrobj() - [20000, 2, ] - - >>> old_err = np.seterr(all='ignore') - >>> np.base_repr(np.geterrobj()[1], 8) - '0' - >>> old_err = np.seterr(divide='warn', over='log', under='call', - invalid='print') - >>> np.base_repr(np.geterrobj()[1], 8) - '4351' - - """) - -add_newdoc('numpy.core.umath', 'seterrobj', - """ - seterrobj(errobj) - - Set the object that defines floating-point error handling. - - The error object contains all information that defines the error handling - behavior in Numpy. `seterrobj` is used internally by the other - functions that set error handling behavior (`seterr`, `seterrcall`). - - Parameters - ---------- - errobj : list - The error object, a list containing three elements: - [internal numpy buffer size, error mask, error callback function]. - - The error mask is a single integer that holds the treatment information - on all four floating point errors. The information for each error type - is contained in three bits of the integer. If we print it in base 8, we - can see what treatment is set for "invalid", "under", "over", and - "divide" (in that order). The printed string can be interpreted with - - * 0 : 'ignore' - * 1 : 'warn' - * 2 : 'raise' - * 3 : 'call' - * 4 : 'print' - * 5 : 'log' - - See Also - -------- - geterrobj, seterr, geterr, seterrcall, geterrcall - getbufsize, setbufsize - - Notes - ----- - For complete documentation of the types of floating-point exceptions and - treatment options, see `seterr`. - - Examples - -------- - >>> old_errobj = np.geterrobj() # first get the defaults - >>> old_errobj - [10000, 0, None] - - >>> def err_handler(type, flag): - ... print "Floating point error (%s), with flag %s" % (type, flag) - ... - >>> new_errobj = [20000, 12, err_handler] - >>> np.seterrobj(new_errobj) - >>> np.base_repr(12, 8) # int for divide=4 ('print') and over=1 ('warn') - '14' - >>> np.geterr() - {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'} - >>> np.geterrcall() is err_handler - True - - """) - - ############################################################################## # # lib._compiled_base functions -- cgit v1.2.1 From c081ad795a70fcd0168edda6d63f3ebc7c5529a7 Mon Sep 17 00:00:00 2001 From: rgommers Date: Mon, 7 Mar 2011 12:55:55 +0800 Subject: DOC: Revert part of previous commit, moving umath docs did not work. If the ldexp/frexp docs belong in ufunc_docsrtings.py, they need an entry in core/code_generators/generate_umath.py. See #1759. --- numpy/add_newdocs.py | 247 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 1cbf27c7d..187180c5a 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -4046,6 +4046,253 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view', """)) +############################################################################## +# +# umath functions +# +############################################################################## + +add_newdoc('numpy.core.umath', 'frexp', + """ + Return normalized fraction and exponent of 2 of input array, element-wise. + + Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``. + + Parameters + ---------- + x : array_like + Input array. + + Returns + ------- + (out1, out2) : tuple of ndarrays, (float, int) + `out1` is a float array with values between -1 and 1. + `out2` is an int array which represent the exponent of 2. + + See Also + -------- + ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. + + Notes + ----- + Complex dtypes are not supported, they will raise a TypeError. + + Examples + -------- + >>> x = np.arange(9) + >>> y1, y2 = np.frexp(x) + >>> y1 + array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, + 0.5 ]) + >>> y2 + array([0, 1, 2, 2, 3, 3, 3, 3, 4]) + >>> y1 * 2**y2 + array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.]) + + """) + +add_newdoc('numpy.core.umath', 'frompyfunc', + """ + frompyfunc(func, nin, nout) + + Takes an arbitrary Python function and returns a Numpy ufunc. + + Can be used, for example, to add broadcasting to a built-in Python + function (see Examples section). + + Parameters + ---------- + func : Python function object + An arbitrary Python function. + nin : int + The number of input arguments. + nout : int + The number of objects returned by `func`. + + Returns + ------- + out : ufunc + Returns a Numpy universal function (``ufunc``) object. + + Notes + ----- + The returned ufunc always returns PyObject arrays. + + Examples + -------- + Use frompyfunc to add broadcasting to the Python function ``oct``: + + >>> oct_array = np.frompyfunc(oct, 1, 1) + >>> oct_array(np.array((10, 30, 100))) + array([012, 036, 0144], dtype=object) + >>> np.array((oct(10), oct(30), oct(100))) # for comparison + array(['012', '036', '0144'], + dtype='|S4') + + """) + +add_newdoc('numpy.core.umath', 'ldexp', + """ + Compute y = x1 * 2**x2. + + Parameters + ---------- + x1 : array_like + The array of multipliers. + x2 : array_like + The array of exponents. + + Returns + ------- + y : array_like + The output array, the result of ``x1 * 2**x2``. + + See Also + -------- + frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`. + + Notes + ----- + Complex dtypes are not supported, they will raise a TypeError. + + `ldexp` is useful as the inverse of `frexp`, if used by itself it is + more clear to simply use the expression ``x1 * 2**x2``. + + Examples + -------- + >>> np.ldexp(5, np.arange(4)) + array([ 5., 10., 20., 40.], dtype=float32) + + >>> x = np.arange(6) + >>> np.ldexp(*np.frexp(x)) + array([ 0., 1., 2., 3., 4., 5.]) + + """) + +add_newdoc('numpy.core.umath', 'geterrobj', + """ + geterrobj() + + Return the current object that defines floating-point error handling. + + The error object contains all information that defines the error handling + behavior in Numpy. `geterrobj` is used internally by the other + functions that get and set error handling behavior (`geterr`, `seterr`, + `geterrcall`, `seterrcall`). + + Returns + ------- + errobj : list + The error object, a list containing three elements: + [internal numpy buffer size, error mask, error callback function]. + + The error mask is a single integer that holds the treatment information + on all four floating point errors. The information for each error type + is contained in three bits of the integer. If we print it in base 8, we + can see what treatment is set for "invalid", "under", "over", and + "divide" (in that order). The printed string can be interpreted with + + * 0 : 'ignore' + * 1 : 'warn' + * 2 : 'raise' + * 3 : 'call' + * 4 : 'print' + * 5 : 'log' + + See Also + -------- + seterrobj, seterr, geterr, seterrcall, geterrcall + getbufsize, setbufsize + + Notes + ----- + For complete documentation of the types of floating-point exceptions and + treatment options, see `seterr`. + + Examples + -------- + >>> np.geterrobj() # first get the defaults + [10000, 0, None] + + >>> def err_handler(type, flag): + ... print "Floating point error (%s), with flag %s" % (type, flag) + ... + >>> old_bufsize = np.setbufsize(20000) + >>> old_err = np.seterr(divide='raise') + >>> old_handler = np.seterrcall(err_handler) + >>> np.geterrobj() + [20000, 2, ] + + >>> old_err = np.seterr(all='ignore') + >>> np.base_repr(np.geterrobj()[1], 8) + '0' + >>> old_err = np.seterr(divide='warn', over='log', under='call', + invalid='print') + >>> np.base_repr(np.geterrobj()[1], 8) + '4351' + + """) + +add_newdoc('numpy.core.umath', 'seterrobj', + """ + seterrobj(errobj) + + Set the object that defines floating-point error handling. + + The error object contains all information that defines the error handling + behavior in Numpy. `seterrobj` is used internally by the other + functions that set error handling behavior (`seterr`, `seterrcall`). + + Parameters + ---------- + errobj : list + The error object, a list containing three elements: + [internal numpy buffer size, error mask, error callback function]. + + The error mask is a single integer that holds the treatment information + on all four floating point errors. The information for each error type + is contained in three bits of the integer. If we print it in base 8, we + can see what treatment is set for "invalid", "under", "over", and + "divide" (in that order). The printed string can be interpreted with + + * 0 : 'ignore' + * 1 : 'warn' + * 2 : 'raise' + * 3 : 'call' + * 4 : 'print' + * 5 : 'log' + + See Also + -------- + geterrobj, seterr, geterr, seterrcall, geterrcall + getbufsize, setbufsize + + Notes + ----- + For complete documentation of the types of floating-point exceptions and + treatment options, see `seterr`. + + Examples + -------- + >>> old_errobj = np.geterrobj() # first get the defaults + >>> old_errobj + [10000, 0, None] + + >>> def err_handler(type, flag): + ... print "Floating point error (%s), with flag %s" % (type, flag) + ... + >>> new_errobj = [20000, 12, err_handler] + >>> np.seterrobj(new_errobj) + >>> np.base_repr(12, 8) # int for divide=4 ('print') and over=1 ('warn') + '14' + >>> np.geterr() + {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'} + >>> np.geterrcall() is err_handler + True + + """) + + ############################################################################## # # lib._compiled_base functions -- cgit v1.2.1