[Numpy ]Modify np.random.shuffle to enable inplace by default (#17133)

* shuffle done

* fix dodstring

python/mxnet/ndarray/numpy/random.py

@@ -23,7 +23,7 @@
 from ..ndarray import NDArray
 
 
-__all__ = ['randint', 'uniform', 'normal', "choice", "rand", "multinomial"]
+__all__ = ['randint', 'uniform', 'normal', "choice", "rand", "multinomial", "shuffle"]
 
 
 def randint(low, high=None, size=None, dtype=None, ctx=None, out=None):
@@ -344,3 +344,39 @@ def rand(*size, **kwargs):
  for s in size:
  output_shape += (s,)
  return uniform(0, 1, size=output_shape, **kwargs)
+
+
+def shuffle(x):
+ """
+ Modify a sequence in-place by shuffling its contents.
+
+ This function only shuffles the array along the first axis of a
+ multi-dimensional array. The order of sub-arrays is changed but
+ their contents remain the same.
+
+ Parameters
+ ----------
+ x: ndarray
+ The array or list to be shuffled.
+
+ Returns
+ -------
+ None
+
+ Examples
+ --------
+ >>> arr = np.arange(10)
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([5., 1., 0., 6., 7., 3., 9., 8., 4., 2.]) # random
+
+ Multi-dimensional arrays are only shuffled along the first axis:
+
+ >>> arr = np.arange(9).reshape((3, 3))
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([[6., 7., 8.], # random
+ [3., 4., 5.],
+ [0., 1., 2.]])
+ """
+ _npi.shuffle(x, out=x)

python/mxnet/numpy/random.py

@@ -20,7 +20,7 @@
 from __future__ import absolute_import
 from ..ndarray import numpy as _mx_nd_np
 
-__all__ = ["randint", "uniform", "normal", "choice", "rand", "multinomial"]
+__all__ = ["randint", "uniform", "normal", "choice", "rand", "multinomial", "shuffle"]
 
 
 def randint(low, high=None, size=None, dtype=None, ctx=None, out=None):
@@ -321,3 +321,39 @@ def rand(*size, **kwargs):
  for s in size:
  output_shape += (s,)
  return _mx_nd_np.random.uniform(0, 1, size=output_shape, **kwargs)
+
+
+def shuffle(x):
+ """
+ Modify a sequence in-place by shuffling its contents.
+
+ This function only shuffles the array along the first axis of a
+ multi-dimensional array. The order of sub-arrays is changed but
+ their contents remain the same.
+
+ Parameters
+ ----------
+ x: ndarray
+ The array or list to be shuffled.
+
+ Returns
+ -------
+ None
+
+ Examples
+ --------
+ >>> arr = np.arange(10)
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([5., 1., 0., 6., 7., 3., 9., 8., 4., 2.]) # random
+
+ Multi-dimensional arrays are only shuffled along the first axis:
+
+ >>> arr = np.arange(9).reshape((3, 3))
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([[6., 7., 8.], # random
+ [3., 4., 5.],
+ [0., 1., 2.]])
+ """
+ _mx_nd_np.random.shuffle(x)

python/mxnet/symbol/numpy/random.py

@@ -21,7 +21,7 @@
 from ...context import current_context
 from . import _internal as _npi
 
-__all__ = ['randint', 'uniform', 'normal', 'rand']
+__all__ = ['randint', 'uniform', 'normal', 'rand', 'shuffle']
 
 
 def randint(low, high=None, size=None, dtype=None, ctx=None, out=None):
@@ -288,3 +288,39 @@ def choice(a, size=None, replace=True, p=None, ctx=None, out=None):
  return _npi.choice(a=a, size=size, replace=replace, ctx=ctx, weighted=False, out=out)
  else:
  return _npi.choice(p, a=a, size=size, replace=replace, ctx=ctx, weighted=True, out=out)
+
+
+def shuffle(x):
+ """
+ Modify a sequence in-place by shuffling its contents.
+
+ This function only shuffles the array along the first axis of a
+ multi-dimensional array. The order of sub-arrays is changed but
+ their contents remain the same.
+
+ Parameters
+ ----------
+ x: _Symbol
+ The array or list to be shuffled.
+
+ Returns
+ -------
+ None
+
+ Examples
+ --------
+ >>> arr = np.arange(10)
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([5., 1., 0., 6., 7., 3., 9., 8., 4., 2.]) # random
+
+ Multi-dimensional arrays are only shuffled along the first axis:
+
+ >>> arr = np.arange(9).reshape((3, 3))
+ >>> np.random.shuffle(arr)
+ >>> arr
+ array([[6., 7., 8.], # random
+ [3., 4., 5.],
+ [0., 1., 2.]])
+ """
+ _npi.shuffle(x, out=x)

src/operator/random/shuffle_op.cc

@@ -122,7 +122,7 @@ void ShuffleForwardCPU(const nnvm::NodeAttrs& attrs,
 
 NNVM_REGISTER_OP(_shuffle)
 .add_alias("shuffle")
-.add_alias("_np__random_shuffle")
+.add_alias("_npi_shuffle")
 .describe(R"code(Randomly shuffle the elements.
 
 This shuffles the array along the first axis.