Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Fix ufunc documention #4400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
charris merged 3 commits into from
Mar 1, 2014
Merged

Fix ufunc documention #4400

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bf00084
DOC, MAINT: Spell check and break long lines in ufunc_docstrings.py.
charris Feb 27, 2014
0a3b146
DOC: Correct and extend the documentation of fmod and remainder ufuncs.
charris Feb 28, 2014
6bfd6d4
DOC: Document ldexp and frexp.
charris Mar 1, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
DOC: Document ldexp and frexp. 
The documentation needs to be in umathmodule.c as that is where ldexp
and frexp and defined. I moved the current documention from
add_newdocs.py to ufunc_docstrings.py, manually translated them into C
strings, and inserted them into umathmodule.c.

Closes #2354.
  • Loading branch information
@charris
charris committed Mar 1, 2014
commit 6bfd6d40d7bac9d4295c88ec59b55e7114c77d3f
77 changes: 0 additions & 77 deletions numpy/add_newdocs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4693,45 +4693,6 @@ def luf(lamdaexpr, *args, **kwargs):
#
##############################################################################

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)
Expand Down Expand Up @@ -4772,44 +4733,6 @@ def luf(lamdaexpr, *args, **kwargs):

""")

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()
Expand Down
94 changes: 94 additions & 0 deletions numpy/core/code_generators/ufunc_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3323,3 +3323,97 @@ def add_newdoc(place, name, doc):
array([0, 0, 0, 0, 1])

""")

# This doc is not currently used, but has been converted to a C string
# that can be found in numpy/core/src/umath/umathmodule.c where the
# frexp ufunc is constructed.
add_newdoc('numpy.core.umath', 'frexp',
"""
Decompose the elements of x into mantissa and twos exponent.

Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``.
The mantissa is lies in the open interval(-1, 1), while the twos
exponent is a signed integer.

Parameters
----------
x : array_like
Array of numbers to be decomposed.
out1: ndarray, optional
Output array for the mantissa. Must have the same shape as `x`.
out2: ndarray, optional
Output array for the exponent. Must have the same shape as `x`.

Returns
-------
(mantissa, exponent) : tuple of ndarrays, (float, int)
`mantissa` is a float array with values between -1 and 1.
`exponent` is an int array which represents 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.])

""")

# This doc is not currently used, but has been converted to a C string
# that can be found in numpy/core/src/umath/umathmodule.c where the
# ldexp ufunc is constructed.
add_newdoc('numpy.core.umath', 'ldexp',
"""
Returns x1 * 2**x2, element-wise.

The mantissas `x1` and twos exponents `x2` are used to construct
floating point numbers ``x1 * 2**x2``.

Parameters
----------
x1 : array_like
Array of multipliers.
x2 : array_like, int
Array of twos exponents.
out : ndarray, optional
Output array for the result.

Returns
-------
y : ndarray or scalar
The result of ``x1 * 2**x2``.

See Also
--------
frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `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.])

""")
96 changes: 90 additions & 6 deletions numpy/core/src/umath/umathmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,50 @@ static PyUFuncGenericFunction ldexp_functions[] = {
#endif
};

static const char frdoc[] =
" Decompose the elements of x into mantissa and twos exponent.\n"
"\n"
" Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``.\n"
" The mantissa is lies in the open interval(-1, 1), while the twos\n"
" exponent is a signed integer.\n"
"\n"
" Parameters\n"
" ----------\n"
" x : array_like\n"
" Array of numbers to be decomposed.\n"
" out1: ndarray, optional\n"
" Output array for the mantissa. Must have the same shape as `x`.\n"
" out2: ndarray, optional\n"
" Output array for the exponent. Must have the same shape as `x`.\n"
"\n"
" Returns\n"
" -------\n"
" (mantissa, exponent) : tuple of ndarrays, (float, int)\n"
" `mantissa` is a float array with values between -1 and 1.\n"
" `exponent` is an int array which represents the exponent of 2.\n"
"\n"
" See Also\n"
" --------\n"
" ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.\n"
"\n"
" Notes\n"
" -----\n"
" Complex dtypes are not supported, they will raise a TypeError.\n"
"\n"
" Examples\n"
" --------\n"
" >>> x = np.arange(9)\n"
" >>> y1, y2 = np.frexp(x)\n"
" >>> y1\n"
" array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875,\n"
" 0.5 ])\n"
" >>> y2\n"
" array([0, 1, 2, 2, 3, 3, 3, 3, 4])\n"
" >>> y1 * 2**y2\n"
" array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.])\n"
"\n";


static char ldexp_signatures[] = {
#ifdef HAVE_LDEXPF
NPY_HALF, NPY_INT, NPY_HALF,
Expand All @@ -266,6 +310,48 @@ static char ldexp_signatures[] = {
#endif
};

static const char lddoc[] =
" Returns x1 * 2**x2, element-wise.\n"
"\n"
" The mantissas `x1` and twos exponents `x2` are used to construct\n"
" floating point numbers ``x1 * 2**x2``.\n"
"\n"
" Parameters\n"
" ----------\n"
" x1 : array_like\n"
" Array of multipliers.\n"
" x2 : array_like, int\n"
" Array of twos exponents.\n"
" out : ndarray, optional\n"
" Output array for the result.\n"
"\n"
" Returns\n"
" -------\n"
" y : ndarray or scalar\n"
" The result of ``x1 * 2**x2``.\n"
"\n"
" See Also\n"
" --------\n"
" frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`.\n"
"\n"
" Notes\n"
" -----\n"
" Complex dtypes are not supported, they will raise a TypeError.\n"
"\n"
" `ldexp` is useful as the inverse of `frexp`, if used by itself it is\n"
" more clear to simply use the expression ``x1 * 2**x2``.\n"
"\n"
" Examples\n"
" --------\n"
" >>> np.ldexp(5, np.arange(4))\n"
" array([ 5., 10., 20., 40.], dtype=float32)\n"
"\n"
" >>> x = np.arange(6)\n"
" >>> np.ldexp(*np.frexp(x))\n"
" array([ 0., 1., 2., 3., 4., 5.])\n"
"\n";


static void
InitOtherOperators(PyObject *dictionary) {
PyObject *f;
Expand All @@ -274,16 +360,14 @@ InitOtherOperators(PyObject *dictionary) {
num = sizeof(frexp_functions) / sizeof(frexp_functions[0]);
f = PyUFunc_FromFuncAndData(frexp_functions, blank3_data,
frexp_signatures, num,
1, 2, PyUFunc_None, "frexp",
"Split the number, x, into a normalized"\
" fraction (y1) and exponent (y2)",0);
1, 2, PyUFunc_None, "frexp", frdoc, 0);
PyDict_SetItemString(dictionary, "frexp", f);
Py_DECREF(f);

num = sizeof(ldexp_functions) / sizeof(ldexp_functions[0]);
f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data, ldexp_signatures, num,
2, 1, PyUFunc_None, "ldexp",
"Compute y = x1 * 2**x2.",0);
f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data,
ldexp_signatures, num,
2, 1, PyUFunc_None, "ldexp", lddoc, 0);
PyDict_SetItemString(dictionary, "ldexp", f);
Py_DECREF(f);

Expand Down