This is an automated email from the ASF dual-hosted git repository. haoj pushed a commit to branch numpy in repository https://gitbox.apache.org/repos/asf/incubator-mxnet.git
commit 90518ddb6692c7bd0d9625f1c086120bff9e7f44 Author: Huang, Guangtai <hgt...@foxmail.com> AuthorDate: Thu Jul 4 16:48:51 2019 +0800 [numpy][doc-fix] zeros_like, linspace, reciprocal, square, and arcsin (#15377) * add _np_zeros_like some fix on '_np_zeros_like' add '_npi_linspace' try reciprocal improve `zeros_like` improve `linspace` try build try build by delete `see also` in python/mxnet/context.py square & reciprocal finish reciprocal finish square finish arcsin revert context.py fix 2 mistakes bug fix for `linspace` and render unify docs try _np_linspace fix some mistakes in _numpy_op_doc.py remove `see also` sections from symbol docs. remove _npi_linspace from _numpy_op_doc fix `_numpy_op_doc`. fix `zeros_like` fix `linspace` finish reciprocal. fix `square`. fix `arcsin` fix problems about pylint fix example in `linspace` fix something fix according to the comments remove linkless `see also` fix according to comments fix to pass sanity change signature of `linspace` fix a mistake * fix bug for build website * fix render of note of `reciprocal` --- python/mxnet/_numpy_op_doc.py | 58 ++++-- python/mxnet/ndarray/numpy/_op.py | 213 +++++++++++++++++++++- python/mxnet/numpy/multiarray.py | 219 ++++++++++++++++++++++- python/mxnet/symbol/numpy/_symbol.py | 162 +++++++++++++++-- src/operator/numpy/np_elemwise_unary_op_basic.cc | 6 +- src/operator/numpy/np_elemwise_unary_op_basic.cu | 6 +- 6 files changed, 620 insertions(+), 44 deletions(-) diff --git a/python/mxnet/_numpy_op_doc.py b/python/mxnet/_numpy_op_doc.py index a27f209..232584c 100644 --- a/python/mxnet/_numpy_op_doc.py +++ b/python/mxnet/_numpy_op_doc.py @@ -75,7 +75,10 @@ def _np_ones_like(a): def _np_zeros_like(a): - """Return an array of zeros with the same shape and type as a given array. + r""" + zeros_like(a) + + Return an array of zeros with the same shape and type as a given array. Parameters ---------- @@ -87,6 +90,39 @@ def _np_zeros_like(a): ------- out : ndarray Array of zeros with the same shape and type as `a`. + + + See Also + -------- + ones_like : Return an array of ones with shape and type of input. + zeros : Return a new array setting values to zero. + + Examples + -------- + >>> x = np.arange(6) + >>> x = x.reshape((2, 3)) + >>> x + array([[0., 1., 2.], + [3., 4., 5.]]) + >>> np.zeros_like(x) + array([[0., 0., 0.], + [0., 0., 0.]]) + >>> y = np.arange(3) + >>> y + array([0., 1., 2.]) + >>> np.zeros_like(y) + array([0., 0., 0.]) + + Notes + ----- + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.zeros_like + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.zeros_like.html>`_ in + the following aspects: + + - The parameter `dtype` and `subok` are not supported now. + - Only 'C' order is supported. """ pass @@ -150,12 +186,12 @@ def _np_cumsum(a, axis=None, dtype=None, out=None): [4., 5., 6.]]) >>> np.cumsum(a) array([ 1., 3., 6., 10., 15., 21.]) - >>> np.cumsum(a, dtype=float) + >>> np.cumsum(a, dtype=float) array([ 1., 3., 6., 10., 15., 21.], dtype=float64) - >>> np.cumsum(a,axis=0) + >>> np.cumsum(a,axis=0) array([[1., 2., 3.], [5., 7., 9.]]) - >>> np.cumsum(a,axis=1) + >>> np.cumsum(a,axis=1) array([[ 1., 3., 6.], [ 4., 9., 15.]]) """ @@ -166,20 +202,20 @@ 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 @@ -188,7 +224,7 @@ def _np_dot(a, b, out=None): First argument. b : ndarray Second argument. - + out : ndarray, optional Output argument. It must have the same shape and type as the expected output. diff --git a/python/mxnet/ndarray/numpy/_op.py b/python/mxnet/ndarray/numpy/_op.py index 7aaba1a..282c08a 100644 --- a/python/mxnet/ndarray/numpy/_op.py +++ b/python/mxnet/ndarray/numpy/_op.py @@ -16,6 +16,7 @@ # specific language governing permissions and limitations # under the License. +# pylint: disable=too-many-lines """Namespace for numpy operators used in Gluon dispatched by F=ndarray.""" # pylint: disable=too-many-lines @@ -31,7 +32,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', 'abs', 'exp', 'arctan', 'sign', 'log', - 'degrees', 'log2', 'rint', 'radians', 'mean'] + 'degrees', 'log2', 'rint', 'radians', 'mean', 'reciprocal', 'square', 'arcsin'] @set_module('mxnet.ndarray.numpy') @@ -839,17 +840,18 @@ def tile(A, reps): @set_module('mxnet.ndarray.numpy') -def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, **kwargs): # pylint: disable=too-many-arguments - """Return evenly spaced numbers over a specified interval. +def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, ctx=None): # pylint: disable=too-many-arguments + r""" + Return evenly spaced numbers over a specified interval. Returns num evenly spaced samples, calculated over the interval [start, stop]. The endpoint of the interval can optionally be excluded. Parameters ---------- - start : array_like + start : real number The starting value of the sequence. - stop : array_like + stop : real number The end value of the sequence, unless endpoint is set to False. In that case, the sequence consists of all but the last of num + 1 evenly spaced samples, so that stop is excluded. Note that the step @@ -879,18 +881,53 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis Only returned if retstep is True Size of spacing between samples. + + See Also + -------- + arange : Similar to `linspace`, but uses a step size (instead of the + number of samples). + + Examples + -------- + >>> np.linspace(2.0, 3.0, num=5) + array([2. , 2.25, 2.5 , 2.75, 3. ]) + >>> np.linspace(2.0, 3.0, num=5, endpoint=False) + array([2. , 2.2, 2.4, 2.6, 2.8]) + >>> np.linspace(2.0, 3.0, num=5, retstep=True) + (array([2. , 2.25, 2.5 , 2.75, 3. ]), 0.25) + + Graphical illustration: + + >>> import matplotlib.pyplot as plt + >>> N = 8 + >>> y = np.zeros(N) + >>> x1 = np.linspace(0, 10, N, endpoint=True) + >>> x2 = np.linspace(0, 10, N, endpoint=False) + >>> plt.plot(x1.asnumpy(), y.asnumpy(), 'o') + [<matplotlib.lines.Line2D object at 0x...>] + >>> plt.plot(x2.asnumpy(), (y + 0.5).asnumpy(), 'o') + [<matplotlib.lines.Line2D object at 0x...>] + >>> plt.ylim([-0.5, 1]) + (-0.5, 1) + >>> plt.show() + Notes ----- - This function currently does not support ``start`` and ``stop`` as ndarrays and - axis could only be 0 now. + This function differs from the original `numpy.linspace + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linspace.html>`_ in + the following aspects: + + - `start` and `stop` do not support list, numpy ndarray and mxnet ndarray + - axis could only be 0 + - There could be an additional `ctx` argument to specify the device, e.g. the i-th + GPU. """ if isinstance(start, (list, _np.ndarray, NDArray)) or \ isinstance(stop, (list, _np.ndarray, NDArray)): raise NotImplementedError('start and stop only support int') if axis != 0: raise NotImplementedError("the function only support axis 0") - ctx = kwargs.pop('ctx', current_context()) if ctx is None: ctx = current_context() if retstep: @@ -1120,6 +1157,7 @@ def abs(x, out=None, **kwargs): return _unary_func_helper(x, _npi.abs, _np.abs, out=out, **kwargs) +@set_module('mxnet.ndarray.numpy') def sign(x, out=None, **kwargs): r""" sign(x, out=None) @@ -1494,3 +1532,162 @@ def radians(x, out=None, **kwargs): """ return _unary_func_helper(x, _npi.radians, _np.radians, out=out, **kwargs) + + +@set_module('mxnet.ndarray.numpy') +def reciprocal(x, out=None, **kwargs): + r""" + reciprocal(x, out=None) + + Return the reciprocal of the argument, element-wise. + + Calculates ``1/x``. + + Parameters + ---------- + x : ndarray or scalar + The values whose reciprocals are required. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + y : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Examples + -------- + >>> np.reciprocal(2.) + 0.5 + >>> x = np.array([1, 2., 3.33]) + >>> np.reciprocal(x) + array([1. , 0.5 , 0.3003003]) + + Notes + ----- + .. note:: + This function is not designed to work with integers. + + For integer arguments with absolute value larger than 1 the result is + always zero because of the way Python handles integer division. For + integer zero the result is an overflow. + + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.reciprocal + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.reciprocal.html>`_ in + the following aspects: + + - Only support ndarray and scalar now. + - `where` argument is not supported. + """ + return _unary_func_helper(x, _npi.reciprocal, _np.reciprocal, out=out, **kwargs) + + +@set_module('mxnet.ndarray.numpy') +def square(x, out=None, **kwargs): + r""" + square(x, out=None) + + Return the element-wise square of the input. + + Parameters + ---------- + x : ndarray or scalar + The values whose squares are required. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + y : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Examples + -------- + >>> np.square(2.) + 4.0 + >>> x = np.array([1, 2., -1]) + >>> np.square(x) + array([1., 4., 1.]) + + Notes + ----- + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.square + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.square.html>`_ in + the following aspects: + + - Only support ndarray and scalar now. + - `where` argument is not supported. + - Complex input is not supported. + """ + return _unary_func_helper(x, _npi.square, _np.square, out=out, **kwargs) + + +@set_module('mxnet.ndarray.numpy') +def arcsin(x, out=None, **kwargs): + r""" + arcsin(x, out=None) + + Inverse sine, element-wise. + + Parameters + ---------- + x : ndarray or scalar + `y`-coordinate on the unit circle. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + angle : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + The inverse sine of each element in `x`, in radians and in the + closed interval ``[-pi/2, pi/2]``. + + Examples + -------- + >>> np.arcsin(1) # pi/2 + 1.5707963267948966 + >>> np.arcsin(-1) # -pi/2 + -1.5707963267948966 + >>> np.arcsin(0) + 0.0 + + Notes + ----- + `arcsin` is a multivalued function: for each `x` there are infinitely + many numbers `z` such that :math:`sin(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, *arcsin* 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. + + The inverse sine is also known as `asin` or sin^{-1}. + + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.arcsin + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.arcsin.html>`_ in + the following aspects: + + - Only support ndarray or scalar now. + - `where` argument is not supported. + - Complex input is not supported. + + References + ---------- + Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, + 10th printing, New York: Dover, 1964, pp. 79ff. + http://www.math.sfu.ca/~cbm/aands/ + """ + return _unary_func_helper(x, _npi.arcsin, _np.arcsin, out=out, **kwargs) diff --git a/python/mxnet/numpy/multiarray.py b/python/mxnet/numpy/multiarray.py index 5e26ff6..513700c 100644 --- a/python/mxnet/numpy/multiarray.py +++ b/python/mxnet/numpy/multiarray.py @@ -47,7 +47,7 @@ __all__ = ['ndarray', 'empty', 'array', 'zeros', 'ones', 'maximum', 'minimum', ' 'argmax', 'add', 'subtract', 'multiply', 'divide', 'mod', 'power', 'concatenate', 'clip', 'split', 'swapaxes', 'expand_dims', 'tile', 'linspace', 'sin', 'cos', 'sin', 'cos', 'sinh', 'cosh', 'log10', 'sqrt', 'abs', 'exp', 'arctan', 'sign', 'log', - 'degrees', 'log2', 'rint', 'radians', 'mean'] + 'degrees', 'log2', 'rint', 'radians', 'mean', 'reciprocal', 'square', 'arcsin'] # This function is copied from ndarray.py since pylint @@ -1993,17 +1993,18 @@ def split(ary, indices_or_sections, axis=0): @set_module('mxnet.numpy') -def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, **kwargs): - """Return evenly spaced numbers over a specified interval. +def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, ctx=None): # pylint: disable=too-many-arguments + r""" + Return evenly spaced numbers over a specified interval. Returns num evenly spaced samples, calculated over the interval [start, stop]. The endpoint of the interval can optionally be excluded. Parameters ---------- - start : array_like + start : real number The starting value of the sequence. - stop : array_like + stop : real number The end value of the sequence, unless endpoint is set to False. In that case, the sequence consists of all but the last of num + 1 evenly spaced samples, so that stop is excluded. Note that the step @@ -2013,15 +2014,16 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis endpoint : bool, optional If True, stop is the last sample. Otherwise, it is not included. Default is True. - retstep: bool, optional + retstep : bool, optional If True, return (samples, step), where step is the spacing between samples. - dtype: dtype, optional + dtype : dtype, optional The type of the output array. If dtype is not given, infer the data type from the other input arguments. axis : int, optional The axis in the result to store the samples. Relevant only if start or stop are array-like. By default (0), the samples will be along a new axis inserted at the beginning. Use -1 to get an axis at the end. + Returns ------- samples : ndarray @@ -2031,8 +2033,50 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis step : float, optional Only returned if retstep is True Size of spacing between samples. + + + See Also + -------- + arange : Similar to `linspace`, but uses a step size (instead of the + number of samples). + + Examples + -------- + >>> np.linspace(2.0, 3.0, num=5) + array([2. , 2.25, 2.5 , 2.75, 3. ]) + >>> np.linspace(2.0, 3.0, num=5, endpoint=False) + array([2. , 2.2, 2.4, 2.6, 2.8]) + >>> np.linspace(2.0, 3.0, num=5, retstep=True) + (array([2. , 2.25, 2.5 , 2.75, 3. ]), 0.25) + + Graphical illustration: + + >>> import matplotlib.pyplot as plt + >>> N = 8 + >>> y = np.zeros(N) + >>> x1 = np.linspace(0, 10, N, endpoint=True) + >>> x2 = np.linspace(0, 10, N, endpoint=False) + >>> plt.plot(x1.asnumpy(), y.asnumpy(), 'o') + [<matplotlib.lines.Line2D object at 0x...>] + >>> plt.plot(x2.asnumpy(), (y + 0.5).asnumpy(), 'o') + [<matplotlib.lines.Line2D object at 0x...>] + >>> plt.ylim([-0.5, 1]) + (-0.5, 1) + >>> plt.show() + + Notes + ----- + + This function differs from the original `numpy.linspace + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linspace.html>`_ in + the following aspects: + + - `start` and `stop` do not support list, numpy ndarray and mxnet ndarray + - axis could only be 0 + - There could be an additional `ctx` argument to specify the device, e.g. the i-th + GPU. """ - return _mx_nd_np.linspace(start, stop, num, endpoint, retstep, dtype, axis, **kwargs) + return _mx_nd_np.linspace(start, stop, num, endpoint, retstep, dtype, axis, ctx) @set_module('mxnet.numpy') @@ -2670,3 +2714,162 @@ def radians(x, out=None, **kwargs): """ return _mx_nd_np.radians(x, out=out, **kwargs) + + +@set_module('mxnet.numpy') +def reciprocal(x, out=None, **kwargs): + r""" + reciprocal(x, out=None) + + Return the reciprocal of the argument, element-wise. + + Calculates ``1/x``. + + Parameters + ---------- + x : ndarray or scalar + The values whose reciprocals are required. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + y : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Examples + -------- + >>> np.reciprocal(2.) + 0.5 + >>> x = np.array([1, 2., 3.33]) + >>> np.reciprocal(x) + array([1. , 0.5 , 0.3003003]) + + Notes + ----- + .. note:: + This function is not designed to work with integers. + + For integer arguments with absolute value larger than 1 the result is + always zero because of the way Python handles integer division. For + integer zero the result is an overflow. + + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.reciprocal + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.reciprocal.html>`_ in + the following aspects: + + - Only support ndarray and scalar now. + - `where` argument is not supported. + """ + return _mx_nd_np.reciprocal(x, out=out, **kwargs) + + +@set_module('mxnet.numpy') +def square(x, out=None, **kwargs): + r""" + square(x, out=None) + + Return the element-wise square of the input. + + Parameters + ---------- + x : ndarray or scalar + The values whose squares are required. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + y : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Examples + -------- + >>> np.square(2.) + 4.0 + >>> x = np.array([1, 2., -1]) + >>> np.square(x) + array([1., 4., 1.]) + + Notes + ----- + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.square + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.square.html>`_ in + the following aspects: + + - Only support ndarray and scalar now. + - `where` argument is not supported. + - Complex input is not supported. + """ + return _mx_nd_np.square(x, out=out, **kwargs) + + +@set_module('mxnet.numpy') +def arcsin(x, out=None, **kwargs): + r""" + arcsin(x, out=None) + + Inverse sine, element-wise. + + Parameters + ---------- + x : ndarray or scalar + `y`-coordinate on the unit circle. + out : ndarray or None, optional + A location into which the result is stored. + If provided, it must have the same shape as the input. + If not provided or None, a freshly-allocated array is returned. + + Returns + ------- + angle : ndarray or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + The inverse sine of each element in `x`, in radians and in the + closed interval ``[-pi/2, pi/2]``. + + Examples + -------- + >>> np.arcsin(1) # pi/2 + 1.5707963267948966 + >>> np.arcsin(-1) # -pi/2 + -1.5707963267948966 + >>> np.arcsin(0) + 0.0 + + Notes + ----- + `arcsin` is a multivalued function: for each `x` there are infinitely + many numbers `z` such that :math:`sin(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, *arcsin* 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. + + The inverse sine is also known as `asin` or sin^{-1}. + + The output `ndarray` has the same `ctx` as the input `ndarray`. + + This function differs from the original `numpy.arcsin + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.arcsin.html>`_ in + the following aspects: + + - Only support ndarray or scalar now. + - `where` argument is not supported. + - Complex input is not supported. + + References + ---------- + Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, + 10th printing, New York: Dover, 1964, pp. 79ff. + http://www.math.sfu.ca/~cbm/aands/ + """ + return _mx_nd_np.arcsin(x, out=out, **kwargs) diff --git a/python/mxnet/symbol/numpy/_symbol.py b/python/mxnet/symbol/numpy/_symbol.py index e499d8e..233f671 100644 --- a/python/mxnet/symbol/numpy/_symbol.py +++ b/python/mxnet/symbol/numpy/_symbol.py @@ -32,7 +32,8 @@ from . import _internal as _npi __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', - 'abs', 'exp', 'arctan', 'sign', 'log', 'degrees', 'log2', 'rint', 'radians', 'mean'] + 'abs', 'exp', 'arctan', 'sign', 'log', 'degrees', 'log2', 'rint', 'radians', 'mean', + 'reciprocal', 'square', 'arcsin'] def _num_outputs(sym): @@ -1449,17 +1450,18 @@ def tile(A, reps): @set_module('mxnet.symbol.numpy') -def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, **kwargs): # pylint: disable=too-many-arguments - """Return evenly spaced numbers over a specified interval. +def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0, ctx=None): # pylint: disable=too-many-arguments + r""" + Return evenly spaced numbers over a specified interval. Returns num evenly spaced samples, calculated over the interval [start, stop]. The endpoint of the interval can optionally be excluded. Parameters ---------- - start : array_like + start : real number The starting value of the sequence. - stop : array_like + stop : real number The end value of the sequence, unless endpoint is set to False. In that case, the sequence consists of all but the last of num + 1 evenly spaced samples, so that stop is excluded. Note that the step @@ -1469,18 +1471,19 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis endpoint : bool, optional If True, stop is the last sample. Otherwise, it is not included. Default is True. - retstep: bool, optional + retstep : bool, optional If True, return (samples, step), where step is the spacing between samples. - dtype: dtype, optional + dtype : dtype, optional The type of the output array. If dtype is not given, infer the data type from the other input arguments. axis : int, optional The axis in the result to store the samples. Relevant only if start or stop are array-like. By default (0), the samples will be along a new axis inserted at the beginning. Use -1 to get an axis at the end. + Returns ------- - samples : ndarray + samples : _Symbol There are num equally spaced samples in the closed interval `[start, stop]` or the half-open interval `[start, stop)` (depending on whether endpoint is True or False). @@ -1488,17 +1491,29 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis Only returned if retstep is True Size of spacing between samples. + + See Also + -------- + arange : Similar to `linspace`, but uses a step size (instead of the + number of samples). + Notes ----- - This function currently does not support ``start`` and ``stop`` as ndarrays and - axis could only be 0 now. + + This function differs from the original `numpy.linspace + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linspace.html>`_ in + the following aspects: + + - `start` and `stop` do not support list, numpy ndarray and mxnet ndarray + - axis could only be 0 + - There could be an additional `ctx` argument to specify the device, e.g. the i-th + GPU. """ if isinstance(start, (list, _np.ndarray)) or \ isinstance(stop, (list, _np.ndarray)): raise NotImplementedError('start and stop only support int') if axis != 0: raise NotImplementedError("the function only support axis 0") - ctx = kwargs.pop('ctx', current_context()) if ctx is None: ctx = current_context() if retstep: @@ -1980,4 +1995,129 @@ def radians(x, out=None, **kwargs): return _unary_func_helper(x, _npi.radians, _np.radians, out=out, **kwargs) +@set_module('mxnet.symbol.numpy') +def reciprocal(x, out=None, **kwargs): + r""" + reciprocal(x, out=None) + + Return the reciprocal of the argument, element-wise. + + Calculates ``1/x``. + + Parameters + ---------- + x : _Symbol or scalar + The values whose reciprocals are required. + out : _Symbol, or None, optional + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + y : _Symbol or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Notes + ----- + .. note:: + This function is not designed to work with integers. + + For integer arguments with absolute value larger than 1 the result is + always zero because of the way Python handles integer division. For + integer zero the result is an overflow. + + The output `symbol` has the same `ctx` as the input `symbol`. + + This function differs from the original `numpy.reciprocal + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.reciprocal.html>`_ in + the following aspects: + + - Only support _Symbol and scalar now. + - `where` argument is not supported. + """ + return _unary_func_helper(x, _npi.reciprocal, _np.reciprocal, out=out, **kwargs) + + +@set_module('mxnet.symbol.numpy') +def square(x, out=None, **kwargs): + r""" + square(x, out=None) + + Return the element-wise square of the input. + + Parameters + ---------- + x : _Symbol or scalar + The values whose reciprocals are required. + out : _Symbol, or None, optional + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + y : _Symbol or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Notes + ----- + The output `symbol` has the same `ctx` as the input `symbol`. + + This function differs from the original `numpy.square + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.square.html>`_ in + the following aspects: + + - Only support _Symbol and scalar now. + - `where` argument is not supported. + """ + return _unary_func_helper(x, _npi.square, _np.square, out=out, **kwargs) + + +@set_module('mxnet.symbol.numpy') +def arcsin(x, out=None, **kwargs): + r""" + arcsin(x, out=None) + + Inverse sine, element-wise. + + Parameters + ---------- + x : _Symbol or scalar + The values whose reciprocals are required. + out : _Symbol, or None, optional + Dummy parameter to keep the consistency with the ndarray counterpart. + + Returns + ------- + angle : _Symbol or scalar + Output array is same shape and type as x. This is a scalar if x is a scalar. + + Notes + ----- + `arcsin` is a multivalued function: for each `x` there are infinitely + many numbers `z` such that :math:`sin(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, *arcsin* 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. + + The inverse sine is also known as `asin` or sin^{-1}. + + The output `symbol` has the same `ctx` as the input `symbol`. + + This function differs from the original `numpy.arcsin + <https://docs.scipy.org/doc/numpy/reference/generated/numpy.arcsin.html>`_ in + the following aspects: + + - Only support _Symbol or scalar now. + - `where` argument is not supported. + - Complex input is not supported. + + References + ---------- + Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, + 10th printing, New York: Dover, 1964, pp. 79ff. + http://www.math.sfu.ca/~cbm/aands/ + """ + return _unary_func_helper(x, _npi.arcsin, _np.arcsin, 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 f98f7df..7f30de0 100644 --- a/src/operator/numpy/np_elemwise_unary_op_basic.cc +++ b/src/operator/numpy/np_elemwise_unary_op_basic.cc @@ -95,7 +95,7 @@ Example:: .set_attr<nnvm::FGradient>("FGradient", ElemwiseGradUseNone{"negative"}); // reciprocal -MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_reciprocal, "x", mshadow_op::reciprocal) +MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_npi_reciprocal, "x", mshadow_op::reciprocal) .describe(R"code(Return the reciprocal of the argument, element-wise. Example:: reciprocal([-2, 1, 3, 1.6, 0.2]) = [-0.5, 1.0, 0.33333334, 0.625, 5.0] @@ -167,7 +167,7 @@ Example:: .set_attr<nnvm::FGradient>("FGradient", MakeZeroGradNodes); // square -MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_square, "x", mshadow_op::square) +MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_npi_square, "x", mshadow_op::square) .describe(R"code(Return the element-wise square of the input. Example:: square([2, 3, 4]) = [4, 9, 16] @@ -279,7 +279,7 @@ MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_tan, "x", mshadow_op::tan) .set_attr<nnvm::FGradient>("FGradient", ElemwiseGradUseOut{ "_backward_tan" }); // arcsin -MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_np_arcsin, "x", mshadow_op::arcsin) +MXNET_OPERATOR_REGISTER_NUMPY_UNARY(_npi_arcsin, "x", mshadow_op::arcsin) .describe(R"code(Returns element-wise inverse sine of the input array. .. math:: arcsin([-1, -.707, 0, .707, 1]) = [-\pi/2, -\pi/4, 0, \pi/4, \pi/2] diff --git a/src/operator/numpy/np_elemwise_unary_op_basic.cu b/src/operator/numpy/np_elemwise_unary_op_basic.cu index bc04b38..8fb1692 100644 --- a/src/operator/numpy/np_elemwise_unary_op_basic.cu +++ b/src/operator/numpy/np_elemwise_unary_op_basic.cu @@ -41,7 +41,7 @@ NNVM_REGISTER_OP(__name$) \ MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_negative, mshadow_op::negation); -MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_reciprocal, mshadow_op::reciprocal); +MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_reciprocal, mshadow_op::reciprocal); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_absolute, mshadow_op::abs); @@ -57,7 +57,7 @@ MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_trunc, mshadow_op::trunc); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_fix, mshadow_op::fix); -MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_square, mshadow_op::square); +MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_square, mshadow_op::square); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_sqrt, mshadow_op::square_root); @@ -84,7 +84,7 @@ MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_cos, mshadow_op::cos); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_tan, mshadow_op::tan); -MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_arcsin, mshadow_op::arcsin); +MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_npi_arcsin, mshadow_op::arcsin); MXNET_OPERATOR_REGISTER_NUMPY_UNARY_GPU(_np_arccos, mshadow_op::arccos);