[Numpy-svn] r6116 - in trunk: doc/source/reference numpy/core/code_generators

numpy-svn@scip... numpy-svn@scip...
Thu Nov 27 23:34:41 CST 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