add doc for multinomial, dot, cumsum, clip, abs, exp, arctan (#15386)

python/mxnet/_numpy_op_doc.py

@@ -114,58 +114,25 @@ def _np_repeat(a, repeats, axis=None):
     pass
 
 
-def _npi_multinomial(a):
-    """Draw samples from a multinomial distribution.
-
-    The multinomial distribution is a multivariate generalisation of the binomial distribution.
-    Take an experiment with one of ``p`` possible outcomes. An example of such an experiment is throwing a dice,
-    where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments.
-    Its values, ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the outcome was ``i``.
-
-
-    Parameters
-    ----------
-    n : int
-        Number of experiments.
-    pvals : sequence of floats, length p
-        Probabilities of each of the p different outcomes. These should sum to 1
-        (however, the last element is always assumed to account for the remaining
-        probability, as long as ``sum(pvals[:-1]) <= 1)``.
-    size : int or tuple of ints, optional
-        Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` sam-
-        ples are drawn. Default is None, in which case a single value is returned.
-
-    Returns
-    -------
-    out : ndarray
-        The drawn samples, of shape size, if that was provided. If not, the shape is ``(N,)``.
-        In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution.
-    """
-    pass
-
-
 def _np_cumsum(a, axis=None, dtype=None, out=None):
-    """
+    """cumsum(a, axis=None, dtype=None, out=None)
+
     Return the cumulative sum of the elements along a given axis.
 
     Parameters
     ----------
-    a : array_like
+    a : ndarray
         Input array.
     axis : int, optional
         Axis along which the cumulative sum is computed. The default
         (None) is to compute the cumsum over the flattened array.
     dtype : dtype, optional
         Type of the returned array and of the accumulator in which the
         elements are summed.  If `dtype` is not specified, it defaults
-        to the dtype of `a`, unless `a` has an integer dtype with a
-        precision less than that of the default platform integer.  In
-        that case, the default platform integer is used.
+        to the dtype of `a`.
     out : ndarray, optional
         Alternative output array in which to place the result. It must
-        have the same shape and buffer length as the expected output
-        but the type will be cast if necessary. See `doc.ufuncs`
-        (Section "Output arguments") for more details.
+        have the same shape, type and buffer length as the expected output.
 
     Returns
     -------
@@ -174,5 +141,85 @@ def _np_cumsum(a, axis=None, dtype=None, out=None):
         specified, in which case a reference to `out` is returned. The
         result has the same size as `a`, and the same shape as `a` if
         `axis` is not None or `a` is a 1-d array.
+
+    Examples
+    --------
+    >>> a = np.array([[1,2,3], [4,5,6]])
+    >>> a
+    array([[1., 2., 3.],
+           [4., 5., 6.]])
+    >>> np.cumsum(a)
+    array([ 1.,  3.,  6., 10., 15., 21.])
+    >>> np.cumsum(a, dtype=float)     
+    array([ 1.,  3.,  6., 10., 15., 21.], dtype=float64)
+    >>> np.cumsum(a,axis=0)      
+    array([[1., 2., 3.],
+           [5., 7., 9.]])
+    >>> np.cumsum(a,axis=1)      
+    array([[ 1.,  3.,  6.],
+           [ 4.,  9., 15.]])
+    """
+    pass
+
+
+def _np_dot(a, b, out=None):
+    """dot(a, b, out=None)
+
+    Dot product of two arrays. Specifically,
+    
+    - If both `a` and `b` are 1-D arrays, it is inner product of vectors
+    
+    - If both `a` and `b` are 2-D arrays, it is matrix multiplication,
+    
+    - If either `a` or `b` is 0-D (scalar), it is equivalent to :func:`multiply`
+      and using ``np.multiply(a, b)`` or ``a * b`` is preferred.
+    
+    - If `a` is an N-D array and `b` is a 1-D array, it is a sum product over
+      the last axis of `a` and `b`.
+    
+    - If `a` is an N-D array and `b` is a 2-D array, it is a
+      sum product over the last axis of `a` and the second-to-last axis of `b`::
+    
+        dot(a, b)[i,j,k] = sum(a[i,j,:] * b[:,k])
+
+    Parameters
+    ----------
+    a : ndarray
+        First argument.
+    b : ndarray
+        Second argument.
+    
+    out : ndarray, optional
+        Output argument. It must have the same shape and type as the expected output.
+
+    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.
+        If `out` is given, then it is returned
+
+    Examples
+    --------
+    >>> a = np.array(3)
+    >>> b = np.array(4)
+    >>> np.dot(a, b)
+    array(12.)
+
+    For 2-D arrays it is the matrix product:
+
+    >>> a = np.array([[1, 0], [0, 1]])
+    >>> b = np.array([[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(5*6)[::-1].reshape((6,5))
+    >>> np.dot(a, b)[2,3,2,2]
+    array(29884.)
+    >>> np.sum(a[2,3,2,:] * b[:,2])
+    array(29884.)
     """
     pass

python/mxnet/ndarray/numpy/_op.py

@@ -1,3 +1,4 @@
+# pylint: disable=C0302
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -28,7 +29,7 @@
 __all__ = ['zeros', 'ones', 'maximum', 'minimum', 'stack', 'arange', 'argmax',
            'add', 'subtract', 'multiply', 'divide', 'mod', 'power', 'concatenate',
            'clip', 'split', 'swapaxes', 'expand_dims', 'tile', 'linspace',
-           'sin', 'cos', 'sinh', 'cosh', 'log10', 'sqrt']
+           'sin', 'cos', 'sinh', 'cosh', 'log10', 'sqrt', 'abs', 'exp', 'arctan']
 
 
 @set_module('mxnet.ndarray.numpy')
@@ -459,8 +460,9 @@ def power(x1, x2, out=None):
 
 @set_module('mxnet.ndarray.numpy')
 def clip(a, a_min, a_max, out=None):
-    """Clip (limit) the values in an array.
+    """clip(a, a_min, a_max, out=None)
 
+    Clip (limit) the values in an array.
     Given an interval, values outside the interval are clipped to
     the interval edges.  For example, if an interval of ``[0, 1]``
     is specified, values smaller than 0 become 0, and values larger
@@ -481,14 +483,28 @@ def clip(a, a_min, a_max, out=None):
     out : ndarray, optional
         The results will be placed in this array. It may be the input
         array for in-place clipping.  `out` must be of the right shape
-        to hold the output.
+        to hold the output.  Its type is preserved.
 
     Returns
     -------
     clipped_array : ndarray
         An array with the elements of `a`, but where values
         < `a_min` are replaced with `a_min`, and those > `a_max`
         with `a_max`.
+
+    Notes
+    -----
+    array_like `a_min` and `a_max` are not supported.
+
+    Examples
+    --------
+    >>> a = np.arange(10)
+    >>> np.clip(a, 1, 8)
+    array([1., 1., 2., 3., 4., 5., 6., 7., 8., 8.], dtype=float32)
+    >>> a
+    array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.], dtype=float32)
+    >>> np.clip(a, 3, 6, out=a)
+    array([3., 3., 3., 3., 4., 5., 6., 6., 6., 6.], dtype=float32)
     """
     if a_min is None and a_max is None:
         raise ValueError('array_clip: must set either max or min')
@@ -882,3 +898,117 @@ def sqrt(x, out=None, **kwargs):
     This function only supports input type of float.
     """
     return _unary_func_helper(x, _npi.sqrt, _np.sqrt, out=out, **kwargs)
+
+
+@set_module('mxnet.ndarray.numpy')
+def abs(x, out=None, **kwargs):
+    r"""abs(x, out=None, **kwargs)
+
+    Calculate the absolute value element-wise.
+
+    Parameters
+    ----------
+    x : ndarray or scalar
+        Input array.
+    out : ndarray or None, optional
+        A location into which the result is stored. If provided, it must have
+        a shape that the inputs broadcast to. If not provided or `None`,
+        a freshly-allocated array is returned.
+
+    Returns
+    -------
+    absolute : ndarray
+        An ndarray containing the absolute value of
+        each element in `x`. This is a scalar if `x` is a scalar.
+
+    Examples
+    --------
+    >>> x = np.array([-1.2, 1.2])
+    >>> np.abs(x)
+    array([1.2, 1.2])
+    """
+    return _unary_func_helper(x, _npi.abs, _np.abs, out=out, **kwargs)
+
+
+@set_module('mxnet.ndarray.numpy')
+def exp(x, out=None, **kwargs):
+    r"""exp(x, out=None, **kwargs)
+
+    Calculate the exponential of all elements in the input array.
+
+    Parameters
+    ----------
+    x : ndarray or scalar
+        Input values.
+    out : ndarray or None, optional
+        A location into which the result is stored. If provided, it must have
+        a shape that the inputs broadcast to. If not provided or `None`,
+        a freshly-allocated array is returned.
+
+    Returns
+    -------
+    out : ndarray or scalar
+        Output array, element-wise exponential of `x`.
+        This is a scalar if `x` is a scalar.
+
+    Examples
+    --------
+    >>> np.exp(1)
+    2.718281828459045
+    >>> x = np.array([-1, 1, -2, 2])
+    >>> np.exp(x)
+    array([0.36787945, 2.7182817 , 0.13533528, 7.389056  ])
+    """
+    return _unary_func_helper(x, _npi.exp, _np.exp, out=out, **kwargs)
+
+
+@set_module('mxnet.ndarray.numpy')
+def arctan(x, out=None, **kwargs):
+    r"""arctan(x, out=None, **kwargs)
+
+    Trigonometric inverse tangent, element-wise.
+
+    The inverse of tan, so that if ``y = tan(x)`` then ``x = arctan(y)``.
+
+    Parameters
+    ----------
+    x : ndarray or scalar
+        Input values.
+    out : ndarray or None, optional
+        A location into which the result is stored. If provided, it must have
+        a shape that the inputs broadcast to. If not provided or `None`,
+        a freshly-allocated array is returned.
+
+    Returns
+    -------
+    out : ndarray or scalar
+        Out has the same shape as `x`. It lies is in
+        ``[-pi/2, pi/2]`` (``arctan(+/-inf)`` returns ``+/-pi/2``).
+        This is a scalar if `x` is a scalar.
+
+    Notes
+    -----
+    `arctan` is a multi-valued function: for each `x` there are infinitely
+    many numbers `z` such that tan(`z`) = `x`.  The convention is to return
+    the angle `z` whose real part lies in [-pi/2, pi/2].
+
+    For real-valued input data types, `arctan` always returns real output.
+    For each value that cannot be expressed as a real number or infinity,
+    it yields ``nan`` and sets the `invalid` floating point error flag.
+
+    For complex-valued input, we do not have support for them yet.
+
+    The inverse tangent is also known as `atan` or tan^{-1}.
+
+    Examples
+    --------
+    We expect the arctan of 0 to be 0, and of 1 to be pi/4:
+
+    >>> x = np.array([0, 1])
+    >>> np.arctan(x)
+    array([0.       , 0.7853982])
+
+    >>> np.pi/4
+    0.7853981633974483
+    """
+    return _unary_func_helper(x, _npi.arctan, _np.arctan, out=out, **kwargs)

python/mxnet/ndarray/numpy/random.py

@@ -140,31 +140,46 @@ def normal(loc=0.0, scale=1.0, size=None, **kwargs):
 
 
 def multinomial(n, pvals, size=None):
-    """Draw samples from a multinomial distribution.
+    """multinomial(n, pvals, size=None)
+
+    Draw samples from a multinomial distribution.
 
     The multinomial distribution is a multivariate generalisation of the binomial distribution.
     Take an experiment with one of ``p`` possible outcomes. An example of such an experiment is throwing a dice,
     where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments.
     Its values, ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the outcome was ``i``.
 
-
     Parameters
     ----------
     n : int
         Number of experiments.
     pvals : sequence of floats, length p
-        Probabilities of each of the p different outcomes. These should sum to 1
-        (however, the last element is always assumed to account for the remaining
-        probability, as long as ``sum(pvals[:-1]) <= 1)``.
+        Probabilities of each of the p different outcomes. These should sum to 1.
     size : int or tuple of ints, optional
-        Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` sam-
-        ples are drawn. Default is None, in which case a single value is returned.
+        Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples
+        are drawn. Default is None, in which case a single value is returned.
 
     Returns
     -------
     out : ndarray
         The drawn samples, of shape size, if that was provided. If not, the shape is ``(N,)``.
         In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution.
+
+    Examples
+    --------
+    Throw a dice 1000 times, and 1000 times again:
+
+    >>> np.random.multinomial(1000, [1/6.]*6, size=2)
+    array([[164, 161, 179, 158, 150, 188],
+           [178, 162, 177, 143, 163, 177]])
+
+    A loaded die is more likely to land on number 6:
+
+    >>> np.random.multinomial(100, [1/7.]*5 + [2/7.])
+    array([19, 14, 12, 11, 21, 23])
+
+    >>> np.random.multinomial(100, [1.0 / 3, 2.0 / 3])
+    array([32, 68])
     """
     if isinstance(pvals, NDArray):
         return _npi.multinomial(pvals, pvals=None, n=n, size=size)