.. _physics-randomNumberGenerator:

Random Number Generators
========================

Class providing pseudo-random number generators---algorithms that produce sequences of numbers with the statistical properties of true randomness. Methods return uniform deviates on :math:`[0,1)`, Gaussian deviates, and raw integer samples, with support for seeding and independent sequences per MPI process and OpenMP thread. Random number generators are used throughout Galacticus for Monte Carlo sampling, stochastic merger tree construction, posterior sampling simulations, and generating scatter in model predictions.

**Default implementation:** ``randomNumberGeneratorGSL``

Methods
-------

``mpiIndependent`` → ``logical``
   Return true if this random number generator produces independent sequences per MPI process (when using the same seed and offsetting is requested).

``openMPIndependent`` → ``logical``
   Return true if this random number generator produces independent sequences per OpenMP thread (when using the same seed and offsetting is requested).

``rangeMinimum`` → ``integer(c_long)``
   Return the smallest integer in the range for this generator.

``rangeMaximum`` → ``integer(c_long)``
   Return the largest integer in the range for this generator.

``sample`` → ``integer(c_long)``
   Return a random integer. If the optional argument ``n`` is supplied the random integer will lie in the range 0 to  ``n``-1 inclusive (with all integers being equally likely). Otherwise, the integer will be drawn from the full range provided by the generator.

   * ``integer(c_long), intent(in ), optional :: n``

``uniformSample`` → ``double precision``
   Return a random number drawn from a uniform distribution on [0,1).

``poissonSample`` → ``integer``
   Return a random number drawn from a Poisson distribution with the given ``mean``.

   * ``double precision, intent(in ) :: mean``

``standardNormalSample`` → ``double precision``
   Return a random number drawn from a standard normal distribution.

``seedSet`` → ``void``
   Reset the seed for this random number generator.

   * ``integer(c_long), intent(in ) :: seed``

   * ``logical , intent(in ) :: offset``

``seed`` → ``integer(c_long)``
   Return the seed for this random number generator.

.. _physics-randomNumberGeneratorGSL:

``randomNumberGeneratorGSL``
----------------------------

A random number generator class which utilizes the :term:`GSL` random number generators.

**(Default implementation)**

**Parameters**

* ``[seed]`` (default ``219_c_long``) — A seed value for the random number generator.
* ``[ompThreadOffset]`` (default ``.false.``) — If true, offset the seed by the OpenMP thread number.
* ``[mpiRankOffset]`` (default ``.false.``) — If true, offset the seed by the MPI process rank.