diff options
Diffstat (limited to 'numpy')
| -rw-r--r-- | numpy/add_newdocs.py | 209 | ||||
| -rw-r--r-- | numpy/core/src/ufuncobject.c | 177 |
2 files changed, 216 insertions, 170 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 3529938a5..ba667a8e9 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -2249,3 +2249,212 @@ add_newdoc('numpy.core.umath','seterrobj', seterrcall """) + +add_newdoc("numpy.core","ufunc","""Optimized functions make it possible to implement arithmetic with arrays efficiently + +Unary ufuncs: +============= + +op(X, out=None) +Apply op to X elementwise + +Parameters +---------- +X : array-like +out : array-like + An array to store the output. Must be the same shape as X. + +Returns +------- +r : array-like + r will have the same shape as X; if out is provided, r will be + equal to out. + +Binary ufuncs: +============== + +op(X, Y, out=None) +Apply op to X and Y elementwise. May "broadcast" to make +the shapes of X and Y congruent. + +The broadcasting rules are: +* Dimensions of length 1 may be prepended to either array +* Arrays may be repeated along dimensions of length 1 + +Parameters +---------- +X : array-like +Y : array-like +out : array-like + An array to store the output. Must be the same shape as the + output would have. + +Returns +------- +r : array-like + The return value; if out is provided, r will be equal to out. +""") +add_newdoc("numpy.core","ufunc", + [("reduce","""reduce(array,axis=0,dtype=None,out=None) +reduce applies the operator to all elements of the array producing +a single result. + +For a one-dimensional array, reduce produces results equivalent to: +r = op.identity +for i in xrange(len(A)): + r = op(r,A[i]) +return r + +For example, add.reduce() is equivalent to sum(). + +Parameters: +----------- + +array : array-like + The array to act on. +axis : integer + The axis along which to apply the reduction. +dtype : data type or None + The type used to represent the intermediate results. Defaults + to the data type of the output array if this is provided, or + the data type of the input array if no output array is provided. +out : array-like or None + A location into which the result is stored. If not provided a + freshly-allocated array is returned. + +Returns: +-------- + +r : array + The reduced values. If out was supplied, r is equal to out. + +Example: +-------- +>>> np.multiply.reduce([2,3,5]) +30 + + +"""), + ("accumulate","""accumulate(array,axis=None,dtype=None,out=None) +accumulate applies the operator to all elements of the array producing +cumulative results. + +For a one-dimensional array, accumulate produces results equivalent to: +r = np.empty(len(A)) +t = op.identity +for i in xrange(len(A)): + t = op(t,A[i]) + r[i] = t +return r + +For example, add.accumulate() is equivalent to cumsum(). + +Parameters: +----------- + +array : array-like + The array to act on. +axis : integer + The axis along which to apply the accumulation. +dtype : data type or None + The type used to represent the intermediate results. Defaults + to the data type of the output array if this is provided, or + the data type of the input array if no output array is provided. +out : array-like or None + A location into which the result is stored. If not provided a + freshly-allocated array is returned. + +Returns: +-------- + +r : array + The accumulated values. If out was supplied, r is equal to out. + +Example: +-------- +>>> np.multiply.accumulate([2,3,5]) +array([2,6,30]) + +"""), + ("reduceat","""reduceat(self,array,indices,axis=None,dtype=None,out=None) +reduceat performs a reduce over an axis using the indices as a guide + +op.reduceat(array,indices) computes +op.reduce(array[indices[i]:indices[i+1]]) +for i=0..end with an implicit indices[i+1]=len(array) +assumed when i=end-1 + +if indices[i+1] <= indices[i]+1 +then the result is array[indices[i]] for that value + +op.accumulate(array) is the same as +op.reduceat(array,indices)[::2] +where indices is range(len(array)-1) with a zero placed +in every other sample: +indices = zeros(len(array)*2-1) +indices[1::2] = range(1,len(array)) + +output shape is based on the size of indices + +Parameters: +----------- + +array : array-like + The array to act on. +indices : array-like + Indices specifying ranges to reduce. +axis : integer + The axis along which to apply the reduceat. +dtype : data type or None + The type used to represent the intermediate results. Defaults + to the data type of the output array if this is provided, or + the data type of the input array if no output array is provided. +out : array-like or None + A location into which the result is stored. If not provided a + freshly-allocated array is returned. + +Returns: +-------- + +r : array + The reduced values. If out was supplied, r is equal to out. + +Example: +-------- +To take the running sum of four successive values: +>>> np.multiply.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2] +array([ 6, 10, 14, 18]) + +"""), + ("outer","""outer(A,B) +Compute the result of applying op to all pairs (a,b) + +op.outer(A,B) is equivalent to +op(A[:,:,...,:,newaxis,...,newaxis]*B[newaxis,...,newaxis,:,...,:]) +where A has B.ndim new axes appended and B has A.ndim new axes prepended. + +For A and B one-dimensional, this is equivalent to +r = empty(len(A),len(B)) +for i in xrange(len(A)): + for j in xrange(len(B)): + r[i,j] = A[i]*B[j] +If A and B are higher-dimensional, the result has dimension A.ndim+B.ndim + +Parameters: +----------- + +A : array-like +B : array-like + +Returns: +-------- + +r : array +Example: +-------- +>>> np.multiply.outer([1,2,3],[4,5,6]) +array([[ 4, 5, 6], + [ 8, 10, 12], + [12, 15, 18]]) + +""")]) diff --git a/numpy/core/src/ufuncobject.c b/numpy/core/src/ufuncobject.c index 8e25ef6c5..a3b1a58a4 100644 --- a/numpy/core/src/ufuncobject.c +++ b/numpy/core/src/ufuncobject.c @@ -3951,174 +3951,12 @@ ufunc_reduceat(PyUFuncObject *self, PyObject *args, PyObject *kwds) static struct PyMethodDef ufunc_methods[] = { - {"reduce", (PyCFunction)ufunc_reduce, METH_VARARGS | METH_KEYWORDS, - "reduce(array,axis=0,dtype=None,out=None)\n" - "reduce applies the operator to all elements of the array producing\n" - "a single result.\n" - "\n" - "For a one-dimensional array, reduce produces results equivalent to:\n" - "r = op.identity\n" - "for i in xrange(len(A)):\n" - " r = op(r,A[i])\n" - "return r\n" - "\n" - "For example, add.reduce() is equivalent to sum().\n" - "\n" - "Parameters:\n" - "-----------\n" - "\n" - "array : array-like\n" - " The array to act on.\n" - "axis : integer\n" - " The axis along which to apply the reduction.\n" - "dtype : data type or None\n" - " The type used to represent the intermediate results. Defaults\n" - " to the data type of the output array if this is provided, or\n" - " the data type of the input array if no output array is provided.\n" - "out : array-like or None\n" - " A location into which the result is stored. If not provided a\n" - " freshly-allocated array is returned.\n" - "\n" - "Returns:\n" - "--------\n" - "\n" - "r : array\n" - " The reduced values. If out was supplied, r is equal to out.\n" - "\n" - "Example:\n" - "--------\n" - ">>> np.multiply.reduce([2,3,5])\n" - "30\n" - "\n" - }, + {"reduce", (PyCFunction)ufunc_reduce, METH_VARARGS | METH_KEYWORDS }, {"accumulate", (PyCFunction)ufunc_accumulate, - METH_VARARGS | METH_KEYWORDS, - "accumulate(array,axis=None,dtype=None,out=None)\n" - "accumulate applies the operator to all elements of the array producing\n" - "cumulative results.\n" - "\n" - "For a one-dimensional array, accumulate produces results equivalent to:\n" - "r = np.empty(len(A))\n" - "t = op.identity\n" - "for i in xrange(len(A)):\n" - " t = op(t,A[i])\n" - " r[i] = t\n" - "return r\n" - "\n" - "For example, add.accumulate() is equivalent to cumsum().\n" - "\n" - "Parameters:\n" - "-----------\n" - "\n" - "array : array-like\n" - " The array to act on.\n" - "axis : integer\n" - " The axis along which to apply the accumulation.\n" - "dtype : data type or None\n" - " The type used to represent the intermediate results. Defaults\n" - " to the data type of the output array if this is provided, or\n" - " the data type of the input array if no output array is provided.\n" - "out : array-like or None\n" - " A location into which the result is stored. If not provided a\n" - " freshly-allocated array is returned.\n" - "\n" - "Returns:\n" - "--------\n" - "\n" - "r : array\n" - " The accumulated values. If out was supplied, r is equal to out.\n" - "\n" - "Example:\n" - "--------\n" - ">>> np.multiply.accumulate([2,3,5])\n" - "array([2,6,30])\n" - "\n" - }, + METH_VARARGS | METH_KEYWORDS }, {"reduceat", (PyCFunction)ufunc_reduceat, - METH_VARARGS | METH_KEYWORDS, - "reduceat(self,array,indices,axis=None,dtype=None,out=None)\n" - "reduceat performs a reduce over an axis using the indices as a guide\n" - "\n" - "op.reduceat(array,indices) computes\n" - "op.reduce(array[indices[i]:indices[i+1]]\n" - "for i=0..end with an implicit indices[i+1]=len(array)\n" - "assumed when i=end-1\n" - "\n" - "if indices[i+1] <= indices[i]+1\n" - "then the result is array[indices[i]] for that value\n" - "\n" - "op.accumulate(array) is the same as\n" - "op.reduceat(array,indices)[::2]\n" - "where indices is range(len(array)-1) with a zero placed\n" - "in every other sample:\n" - "indices = zeros(len(array)*2-1)\n" - "indices[1::2] = range(1,len(array))\n" - "\n" - "output shape is based on the size of indices\n" - "\n" - "Parameters:\n" - "-----------\n" - "\n" - "array : array-like\n" - " The array to act on.\n" - "indices : array-like\n" - " Indices specifying ranges to reduce.\n" - "axis : integer\n" - " The axis along which to apply the reduceat.\n" - "dtype : data type or None\n" - " The type used to represent the intermediate results. Defaults\n" - " to the data type of the output array if this is provided, or\n" - " the data type of the input array if no output array is provided.\n" - "out : array-like or None\n" - " A location into which the result is stored. If not provided a\n" - " freshly-allocated array is returned.\n" - "\n" - "Returns:\n" - "--------\n" - "\n" - "r : array\n" - " The reduced values. If out was supplied, r is equal to out.\n" - "\n" - "Example:\n" - "--------\n" - "To take the running sum of four successive values:\n" - ">>> np.multiply.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2]\n" - "array([ 6, 10, 14, 18])\n" - "\n" - }, - {"outer", (PyCFunction)ufunc_outer, METH_VARARGS | METH_KEYWORDS, - "outer(A,B)\n" - "Compute the result of applying op to all pairs (a,b)\n" - "\n" - "op.outer(A,B) is equivalent to\n" - "op(A[:,:,...,:,newaxis,...,newaxis]*B[newaxis,...,newaxis,:,...,:]\n" - "where A has B.ndim new axes appended and B has A.ndim new axes prepended.\n" - "\n" - "For A and B one-dimensional, this is equivalent to\n" - "r = empty(len(A),len(B))\n" - "for i in xrange(len(A)):\n" - " for j in xrange(len(B)):\n" - " r[i,j] = A[i]*B[j]\n" - "If A and B are higher-dimensional, the result has dimension A.ndim+B.ndim\n" - "\n" - "Parameters:\n" - "-----------\n" - "\n" - "A : array-like\n" - "B : array-like\n" - "\n" - "Returns:\n" - "--------\n" - "\n" - "r : array\n" - "Example:\n" - "--------\n" - ">>> np.multiply.outer([1,2,3],[4,5,6])\n" - "array([[ 4, 5, 6],\n" - " [ 8, 10, 12],\n" - " [12, 15, 18]])\n" - "\n" - }, + METH_VARARGS | METH_KEYWORDS }, + {"outer", (PyCFunction)ufunc_outer, METH_VARARGS | METH_KEYWORDS }, {NULL, NULL} /* sentinel */ }; @@ -4258,9 +4096,8 @@ ufunc_get_identity(PyUFuncObject *self) #undef _typecharfromnum -static char Ufunctype__doc__[] = - "Optimized functions make it possible to implement arithmetic "\ - "with arrays efficiently"; +/* Docstring is now set from python */ +/* static char *Ufunctype__doc__ = NULL; */ static PyGetSetDef ufunc_getset[] = { {"__doc__", (getter)ufunc_get_doc, NULL, "documentation string"}, @@ -4297,7 +4134,7 @@ static PyTypeObject PyUFunc_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT, /* tp_flags */ - Ufunctype__doc__, /* tp_doc */ + NULL, /* tp_doc */ /* was Ufunctype__doc__ */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ |