Update documentation

Author: sethrj

doc/modules/algorithm.rst

@@ -206,12 +206,12 @@ shuffle
 -------
 
 The "shuffle" subroutine depends on the :ref:`modules_random` module so that it
-can use the supported random number generator to randomly reorder an array.
+can use the default random number generator to randomly reorder an array.
 
 Example::
 
   use flc_algorithm, only : shuffle
-  use flc_random, only : Engine
+  use flc_random, only : Engine => MersenneEngine4
   implicit none
   integer :: i
   integer, dimension(8) :: iarr = (/ ((i), i = -4, 3) /)

doc/modules/random.rst

@@ -9,53 +9,67 @@ Random
 ******
 
 The ``flc_random`` module contains advanced pseudo-random number generation
-from the `<random>`_ C++ header. Currently
-random number generation is hardwired to the ``std::mt19937_64`` 64-bit
-Mersenne Twister by Matsumoto and Nishimura.
+from the `<random>`_ C++ header.
 
 The C++11 way of generating random numbers takes some getting used to. Rather
 than having a single global function that returns a random real number in the
 range :math:`[0,1)`, C++11 has independent *engine* objects that generate
 streams of random bits. Different *distribution* objects convert those bits
 into samples of a distribution.
 
+Although C++11 defines a dizzying variety of random number engines,
+``flc_random`` wraps just two: the 32- and 64-bit `Mersenne Twister`
+algorithms. The 32-bit version (``MersenneEngine4``) is currently the only
+engine type that can be used with distributions and algorithms.
+
 Flibcpp wraps distribution objects as independent subroutines. Each subroutine
 accepts the constructor parameters of the distribution, the random engine, and
 a target Fortran array to be filled with random numbers.
 
 Generating an array with 10 normally-distributed reals with a mean of 8 and a
 standard deviation of 2 is done as such::
 
-    use flc_random, only : Engine, normal_distribution
+    use flc_random, only : Engine => MersenneEngine4, normal_distribution
     real(C_DOUBLE), dimension(20) :: arr
     type(Engine) :: rng
 
     rng = Engine()
     call normal_distribution(8.0d0, 2.0d0, rng, arr)
+    call rng%release()
 
 .. _<random> : https://en.cppreference.com/w/cpp/numeric/random
+.. _Mersenne Twister : https://en.wikipedia.org/wiki/Mersenne_Twister
+
+Engines
+=======
+
+The two Mersenne twister engines in ``flc_random`` return different-sized
+integers per call:
+
+ - ``MersenneEngine4``: each invocation returns a 32-bit ``integer(4)``
+ - ``MersenneEngine8``: each invocation returns a 64-bit ``integer(8)``
+
+Engines can be constructed using one of two interface functions: the
+argument-free ``MersenneEngine4()`` uses the default seed, and the engine takes
+a single argument ``MersenneEngine4(1234567)`` with the seed. Alternatively,
+the seed can be set (or reset) using the ``seed()`` type-bound procedure.
 
-Engine
-======
+Generally, engines are used with distributions (described below). However, if
+necessary, individual randomly generated values can be obtained by calling
+the ``next()`` type-bound procedure.
 
-The ``Engine`` is a derived type that wraps the Mersenne Twister PRNG engine.
-Its interface is::
+.. warning:: C++ generates *unsigned* integers with entropy in every bit. This
+   means that the integers obtained from ``engine%next()``, reinterpreted as
+   signed Fortran integers, may be negative.
 
-    type, public :: Engine
-    contains
-     procedure :: seed => swigf_Engine_seed
-     procedure :: discard => swigf_Engine_discard
-     procedure :: release => delete_Engine
-    end type Engine
-    interface Engine
-     module procedure new_Engine
-    end interface
+In most cases, the default distribution-compatible ``MersenneEngine4`` should
+be used, since the distributions described below require it.
 
 Distributions
 =============
 
 Distributions produce numerical values from the random bitstream provided by
-the Engine.
+an RNG engine.
 
 normal_distribution
 -------------------