From 9582869974d522cf5b9e86ee1cbb55f161cf62dd Mon Sep 17 00:00:00 2001 From: Haozheng Fan Date: Fri, 28 Jun 2019 11:54:59 +0800 Subject: [PATCH] add doc for multinomial, dot, cumsum, clip, abs, exp, arctan (#15386) --- python/mxnet/_numpy_op_doc.py | 123 +++++++++++----- python/mxnet/ndarray/numpy/_op.py | 136 +++++++++++++++++- python/mxnet/ndarray/numpy/random.py | 29 +++- python/mxnet/numpy/multiarray.py | 135 ++++++++++++++++- python/mxnet/numpy/random.py | 29 +++- python/mxnet/symbol/numpy/_symbol.py | 97 ++++++++++++- .../numpy/np_elemwise_unary_op_basic.cc | 6 +- .../numpy/np_elemwise_unary_op_basic.cu | 4 +- 8 files changed, 492 insertions(+), 67 deletions(-) diff --git a/python/mxnet/_numpy_op_doc.py b/python/mxnet/_numpy_op_doc.py index ca8636cf5029..f32e832ca8b0 100644 --- a/python/mxnet/_numpy_op_doc.py +++ b/python/mxnet/_numpy_op_doc.py @@ -114,43 +114,14 @@ 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 @@ -158,14 +129,10 @@ def _np_cumsum(a, axis=None, dtype=None, out=None): 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 diff --git a/python/mxnet/ndarray/numpy/_op.py b/python/mxnet/ndarray/numpy/_op.py index 449f495a4915..132b1795341d 100644 --- a/python/mxnet/ndarray/numpy/_op.py +++ b/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,7 +483,7 @@ 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 ------- @@ -489,6 +491,20 @@ def clip(a, a_min, a_max, out=None): 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) diff --git a/python/mxnet/ndarray/numpy/random.py b/python/mxnet/ndarray/numpy/random.py index 8607fd5c3514..4522f30dc85e 100644 --- a/python/mxnet/ndarray/numpy/random.py +++ b/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) diff --git a/python/mxnet/numpy/multiarray.py b/python/mxnet/numpy/multiarray.py index 9d9966b8066e..97571ef4465d 100644 --- a/python/mxnet/numpy/multiarray.py +++ b/python/mxnet/numpy/multiarray.py @@ -46,7 +46,7 @@ __all__ = ['ndarray', 'empty', 'array', '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'] + 'sinh', 'cosh', 'log10', 'sqrt', 'abs', 'exp', 'arctan'] # This function is copied from ndarray.py since pylint @@ -1702,8 +1702,9 @@ def power(x1, x2, out=None): @set_module('mxnet.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 @@ -1724,7 +1725,7 @@ 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 ------- @@ -1732,6 +1733,20 @@ def clip(a, a_min, a_max, out=None): 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) """ return _mx_nd_np.clip(a, a_min, a_max, out=out) @@ -2057,3 +2072,117 @@ def sqrt(x, out=None, **kwargs): This function only supports input type of float. """ return _mx_nd_np.sqrt(x, out=out, **kwargs) + + +@set_module('mxnet.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 _mx_nd_np.abs(x, out=out, **kwargs) + + +@set_module('mxnet.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 _mx_nd_np.exp(x, out=out, **kwargs) + + +@set_module('mxnet.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 _mx_nd_np.arctan(x, out=out, **kwargs) diff --git a/python/mxnet/numpy/random.py b/python/mxnet/numpy/random.py index cda1adafe24f..2a4fe0ed98fb 100644 --- a/python/mxnet/numpy/random.py +++ b/python/mxnet/numpy/random.py @@ -101,30 +101,45 @@ def normal(loc=0.0, scale=1.0, size=None, **kwargs): def multinomial(n, pvals, size=None, **kwargs): - """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]) """ return _mx_nd_np.random.multinomial(n, pvals, size, **kwargs) diff --git a/python/mxnet/symbol/numpy/_symbol.py b/python/mxnet/symbol/numpy/_symbol.py index 55577e9e45f0..8970beadf984 100644 --- a/python/mxnet/symbol/numpy/_symbol.py +++ b/python/mxnet/symbol/numpy/_symbol.py @@ -31,7 +31,8 @@ __all__ = ['zeros', 'ones', 'maximum', 'minimum', 'stack', 'concatenate', 'arange', 'argmax', 'clip', 'add', 'subtract', 'multiply', 'divide', 'mod', 'power', 'split', 'swapaxes', - 'expand_dims', 'tile', 'linspace', 'sin', 'cos', 'sinh', 'cosh', 'log10', 'sqrt'] + 'expand_dims', 'tile', 'linspace', 'sin', 'cos', 'sinh', 'cosh', 'log10', 'sqrt', + 'abs', 'exp', 'arctan'] def _num_outputs(sym): @@ -1154,8 +1155,9 @@ def argmax(a, axis=None, out=None): @set_module('mxnet.symbol.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 @@ -1173,10 +1175,10 @@ def clip(a, a_min, a_max, out=None): Maximum value. If `None`, clipping is not performed on upper interval edge. Not more than one of `a_min` and `a_max` may be `None`. - out : _Symbol, optional + out : _Symbol or `None` 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 ------- @@ -1184,6 +1186,10 @@ def clip(a, a_min, a_max, out=None): 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. """ if a_min is None and a_max is None: raise ValueError('array_clip: must set either max or min') @@ -1555,4 +1561,87 @@ def sqrt(x, out=None, **kwargs): return _unary_func_helper(x, _npi.sqrt, _np.sqrt, out=out, **kwargs) +@set_module('mxnet.symbol.numpy') +def abs(x, out=None, **kwargs): + r"""abs(x, out=None, **kwargs) + + Calculate the absolute value element-wise. + + Parameters + ---------- + x : _Symbol or scalar + Input array. + out : _Symbol or None + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + absolute : _Symbol + An ndarray containing the absolute value of + each element in `x`. This is a scalar if `x` is a scalar. + """ + return _unary_func_helper(x, _npi.abs, _np.abs, out=out, **kwargs) + + +@set_module('mxnet.symbol.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 : _Symbol or scalar + Input values. + out : _Symbol or None + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + out : _Symbol + Output array, element-wise exponential of `x`. + This is a scalar if `x` is a scalar. + """ + return _unary_func_helper(x, _npi.exp, _np.exp, out=out, **kwargs) + + +@set_module('mxnet.symbol.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 : _Symbol or scalar + Input values. + out : _Symbol or None + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + out : _Symbol + 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}. + """ + return _unary_func_helper(x, _npi.arctan, _np.arctan, out=out, **kwargs) + + _set_np_symbol_class(_Symbol) diff --git a/src/operator/numpy/np_elemwise_unary_op_basic.cc b/src/operator/numpy/np_elemwise_unary_op_basic.cc index 4932ee8de620..768f1bbb1f35 100644 --- a/src/operator/numpy/np_elemwise_unary_op_basic.cc +++ b/src/operator/numpy/np_elemwise_unary_op_basic.cc @@ -104,7 +104,7 @@ Example:: // abs MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_absolute, "x", mshadow_op::abs) -.add_alias("_np_abs") +.add_alias("_npi_abs") .describe(R"code(Returns element-wise absolute value of the input. Example:: absolute([-2, 0, 3]) = [2, 0, 3] @@ -191,7 +191,7 @@ Example:: .set_attr("FGradient", ElemwiseGradUseOut{"_backward_cbrt"}); // exp -MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_exp, "x", mshadow_op::exp) +MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_npi_exp, "x", mshadow_op::exp) .describe(R"code(Calculate the exponential of all elements in the input array. Example:: exp([0, 1, 2]) = [1., 2.71828175, 7.38905621] @@ -298,7 +298,7 @@ The storage type of ``arccos`` output is always dense .set_attr("FGradient", ElemwiseGradUseIn{ "_backward_arccos" }); // arctan -MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_arctan, "x", mshadow_op::arctan) +MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_npi_arctan, "x", mshadow_op::arctan) .describe(R"code(Returns element-wise inverse tangent of the input array. .. math:: arctan([-1, 0, 1]) = [-\pi/4, 0, \pi/4] diff --git a/src/operator/numpy/np_elemwise_unary_op_basic.cu b/src/operator/numpy/np_elemwise_unary_op_basic.cu index 887c74e63e3e..8364ace1ed7d 100644 --- a/src/operator/numpy/np_elemwise_unary_op_basic.cu +++ b/src/operator/numpy/np_elemwise_unary_op_basic.cu @@ -63,7 +63,7 @@ MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_sqrt, mshadow_op::square_root); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_cbrt, mshadow_op::cube_root); -MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_exp, mshadow_op::exp); +MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_exp, mshadow_op::exp); NNVM_REGISTER_OP(_np_log) .set_attr("FCompute", UnaryOp::Compute); @@ -88,7 +88,7 @@ MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_arcsin, mshadow_op::arcsin); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_arccos, mshadow_op::arccos); -MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_arctan, mshadow_op::arctan); +MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_arctan, mshadow_op::arctan); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_degrees, mshadow_op::degrees);