ENH: np.random.default_gen() (#13840)

* ENH: Rename seed_seq argument to seed and replace Generator() with default_gen()

3 files changed, 14 insertions, 11 deletions

diff --git a/doc/source/reference/random/generator.rst b/doc/source/reference/random/generator.rst
index 22bce2e6c..c284b245c 100644
--- a/doc/source/reference/random/generator.rst
+++ b/doc/source/reference/random/generator.rst
@@ -12,6 +12,8 @@ random values from useful distributions. The default BitGenerator used by
 can be changed by passing an instantized BitGenerator to ``Generator``.
 
 
+.. autofunction:: default_gen
+
 .. autoclass:: Generator
 	:exclude-members:
 
diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index b862788ea..7a171aa73 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -48,9 +48,10 @@ the random values are generated by `~.PCG64`. The
 
 .. code-block:: python
 
-  # As replacement for RandomState()
-  from numpy.random import Generator
-  rg = Generator()
+  # As replacement for RandomState(); default_gen() instantiates Generator with
+  # the default PCG64 BitGenerator.
+  from numpy.random import default_gen
+  rg = default_gen()
   rg.standard_normal()
   rg.bit_generator
 
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index 11638824a..4eb175d57 100644
--- a/doc/source/reference/random/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -19,15 +19,15 @@ Quick comparison of legacy `mtrand <legacy>`_ to the new `Generator`
 ================== ==================== =============
 Feature            Older Equivalent     Notes
 ------------------ -------------------- -------------
-`Generator`        `RandomState`        ``Generator`` requires a stream
+`~.Generator`      `~.RandomState`      ``Generator`` requires a stream
                                         source, called a `BitGenerator
                                         <bit_generators>` A number of these
                                         are provided.  ``RandomState`` uses
-                                        only the Box- Muller method.
+                                        only the Mersenne Twister.
 ------------------ -------------------- -------------
-``np.random.``     ``np.random.``       Access the values in a BitGenerator,
-``Generator().``   ``random_sample()``  convert them to ``float64`` in the
-``random()``                            interval ``[0.0.,`` `` 1.0)``.
+``random``         ``random_sample``    Access the values in a BitGenerator,
+                                        convert them to ``float64`` in the
+                                        interval ``[0.0.,`` `` 1.0)``.
                                         In addition to the ``size`` kwarg, now
                                         supports ``dtype='d'`` or ``dtype='f'``,
                                         and an ``out`` kwarg to fill a user-
@@ -36,8 +36,8 @@ Feature            Older Equivalent     Notes
                                         Many other distributions are also
                                         supported.
 ------------------ -------------------- -------------
-``Generator().``   ``randint``,         Use the ``endpoint`` kwarg to adjust
-``integers()``     ``random_integers``  the inclusion or exclution of the
+``integers``       ``randint``,         Use the ``endpoint`` kwarg to adjust
+                   ``random_integers``  the inclusion or exclution of the
                                         ``high`` interval endpoint
 ================== ==================== =============
 
@@ -56,7 +56,7 @@ And in more detail:
   random numbers from a discrete uniform distribution. The ``rand`` and
   ``randn`` methods are only available through the legacy `~.RandomState`.
   This replaces both ``randint`` and the deprecated ``random_integers``.
-* The Box-Muller used to produce NumPy's normals is no longer available.
+* The Box-Muller method used to produce NumPy's normals is no longer available.
 * All bit generators can produce doubles, uint64s and
   uint32s via CTypes (`~PCG64.ctypes`) and CFFI (`~PCG64.cffi`).
   This allows these bit generators to be used in numba.