[Numpy-discussion] New random.Generator method: permuted

[Warren Weckesser]

In one of the previous weekly zoom meetings, it was suggested
to ping the mailing list about an updated PR that implements
the `permuted` method for the Generator class in numpy.random.
The relevant issue is

    https://github.com/numpy/numpy/issues/5173

and the PR is

    https://github.com/numpy/numpy/pull/15121

The new method (as it would be called from Python) is

    permuted(x, axis=None, out=None)

The CircleCI rendering of the docstring from the pull request is

    https://14745-908607-gh.circle-artifacts.com/0/doc/build/html/reference/random/generated/numpy.random.Generator.permuted.html

The new method is an alternative to the existing `shuffle` and
`permutation` methods.  It handles the `axis` parameter similar
to how the sort methods do, i.e. when `axis` is given, the slices
along the axis are shuffled independently.  This new documentation
(added as part of the pull request) explains the API of the various
related methods:

    https://14745-908607-gh.circle-artifacts.com/0/doc/build/html/reference/random/generator.html#permutations

Additional feedback on the implementation of `permuted` in the
pull request is welcome.  Further discussion of the API should
be held in the issue gh-5173 (but please familiarize yourself
with the discussion of the API in gh-5173--there has already
been quite a long discussion of several different APIs).

Thanks,

Warren