You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mxnet.apache.org by GitBox <gi...@apache.org> on 2021/10/03 22:57:09 UTC
[GitHub] [incubator-mxnet] barry-jin commented on a change in pull request #20592: Standardize MXNet NumPy Statistical & Linalg Functions
barry-jin commented on a change in pull request #20592:
URL: https://github.com/apache/incubator-mxnet/pull/20592#discussion_r720917943
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -4168,11 +4248,10 @@ def expm1(x, out=None, **kwargs):
"""
return _mx_nd_np.expm1(x, out=out, **kwargs)
-
Review comment:
Do not remove/add any unnecessary new lines.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -5183,6 +5469,58 @@ def arcsinh(x, out=None, **kwargs):
"""
return _mx_nd_np.arcsinh(x, out=out, **kwargs)
+asinh = arcsinh
+asinh.__doc__ = """
+ Inverse hyperbolic cosine, element-wise.
+
+ Notes
+ ----------
+ `asinh` is a alias for `arcsinh`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#asinh-x
+ instead of an official NumPy operator.
+
+ >>>np.asinh is np.arcsinh
+ True
+
+ Parameters
+ ----------
+ x : ndarray or scalar
+ Input array.
+ out : ndarray or None, optional
+ A location into which the result is stored.
+
+ Returns
+ -------
+ asinh : ndarray
+ Array of the same shape as `x`.
+ This is a scalar if `x` is a scalar.
+
+ .. note::
Review comment:
The same here.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -3592,6 +3616,7 @@ def remainder(x1, x2, out=None, **kwargs):
return _mx_nd_np.remainder(x1, x2, out=out)
+
Review comment:
Do not remove/add any unnecessary new lines.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -6533,6 +6972,56 @@ def dsplit(ary, indices_or_sections):
"""
return _mx_nd_np.dsplit(ary, indices_or_sections)
+@set_module('mxnet.numpy')
+def concat(seq, axis=0, out=None):
+ """Join a sequence of arrays along an existing axis.
+
+ Parameters
+ ----------
+ a1, a2, ... : sequence of array_like
+ The arrays must have the same shape, except in the dimension
+ corresponding to `axis` (the first, by default).
+ axis : int, optional
+ The axis along which the arrays will be joined. If axis is None,
+ arrays are flattened before use. Default is 0.
+ out : ndarray, optional
+ If provided, the destination to place the result. The shape must be
+ correct, matching that of what concatenate would have returned if no
+ out argument were specified.
+
+ Returns
+ -------
+ res : ndarray
+ The concatenated array.
+
+ See Also
+ --------
+ split : Split array into a list of multiple sub-arrays of equal size.
+ hsplit : Split array into multiple sub-arrays horizontally (column wise)
+ vsplit : Split array into multiple sub-arrays vertically (row wise)
+ dsplit : Split array into multiple sub-arrays along the 3rd axis (depth).
+ stack : Stack a sequence of arrays along a new axis.
+ hstack : Stack arrays in sequence horizontally (column wise)
+ vstack : Stack arrays in sequence vertically (row wise)
+ dstack : Stack arrays in sequence depth wise (along third dimension)
+
+ Examples
+ --------
+ >>> a = np.array([[1, 2], [3, 4]])
+ >>> b = np.array([[5, 6]])
+ >>> np.concat((a, b), axis=0)
+ array([[1., 2.],
+ [3., 4.],
+ [5., 6.]])
+
+ >>> np.concat((a, b.T), axis=1)
+ array([[1., 2., 5.],
+ [3., 4., 6.]])
+
Review comment:
Add note here to elaborate that concat is a standardized API and is equivelant to concatenate and also provide the reference.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -4168,11 +4248,10 @@ def expm1(x, out=None, **kwargs):
"""
return _mx_nd_np.expm1(x, out=out, **kwargs)
-
@set_module('mxnet.numpy')
@wrap_np_unary_func
def arcsin(x, out=None, **kwargs):
- r"""
Review comment:
What should 'r' be removed here?
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -4264,6 +4405,49 @@ def arccos(x, out=None, **kwargs):
"""
return _mx_nd_np.arccos(x, out=out, **kwargs)
+acos = arccos
+acos.__doc__ = """
+ Trigonometric inverse cosine, element-wise.
+ The inverse of cos so that, if y = cos(x), then x = acos(y).
+
+ Notes
+ ----------
+ `acos` is a alias for `arccos`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#acos-x
+ instead of an official NumPy operator.
+
+ >>>np.acos is np.arccos
+ True
+
+ Parameters
+ ----------
+ x : ndarray
+ x-coordinate on the unit circle. For real arguments, the domain is [-1, 1].
+ out : ndarray, 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.
+ A tuple (possible only as a keyword argument) must have length equal to the number of outputs.
+
+ Returns
+ ----------
+ angle : ndarray
+ The angle of the ray intersecting the unit circle at the given x-coordinate in radians [0, pi].
+ This is a scalar if x is a scalar.
+
+ Notes
Review comment:
Could you append a note here to elaborate that acos is a standardized API and is equivelant to arccos and also provide the reference.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -4309,6 +4493,56 @@ def arctan(x, out=None, **kwargs):
"""
return _mx_nd_np.arctan(x, out=out, **kwargs)
+atan = arctan
+atan.__doc__ = """
+ Trigonometric inverse tangent, element-wise.
+ The inverse of tan, so that if ``y = tan(x)`` then ``x = atan(y)``.
+
+ Notes
+ ---------
+ `atan` is a alias for `arctan`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#atan-x
+ instead of an official NumPy operator.
+
+ >>>np.atan is np.arctan
+ True
+
+ 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]`` (``atan(+/-inf)`` returns ``+/-pi/2``).
+ This is a scalar if `x` is a scalar.
+
+ Notes
Review comment:
Could you append a note here to elaborate that atan is a standardized API and is equivelant to arctan and also provide the reference.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -55,26 +55,25 @@
from .fallback import * # pylint: disable=wildcard-import,unused-wildcard-import
from . import fallback
-
Review comment:
Do not remove/add any unnecessary new lines.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -8877,6 +9460,52 @@ def ldexp(x1, x2, out=None, **kwargs):
"""
return _mx_nd_np.ldexp(x1, x2, out)
+@set_module('mxnet.numpy')
+def vecdot(a, b, axis=None):
Review comment:
Move vecdot to mxnet.numpy.linalg namespace.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -4225,6 +4304,68 @@ def arcsin(x, out=None, **kwargs):
"""
return _mx_nd_np.arcsin(x, out=out, **kwargs)
+asin = arcsin
+asin.__doc__ = """
+ Inverse sine, element-wise.
+
+ Notes
+ ----------
+ `asin` is a alias for `arcsin`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#asin-x
+ instead of an official NumPy operator.
+
+ >>>np.asin is np.asin
+ True
+
+ 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.asin(1) # pi/2
+ 1.5707963267948966
+ >>> np.asin(-1) # -pi/2
+ -1.5707963267948966
+ >>> np.asin(0)
+ 0.0
+
+ .. note::
+ `asin` 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, *asin* 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.
Review comment:
Could you append a note here to elaborate that asin is a standardized API and is equivelant to arcsin and also provide the reference.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -5277,6 +5665,57 @@ def arctanh(x, out=None, **kwargs):
"""
return _mx_nd_np.arctanh(x, out=out, **kwargs)
+atanh = arctanh
+atanh.__doc__ = """
+ Inverse hyperbolic tangent, element-wise.
+
+ Notes
+ `atanh` is a alias for `arctanh`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#atanh-x
+ instead of an official NumPy operator.
+
+ >>>np.atanh is np.arctanh
+ True
+
+ Parameters
+ ----------
+ x : ndarray or scalar
+ Input array.
+ out : ndarray or None, optional
+ A location into which the result is stored.
+
+ Returns
+ -------
+ atanh : ndarray
+ Array of the same shape as `x`.
+ This is a scalar if `x` is a scalar.
+
+ .. note::
Review comment:
The same here.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -5230,6 +5568,56 @@ def arccosh(x, out=None, **kwargs):
"""
return _mx_nd_np.arccosh(x, out=out, **kwargs)
+acosh = arccosh
+acosh.__doc__ = """
+ Inverse hyperbolic cosine, element-wise.
+
+ Notes
+ `acosh` is a alias for `arccosh`. It is a standard API in
+ https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#acosh-x
+ instead of an official NumPy operator.
+
+ >>>np.acosh is np.arccosh
+ True
+
+ Parameters
+ ----------
+ x : ndarray or scalar
+ Input array.
+ out : ndarray or None, optional
+ A location into which the result is stored.
+
+ Returns
+ -------
+ acosh : ndarray
+ Array of the same shape as `x`.
+ This is a scalar if `x` is a scalar.
+
+ .. note::
+ `acosh` is a multivalued function: for each `x` there are infinitely
Review comment:
The same here.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -5866,7 +6305,7 @@ def trace(a, offset=0, axis1=0, axis2=1, out=None):
@set_module('mxnet.numpy')
-def transpose(a, axes=None):
+def transpose(a: array, axes=None):
Review comment:
Currently, we do not need to add type hint as some of the CI is still using Python < 3.8
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -8877,6 +9460,52 @@ def ldexp(x1, x2, out=None, **kwargs):
"""
return _mx_nd_np.ldexp(x1, x2, out)
+@set_module('mxnet.numpy')
+def vecdot(a, b, axis=None):
+ r"""
+ Return the dot product of two vectors.
+ Note that `vecdot` handles multidimensional arrays differently than `dot`:
+ it does *not* perform a matrix product, but flattens input arguments
+ to 1-D vectors first. Consequently, it should only be used for vectors.
+
+ Parameters
+ ----------
+ a : ndarray
+ First argument to the dot product.
+ b : ndarray
+ Second argument to the dot product.
+ axis : axis over which to compute the dot product. Must be an integer on
+ the interval [-N, N) , where N is the rank (number of dimensions) of
+ the shape determined according to Broadcasting . If specified as a
+ negative integer, the function must determine the axis along which
+ to compute the dot product by counting backward from the last dimension
+ (where -1 refers to the last dimension). If None , the function must
+ compute the dot product over the last axis. Default: None .
+
+ Returns
+ -------
+ output : ndarray
+ Dot product of `a` and `b`.
+
+ See Also
+ --------
+ dot : Return the dot product without using the complex conjugate of the
+ first argument.
+
+ Examples
+ --------
+ Note that higher-dimensional arrays are flattened!
+
+ >>> a = np.array([[1, 4], [5, 6]])
+ >>> b = np.array([[4, 1], [2, 2]])
+ >>> np.vecdot(a, b)
+ array(30.)
+ >>> np.vecdot(b, a)
+ array(30.)
+ >>> 1*4 + 4*1 + 5*2 + 6*2
+ 30
+ """
Review comment:
Indent using 4 spaces.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -2016,13 +2040,13 @@ def mean(self, axis=None, dtype=None, out=None, keepdims=False): # pylint: disa
return mean(self, axis=axis, dtype=dtype, out=out, keepdims=keepdims)
# pylint: disable=too-many-arguments, arguments-differ
- def std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
+ def std(self, axis=None, dtype=None, out=None, correction=0, keepdims=False):
"""Returns the standard deviation of the array elements along given axis."""
- return std(self, axis=axis, dtype=dtype, ddof=ddof, keepdims=keepdims, out=out)
+ return std(self, axis=axis, dtype=dtype, correction=correction, keepdims=keepdims, out=out)
- def var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
+ def var(self, axis=None, dtype=None, out=None, correction=0, keepdims=False):
Review comment:
Add decorator @wrap_data_api_statical_func here.
##########
File path: python/mxnet/numpy/multiarray.py
##########
@@ -2016,13 +2040,13 @@ def mean(self, axis=None, dtype=None, out=None, keepdims=False): # pylint: disa
return mean(self, axis=axis, dtype=dtype, out=out, keepdims=keepdims)
# pylint: disable=too-many-arguments, arguments-differ
- def std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
+ def std(self, axis=None, dtype=None, out=None, correction=0, keepdims=False):
Review comment:
Add decorator @wrap_data_api_statical_func here.
##########
File path: python/mxnet/util.py
##########
@@ -645,6 +645,52 @@ def _wrap_np_binary_func(x1, x2, out=None, **kwargs):
return func(x1, x2, out=out)
return _wrap_np_binary_func
+def wrap_data_api_statical_func(func):
+ """A convenience decorator for wrapping data apis standardized statical functions to provide
+ context keyward backward compatibility
+ Parameters
+ ----------
+ func : a numpy-compatible array statical function to be wrapped for context keyward change.
+ Returns
+ -------
+ Function
+ A function wrapped with context keyward changes.
+ """
Review comment:
Indent using 4 spaces.
##########
File path: python/mxnet/util.py
##########
@@ -645,6 +645,52 @@ def _wrap_np_binary_func(x1, x2, out=None, **kwargs):
return func(x1, x2, out=out)
return _wrap_np_binary_func
+def wrap_data_api_statical_func(func):
+ """A convenience decorator for wrapping data apis standardized statical functions to provide
+ context keyward backward compatibility
+ Parameters
+ ----------
+ func : a numpy-compatible array statical function to be wrapped for context keyward change.
+ Returns
+ -------
+ Function
+ A function wrapped with context keyward changes.
+ """
+
+ @functools.wraps(func)
+ def _wrap_api_creation_func(*args, **kwargs):
+ if len(kwargs) != 0:
+ correction = kwargs.pop('ddof', None)
+ if correction is not None:
+ kwargs['correction'] = correction
+ return func(*args, **kwargs)
+
+ return _wrap_api_creation_func
+
+def wrap_data_api_linalg_func(func):
+ """A convenience decorator for wrapping data apis standardized linalg functions to provide
+ context keyward backward compatibility
+ Parameters
Review comment:
Indent using 4 spaces.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@mxnet.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org