ENH: random: Add the method `permuted` to Generator. (#15121)

* ENH: random: Make _shuffle_raw and _shuffle_int standalone functions.

* ENH: random: Add the method `permuted` to Generator.

The method permuted(x, axis=None, out=None) shuffles an array.
Unlike the existing shuffle method, it shuffles the slices along
the given axis independently.

Closes gh-5173.

1 files changed, 94 insertions, 0 deletions

diff --git a/doc/source/reference/random/generator.rst b/doc/source/reference/random/generator.rst
index a2cbb493a..8706e1de2 100644
--- a/doc/source/reference/random/generator.rst
+++ b/doc/source/reference/random/generator.rst
@@ -36,11 +36,105 @@ Simple random data
 
 Permutations
 ============
+The methods for randomly permuting a sequence are
+
 .. autosummary::
    :toctree: generated/
 
    ~numpy.random.Generator.shuffle
    ~numpy.random.Generator.permutation
+   ~numpy.random.Generator.permuted
+
+The following table summarizes the behaviors of the methods.
+
++--------------+-------------------+------------------+
+| method       | copy/in-place     | axis handling    |
++==============+===================+==================+
+| shuffle      | in-place          | as if 1d         |
++--------------+-------------------+------------------+
+| permutation  | copy              | as if 1d         |
++--------------+-------------------+------------------+
+| permuted     | either (use 'out' | axis independent |
+|              | for in-place)     |                  |
++--------------+-------------------+------------------+
+
+The following subsections provide more details about the differences.
+
+In-place vs. copy
+~~~~~~~~~~~~~~~~~
+The main difference between `Generator.shuffle` and `Generator.permutation`
+is that `Generator.shuffle` operates in-place, while `Generator.permutation`
+returns a copy.
+
+By default, `Generator.permuted` returns a copy.  To operate in-place with
+`Generator.permuted`, pass the same array as the first argument *and* as
+the value of the ``out`` parameter.  For example,
+
+    >>> rg = np.random.default_rng()
+    >>> x = np.arange(0, 15).reshape(3, 5)
+    >>> x
+    array([[ 0,  1,  2,  3,  4],
+           [ 5,  6,  7,  8,  9],
+           [10, 11, 12, 13, 14]])
+    >>> y = rg.permuted(x, axis=1, out=x)
+    >>> x
+    array([[ 1,  0,  2,  4,  3],  # random
+           [ 6,  7,  8,  9,  5],
+           [10, 14, 11, 13, 12]])
+
+Note that when ``out`` is given, the return value is ``out``:
+
+    >>> y is x
+    True
+
+Handling the ``axis`` parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An important distinction for these methods is how they handle the ``axis``
+parameter.  Both `Generator.shuffle` and `Generator.permutation` treat the
+input as a one-dimensional sequence, and the ``axis`` parameter determines
+which dimension of the input array to use as the sequence. In the case of a
+two-dimensional array, ``axis=0`` will, in effect, rearrange the rows of the
+array, and  ``axis=1`` will rearrange the columns.  For example
+
+    >>> rg = np.random.default_rng()
+    >>> x = np.arange(0, 15).reshape(3, 5)
+    >>> x
+    array([[ 0,  1,  2,  3,  4],
+           [ 5,  6,  7,  8,  9],
+           [10, 11, 12, 13, 14]])
+    >>> rg.permutation(x, axis=1)
+    array([[ 1,  3,  2,  0,  4],  # random
+           [ 6,  8,  7,  5,  9],
+           [11, 13, 12, 10, 14]])
+
+Note that the columns have been rearranged "in bulk": the values within
+each column have not changed.
+
+The method `Generator.permuted` treats the ``axis`` parameter similar to
+how `numpy.sort` treats it.  Each slice along the given axis is shuffled
+independently of the others.  Compare the following example of the use of
+`Generator.permuted` to the above example of `Generator.permutation`:
+
+    >>> rg.permuted(x, axis=1)
+    array([[ 1,  0,  2,  4,  3],  # random
+           [ 5,  7,  6,  9,  8],
+           [10, 14, 12, 13, 11]])
+
+In this example, the values within each row (i.e. the values along
+``axis=1``) have been shuffled independently.  This is not a "bulk"
+shuffle of the columns.
+
+Shuffling non-NumPy sequences
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`Generator.shuffle` works on non-NumPy sequences.  That is, if it is given
+a sequence that is not a NumPy array, it shuffles that sequence in-place.
+For example,
+
+    >>> rg = np.random.default_rng()
+    >>> a = ['A', 'B', 'C', 'D', 'E']
+    >>> rg.shuffle(a)  # shuffle the list in-place
+    >>> a
+    ['B', 'D', 'A', 'E', 'C']  # random
 
 Distributions
 =============