[Numpy-svn] r6116 - in trunk: doc/source/reference numpy/core/code_generators
numpy-svn at scipy.org
numpy-svn at scipy.org
Fri Nov 28 00:34:41 EST 2008
Author: charris
Date: 2008-11-27 23:34:33 -0600 (Thu, 27 Nov 2008)
New Revision: 6116
Modified:
trunk/doc/source/reference/ufuncs.rst
trunk/numpy/core/code_generators/docstrings.py
trunk/numpy/core/code_generators/generate_umath.py
Log:
Add preliminary docstrings for:
log2, exp2, logaddexp, logaddexp2, rad2deg, deg2rad.
The complete docstring for fmin and fmax are on the web but
haven't yet been merged.
Modified: trunk/doc/source/reference/ufuncs.rst
===================================================================
--- trunk/doc/source/reference/ufuncs.rst 2008-11-28 03:52:16 UTC (rev 6115)
+++ trunk/doc/source/reference/ufuncs.rst 2008-11-28 05:34:33 UTC (rev 6116)
@@ -77,20 +77,20 @@
with a dimension of length 1 to satisfy property 2.
.. admonition:: Example
-
+
If ``a.shape`` is (5,1), ``b.shape`` is (1,6), ``c.shape`` is (6,)
and d.shape is ``()`` so that d is a scalar, then *a*, *b*, *c*,
and *d* are all broadcastable to dimension (5,6); and
-
+
- *a* acts like a (5,6) array where ``a[:,0]`` is broadcast to the other
columns,
-
+
- *b* acts like a (5,6) array where ``b[0,:]`` is broadcast
to the other rows,
-
+
- *c* acts like a (1,6) array and therefore like a (5,6) array
where ``c[:]` is broadcast to every row, and finally,
-
+
- *d* acts like a (5,6) array where the single value is repeated.
@@ -205,8 +205,8 @@
.. admonition:: Figure
- Code segment showing the can cast safely table for a 32-bit system.
-
+ Code segment showing the can cast safely table for a 32-bit system.
+
>>> def print_table(ntypes):
... print 'X',
... for char in ntypes: print char,
@@ -245,7 +245,7 @@
You should note that, while included in the table for completeness,
the 'S', 'U', and 'V' types cannot be operated on by ufuncs. Also,
note that on a 64-bit system the integer types may have different
-sizes resulting in a slightly altered table.
+sizes resulting in a slightly altered table.
Mixed scalar-array operations use a different set of casting rules
that ensure that a scalar cannot upcast an array unless the scalar is
@@ -264,7 +264,7 @@
--------------------------
All ufuncs take optional keyword arguments. These represent rather
-advanced usage and will likely not be used by most users.
+advanced usage and will likely not be used by most users.
.. index::
pair: ufunc; keyword arguments
@@ -296,7 +296,7 @@
----------
There are some informational attributes that universal functions
-possess. None of the attributes can be set.
+possess. None of the attributes can be set.
.. index::
pair: ufunc; attributes
@@ -316,7 +316,7 @@
ufunc.nin
ufunc.nout
- ufunc.nargs
+ ufunc.nargs
ufunc.ntypes
ufunc.types
ufunc.identity
@@ -386,7 +386,7 @@
.. note::
The ufunc still returns its output(s) even if you use the optional
- output argument(s).
+ output argument(s).
Math operations
---------------
@@ -398,6 +398,7 @@
multiply
divide
logaddexp
+ logaddexp2
true_divide
floor_divide
negative
@@ -410,10 +411,12 @@
sign
conj
exp
+ exp2
log
+ log2
+ log10
expm1
log1p
- log10
sqrt
square
reciprocal
@@ -433,7 +436,7 @@
Trigonometric functions
-----------------------
All trigonometric functions use radians when an angle is called for.
-The ratio of degrees to radians is :math:`180^{\circ}/\pi.`
+The ratio of degrees to radians is :math:`180^{\circ}/\pi.`
.. autosummary::
@@ -458,7 +461,7 @@
-----------------------
These function all need integer arguments and they maniuplate the bit-
-pattern of those arguments.
+pattern of those arguments.
.. autosummary::
@@ -501,7 +504,7 @@
element-by-element array comparisons. Be sure to understand the
operator precedence: (a>2) & (a<5) is the proper syntax because a>2 &
a<5 will result in an error due to the fact that 2 & a is evaluated
- first.
+ first.
.. autosummary::
@@ -514,7 +517,7 @@
method of the maximum ufunc is much faster. Also, the max() method
will not give answers you might expect for arrays with greater than
one dimension. The reduce method of minimum also allows you to compute
- a total minimum over an array.
+ a total minimum over an array.
.. autosummary::
@@ -528,7 +531,7 @@
two arrays is larger. In contrast, max(a,b) treats the objects a and b
as a whole, looks at the (total) truth value of a>b and uses it to
return either a or b (as a whole). A similar difference exists between
- minimum(a,b) and min(a,b).
+ minimum(a,b) and min(a,b).
Floating functions
@@ -536,7 +539,7 @@
Recall that all of these functions work element-by-element over an
array, returning an array output. The description details only a
-single operation.
+single operation.
.. autosummary::
Modified: trunk/numpy/core/code_generators/docstrings.py
===================================================================
--- trunk/numpy/core/code_generators/docstrings.py 2008-11-28 03:52:16 UTC (rev 6115)
+++ trunk/numpy/core/code_generators/docstrings.py 2008-11-28 05:34:33 UTC (rev 6116)
@@ -691,8 +691,9 @@
"""
Return the truncated value of the input, element-wise.
- The truncated value of the scalar `x` is the nearest integer `i`, such
- that i is not larger than x amplitude
+ The truncated value of the scalar `x` is the nearest integer `i` which
+ is closer to zero than `x` is. In short, the fractional part of the
+ signed number `x` is discarded.
Parameters
----------
@@ -789,7 +790,9 @@
add_newdoc('numpy.core.umath', 'degrees',
"""
- Convert angles from radians to degrees.
+ Convert angles from radians to degrees. This is the same
+ function as rad2deg but the latter is preferred because of
+ the more descriptive name.
Parameters
----------
@@ -804,6 +807,8 @@
See Also
--------
+ rad2deg : Convert angles from radians to degrees.
+ deg2rad : Convert angles from degrees to radians.
radians : Convert angles from degrees to radians.
unwrap : Remove large jumps in angle by wrapping.
@@ -818,6 +823,41 @@
""")
+add_newdoc('numpy.core.umath', 'rad2deg',
+ """
+ Convert angles from radians to degrees. This is the same
+ function as degrees but is preferred because its more
+ descriptive name.
+
+ Parameters
+ ----------
+ x : array_like
+ Angle in radians.
+
+ Returns
+ -------
+ y : ndarray
+ The corresponding angle in degrees.
+
+
+ See Also
+ --------
+ degrees : Convert angles from radians to degrees.
+ deg2rad : Convert angles from degrees to radians.
+ radians : Convert angles from degrees to radians.
+ unwrap : Remove large jumps in angle by wrapping.
+
+ Notes
+ -----
+ rad2deg(x) is ``180 * x / pi``.
+
+ Examples
+ --------
+ >>> np.rad2deg(np.pi/2)
+ 90.0
+
+ """)
+
add_newdoc('numpy.core.umath', 'divide',
"""
Divide arguments element-wise.
@@ -962,6 +1002,22 @@
""")
+add_newdoc('numpy.core.umath', 'exp2',
+ """
+ Calculate `2**p` for all `p` in the input array.
+
+ Parameters
+ ----------
+ x : array_like
+ Input values.
+
+ Returns
+ -------
+ out : ndarray
+ Element-wise 2 to the power `x`.
+
+ """)
+
add_newdoc('numpy.core.umath', 'expm1',
"""
Return the exponential of the elements in the array minus one.
@@ -1661,6 +1717,82 @@
""")
+add_newdoc('numpy.core.umath', 'log2',
+ """
+ Base-2 logarithm of `x`.
+
+ Parameters
+ ----------
+ x : array_like
+ Input values.
+
+ Returns
+ -------
+ y : ndarray
+ Base-2 logarithm of `x`.
+
+ See Also
+ --------
+ log, log10, log1p
+
+ """)
+
+add_newdoc('numpy.core.umath', 'logaddexp',
+ """
+ Logarithm of `exp(x) + exp(y)`.
+
+ This function is useful in statistics where the calculated probabilities of
+ events may be so small as to excede the range of normal floating point
+ numbers. In such cases the logarithm of the calculated probability is
+ stored. This function allows adding probabilities stored in such a fashion.
+
+ Parameters
+ ----------
+ x : array_like
+ Input values.
+ y : array_like
+ Input values.
+
+
+ Returns
+ -------
+ result : ndarray
+ Logarithm of `exp(x) + exp(y)`.
+
+ See Also
+ --------
+ logaddexp2
+
+ """)
+
+add_newdoc('numpy.core.umath', 'logaddexp2',
+ """
+ Base-2 Logarithm of `2**x + 2**y`.
+
+ This function is useful in machine learning when the calculated probabilities of
+ events may be so small as to excede the range of normal floating point
+ numbers. In such cases the base-2 logarithm of the calculated probability
+ can be used instead. This function allows adding probabilities stored in such a fashion.
+
+ Parameters
+ ----------
+ x : array_like
+ Input values.
+ y : array_like
+ Input values.
+
+
+ Returns
+ -------
+ result : ndarray
+ Base-2 logarithm of `2**x + 2**y`.
+
+ See Also
+ --------
+ logaddexp
+
+ """)
+
add_newdoc('numpy.core.umath', 'log1p',
"""
`log(1 + x)` in base `e`, elementwise.
@@ -1921,6 +2053,16 @@
""")
+add_newdoc('numpy.core.umath', 'fmax',
+ """
+
+ """)
+
+add_newdoc('numpy.core.umath', 'fmin',
+ """
+
+ """)
+
add_newdoc('numpy.core.umath', 'modf',
"""
Return the fractional and integral part of a number.
@@ -2102,7 +2244,8 @@
add_newdoc('numpy.core.umath', 'radians',
"""
- Convert angles from degrees to radians.
+ Convert angles from degrees to radians. This function is
+ the same as deg2rad, which is more descriptive..
Parameters
----------
@@ -2116,6 +2259,8 @@
See Also
--------
+ deg2rad : Convert angles from degrees to radians.
+ rad2deg : Convert angles from radians to degrees.
degrees : Convert angles from radians to degrees.
unwrap : Remove large jumps in angle by wrapping.
@@ -2130,6 +2275,39 @@
""")
+add_newdoc('numpy.core.umath', 'deg2rad',
+ """
+ Convert angles from degrees to radians. This is the same
+ function as radians, but deg2rad is a more descriptive name.
+
+ Parameters
+ ----------
+ x : array_like
+ Angles in degrees.
+
+ Returns
+ -------
+ y : ndarray
+ The corresponding angle in radians.
+
+ See Also
+ --------
+ radians : Convert angles from degrees to radians.
+ rad2deg : Convert angles from radians to degrees.
+ degrees : Convert angles from radians to degrees.
+ unwrap : Remove large jumps in angle by wrapping.
+
+ Notes
+ -----
+ ``deg2rad(x)`` is ``x * pi / 180``.
+
+ Examples
+ --------
+ >>> np.deg2rad(180)
+ 3.1415926535897931
+
+ """)
+
add_newdoc('numpy.core.umath', 'reciprocal',
"""
Return element-wise reciprocal.
Modified: trunk/numpy/core/code_generators/generate_umath.py
===================================================================
--- trunk/numpy/core/code_generators/generate_umath.py 2008-11-28 03:52:16 UTC (rev 6115)
+++ trunk/numpy/core/code_generators/generate_umath.py 2008-11-28 05:34:33 UTC (rev 6116)
@@ -330,12 +330,12 @@
),
'logaddexp' :
Ufunc(2, 1, None,
- "",
+ docstrings.get('numpy.core.umath.logaddexp'),
TD(flts, f="logaddexp")
),
'logaddexp2' :
Ufunc(2, 1, None,
- "",
+ docstrings.get('numpy.core.umath.logaddexp2'),
TD(flts, f="logaddexp2")
),
'bitwise_and' :
@@ -381,7 +381,7 @@
),
'rad2deg' :
Ufunc(1, 1, None,
- '',
+ docstrings.get('numpy.core.umath.rad2deg'),
TD(fltsM, f='rad2deg'),
),
'radians' :
@@ -391,7 +391,7 @@
),
'deg2rad' :
Ufunc(1, 1, None,
- '',
+ docstrings.get('numpy.core.umath.deg2rad'),
TD(fltsM, f='deg2rad'),
),
'arccos' :
@@ -474,7 +474,7 @@
),
'exp2' :
Ufunc(1, 1, None,
- '',
+ docstrings.get('numpy.core.umath.exp2'),
TD(flts, f='exp2'),
TD(M, f='exp2'),
),
@@ -492,7 +492,7 @@
),
'log2' :
Ufunc(1, 1, None,
- '',
+ docstrings.get('numpy.core.umath.log2'),
TD(flts, f='log2'),
TD(M, f='log2'),
),
@@ -522,7 +522,7 @@
),
'trunc' :
Ufunc(1, 1, None,
- '',
+ docstrings.get('numpy.core.umath.trunc'),
TD(flts, f='trunc'),
TD(M, f='trunc'),
),
More information about the Numpy-svn
mailing list