diff options
| -rw-r--r-- | numpy/add_newdocs.py | 163 | ||||
| -rw-r--r-- | numpy/core/blasdot/_dotblas.c | 55 | ||||
| -rw-r--r-- | numpy/core/numeric.py | 101 |
3 files changed, 199 insertions, 120 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index a700458a9..e9548d8f5 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -549,7 +549,7 @@ add_newdoc('numpy.core.multiarray', 'concatenate', """) -add_newdoc('numpy.core.multiarray', 'inner', +add_newdoc('numpy.core', 'inner', """ inner(a, b) @@ -940,6 +940,167 @@ add_newdoc('numpy.core.multiarray','getbuffer', """) +add_newdoc('numpy.core', 'dot', + """ + dot(a, b) + + Dot product of two arrays. + + For 2-D arrays it is equivalent to matrix multiplication, and for 1-D + arrays to inner product of vectors (without complex conjugation). For + N dimensions it is a sum product over the last axis of `a` and + the second-to-last of `b`:: + + dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) + + Parameters + ---------- + a : array_like + First argument. + b : array_like + Second argument. + + Returns + ------- + output : ndarray + 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. + + Raises + ------ + ValueError + If the last dimension of `a` is not the same size as + the second-to-last dimension of `b`. + + See Also + -------- + vdot : Complex-conjugating dot product. + tensordot : Sum products over arbitrary axes. + + Examples + -------- + >>> np.dot(3, 4) + 12 + + Neither argument is complex-conjugated: + + >>> np.dot([2j, 3j], [2j, 3j]) + (-13+0j) + + For 2-D arrays it's the matrix product: + + >>> a = [[1, 0], [0, 1]] + >>> b = [[4, 1], [2, 2]] + >>> np.dot(a, b) + array([[4, 1], + [2, 2]]) + + >>> a = np.arange(3*4*5*6).reshape((3,4,5,6)) + >>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3)) + >>> np.dot(a, b)[2,3,2,1,2,2] + 499128 + >>> sum(a[2,3,2,:] * b[1,2,:,2]) + 499128 + + """) + +add_newdoc('numpy.core', 'alterdot', + """ + Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions. + + Typically, as a user of Numpy, you do not explicitly call this function. If + Numpy is built with an accelerated BLAS, this function is automatically + called when Numpy is imported. + + When Numpy is built with an accelerated BLAS like ATLAS, these functions + are replaced to make use of the faster implementations. The faster + implementations only affect float32, float64, complex64, and complex128 + arrays. Furthermore, the BLAS API only includes matrix-matrix, + matrix-vector, and vector-vector products. Products of arrays with larger + dimensionalities use the built in functions and are not accelerated. + + See Also + -------- + restoredot : `restoredot` undoes the effects of `alterdot`. + + """) + +add_newdoc('numpy.core', 'restoredot', + """ + Restore `dot`, `vdot`, and `innerproduct` to the default non-BLAS + implementations. + + Typically, the user will only need to call this when troubleshooting and + installation problem, reproducing the conditions of a build without an + accelerated BLAS, or when being very careful about benchmarking linear + algebra operations. + + See Also + -------- + alterdot : `restoredot` undoes the effects of `alterdot`. + + """) + +add_newdoc('numpy.core', 'vdot', + """ + Return the dot product of two vectors. + + The vdot(`a`, `b`) function handles complex numbers differently than + dot(`a`, `b`). If the first argument is complex the complex conjugate + of the first argument is used for the calculation of the dot product. + + For 2-D arrays it is equivalent to matrix multiplication, and for 1-D + arrays to inner product of vectors (with complex conjugation of `a`). + For N dimensions it is a sum product over the last axis of `a` and + the second-to-last of `b`:: + + dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) + + Parameters + ---------- + a : array_like + If `a` is complex the complex conjugate is taken before calculation + of the dot product. + b : array_like + Second argument to the dot product. + + Returns + ------- + output : ndarray + Returns dot product of `a` and `b`. Can be an int, float, or + complex depending on the types of `a` and `b`. + + See Also + -------- + dot : Return the dot product without using the complex conjugate of the + first argument. + + Notes + ----- + The dot product is the summation of element wise multiplication. + + .. math:: + a \\cdot b = \\sum_{i=1}^n a_i^*b_i = a_1^*b_1+a_2^*b_2+\\cdots+a_n^*b_n + + Examples + -------- + >>> a = np.array([1+2j,3+4j]) + >>> b = np.array([5+6j,7+8j]) + >>> np.vdot(a, b) + (70-8j) + >>> np.vdot(b, a) + (70+8j) + >>> a = np.array([[1, 4], [5, 6]]) + >>> b = np.array([[4, 1], [2, 2]]) + >>> np.vdot(a, b) + 30 + >>> np.vdot(b, a) + 30 + + """) + + ############################################################################## # # Documentation for ndarray attributes and methods diff --git a/numpy/core/blasdot/_dotblas.c b/numpy/core/blasdot/_dotblas.c index 7f8007dd5..ae9af4a00 100644 --- a/numpy/core/blasdot/_dotblas.c +++ b/numpy/core/blasdot/_dotblas.c @@ -77,8 +77,9 @@ CDOUBLE_dot(void *a, npy_intp stridea, void *b, npy_intp strideb, void *res, static npy_bool altered=NPY_FALSE; -static char doc_alterdot[] = "alterdot() changes all dot functions to use blas."; - +/* + * alterdot() changes all dot functions to use blas. + */ static PyObject * dotblas_alterdot(PyObject *NPY_UNUSED(dummy), PyObject *args) { @@ -112,8 +113,9 @@ dotblas_alterdot(PyObject *NPY_UNUSED(dummy), PyObject *args) return Py_None; } -static char doc_restoredot[] = "restoredot() restores dots to defaults."; - +/* + * restoredot() restores dots to defaults. + */ static PyObject * dotblas_restoredot(PyObject *NPY_UNUSED(dummy), PyObject *args) { @@ -196,12 +198,13 @@ _bad_strides(PyArrayObject *ap) return 0; } -static char doc_matrixproduct[] = \ - "dot(a,b)\nReturns the dot product of a and b for arrays of " \ - "floating point types.\nLike the generic numpy equivalent the " \ - "product sum is over\nthe last dimension of a and the second-to-last "\ - "dimension of b.\nNB: The first argument is not conjugated."; - +/* + * dot(a,b) + * Returns the dot product of a and b for arrays of floating point types. + * Like the generic numpy equivalent the product sum is over + * the last dimension of a and the second-to-last dimension of b. + * NB: The first argument is not conjugated.; + */ static PyObject * dotblas_matrixproduct(PyObject *NPY_UNUSED(dummy), PyObject *args) { @@ -796,11 +799,14 @@ dotblas_matrixproduct(PyObject *NPY_UNUSED(dummy), PyObject *args) } -static char doc_innerproduct[] = \ - "innerproduct(a,b)\nReturns the inner product of a and b for arrays of "\ - "floating point types.\nLike the generic NumPy equivalent the product "\ - "sum is over\nthe last dimension of a and b.\nNB: The first argument is "\ - "not conjugated."; +/* + * innerproduct(a,b) + * + * Returns the inner product of a and b for arrays of + * floating point types. Like the generic NumPy equivalent the product + * sum is over the last dimension of a and b. + * NB: The first argument is not conjugated. + */ static PyObject * dotblas_innerproduct(PyObject *NPY_UNUSED(dummy), PyObject *args) @@ -1048,9 +1054,12 @@ dotblas_innerproduct(PyObject *NPY_UNUSED(dummy), PyObject *args) } -static char doc_vdot[] = "vdot(a,b)\nReturns the dot product of a and b for scalars and vectors\nof floating point and complex types. The first argument, a, is conjugated."; - - +/* + * vdot(a,b) + * + * Returns the dot product of a and b for scalars and vectors of + * floating point and complex types. The first argument, a, is conjugated. + */ static PyObject *dotblas_vdot(PyObject *NPY_UNUSED(dummy), PyObject *args) { PyObject *op1, *op2; PyArrayObject *ap1=NULL, *ap2=NULL, *ret=NULL; @@ -1151,11 +1160,11 @@ static PyObject *dotblas_vdot(PyObject *NPY_UNUSED(dummy), PyObject *args) { } static struct PyMethodDef dotblas_module_methods[] = { - {"dot", (PyCFunction)dotblas_matrixproduct, 1, doc_matrixproduct}, - {"inner", (PyCFunction)dotblas_innerproduct, 1, doc_innerproduct}, - {"vdot", (PyCFunction)dotblas_vdot, 1, doc_vdot}, - {"alterdot", (PyCFunction)dotblas_alterdot, 1, doc_alterdot}, - {"restoredot", (PyCFunction)dotblas_restoredot, 1, doc_restoredot}, + {"dot", (PyCFunction)dotblas_matrixproduct, 1, NULL}, + {"inner", (PyCFunction)dotblas_innerproduct, 1, NULL}, + {"vdot", (PyCFunction)dotblas_vdot, 1, NULL}, + {"alterdot", (PyCFunction)dotblas_alterdot, 1, NULL}, + {"restoredot", (PyCFunction)dotblas_restoredot, 1, NULL}, {NULL, NULL, 0, NULL} /* sentinel */ }; diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py index ff2eb6ca9..57f36cfad 100644 --- a/numpy/core/numeric.py +++ b/numpy/core/numeric.py @@ -608,9 +608,6 @@ def convolve(a,v,mode='full'): mode = _mode_from_name(mode) return multiarray.correlate(a, v[::-1], mode) -inner = multiarray.inner -dot = multiarray.dot - def outer(a,b): """ Returns the outer product of two vectors. @@ -654,110 +651,22 @@ def outer(a,b): b = asarray(b) return a.ravel()[:,newaxis]*b.ravel()[newaxis,:] -def vdot(a, b): - """ - Return the dot product of two vectors. - - The vdot(`a`, `b`) function handles complex numbers differently than - dot(`a`, `b`). If the first argument is complex the complex conjugate - of the first argument is used for the calculation of the dot product. - - For 2-D arrays it is equivalent to matrix multiplication, and for 1-D - arrays to inner product of vectors (with complex conjugation of `a`). - For N dimensions it is a sum product over the last axis of `a` and - the second-to-last of `b`:: - - dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) - - Parameters - ---------- - a : array_like - If `a` is complex the complex conjugate is taken before calculation - of the dot product. - b : array_like - Second argument to the dot product. - - Returns - ------- - output : ndarray - Returns dot product of `a` and `b`. Can be an int, float, or - complex depending on the types of `a` and `b`. - - See Also - -------- - dot : Return the dot product without using the complex conjugate of the - first argument. - - Notes - ----- - The dot product is the summation of element wise multiplication. - - .. math:: - a \\cdot b = \\sum_{i=1}^n a_i^*b_i = a_1^*b_1+a_2^*b_2+\\cdots+a_n^*b_n - - Examples - -------- - >>> a = np.array([1+2j,3+4j]) - >>> b = np.array([5+6j,7+8j]) - >>> np.vdot(a, b) - (70-8j) - >>> np.vdot(b, a) - (70+8j) - >>> a = np.array([[1, 4], [5, 6]]) - >>> b = np.array([[4, 1], [2, 2]]) - >>> np.vdot(a, b) - 30 - >>> np.vdot(b, a) - 30 - - """ - return dot(asarray(a).ravel().conj(), asarray(b).ravel()) - # try to import blas optimized dot if available try: # importing this changes the dot function for basic 4 types # to blas-optimized versions. from _dotblas import dot, vdot, inner, alterdot, restoredot except ImportError: + # docstrings are in add_newdocs.py + inner = multiarray.inner + dot = multiarray.dot + def vdot(a, b): + return dot(asarray(a).ravel().conj(), asarray(b).ravel()) def alterdot(): - """ - Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions. - - Typically, as a user of Numpy, you do not explicitly call this function. If - Numpy is built with an accelerated BLAS, this function is automatically - called when Numpy is imported. - - When Numpy is built with an accelerated BLAS like ATLAS, these functions - are replaced to make use of the faster implementations. The faster - implementations only affect float32, float64, complex64, and complex128 - arrays. Furthermore, the BLAS API only includes matrix-matrix, - matrix-vector, and vector-vector products. Products of arrays with larger - dimensionalities use the built in functions and are not accelerated. - - See Also - -------- - restoredot : `restoredot` undoes the effects of `alterdot`. - - """ pass def restoredot(): - """ - Restore `dot`, `vdot`, and `innerproduct` to the default non-BLAS - implementations. - - Typically, the user will only need to call this when troubleshooting and - installation problem, reproducing the conditions of a build without an - accelerated BLAS, or when being very careful about benchmarking linear - algebra operations. - - See Also - -------- - alterdot : `restoredot` undoes the effects of `alterdot`. - - """ pass - def tensordot(a, b, axes=2): """ Returns the tensor dot product for (ndim >= 1) arrays along an axes. |