diff options
Diffstat (limited to 'numpy/add_newdocs.py')
| -rw-r--r-- | numpy/add_newdocs.py | 173 |
1 files changed, 152 insertions, 21 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 4cc626ca9..75f88a85f 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -28,9 +28,9 @@ add_newdoc('numpy.core', 'flatiter', It allows iterating over the array as if it were a 1-D array, either in a for-loop or by calling its `next` method. - Iteration is done in C-contiguous style, with the last index varying the - fastest. The iterator can also be indexed using basic slicing or - advanced indexing. + Iteration is done in row-major, C-style order (the last + index varying the fastest). The iterator can also be indexed using + basic slicing or advanced indexing. See Also -------- @@ -745,8 +745,9 @@ add_newdoc('numpy.core.multiarray', 'empty', dtype : data-type, optional Desired output data-type. order : {'C', 'F'}, optional - Whether to store multi-dimensional data in C (row-major) or - Fortran (column-major) order in memory. + Whether to store multi-dimensional data in row-major + (C-style) or column-major (Fortran-style) order in + memory. Returns ------- @@ -1142,7 +1143,7 @@ add_newdoc('numpy.core.multiarray', 'concatenate', """ concatenate((a1, a2, ...), axis=0) - Join a sequence of arrays together. + Join a sequence of arrays along an existing axis. Parameters ---------- @@ -1166,6 +1167,7 @@ add_newdoc('numpy.core.multiarray', 'concatenate', hsplit : Split array into multiple sub-arrays horizontally (column wise) vsplit : Split array into multiple sub-arrays vertically (row wise) dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). + stack : Stack a sequence of arrays along a new axis. hstack : Stack arrays in sequence horizontally (column wise) vstack : Stack arrays in sequence vertically (row wise) dstack : Stack arrays in sequence depth wise (along third dimension) @@ -1942,6 +1944,7 @@ add_newdoc('numpy.core', 'dot', vdot : Complex-conjugating dot product. tensordot : Sum products over arbitrary axes. einsum : Einstein summation convention. + matmul : '@' operator as method with out parameter. Examples -------- @@ -1953,7 +1956,7 @@ add_newdoc('numpy.core', 'dot', >>> np.dot([2j, 3j], [2j, 3j]) (-13+0j) - For 2-D arrays it's the matrix product: + For 2-D arrays it is the matrix product: >>> a = [[1, 0], [0, 1]] >>> b = [[4, 1], [2, 2]] @@ -1970,6 +1973,130 @@ add_newdoc('numpy.core', 'dot', """) +add_newdoc('numpy.core', 'matmul', + """ + matmul(a, b, out=None) + + Matrix product of two arrays. + + The behavior depends on the arguments in the following way. + + - If both arguments are 2-D they are multiplied like conventional + matrices. + - If either argument is N-D, N > 2, it is treated as a stack of + matrices residing in the last two indexes and broadcast accordingly. + - If the first argument is 1-D, it is promoted to a matrix by + prepending a 1 to its dimensions. After matrix multiplication + the prepended 1 is removed. + - If the second argument is 1-D, it is promoted to a matrix by + appending a 1 to its dimensions. After matrix multiplication + the appended 1 is removed. + + Multiplication by a scalar is not allowed, use ``*`` instead. Note that + multiplying a stack of matrices with a vector will result in a stack of + vectors, but matmul will not recognize it as such. + + ``matmul`` differs from ``dot`` in two important ways. + + - Multiplication by scalars is not allowed. + - Stacks of matrices are broadcast together as if the matrices + were elements. + + .. warning:: + This function is preliminary and included in Numpy 1.10 for testing + and documentation. Its semantics will not change, but the number and + order of the optional arguments will. + + .. versionadded:: 1.10.0 + + Parameters + ---------- + a : array_like + 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 + ------- + output : ndarray + Returns the dot product of `a` and `b`. If `a` and `b` are both + 1-D arrays then a scalar is returned; otherwise an array is + returned. If `out` is given, then it is returned. + + Raises + ------ + ValueError + If the last dimension of `a` is not the same size as + the second-to-last dimension of `b`. + + If scalar value is passed. + + See Also + -------- + vdot : Complex-conjugating dot product. + tensordot : Sum products over arbitrary axes. + einsum : Einstein summation convention. + dot : alternative matrix product with different broadcasting rules. + + Notes + ----- + The matmul function implements the semantics of the `@` operator introduced + in Python 3.5 following PEP465. + + Examples + -------- + For 2-D arrays it is the matrix product: + + >>> a = [[1, 0], [0, 1]] + >>> b = [[4, 1], [2, 2]] + >>> np.matmul(a, b) + array([[4, 1], + [2, 2]]) + + For 2-D mixed with 1-D, the result is the usual. + + >>> a = [[1, 0], [0, 1]] + >>> b = [1, 2] + >>> np.matmul(a, b) + array([1, 2]) + >>> np.matmul(b, a) + array([1, 2]) + + + Broadcasting is conventional for stacks of arrays + + >>> a = np.arange(2*2*4).reshape((2,2,4)) + >>> b = np.arange(2*2*4).reshape((2,4,2)) + >>> np.matmul(a,b).shape + (2, 2, 2) + >>> np.matmul(a,b)[0,1,1] + 98 + >>> sum(a[0,1,:] * b[0,:,1]) + 98 + + Vector, vector returns the scalar inner product, but neither argument + is complex-conjugated: + + >>> np.matmul([2j, 3j], [2j, 3j]) + (-13+0j) + + Scalar multiplication raises an error. + + >>> np.matmul([1,2], 3) + Traceback (most recent call last): + ... + ValueError: Scalar operands are not allowed, use '*' instead + + """) + + add_newdoc('numpy.core', 'einsum', """ einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe') @@ -2293,7 +2420,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', strides : tuple of ints, optional Strides of data in memory. order : {'C', 'F'}, optional - Row-major or column-major order. + Row-major (C-style) or column-major (Fortran-style) order. Attributes ---------- @@ -3438,9 +3565,9 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('flatten', Parameters ---------- order : {'C', 'F', 'A'}, optional - Whether to flatten in C (row-major), Fortran (column-major) order, - or preserve the C/Fortran ordering from `a`. - The default is 'C'. + Whether to flatten in row-major (C-style) or + column-major (Fortran-style) order or preserve the + C/Fortran ordering from `a`. The default is 'C'. Returns ------- @@ -4190,10 +4317,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('sort', last axis. kind : {'quicksort', 'mergesort', 'heapsort'}, optional Sorting algorithm. Default is 'quicksort'. - order : list, optional + order : str or list of str, optional When `a` is an array with fields defined, this argument specifies - which fields to compare first, second, etc. Not all fields need be - specified. + which fields to compare first, second, etc. A single field can + be specified as a string, and not all fields need be specified, + but unspecified fields will still be used, in the order in which + they come up in the dtype, to break ties. See Also -------- @@ -4257,10 +4386,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('partition', last axis. kind : {'introselect'}, optional Selection algorithm. Default is 'introselect'. - order : list, optional + order : str or list of str, optional When `a` is an array with fields defined, this argument specifies - which fields to compare first, second, etc. Not all fields need be - specified. + which fields to compare first, second, etc. A single field can + be specified as a string, and not all fields need be specified, + but unspecified fields will still be used, in the order in which + they come up in the dtype, to break ties. See Also -------- @@ -5014,8 +5145,9 @@ add_newdoc('numpy.core.multiarray', 'ravel_multi_index', In 'clip' mode, a negative index which would normally wrap will clip to 0 instead. order : {'C', 'F'}, optional - Determines whether the multi-index should be viewed as indexing in - C (row-major) order or FORTRAN (column-major) order. + Determines whether the multi-index should be viewed as + indexing in row-major (C-style) or column-major + (Fortran-style) order. Returns ------- @@ -5064,9 +5196,8 @@ add_newdoc('numpy.core.multiarray', 'unravel_index', 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. + row-major (C-style) or column-major (Fortran-style) order. Returns ------- |