path: root/lib/stdlib/doc/src/rand.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2015</year><year>2023</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>rand</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno>1</docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev>A</rev>
    <file>rand.xml</file>
  </header>
  <module since="OTP 18.0">rand</module>
  <modulesummary>Pseudo random number generation.</modulesummary>
  <description>
    <p>
      This module provides a pseudo random number generator.
      The module contains a number of algorithms.
      The uniform distribution algorithms are based on the
      <url href="http://xorshift.di.unimi.it">
	Xoroshiro and Xorshift algorithms
      </url>
      by Sebastiano Vigna.
      The normal distribution algorithm uses the
      <url href="http://www.jstatsoft.org/v05/i08">
	Ziggurat Method by Marsaglia and Tsang
      </url>
      on top of the uniform distribution algorithm.
    </p>
    <p>
      For most algorithms, jump functions are provided for generating
      non-overlapping sequences for parallel computations.
      The jump functions perform calculations
      equivalent to perform a large number of repeated calls
      for calculating new states, but execute in a time
      roughly equivalent to one regular iteration per generator bit.
    </p>

    <p>
      At the end of this module documentation there are also some
      <seeerl marker="#niche_algorithms">
        niche algorithms
      </seeerl>
      to be used without this module's normal
      <seeerl marker="#plug_in_api">
        plug-in framework API
      </seeerl>
      that may be useful for special purposes like
      short generation time when quality is not essential,
      for seeding other generators, and such.
    </p>

    <p>
      <marker id="algorithms"/>
      The following algorithms are provided:
    </p>

    <taglist>
      <tag since="OTP 22.0"><c>exsss</c></tag>
      <item>
        <p>Xorshift116**, 58 bits precision and period of 2^116-1</p>
        <p>Jump function: equivalent to 2^64 calls</p>
	<p>
	  This is the Xorshift116 generator combined with the StarStar scrambler
	  from the 2018 paper by David Blackman and Sebastiano Vigna:
	  <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf">
	    Scrambled Linear Pseudorandom Number Generators
	  </url>
	</p>
	<p>
	  The generator does not need 58-bit rotates so it is faster
	  than the Xoroshiro116 generator, and when combined with
	  the StarStar scrambler it does not have any weak low bits
	  like <c>exrop</c> (Xoroshiro116+).
	</p>
	<p>
	  Alas, this combination is about 10% slower than <c>exrop</c>,
	  but is despite that the
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>
          </seeerl>
          thanks to its statistical qualities.
	</p>
      </item>
      <tag since="OTP 22.0"><c>exro928ss</c></tag>
      <item>
        <p>Xoroshiro928**, 58 bits precision and a period of 2^928-1</p>
        <p>Jump function: equivalent to 2^512 calls</p>
	<p>
	  This is a 58 bit version of Xoroshiro1024**,
	  from the 2018 paper by David Blackman and Sebastiano Vigna:
	  <url href="http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf">
	    Scrambled Linear Pseudorandom Number Generators
	  </url>
	  that on a 64 bit Erlang system executes only
          about 40% slower than the
          <seeerl marker="#default-algorithm">
            <em>default</em> <c>exsss</c> <em>algorithm</em>
          </seeerl>
          but with much longer period and better statistical properties,
          but on the flip side a larger state.
	</p>
	<p>
	  Many thanks to Sebastiano Vigna for his help with
	  the 58 bit adaption.
	</p>
      </item>
      <tag since="OTP 20.0"><c>exrop</c></tag>
      <item>
        <p>Xoroshiro116+, 58 bits precision and period of 2^116-1</p>
        <p>Jump function: equivalent to 2^64 calls</p>
      </item>
      <tag since="OTP 20.0"><c>exs1024s</c></tag>
      <item>
        <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p>
        <p>Jump function: equivalent to 2^512 calls</p>
      </item>
      <tag since="OTP 20.0"><c>exsp</c></tag>
      <item>
        <p>Xorshift116+, 58 bits precision and period of 2^116-1</p>
        <p>Jump function: equivalent to 2^64 calls</p>
	<p>
	  This is a corrected version of the previous
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>,
          </seeerl>
	  that now has been superseded by Xoroshiro116+ (<c>exrop</c>).
	  Since there is no native 58 bit rotate instruction this
	  algorithm executes a little (say &lt; 15%) faster than <c>exrop</c>.
	  See the 
	  <url href="http://xorshift.di.unimi.it">algorithms' homepage</url>.
	</p>
      </item>
    </taglist>

    <p>
      <marker id="default-algorithm"/>
      The current <em>default algorithm</em> is
      <seeerl marker="#algorithms">
      <c>exsss</c> (Xorshift116**).
      </seeerl>
      If a specific algorithm is
      required, ensure to always use <seemfa marker="#seed/1">
      <c>seed/1</c></seemfa> to initialize the state.
    </p>
    <p>
      Which algorithm that is the default may change between
      Erlang/OTP releases, and is selected to be one with high
      speed, small state and "good enough" statistical properties.
    </p>

    <p>
      Undocumented (old) algorithms are deprecated but still implemented
      so old code relying on them will produce
      the same pseudo random sequences as before.
    </p>

    <note>
      <p>
	There were a number of problems in the implementation
	of the now undocumented algorithms, which is why
	they are deprecated.  The new algorithms are a bit slower
	but do not have these problems:
      </p>
      <p>
	Uniform integer ranges had a skew in the probability distribution
	that was not noticable for small ranges but for large ranges
	less than the generator's precision the probability to produce
	a low number could be twice the probability for a high.
      </p>
      <p>
	Uniform integer ranges larger than or equal to the generator's
	precision used a floating point fallback that only calculated
	with 52 bits which is smaller than the requested range
	and therefore were not all numbers in the requested range
	even possible to produce.
      </p>
      <p>
	Uniform floats had a non-uniform density so small values
	i.e less than 0.5 had got smaller intervals decreasing
	as the generated value approached 0.0 although still uniformly
	distributed for sufficiently large subranges.  The new algorithms
	produces uniformly distributed floats on the form N * 2.0^(-53)
	hence equally spaced.
      </p>
    </note>

    <p>Every time a random number is requested, a state is used to
      calculate it and a new state is produced. The state can either be
      implicit or be an explicit argument and return value.</p>

    <p>The functions with implicit state use the process dictionary
      variable <c>rand_seed</c> to remember the current state.</p>

    <p>If a process calls
      <seemfa marker="#uniform/0"><c>uniform/0</c></seemfa>,
      <seemfa marker="#uniform/1"><c>uniform/1</c></seemfa> or
      <seemfa marker="#uniform_real/0"><c>uniform_real/0</c></seemfa> without
      setting a seed first, <seemfa marker="#seed/1"><c>seed/1</c></seemfa>
      is called automatically with the
      <seeerl marker="#default-algorithm">
        <em>default algorithm</em>
      </seeerl>
      and creates a non-constant seed.</p>

    <p>The functions with explicit state never use the process dictionary.</p>

    <p><em>Examples:</em></p>

    <p>
      Simple use; creates and seeds the
      <seeerl marker="#default-algorithm">
        <em>default algorithm</em>
      </seeerl>
      with a non-constant seed if not already done:
    </p>

    <pre>
R0 = rand:uniform(),
R1 = rand:uniform(),</pre>

    <p>Use a specified algorithm:</p>

    <pre>
_ = rand:seed(exs928ss),
R2 = rand:uniform(),</pre>

    <p>Use a specified algorithm with a constant seed:</p>

    <pre>
_ = rand:seed(exs928ss, {123, 123534, 345345}),
R3 = rand:uniform(),</pre>

   <p>Use the functional API with a non-constant seed:</p>

   <pre>
S0 = rand:seed_s(exsss),
{R4, S1} = rand:uniform_s(S0),</pre>

   <p>Textbook basic form Box-Muller standard normal deviate</p>

   <pre>
R5 = rand:uniform_real(),
R6 = rand:uniform(),
SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre>

   <p>Create a standard normal deviate:</p>

   <pre>
{SND1, S2} = rand:normal_s(S1),</pre>

   <p>Create a normal deviate with mean -3 and variance 0.5:</p>

   <pre>
{ND0, S3} = rand:normal_s(-3, 0.5, S2),</pre>

    <note>
      <p>The builtin random number generator algorithms are not
        cryptographically strong. If a cryptographically strong
        random number generator is needed, use something like
        <seemfa marker="crypto:crypto#rand_seed/0"><c>crypto:rand_seed/0</c></seemfa>.
      </p>
    </note>

    <p>
      For all these generators except <c>exro928ss</c> and <c>exsss</c>
      the lowest bit(s) has got a slightly less
      random behaviour than all other bits.
      1 bit for <c>exrop</c> (and <c>exsp</c>),
      and 3 bits for <c>exs1024s</c>.
      See for example the explanation in the
      <url href="http://xoroshiro.di.unimi.it/xoroshiro128plus.c">
	Xoroshiro128+
      </url>
      generator source code:
    </p>
    <pre>
Beside passing BigCrush, this generator passes the PractRand test suite
up to (and included) 16TB, with the exception of binary rank tests,
which fail due to the lowest bit being an LFSR; all other bits pass all
tests. We suggest to use a sign test to extract a random Boolean value.</pre>
    <p>
      If this is a problem; to generate a boolean with these algorithms
      use something like this:
    </p>
    <pre>(rand:uniform(256) > 128) % -> boolean()</pre>
    <pre>((rand:uniform(256) - 1) bsr 7) % -> 0 | 1</pre>
    <p>
      For a general range, with <c>N = 1</c> for <c>exrop</c>,
      and <c>N = 3</c> for <c>exs1024s</c>:
    </p>
    <pre>(((rand:uniform(Range bsl N) - 1) bsr N) + 1)</pre>
    <p>
      The floating point generating functions in this module
      waste the lowest bits when converting from an integer
      so they avoid this snag.
    </p>


  </description>
  <datatypes>
    <datatype>
      <name name="builtin_alg"/>
    </datatype>
    <datatype>
      <name name="alg"/>
    </datatype>
    <datatype>
      <name name="alg_handler"/>
    </datatype>
    <datatype>
      <name name="alg_state"/>
    </datatype>
    <datatype>
      <name name="state"/>
      <desc><p>Algorithm-dependent state.</p></desc>
    </datatype>
    <datatype>
      <name name="export_state"/>
      <desc>
	<p>
	  Algorithm-dependent state that can be printed or saved to file.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="seed"/>
      <desc>
	<p>
	  A seed value for the generator.
	</p>
	<p>
	  A list of integers sets the generator's internal state directly,
	  after algorithm-dependent checks of the value
	  and masking to the proper word size.
          The number of integers must be equal to the
          number of state words in the generator.
	</p>
	<p>
	  An integer is used as the initial state for a SplitMix64 generator.
	  The output values of that is then used for setting
	  the generator's internal state
	  after masking to the proper word size
	  and if needed avoiding zero values.
	</p>
	<p>
	  A traditional 3-tuple of integers seed is passed through
	  algorithm-dependent hashing functions to create
	  the generator's initial state.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="exsplus_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="exro928_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="exrop_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="exs1024_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="exs64_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="dummy_state"/>
      <desc><p>Algorithm specific internal state</p></desc>
    </datatype>
    <datatype>
      <name name="splitmix64_state"/>
      <desc><p>Algorithm specific state</p></desc>
    </datatype>
    <datatype>
      <name name="uint58"/>
      <desc><p>0 .. (2^58 - 1)</p></desc>
    </datatype>
    <datatype>
      <name name="uint64"/>
      <desc><p>0 .. (2^64 - 1)</p></desc>
    </datatype>
    <datatype>
      <name name="mwc59_state"/>
      <desc><p>1 .. ((16#1ffb072 * 2^29 - 1) - 1)</p></desc>
    </datatype>
  </datatypes>


  <funcs>
    <fsdescription>
      <marker id="plug_in_api"/>
      <title>Plug-in framework API</title>
    </fsdescription>
    <func>
      <name name="bytes" arity="1" since="OTP 24.0"/>
      <fsummary>Return a random binary.</fsummary>
      <desc>
      <p>
        Returns, for a specified integer <c><anno>N</anno> >= 0</c>,
        a <c>binary()</c> with that number of random bytes.
        Generates as many random numbers as required using
        the selected algorithm to compose the binary,
        and updates the state in the process dictionary accordingly.
      </p>
      </desc>
    </func>

    <func>
      <name name="bytes_s" arity="2" since="OTP 24.0"/>
      <fsummary>Return a random binary.</fsummary>
      <desc>
      <p>
        Returns, for a specified integer <c><anno>N</anno> >= 0</c>
        and a state, a <c>binary()</c> with that number of random bytes,
        and a new state.
        Generates as many random numbers as required using
        the selected algorithm to compose the binary,
        and the new state.
      </p>
      </desc>
    </func>

    <func>
      <name name="export_seed" arity="0" since="OTP 18.0"/>
      <fsummary>Export the random number generation state.</fsummary>
      <desc>
        <p>Returns the random number state in an external format.
          To be used with <seemfa marker="#seed/1"><c>seed/1</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="export_seed_s" arity="1" since="OTP 18.0"/>
      <fsummary>Export the random number generation state.</fsummary>
      <desc>
        <p>Returns the random number generator state in an external format.
          To be used with <seemfa marker="#seed/1"><c>seed/1</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="jump" arity="0" since="OTP 20.0"/>
      <fsummary>Return the seed after performing jump calculation
          to the state in the process dictionary.</fsummary>
      <desc>
          <p>Returns the state
              after performing jump calculation
              to the state in the process dictionary.</p>
      <p>This function generates a <c>not_implemented</c> error exception
           when the jump function is not implemented for
           the algorithm specified in the state
           in the process dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="jump" arity="1" since="OTP 20.0"/>
      <fsummary>Return the seed after performing jump calculation.</fsummary>
      <desc>
          <p>Returns the state after performing jump calculation
              to the given state. </p>
      <p>This function generates a <c>not_implemented</c> error exception
           when the jump function is not implemented for
           the algorithm specified in the state.</p>
      </desc>
    </func>

    <func>
      <name name="normal" arity="0" since="OTP 18.0"/>
      <fsummary>Return a standard normal distributed random float.</fsummary>
      <desc>
        <p>Returns a standard normal deviate float (that is, the mean
          is 0 and the standard deviation is 1) and updates the state in
          the process dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="normal" arity="2" since="OTP 20.0"/>
      <fsummary>Return a normal distributed random float.</fsummary>
      <desc>
        <p>Returns a normal N(Mean, Variance) deviate float
          and updates the state in the process dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="normal_s" arity="1" since="OTP 18.0"/>
      <fsummary>Return a standard normal distributed random float.</fsummary>
      <desc>
        <p>Returns, for a specified state, a standard normal
          deviate float (that is, the mean is 0 and the standard
          deviation is 1) and a new state.</p>
      </desc>
    </func>

    <func>
      <name name="normal_s" arity="3" since="OTP 20.0"/>
      <fsummary>Return a normal distributed random float.</fsummary>
      <desc>
        <p>Returns, for a specified state, a normal N(Mean, Variance)
          deviate float and a new state.</p>
      </desc>
    </func>

    <func>
      <name name="seed" arity="1" clause_i="1" since="OTP 18.0"/>
      <name name="seed" arity="1" clause_i="2" since="OTP 24.0"/>
      <fsummary>Seed random number generator.</fsummary>
      <desc>
        <p>
	  Seeds random number generation with the specifed algorithm and
          time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c>
	  is an algorithm.
          <c><anno>Alg</anno>&nbsp;=&nbsp;default</c>
          is an alias for the
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>.
          </seeerl>
	</p>
        <p>Otherwise recreates the exported seed in the process dictionary,
          and returns the state. See also
          <seemfa marker="#export_seed/0"><c>export_seed/0</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="seed" arity="2" clause_i="1" since="OTP 18.0"/>
      <name name="seed" arity="2" clause_i="2" since="OTP 24.0"/>
      <fsummary>Seed the random number generation.</fsummary>
      <desc>
        <p>
          Seeds random number generation with the specified algorithm and
          integers in the process dictionary and returns the state.
          <c><anno>Alg</anno>&nbsp;=&nbsp;default</c>
          is an alias for the
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>.
          </seeerl>
        </p>
      </desc>
    </func>

    <func>
      <name name="seed_s" arity="1" clause_i="1" since="OTP 18.0"/>
      <name name="seed_s" arity="1" clause_i="2" since="OTP 24.0"/>
      <fsummary>Seed random number generator.</fsummary>
      <desc>
        <p>
	  Seeds random number generation with the specifed algorithm and
          time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c>
	  is an algorithm.
          <c><anno>Alg</anno>&nbsp;=&nbsp;default</c>
          is an alias for the
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>.
          </seeerl>
	</p>
        <p>Otherwise recreates the exported seed and returns the state.
          See also <seemfa marker="#export_seed/0">
          <c>export_seed/0</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="seed_s" arity="2" clause_i="1" since="OTP 18.0"/>
      <name name="seed_s" arity="2" clause_i="2" since="OTP 24.0"/>
      <fsummary>Seed the random number generation.</fsummary>
      <desc>
        <p>
          Seeds random number generation with the specified algorithm and
          integers and returns the state.
          <c><anno>Alg</anno>&nbsp;=&nbsp;default</c>
          is an alias for the
          <seeerl marker="#default-algorithm">
            <em>default algorithm</em>.
          </seeerl>
        </p>
      </desc>
    </func>

    <func>
      <name name="uniform" arity="0" since="OTP 18.0"/>
      <fsummary>Return a random float.</fsummary>
      <desc>
        <p>
	  Returns a random float uniformly distributed in the value
          range <c>0.0 =&lt; <anno>X</anno> &lt; 1.0</c> and
          updates the state in the process dictionary.
	</p>
	<p>
	  The generated numbers are on the form N * 2.0^(-53),
	  that is; equally spaced in the interval.
	</p>
	<warning>
	  <p>
	    This function may return exactly <c>0.0</c> which can be
	    fatal for certain applications.  If that is undesired
	    you can use <c>(1.0 - rand:uniform())</c> to get the
	    interval <c>0.0 &lt; <anno>X</anno> =&lt; 1.0</c>, or instead use
	    <seemfa marker="#uniform_real/0"><c>uniform_real/0</c></seemfa>.
	  </p>
	  <p>
	    If neither endpoint is desired you can test and re-try
	    like this:
	  </p>
	  <pre>
my_uniform() ->
    case rand:uniform() of
        0.0 -> my_uniform();
	X -> X
    end
end.</pre>
	</warning>
      </desc>
    </func>

    <func>
      <name name="uniform_real" arity="0" since="OTP 21.0"/>
      <fsummary>Return a random float.</fsummary>
      <desc>
        <p>
	  Returns a random float
	  uniformly distributed in the value range
	  <c>DBL_MIN =&lt; <anno>X</anno> &lt; 1.0</c>
	  and updates the state in the process dictionary.
	</p>
	<p>
	  Conceptually, a random real number <c>R</c> is generated
	  from the interval <c>0 =&lt; R &lt; 1</c> and then the
	  closest rounded down normalized number
	  in the IEEE 754 Double precision format
	  is returned.
	</p>
	<note>
	  <p>
	    The generated numbers from this function has got better
	    granularity for small numbers than the regular
	    <seemfa marker="#uniform/0"><c>uniform/0</c></seemfa>
	    because all bits in the mantissa are random.
	    This property, in combination with the fact that exactly zero
	    is never returned is useful for algorithms doing for example
	    <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>.
	  </p>
	</note>
	<p>
	  See
	  <seemfa marker="#uniform_real_s/1"><c>uniform_real_s/1</c></seemfa>
	  for more explanation.
	</p>
      </desc>
    </func>

    <func>
      <name name="uniform" arity="1" since="OTP 18.0"/>
      <fsummary>Return a random integer.</fsummary>
      <desc>
        <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>,
          a random integer uniformly distributed in the value range
          <c>1 =&lt; <anno>X</anno> =&lt; <anno>N</anno></c> and
          updates the state in the process dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="uniform_s" arity="1" since="OTP 18.0"/>
      <fsummary>Return a random float.</fsummary>
      <desc>
        <p>
	  Returns, for a specified state, random float
          uniformly distributed in the value range <c>0.0 =&lt;
          <anno>X</anno> &lt; 1.0</c> and a new state.
	</p>
	<p>
	  The generated numbers are on the form N * 2.0^(-53),
	  that is; equally spaced in the interval.
	</p>
	<warning>
	  <p>
	    This function may return exactly <c>0.0</c> which can be
	    fatal for certain applications.  If that is undesired
	    you can use <c>(1.0 - rand:uniform(State))</c> to get the
	    interval <c>0.0 &lt; <anno>X</anno> =&lt; 1.0</c>, or instead use
	    <seemfa marker="#uniform_real_s/1"><c>uniform_real_s/1</c></seemfa>.
	  </p>
	  <p>
	    If neither endpoint is desired you can test and re-try
	    like this:
	  </p>
	  <pre>
my_uniform(State) ->
    case rand:uniform(State) of
        {0.0, NewState} -> my_uniform(NewState);
	Result -> Result
    end
end.</pre>
	</warning>
      </desc>
    </func>

    <func>
      <name name="uniform_real_s" arity="1" since="OTP 21.0"/>
      <fsummary>Return a random float.</fsummary>
      <desc>
        <p>
	  Returns, for a specified state, a random float
	  uniformly distributed in the value range
	  <c>DBL_MIN =&lt; <anno>X</anno> &lt; 1.0</c>
	  and updates the state in the process dictionary.
	</p>
	<p>
	  Conceptually, a random real number <c>R</c> is generated
	  from the interval <c>0 =&lt; R &lt; 1</c> and then the
	  closest rounded down normalized number
	  in the IEEE 754 Double precision format
	  is returned.
	</p>
	<note>
	  <p>
	    The generated numbers from this function has got better
	    granularity for small numbers than the regular
	    <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa>
	    because all bits in the mantissa are random.
	    This property, in combination with the fact that exactly zero
	    is never returned is useful for algorithms doing for example
	    <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>.
	  </p>
	</note>
	<p>
	  The concept implicates that the probability to get
	  exactly zero is extremely low; so low that this function
	  is in fact guaranteed to never return zero.  The smallest
	  number that it might return is <c>DBL_MIN</c>, which is
	  2.0^(-1022).
	</p>
	<p>
	  The value range stated at the top of this function
	  description is technically correct, but
	  <c>0.0 =&lt; <anno>X</anno> &lt; 1.0</c>
	  is a better description of the generated numbers'
	  statistical distribution.  Except that exactly 0.0
	  is never returned, which is not possible to observe
	  statistically.
	</p>
	<p>
	  For example; for all sub ranges
	  <c>N*2.0^(-53) =&lt; X &lt; (N+1)*2.0^(-53)</c>
	  where
	  <c>0 =&lt; integer(N) &lt; 2.0^53</c>
	  the probability is the same.
	  Compare that with the form of the numbers generated by
	  <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa>.
	</p>
	<p>
	  Having to generate extra random bits for
	  small numbers costs a little performance.
	  This function is about 20% slower than the regular
	  <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa>
	</p>
      </desc>
    </func>

    <func>
      <name name="uniform_s" arity="2" since="OTP 18.0"/>
      <fsummary>Return a random integer.</fsummary>
      <desc>
        <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>
          and a state, a random integer uniformly distributed in the value
          range <c>1 =&lt; <anno>X</anno> =&lt; <anno>N</anno></c> and a
          new state.</p>
      </desc>
    </func>
  </funcs>


  <funcs>
    <fsdescription>
      <marker id="niche_algorithms"/>
      <title>Niche algorithms API</title>
      <p>
        This section contains special purpose algorithms
        that does not use the
        <seeerl marker="#plug_in_api">plug-in framework API</seeerl>,
        for example for speed reasons.
      </p>
      <p>
        Since these algorithms lack the plug-in framework support,
        generating numbers in a range other than the
        generator's own generated range may become a problem.
      </p>
      <p>
        There are at least 3 ways to do this, assuming that
        the range is less than the generator's range:
      </p>
      <taglist>
        <tag>Modulo</tag>
        <item>
          <p>
            To generate a number <c>V</c> in the range 0..<c>Range</c>-1:
          </p>
          <list type="bulleted">
            <item>Generate a number <c>X</c>.</item>
            <item>
              Use <c>V&nbsp;=&nbsp;X&nbsp;rem&nbsp;Range</c> as your value.
            </item>
          </list>
          <p>
            This method uses <c>rem</c>, that is, the remainder of
            an integer division, which is a slow operation.
          </p>
          <p>
            Low bits from the generator propagate straight through
            to the generated value, so if the generator has got
            weaknesses in the low bits this method propagates
            them too.
          </p>
          <p>
            If <c>Range</c> is not a divisor of the generator range,
            the generated numbers have a bias.
            Example:
          </p>
          <p>
            Say the generator generates a byte, that is,
            the generator range is 0..255,
            and the desired range is 0..99 (<c>Range=100</c>).
            Then there are 3 generator outputs that produce the value 0,
            that is; 0, 100 and 200.  But there are only
            2 generator outputs that produce the value 99,
            which are; 99 and 199.  So the probability for
            a value <c>V</c> in 0..55 is 3/2 times
            the probability for the other values 56..99.
          </p>
          <p>
            If <c>Range</c> is much smaller than the generator range,
            then this bias gets hard to detect.  The rule of thumb is
            that if <c>Range</c> is smaller than the square root
            of the generator range, the bias is small enough.
            Example:
          </p>
          <p>
            A byte generator when <c>Range=20</c>.
            There are 12 (<c>256&nbsp;div&nbsp;20</c>)
            possibilities to generate the highest numbers
            and one more to generate a number
            <c>V</c>&nbsp;&lt;&nbsp;16 (<c>256&nbsp;rem&nbsp;20</c>).
            So the probability is 13/12 for a low number
            versus a high.  To detect that difference
            with some confidence you would need to generate
            a lot more numbers than the generator range,
            256 in this small example.
          </p>
        </item>
        <tag>Truncated multiplication</tag>
        <item>
          <p>
            To generate a number <c>V</c> in the range 0..<c>Range</c>-1,
            when you have a generator with the range
            0..2^<c>Bits</c>-1:
          </p>
          <list type="bulleted">
            <item>Generate a number <c>X</c>.</item>
            <item>
              Use <c>V&nbsp;=&nbsp;X*Range&nbsp;bsr&nbsp;Bits</c>
              as your value.
            </item>
          </list>
          <p>
            If the multiplication <c>X*Range</c> creates a bignum
            this method becomes very slow.
          </p>
          <p>
            High bits from the generator propagate through
            to the generated value, so if the generator has got
            weaknesses in the high bits this method propagates
            them too.
          </p>
          <p>
            If <c>Range</c> is not a divisor of the generator range,
            the generated numbers have a bias,
            pretty much as for the <em>Modulo</em> method above.
          </p>
        </item>
        <tag>Shift or mask</tag>
        <item>
          <p>
            To generate a number in the range 0..2^<c>RBits</c>-1,
            when you have a generator with the range 0..2^<c>Bits</c>:
          </p>
          <list type="bulleted">
            <item>Generate a number <c>X</c>.</item>
            <item>
              Use <c>V&nbsp;=&nbsp;X&nbsp;band&nbsp;((1&nbsp;bsl&nbsp;RBits)-1)</c>
              or <c>V&nbsp;=&nbsp;X&nbsp;bsr&nbsp;(Bits-RBits)</c>
              as your value.
            </item>
          </list>
          <p>
            Masking with <c>band</c> preserves the low bits,
            and right shifting with <c>bsr</c> preserves the high,
            so if the generator has got weaknesses in high or low
            bits; choose the right operator.
          </p>
          <p>
            If the generator has got a range that is not a power of 2
            and this method is used anyway, it introduces bias
            in the same way as for the <em>Modulo</em> method above.
          </p>
        </item>
        <tag>Rejection</tag>
        <item>
          <list type="bulleted">
            <item>Generate a number <c>X</c>.</item>
            <item>
              If <c>X</c> is in the range, use <c>V&nbsp;=&nbsp;X</c>
              as your value, otherwise reject it and repeat.
            </item>
          </list>
          <p>
            In theory it is not certain that this method
            will ever complete, but in practice you ensure
            that the probability of rejection is low.
            Then the probability for yet another iteration
            decreases exponentially so the expected mean
            number of iterations will often be between 1 and 2.
            Also, since the base generator is a full length generator,
            a value that will break the loop must eventually
            be generated.
          </p>
        </item>
      </taglist>
      <p>
        Chese methods can be combined, such as using the <em>Modulo</em>
        method and only if the generator value would create bias
        use <em>Rejection</em>.  Or using <em>Shift or mask</em>
        to reduce the size of a generator value so that
        <em>Truncated multiplication</em> will not create a bignum.
      </p>
      <p>
        The recommended way to generate a floating point number
        (IEEE 745 double, that has got a 53-bit mantissa)
        in the range 0..1, that is
        0.0&nbsp;=&lt;&nbsp;<c>V</c>&nbsp;&lt;1.0
        is to generate a 53-bit number <c>X</c> and then use
        <c>V&nbsp;=&nbsp;X&nbsp;*&nbsp;(1.0/((1&nbsp;bsl&nbsp;53)))</c>
        as your value.  This will create a value on the form
        <c>N</c>*2^-53 with equal probability for every
        possible <c>N</c> for the range.
      </p>
    </fsdescription>
    <func>
      <name name="splitmix64_next" arity="1" since="OTP 25.0"/>
      <fsummary>Return a random integer and new state.</fsummary>
      <desc>
        <p>
          Returns a random 64-bit integer <c><anno>X</anno></c>
          and a new generator state <c><anno>NewAlgState</anno></c>,
          according to the SplitMix64 algorithm.
        </p>
        <p>
          This generator is used internally in the <c>rand</c>
          module for seeding other generators since it is of a
          quite different breed which reduces the probability for
          creating an accidentally bad seed.
        </p>
      </desc>
    </func>
    <func>
      <name name="exsp_next" arity="1" since="OTP 25.0"/>
      <fsummary>Return a random integer and new state.</fsummary>
      <desc>
        <p>
          Returns a random 58-bit integer <c><anno>X</anno></c>
          and a new generator state <c><anno>NewAlgState</anno></c>,
          according to the Xorshift116+ algorithm.
        </p>
        <p>
          This is an API function into the internal implementation of the
          <seeerl marker="#algorithms"><c>exsp</c></seeerl>
          algorithm that enables using it without the overhead
          of the plug-in framework, which might be useful
          for time critial applications.
          On a typical 64 bit Erlang VM this approach executes
          in just above 30% (1/3) of the time
          for the default algorithm through
          this module's normal plug-in framework.
        </p>
        <p>
          To seed this generator use
          <seemfa marker="#seed_s/1">
            <c>{_, <anno>AlgState</anno>} = rand:seed_s(exsp)</c>
          </seemfa>
          or
          <seemfa marker="#seed_s/1">
            <c>{_, <anno>AlgState</anno>} = rand:seed_s(exsp, Seed)</c>
          </seemfa>
          with a specific <c>Seed</c>.
        </p>
        <note>
          <p>
            This function offers no help in generating a number
            on a selected range, nor in generating a floating point number.
            It is easy to accidentally mess up the fairly good
            statistical properties of this generator when doing either.
            See the recepies at the start of this
            <seeerl marker="#niche_algorithms">
              Niche algorithms API
            </seeerl>
            description.
            Note also the caveat about weak low bits that
            this generator suffers from.
            The generator is exported in this form
            primarily for performance.
          </p>
        </note>
      </desc>
    </func>
    <func>
      <name name="exsp_jump" arity="1" since="OTP 25.0"/>
      <fsummary>Return the new state as from 2^64 iterations.</fsummary>
      <desc>
        <p>
          Returns a new generator state equivalent of the state
          after iterating over
          <seemfa marker="#exsp_next/1"><c>exsp_next/1</c></seemfa>
          2^64 times.
        </p>
        <p>
          See the description of jump functions
          at the top of this module description.
        </p>
      </desc>
    </func>
    <func>
      <name name="mwc59" arity="1" since="OTP 25.0"/>
      <fsummary>Return a new generator state.</fsummary>
      <desc>
        <p>
          Returns a new generator state <c><anno>CX1</anno></c>,
          according to a Multiply With Carry generator,
          which is an efficient implementation of a
          Multiplicative Congruential Generator with
          a power of 2 multiplier and a prime modulus.
        </p>
        <p>
          This generator uses the multiplier 2^32 and the modulus
          16#7fa6502&nbsp;*&nbsp;2^32&nbsp;-&nbsp;1,
          which have been selected,
          in collaboration with Sebastiano Vigna,
          to avoid bignum operations
          and still get good statistical quality.
          It can be written as:<br/>
          <c>C&nbsp;=&nbsp;<anno>CX0</anno>&nbsp;bsr&nbsp;32</c><br/>
          <c>X&nbsp;=&nbsp;<anno>CX0</anno>&nbsp;band&nbsp;((1&nbsp;bsl&nbsp;32)-1))</c><br/>
          <c><anno>CX1</anno>&nbsp;=&nbsp;16#7fa6502&nbsp;*&nbsp;X&nbsp;+&nbsp;C</c>
        </p>
        <p>
          Because the generator uses a multiplier that is
          a power of 2 it gets statistical flaws for collision tests
          and birthday spacings tests in 2 and 3 dimensions,
          and even these caveats apply only to the MWC "digit",
          that is the low 32 bits (due to the multiplier) of
          the generator state.
        </p>
        <p>
          The quality of the output value improves much by using
          a scrambler instead of just taking the low bits.
          Function
          <seemfa marker="#mwc59_value32/1">
            <c>mwc59_value32</c>
          </seemfa>
          is a fast scrambler that returns a decent 32-bit number.
          The slightly slower
          <seemfa marker="#mwc59_value/1">
            <c>mwc59_value</c>
          </seemfa>
          scrambler returns 59 bits of very good quality, and
          <seemfa marker="#mwc59_float/1"><c>mwc59_float</c></seemfa>
          returns a <c>float()</c> of very good quality.
        </p>
        <p>
          The low bits of the base generator are surprisingly good,
          so the lowest 16 bits actually pass fairly strict PRNG tests,
          despite the generator's weaknesses that lie in the high
          bits of the 32-bit MWC "digit".  It is recommended
          to use <c>rem</c> on the the generator state,
          or bit mask extracting the lowest bits to produce numbers
          in a range 16 bits or less.
          See the recepies at the start of this
          <seeerl marker="#niche_algorithms">
            Niche algorithms API
          </seeerl>
          description.
        </p>
        <p>
          On a typical 64 bit Erlang VM this generator executes
          in below 8% (1/13) of the time
          for the default algorithm in the
          <seeerl marker="#plug_in_api">
            plug-in framework API
          </seeerl>
          of this module.  With the
          <seemfa marker="#mwc59_value32/1">
            <c>mwc59_value32</c>
          </seemfa>
          scrambler the total time becomes 16% (1/6),
          and with
          <seemfa marker="#mwc59_value/1">
            <c>mwc59_value</c>
          </seemfa>
          it becomes 20% (1/5) of the time for the default algorithm.
          With
          <seemfa marker="#mwc59_float/1"><c>mwc59_float</c></seemfa>
          the total time is 60% of the time for the default
          algorithm generating a <c>float()</c>.
        </p>
        <note>
          <p>
            This generator is a niche generator for high speed
            applications.  It has a much shorter period
            than the default generator, which in itself
            is a quality concern, although when used with the
            value scramblers it passes strict PRNG tests.
            The generator is much faster than
            <seemfa marker="#exsp_next/1"><c>exsp_next/1</c></seemfa>
            but with a bit lower quality.
          </p>
        </note>
      </desc>
    </func>
    <func>
      <name name="mwc59_value32" arity="1" since="OTP 25.0"/>
      <fsummary>Return the generator value.</fsummary>
      <desc>
        <p>
          Returns a 32-bit value <c><anno>V</anno></c>
          from a generator state <c><anno>CX</anno></c>.
          The generator state is scrambled using
          an 8-bit xorshift which masks
          the statistical imperfecions of the base generator
          <seemfa marker="#mwc59/1"><c>mwc59</c></seemfa>
          enough to produce numbers of decent quality.
          Still some problems in 2- and 3-dimensional
          birthday spacing and collision tests show through.
        </p>
        <p>
          When using this scrambler it is in general better to use
          the high bits of the value than the low.
          The lowest 8 bits are of good quality and pass right through
          from the base generator.  They are combined with the next 8
          in the xorshift making the low 16 good quality,
          but in the range 16..31 bits there are weaker bits
          that you do not want to have as the high bits
          of your generated values.
          Therefore it is in general safer to shift out low bits.
          See the recepies at the start of this
          <seeerl marker="#niche_algorithms">
            Niche algorithms API
          </seeerl>
          description.
        </p>
        <p>
          For a non power of 2 range less than about 16 bits
          (to not get too much bias and to avoid bignums)
          truncated multiplication can be used,
          which is much faster than using <c>rem</c>:
          <c>(Range*<anno>V</anno>)&nbsp;bsr&nbsp;32</c>.
        </p>
      </desc>
    </func>
    <func>
      <name name="mwc59_value" arity="1" since="OTP 25.0"/>
      <fsummary>Return the generator value.</fsummary>
      <desc>
        <p>
          Returns a 59-bit value <c><anno>V</anno></c>
          from a generator state <c><anno>CX</anno></c>.
          The generator state is scrambled using
          an 4-bit followed by a 27-bit xorshift, which masks
          the statistical imperfecions of the base generator
          <seemfa marker="#mwc59/1"><c>mwc59</c></seemfa>
          enough that all 59 bits are of very good quality.
        </p>
        <p>
          Be careful to not accidentaly create a bignum
          when handling the value <c><anno>V</anno></c>.
        </p>
        <p>
          It is in general general better to use the high bits
          from this scrambler than the low.
          See the recepies at the start of this
          <seeerl marker="#niche_algorithms">
            Niche algorithms API
          </seeerl>
          description.
        </p>
        <p>
          For a non power of 2 range less than about 29 bits
          (to not get too much bias and to avoid bignums)
          truncated multiplication can be used,
          which is much faster than using <c>rem</c>.
          Example for range 1'000'000'000;
          the range is 30 bits, we use 29 bits from the generator,
          adding up to 59 bits, which is not a bignum:
          <c>(1000000000&nbsp;*&nbsp;(<anno>V</anno>&nbsp;bsr&nbsp;(59-29)))&nbsp;bsr&nbsp;29</c>.
        </p>
      </desc>
    </func>
    <func>
      <name name="mwc59_float" arity="1" since="OTP 25.0"/>
      <fsummary>Return a generated float.</fsummary>
      <desc>
        <p>
          Returns the generator value <c><anno>V</anno></c>
          from a generator state <c><anno>CX</anno></c>,
          as a <c>float()</c>.
          The generator state is scrambled as with
          <seemfa marker="#mwc59_value/1">
            <c>mwc59_value/1</c>
          </seemfa>
          before converted to a <c>float()</c>.
        </p>
      </desc>
    </func>
    <func>
      <name name="mwc59_seed" arity="0" since="OTP 25.0"/>
      <name name="mwc59_seed" arity="1" since="OTP 25.0"/>
      <fsummary>Create a generator state.</fsummary>
      <desc>
        <p>
          Returns a generator state <c><anno>CX</anno></c>.
          <c><anno>S</anno></c> is hashed to create the generator state,
          to avoid that similar seeds create similar sequences.
        </p>
        <p>
          Without <c><anno>S</anno></c>,
          the generator state is created as for
          <seemfa marker="#seed_s/1"><c>seed_s(atom())</c></seemfa>.
        </p>
      </desc>
    </func>
  </funcs>
</erlref>