DOC: Final doc changes for release 1.19

.travis.yml

@@ -51,6 +51,9 @@ matrix:
     - os: linux
       python: 3.6
       env: [PYPI=true, COVERAGE=false, NUMPY=1.17.5]
+    - os: linux
+      python: 3.8
+      env: [PYPI=true, COVERAGE=false, RANDOMGEN_CYTHON_COVERAGE=false, RANDOMGEN_DEBUG=false, Cython=3.0a5]
   allow_failures:
     - os: linux
       arch: ppc64le
@@ -60,6 +63,9 @@ matrix:
       arch: s390x
       python: 3.6
       env: [PYPI=true, S390X=1, COVERAGE=true]
+    - os: linux
+      python: 3.8
+      env: [PYPI=true, COVERAGE=false, RANDOMGEN_CYTHON_COVERAGE=false, RANDOMGEN_DEBUG=false, Cython=3.0a5]
 
 before_install:
   - git fetch --tags

README.md

@@ -1,7 +1,8 @@
 # RandomGen
 
-A general purpose Random Number Generator with settable PRNG interface, and a large
-collection of Pseudo-Random Number Generators (PRNGs).
+This package contains additional bit generators for NumPy's
+`Generator` and an `ExtendedGenerator` exposing methods not in `Generator`.
+
 
 **Continuous Integration**
 
@@ -79,65 +80,6 @@ While I have no immediate plans to remove anything, after a 1.19 release I will:
 * Add some distributions that are not supported in NumPy. _Ongoing_
 * Add any interesting bit generators I come across. _Recent additions include the DXSM and CM-DXSM variants of PCG64 and the LXM generator._
 
-
-## Python 2.7 Support
-
-v1.16 is the final major version that supports Python 2.7. Any bugs
-in v1.16 will be patched until the end of 2019. All future releases
-are Python 3, with an initial minimum version of 3.5.
-
-# Features
-
-* Designed as a replacement for NumPy's 1.16's RandomState
-
-  ```python
-  from randomgen import Generator, MT19937
-  rnd = Generator(MT19937())
-  x = rnd.standard_normal(100)
-  y = rnd.random(100)
-  z = rnd.randn(10,10)
-  ```
-
-* Default random generator is a fast generator called Xoroshiro128plus
-* Support for random number generators that support independent streams
-  and jumping ahead so that sub-streams can be generated
-* Faster random number generation, especially for normal, standard
-  exponential and standard gamma using the Ziggurat method
-
-  ```python
-  from randomgen import Generator
-  # Default bit generator is Xoroshiro128
-  rnd = Generator()
-  w = rnd.standard_normal(10000)
-  x = rnd.standard_exponential(10000)
-  y = rnd.standard_gamma(5.5, 10000)
-  ```
-
-* Support for 32-bit floating randoms for core generators.
-  Currently supported:
-
-  * Uniforms (`random`)
-  * Exponentials (`standard_exponential`, both Inverse CDF and Ziggurat)
-  * Normals (`standard_normal`)
-  * Standard Gammas (via `standard_gamma`)
-
-  **WARNING**: The 32-bit generators are **experimental** and subject
-  to change.
-
-  **Note**: There are _no_ plans to extend the alternative precision
-  generation to all distributions.
-
-* Support for filling existing arrays using `out` keyword argument. Currently
-  supported in (both 32- and 64-bit outputs)
-
-  * Uniforms (`random`)
-  * Exponentials (`standard_exponential`)
-  * Normals (`standard_normal`)
-  * Standard Gammas (via `standard_gamma`)
-
-* Support for Lemire's method of generating uniform integers on an
-  arbitrary interval by setting `use_masked=True`.
-
 ## Included Pseudo Random Number Generators
 
 This module includes a number of alternative random
@@ -156,47 +98,11 @@ The RNGs include:
   and [xoshiro512**](http://xorshift.di.unimi.it/)
 * [PCG64](http://www.pcg-random.org/)
 * ThreeFry and Philox from [Random123](https://www.deshawresearch.com/resources_random123.html)
+* Other cryptographic-based generators: `AESCounter`, `SPECK128`, `ChaCha`, and `HC128`.
+* Hardware (non-reproducible) random number generator on AMD64 using `RDRAND`.
+* Chaotic PRNGS: Small-Fast Chaotic (`SFC64`) and Jenkin's Small-Fast (`JSF`).
 
-## Differences from `numpy.random.RandomState`
-
-### Note
-These comparisons are relative to NumPy 1.16. The project has been
-substantially merged into NumPy 1.17+.
-
-### New Features relative to NumPy 1.16
-
-* `standard_normal`, `normal`, `randn` and `multivariate_normal` all
-  use the much faster (100%+) Ziggurat method.
-* `standard_gamma` and `gamma` both use the much faster Ziggurat method.
-* `standard_exponential` `exponential` both support an additional
-  `method` keyword argument which can be `inv` or
-  `zig` where `inv` corresponds to the current method using the inverse
-  CDF and `zig` uses the much faster (100%+) Ziggurat method.
-* Core random number generators can produce either single precision
-  (`np.float32`) or double precision (`np.float64`, the default) using
-  the optional keyword argument `dtype`
-* Core random number generators can fill existing arrays using the
-  `out` keyword argument
-* Standardizes integer-values random values as int64 for all platforms.
-* `randint` supports generating using rejection sampling on masked
-  values (the default) or Lemire's method.  Lemire's method can be much
-  faster when the required interval length is much smaller than the
-  closes power of 2.
-
-### New Functions
-
-* `random_entropy` - Read from the system entropy provider, which is
-  commonly used in cryptographic applications
-* `random_raw` - Direct access to the values produced by the underlying
-  PRNG. The range of the values returned depends on the specifics of the
-  PRNG implementation.
-* `random_uintegers` - unsigned integers, either 32- (`[0, 2**32-1]`)
-  or 64-bit (`[0, 2**64-1]`)
-* `jump` - Jumps RNGs that support it.  `jump` moves the state a great
-  distance. _Only available if supported by the RNG._
-* `advance` - Advanced the RNG 'as-if' a number of draws were made,
-  without actually drawing the numbers. _Only available if supported by
-  the RNG._
+
 
 ## Status
 
@@ -210,7 +116,7 @@ substantially merged into NumPy 1.17+.
 ## Version
 
 The package version matches the latest version of NumPy where
-`RandomState(MT19937())` passes all NumPy test.
+`Generator(MT19937())` passes all NumPy test.
 
 ## Documentation
 
@@ -223,9 +129,9 @@ the latest commit (unreleased) is available under
 ## Requirements
 Building requires:
 
-* Python (3.5, 3.6, 3.7, 3.8)
+* Python (3.6, 3.7, 3.8)
 * NumPy (1.14, 1.15, 1.16, 1.17, 1.18, 1.19)
-* Cython (0.27+)
+* Cython (0.29+)
 * tempita (0.5+), if not provided by Cython
 
 Testing requires pytest (4.0+).
@@ -236,8 +142,8 @@ versions.
 ## Development and Testing
 
 All development has been on 64-bit Linux, and it is regularly tested on
-Travis-CI (Linux/OSX), Appveyor (Windows), Cirrus (FreeBSD) and Drone.io
-(ARM/ARM64 Linux).
+Travis-CI (Linux-AMD64, Linux-PPC-LE, Linus-S390X, and OSX), Appveyor (Windows 32/64),
+Cirrus (FreeBSD) and Drone.io (ARM/ARM64 Linux).
 
 Tests are in place for all RNGs. The MT19937 is tested against
 NumPy's implementation for identical results. It also passes NumPy's
@@ -275,26 +181,7 @@ python setup.py install --no-sse2
 ### Windows
 
 Either use a binary installer, or if building from scratch, use
-Python 3.6/3.7 with Visual Studio 2015/2017 Community Edition. It can also
-be build using Microsoft Visual C++ Compiler for Python 2.7 and
-Python 2.7.
-
-## Using
-
-The separate generators are importable from `randomgen`
-
-```python
-from randomgen import Generator, ThreeFry, PCG64, MT19937
-rg = Generator(ThreeFry())
-rg.random(100)
-
-rg = Generator(PCG64())
-rg.random(100)
-
-# Identical to NumPy
-rg = Generator(MT19937())
-rg.random(100)
-```
+Python 3.6/3.7 with Visual Studio 2015 Build Toolx.
 
 ## License
 

ci/pypi-install.sh

@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
 
 pip install --upgrade pip
-pip install cython pytest setuptools --upgrade
-if [[ -z ${NUMPY} ]]; then
-  pip install numpy --upgrade
-else
+pip install numpy cython pytest setuptools --upgrade
+if [[ -n ${NUMPY} ]]; then
   pip install numpy=="${NUMPY}" --upgrade --pre -v
 fi
+if [[ -n ${CYTHON} ]]; then
+  pip install cython=="${CYTHON}" --upgrade --pre -v
+fi
 
 if [[ -z ${PPC64_LE} && -z ${S390X} ]]; then
     pip install pandas --upgrade

doc/source/change-log.rst

@@ -18,15 +18,21 @@ Change Log
 v1.19.0
 =======
 
+- Added a :class:`randomgen.sfc.SFC64` which supports generating streams using distinct
+  Weyl constants.
+- Added a :class:`randomgen.pcg64.CustomPCG64` which supports setting the LCG multiplier,
+  changing the output function (including support for user-defined output functions) and
+  pre- or post-state update generation.
+- Added a :class:`randomgen.lxm.LXM` which generates variates using a mix of two simple,
+  but flawed generators: an Xorshift and a 64-bit LCG. This has been
+  proposed for including in `in Java`_.
 - Added a :class:`randomgen.wrapper.UserBitGenerator` which allows bit generators to be written
   in Python or numba.
 - Added :class:`randomgen.generator.ExtendedGenerator` which contains features not in :class:`numpy.random.Generator`.
 - Added  support for the ``DXSM`` and ``CM-DXSM`` variants of :class:`randomgen.pcg64.PCG64`. The
   ``CM-DXSM`` variant is the official PCG 2.0 generator.
 - Added support for broadcasting inputs in :class:`randomgen.generator.ExtendedGenerator.multivariate_normal`.
 - Added support for the `++` variant of :class:`randomgen.xoroshiro128.Xoroshiro128`.
-- Added :class:`randomgen.lxm.LXM` which mixes a LCG and an Xorshift PRNGs. This has been
-  proposed for including in `in Java`_.
 - Fixed a bug the produced incorrect results in :func:`~randomgen.mt19937.MT19937.jumped`.
 - Fixed multiple bugs in :class:`~randomgen.generator.Generator` that were fixed in :class:`numpy.random.Generator`.
 

doc/source/conf.py

@@ -127,8 +127,8 @@
     "globaltoc_collapse": True,
     "globaltoc_includehidden": True,
     "theme_color": "#2196f3",
-    "color_primary": "red",
-    "color_accent": "amber",
+    "color_primary": "deep-purple",
+    "color_accent": "purple",
     "html_minify": True,
     "css_minify": True,
     "master_doc": False,
@@ -137,6 +137,11 @@
         "1.17's Generator"
     },
     "logo_icon": "casino",
+    "version_dropdown": True,
+    "version_info": {
+        "Release": "https://bashtage.github.io/randomgen/",
+        "Development": "https://bashtage.github.io/randomgen/devel/",
+    },
 }
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

doc/source/evolution.rst

@@ -0,0 +1,48 @@
+.. _evolution:
+
+Evolution of randomgen
+======================
+
+Changes in 1.19
+---------------
+
+:class:`~randomgen.generator.Generator` and :class:`~randomgen.mtrand.RandomState` have been
+officially deprecated, and will warn with a ``FutureWarning`` about their removal. They will
+also receive virtually no maintenance. It is now time to move to NumPy's :class:`numpy.random.Generator`
+which has features not in :class:`~randomgen.generator.Generator` and is maintained more actively.
+
+A few distributions that are not present in :class:`~randomgen.generator.Generator` have been moved
+to :class:`~randomgen.generator.ExtendedGenerator`:
+
+* :func:`~randomgen.generator.ExtendedGenerator.multivariate_normal`: which supports broadcasting
+* :func:`~randomgen.generator.ExtendedGenerator.uintegers`: fast 32 and 64-bit uniform integers
+* :func:`~randomgen.generator.ExtendedGenerator.complex_normal`: scalar complex normals
+
+There are no plans to remove any of the bit generators, e.g., :class:`~randomgen.aes.AESCounter`,
+:class:`~randomgen.threefry.ThreeFry`, or :class:`~randomgen.pcg64.PCG64`.
+
+Changes between 1.16 and 1.18
+-----------------------------
+
+There are many changes between v1.16.x and v1.18.x. These reflect API
+decision taken in conjunction with NumPy in preparation of the core
+of ``randomgen`` being used as the preferred random number generator in
+NumPy. These all issue ``DeprecationWarning`` except for ``BitGenerator.generator``
+which raises ``NotImplementedError``. The C-API has also changed to reflect
+the preferred naming the underlying Pseudo-RNGs, which are now known as
+bit generators (or ``BitGenerator``).
+
+The main changes are
+
+* Rename ``RandomGenerator`` to :class:`~randomgen.generator.Generator`.
+* Rename :meth:`~randomgen.generator.Generator.randint` to
+  :meth:`~randomgen.generator.Generator.integers`.
+* Rename :meth:`~randomgen.generator.Generator.random_integers` to
+  :meth:`~randomgen.generator.Generator.integers`.
+* Rename :meth:`~randomgen.generator.Generator.random_sample` to
+  :meth:`~randomgen.generator.Generator.random`.
+* Change ``jump`` which operated in-place to ``jumped`` which returns a new ``BitGenerator``.
+* Rename Basic RNG to bit generator, which impacts the API in multiple places where names
+  like ``brng`` and ``basic_rng`` have been replaced by ``bitgen`` or ``bit_generator``.
+* Support for :class:`~randomgen.seed_sequence.SeedSequences` (also support NumPy ``SeedSequence`` instances)
+* Removed support for Python 2.7

doc/source/extending.rst

@@ -17,11 +17,11 @@ provided by ``ctypes.next_double``.
 
 .. code-block:: python
 
-    from randomgen import Xoroshiro128
+    from randomgen import ChaCha
     import numpy as np
     import numba as nb
 
-    x = Xoroshiro128()
+    x = ChaCha()
     f = x.ctypes.next_double
     s = x.ctypes.state
     state_addr = x.ctypes.state_address
@@ -49,7 +49,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/Xoroshiro128) randoms')
+    print('1,000,000 Box-Muller (numba/ChaCha) randoms')
     %timeit np.random.standard_normal(1000000)
     print('1,000,000 Box-Muller (NumPy) randoms')
 

doc/source/future.rst

@@ -6,12 +6,16 @@ number generation was always the goal of this project (and its predecessor
 `NextGen NumPy RandomState <https://github.com/bashtage/ng-numpy-randomstate>`_),
 and so it has succeeded.
 
-While I have no immediate plans to remove anything, after a 1.19 release I will:
+The future plans for randomgen are:
 
 * Remove :class:`~randomgen.generator.Generator` and :class:`~randomgen.mtrand.RandomState`. These
-  duplicate NumPy and will diverge over time.  The versions in NumPy are authoritative.
-* Preserve novel methods of :class:`~randomgen.generator.Generator` in a
-  :class:`~randomgen.generator.ExtendedGenerator`.
-* Add some distributions that are not supported in NumPy.
-* Add any interesting bit generators I come across.
+  duplicate NumPy and will diverge over time.  The versions in NumPy are authoritative. These
+  have been deprecated as of version 1.19 and will be removed in 1.21.
+* The novel methods of :class:`~randomgen.generator.Generator` in a
+  :class:`~randomgen.generator.ExtendedGenerator`. :class:`~randomgen.generator.ExtendedGenerator`
+  will be maintained, although it is possible that some of the methods may
+  migrate to NumPy.
+* Add useful distributions that are not supported in NumPy. Pull requests adding useful
+  generators are welcome.
+* Add any novel and interesting bit generators, and extend that capabilities of existing ones.