MAINT: remove xoshiro* BitGenerators

11 files changed, 27 insertions, 115 deletions

diff --git a/doc/source/reference/random/bit_generators/index.rst b/doc/source/reference/random/bit_generators/index.rst
index a030727c4..c5a2b4466 100644
--- a/doc/source/reference/random/bit_generators/index.rst
+++ b/doc/source/reference/random/bit_generators/index.rst
@@ -21,6 +21,4 @@ Stable RNGs
    MT19937 <mt19937>
    PCG64 <pcg64>
    Philox <philox>
-   Xoshiro256** <xoshiro256>
-   Xoshiro512** <xoshiro512>
 
diff --git a/doc/source/reference/random/bit_generators/xoshiro256.rst b/doc/source/reference/random/bit_generators/xoshiro256.rst
deleted file mode 100644
index fedc61b33..000000000
--- a/doc/source/reference/random/bit_generators/xoshiro256.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-Xoshiro256**
-------------
-
-.. module:: numpy.random.xoshiro256
-
-.. currentmodule:: numpy.random.xoshiro256
-
-.. autoclass:: Xoshiro256
-	:exclude-members:
-
-Seeding and State
-=================
-
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro256.seed
-   ~Xoshiro256.state
-
-Parallel generation
-===================
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro256.jumped
-
-Extending
-=========
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro256.cffi
-   ~Xoshiro256.ctypes
-
-
diff --git a/doc/source/reference/random/bit_generators/xoshiro512.rst b/doc/source/reference/random/bit_generators/xoshiro512.rst
deleted file mode 100644
index e39346cd6..000000000
--- a/doc/source/reference/random/bit_generators/xoshiro512.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-Xoshiro512**
-------------
-
-.. module:: numpy.random.xoshiro512
-
-.. currentmodule:: numpy.random.xoshiro512
-
-.. autoclass:: Xoshiro512
-	:exclude-members:
-
-Seeding and State
-=================
-
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro512.seed
-   ~Xoshiro512.state
-
-Parallel generation
-===================
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro512.jumped
-
-Extending
-=========
-.. autosummary::
-   :toctree: generated/
-
-   ~Xoshiro512.cffi
-   ~Xoshiro512.ctypes
-
-
diff --git a/doc/source/reference/random/extending.rst b/doc/source/reference/random/extending.rst
index 28db4021c..22f9cb7e4 100644
--- a/doc/source/reference/random/extending.rst
+++ b/doc/source/reference/random/extending.rst
@@ -18,11 +18,11 @@ provided by ``ctypes.next_double``.
 
 .. code-block:: python
 
-    from numpy.random import Xoshiro256
+    from numpy.random import PCG64
     import numpy as np
     import numba as nb
 
-    x = Xoshiro256()
+    x = PCG64()
     f = x.ctypes.next_double
     s = x.ctypes.state
     state_addr = x.ctypes.state_address
@@ -50,7 +50,7 @@ provided by ``ctypes.next_double``.
     # Must use state address not state with numba
     normalsj(1, state_addr)
     %timeit normalsj(1000000, state_addr)
-    print('1,000,000 Box-Muller (numba/Xoshiro256) randoms')
+    print('1,000,000 Box-Muller (numba/PCG64) randoms')
     %timeit np.random.standard_normal(1000000)
     print('1,000,000 Box-Muller (NumPy) randoms')
 
@@ -66,7 +66,7 @@ Cython
 ======
 
 Cython can be used to unpack the ``PyCapsule`` provided by a BitGenerator.
-This example uses `~xoshiro256.Xoshiro256` and
+This example uses `~pcg64.PCG64` and
 ``random_gauss_zig``, the Ziggurat-based generator for normals, to fill an
 array.  The usual caveats for writing high-performance code using Cython --
 removing bounds checks and wrap around, providing array alignment information
@@ -80,7 +80,7 @@ removing bounds checks and wrap around, providing array alignment information
     from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
     from numpy.random.common cimport *
     from numpy.random.distributions cimport random_gauss_zig
-    from numpy.random import Xoshiro256
+    from numpy.random import PCG64
 
 
     @cython.boundscheck(False)
@@ -91,7 +91,7 @@ removing bounds checks and wrap around, providing array alignment information
         cdef const char *capsule_name = "BitGenerator"
         cdef double[::1] random_values
 
-        x = Xoshiro256()
+        x = PCG64()
         capsule = x.capsule
         if not PyCapsule_IsValid(capsule, capsule_name):
             raise ValueError("Invalid pointer to anon_func_state")
@@ -117,7 +117,7 @@ RNG structure.
         cdef const char *capsule_name = "BitGenerator"
         cdef double[::1] random_values
 
-        x = Xoshiro256()
+        x = PCG64()
         capsule = x.capsule
         # Optional check that the capsule if from a BitGenerator
         if not PyCapsule_IsValid(capsule, capsule_name):
diff --git a/doc/source/reference/random/generator.rst b/doc/source/reference/random/generator.rst
index 8b086e901..22bce2e6c 100644
--- a/doc/source/reference/random/generator.rst
+++ b/doc/source/reference/random/generator.rst
@@ -8,7 +8,7 @@ a wide range of distributions, and served as a replacement for
 the two is that ``Generator`` relies on an additional BitGenerator to
 manage state and generate the random bits, which are then transformed into
 random values from useful distributions. The default BitGenerator used by
-``Generator`` is :class:`~xoshiro256.Xoshiro256`.  The BitGenerator
+``Generator`` is `~PCG64`.  The BitGenerator
 can be changed by passing an instantized BitGenerator to ``Generator``.
 
 
diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index 42956590a..a35ba4aaf 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -30,8 +30,8 @@ instance's methods are imported into the numpy.random namespace, see
 Quick Start
 -----------
 
-By default, `Generator` uses normals provided by `xoshiro256.Xoshiro256`
-which will be faster than the legacy methods in `RandomState`
+By default, `Generator` uses normals provided by `PCG64` which will be
+statistically more reliable than the legacy methods in `RandomState`
 
 .. code-block:: python
 
@@ -40,7 +40,7 @@ which will be faster than the legacy methods in `RandomState`
   random.standard_normal()
 
 `Generator` can be used as a direct replacement for `~RandomState`, although
-the random values are generated by `~xoshiro256.Xoshiro256`. The
+the random values are generated by `~PCG64`. The
 `Generator` holds an instance of a BitGenerator. It is accessible as
 ``gen.bit_generator``.
 
@@ -120,8 +120,8 @@ What's New or Different
   source of randomness that is used in cryptographic applications (e.g.,
   ``/dev/urandom`` on Unix).
 * All BitGenerators can produce doubles, uint64s and uint32s via CTypes
-  (`~xoshiro256.Xoshiro256.ctypes`) and CFFI
-  (:meth:`~xoshiro256.Xoshiro256.cffi`). This allows the bit generators to
+  (`~PCG64.ctypes`) and CFFI
+  (:meth:`~PCG64.cffi`). This allows the bit generators to
   be used in numba.
 * The bit generators can be used in downstream projects via
   :ref:`Cython <randomgen_cython>`.
@@ -156,15 +156,11 @@ The included BitGenerators are:
 * Xorshiro256** and Xorshiro512** - The most recently introduced XOR,
   shift, and rotate generator. Supports ``jumped`` and so can be used in
   parallel applications. See the documentation for
-  `~xoshiro256.Xoshirt256.jumped` for details. More information about these bit
-  generators is available at the `xorshift, xoroshiro and xoshiro authors'
-  page`_.
 * ThreeFry and Philox - counter-based generators capable of being advanced an
   arbitrary number of steps or generating independent streams. See the
   `Random123`_ page for more details about this class of bit generators.
 
 .. _`PCG author's page`: http://www.pcg-random.org/
-.. _`xorshift, xoroshiro and xoshiro authors' page`:  http://xoroshiro.di.unimi.it/
 .. _`Random123`: https://www.deshawresearch.com/resources_random123.html
 
 Generator
diff --git a/doc/source/reference/random/multithreading.rst b/doc/source/reference/random/multithreading.rst
index 7ce90af99..849d64d4e 100644
--- a/doc/source/reference/random/multithreading.rst
+++ b/doc/source/reference/random/multithreading.rst
@@ -10,21 +10,21 @@ these requirements.
 This example makes use of Python 3 :mod:`concurrent.futures` to fill an array
 using multiple threads.  Threads are long-lived so that repeated calls do not
 require any additional overheads from thread creation. The underlying
-BitGenerator is `Xoshiro256` which is fast, has a long period and supports
-using `Xoshiro256.jumped` to return a new generator while advancing the
+BitGenerator is `PCG64` which is fast, has a long period and supports
+using `PCG64.jumped` to return a new generator while advancing the
 state. The random numbers generated are reproducible in the sense that the same
 seed will produce the same outputs.
 
 .. code-block:: ipython
 
-    from numpy.random import Generator, Xoshiro256
+    from numpy.random import Generator, PCG64
     import multiprocessing
     import concurrent.futures
     import numpy as np
 
     class MultithreadedRNG(object):
         def __init__(self, n, seed=None, threads=None):
-            rg = Xoshiro256(seed)
+            rg = PCG64(seed)
             if threads is None:
                 threads = multiprocessing.cpu_count()
             self.threads = threads
@@ -89,7 +89,7 @@ The single threaded call directly uses the BitGenerator.
 .. code-block:: ipython
 
     In [5]: values = np.empty(10000000)
-        ...: rg = Generator(Xoshiro256())
+        ...: rg = Generator(PCG64())
         ...: %timeit rg.standard_normal(out=values)
 
     99.6 ms ± 222 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
@@ -100,7 +100,7 @@ that does not use an existing array due to array creation overhead.
 
 .. code-block:: ipython
 
-    In [6]: rg = Generator(Xoshiro256())
+    In [6]: rg = Generator(PCG64())
         ...: %timeit rg.standard_normal(10000000)
 
     125 ms ± 309 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index a6de9c8dc..b5bb18533 100644
--- a/doc/source/reference/random/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -58,8 +58,7 @@ And in more detail:
   This replaces both ``randint`` and the deprecated ``random_integers``.
 * The Box-Muller used to produce NumPy's normals is no longer available.
 * All bit generators can produce doubles, uint64s and
-  uint32s via CTypes (`~.xoshiro256.Xoshiro256.
-  ctypes`) and CFFI (`~.xoshiro256.Xoshiro256.cffi`).
+  uint32s via CTypes (`~PCG64.ctypes`) and CFFI (`~PCG64.cffi`).
   This allows these bit generators to be used in numba.
 * The bit generators can be used in downstream projects via
   Cython.
@@ -67,9 +66,9 @@ And in more detail:
 
 .. ipython:: python
 
-  from  numpy.random import Generator, Xoshiro256
+  from  numpy.random import Generator, PCG64
   import numpy.random
-  rg = Generator(Xoshiro256())
+  rg = Generator(PCG64())
   %timeit rg.standard_normal(100000)
   %timeit numpy.random.standard_normal(100000)
 
diff --git a/doc/source/reference/random/parallel.rst b/doc/source/reference/random/parallel.rst
index 6c495cc29..36e173ef2 100644
--- a/doc/source/reference/random/parallel.rst
+++ b/doc/source/reference/random/parallel.rst
@@ -72,10 +72,6 @@ are listed below.
 +-----------------+-------------------------+-------------------------+-------------------------+
 | ThreeFry        | :math:`2^{256}`         | :math:`2^{128}`         | 64                      |
 +-----------------+-------------------------+-------------------------+-------------------------+
-| Xoshiro256**    | :math:`2^{256}`         | :math:`2^{128}`         | 64                      |
-+-----------------+-------------------------+-------------------------+-------------------------+
-| Xoshiro512**    | :math:`2^{512}`         | :math:`2^{256}`         | 64                      |
-+-----------------+-------------------------+-------------------------+-------------------------+
 
 ``jumped`` can be used to produce long blocks which should be long enough to not
 overlap.
@@ -83,13 +79,13 @@ overlap.
 .. code-block:: python
 
   from numpy.random.entropy import random_entropy
-  from numpy.random import Xoshiro256
+  from numpy.random import PCG64
 
   entropy = random_entropy(2).astype(np.uint64)
   # 64-bit number as a seed
   seed = entropy[0] * 2**32 + entropy[1]
   blocked_rng = []
-  rng = Xoshiro256(seed)
+  rng = PCG64(seed)
   for i in range(10):
       blocked_rng.append(rng.jumped(i))
 
diff --git a/doc/source/reference/random/performance.py b/doc/source/reference/random/performance.py
index f1dc50c9d..aeb82e086 100644
--- a/doc/source/reference/random/performance.py
+++ b/doc/source/reference/random/performance.py
@@ -4,10 +4,9 @@ from timeit import repeat
 import pandas as pd
 
 import numpy as np
-from numpy.random import MT19937, ThreeFry, PCG64, Philox, \
-    Xoshiro256, Xoshiro512
+from numpy.random import MT19937, ThreeFry, PCG64, Philox
 
-PRNGS = [MT19937, PCG64, Philox, ThreeFry, Xoshiro256, Xoshiro512]
+PRNGS = [MT19937, PCG64, Philox, ThreeFry]
 
 funcs = OrderedDict()
 integers = 'integers(0, 2**{bits},size=1000000, dtype="uint{bits}")'
diff --git a/doc/source/reference/random/performance.rst b/doc/source/reference/random/performance.rst
index 014db19a3..c1b501f8f 100644
--- a/doc/source/reference/random/performance.rst
+++ b/doc/source/reference/random/performance.rst
@@ -7,13 +7,7 @@ Performance
 
 Recommendation
 **************
-The recommended generator for single use is :class:`~.xoshiro256.Xoshiro256`.
-The recommended generator for use in large-scale parallel applications is
-:class:`~.xoshiro512.Xoshiro512` where the `jumped` method is used to advance
-the state. For very large scale applications -- requiring 1,000+ independent
-streams -- is the best choice. For very large scale applications -- requiring
-1,000+ independent streams, :class:`~pcg64.PCG64` or :class:`~.philox.Philox`
-are the best choices.
+The recommended generator for single use is :class:`~PCG64`.
 
 Timings
 *******