diff options
Diffstat (limited to 'lib/stdlib/doc/src/rand.xml')
| -rw-r--r-- | lib/stdlib/doc/src/rand.xml | 290 |
1 files changed, 153 insertions, 137 deletions
diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 50057259c6..1dcc3de000 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -33,215 +33,231 @@ <file>rand.xml</file> </header> <module>rand</module> - <modulesummary>Pseudo random number generation</modulesummary> + <modulesummary>Pseudo random number generation.</modulesummary> <description> - <p>Random number generator.</p> - - <p>The module contains several different algorithms and can be - extended with more in the future. The current uniform - distribution algorithms uses the - <url href="http://xorshift.di.unimi.it"> - scrambled Xorshift algorithms by Sebastiano Vigna</url> and the - normal distribution algorithm uses the - <url href="http://www.jstatsoft.org/v05/i08"> - Ziggurat Method by Marsaglia and Tsang</url>. - </p> - - <p>The implemented algorithms are:</p> + <p>This module provides a random number generator. The module contains + a number of algorithms. The uniform distribution algorithms use the + <url href="http://xorshift.di.unimi.it">scrambled Xorshift algorithms by + Sebastiano Vigna</url>. The normal distribution algorithm uses the + <url href="http://www.jstatsoft.org/v05/i08">Ziggurat Method by Marsaglia + and Tsang</url>.</p> + + <p>The following algorithms are provided:</p> + <taglist> - <tag><c>exsplus</c></tag> <item>Xorshift116+, 58 bits precision and period of 2^116-1.</item> - <tag><c>exs64</c></tag> <item>Xorshift64*, 64 bits precision and a period of 2^64-1.</item> - <tag><c>exs1024</c></tag> <item>Xorshift1024*, 64 bits precision and a period of 2^1024-1.</item> + <tag><c>exsplus</c></tag> + <item> + <p>Xorshift116+, 58 bits precision and period of 2^116-1</p> + </item> + <tag><c>exs64</c></tag> + <item> + <p>Xorshift64*, 64 bits precision and a period of 2^64-1</p> + </item> + <tag><c>exs1024</c></tag> + <item> + <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p> + </item> </taglist> - <p>The current default algorithm is <c>exsplus</c>. The default - may change in future. If a specific algorithm is required make - sure to always use <seealso marker="#seed-1">seed/1</seealso> - to initialize the state. - </p> + <p>The default algorithm is <c>exsplus</c>. If a specific algorithm is + required, ensure to always use <seealso marker="#seed-1"> + <c>seed/1</c></seealso> to initialize the state.</p> <p>Every time a random number is requested, a state is used to - calculate it and a new state produced. The state can either be - implicit or it can be an explicit argument and return value. - </p> + 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> + variable <c>rand_seed</c> to remember the current state.</p> + + <p>If a process calls + <seealso marker="#uniform-0"><c>uniform/0</c></seealso> or + <seealso marker="#uniform-1"><c>uniform/1</c></seealso> without + setting a seed first, <seealso marker="#seed-1"><c>seed/1</c></seealso> + is called automatically with the default algorithm 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 default algorithm + with a non-constant seed if not already done:</p> + + <pre> +R0 = rand:uniform(), +R1 = rand:uniform(),</pre> - <p>If a process calls <seealso marker="#uniform-0">uniform/0</seealso> or - <seealso marker="#uniform-1">uniform/1</seealso> without - setting a seed first, <seealso marker="#seed-1">seed/1</seealso> - is called automatically with the default algorithm and creates a - non-constant seed.</p> + <p>Use a specified algorithm:</p> - <p>The functions with explicit state never use the process - dictionary.</p> + <pre> +_ = rand:seed(exs1024), +R2 = rand:uniform(),</pre> + + <p>Use a specified algorithm with a constant seed:</p> - <p>Examples:</p> <pre> - %% Simple usage. Creates and seeds the default algorithm - %% with a non-constant seed if not already done. - R0 = rand:uniform(), - R1 = rand:uniform(), - - %% Use a given algorithm. - _ = rand:seed(exs1024), - R2 = rand:uniform(), - - %% Use a given algorithm with a constant seed. - _ = rand:seed(exs1024, {123, 123534, 345345}), - R3 = rand:uniform(), - - %% Use the functional api with non-constant seed. - S0 = rand:seed_s(exsplus), - {R4, S1} = rand:uniform_s(S0), - - %% Create a standard normal deviate. - {SND0, S2} = rand:normal_s(S1), - </pre> - - <note><p>This random number generator is not cryptographically - strong. If a strong cryptographic random number generator is - needed, use one of functions in the - <seealso marker="crypto:crypto">crypto</seealso> - module, for example <c>crypto:strong_rand_bytes/1</c>.</p></note> +_ = rand:seed(exs1024, {123, 123534, 345345}), +R3 = rand:uniform(),</pre> + + <p>Use the functional API with a non-constant seed:</p> + + <pre> +S0 = rand:seed_s(exsplus), +{R4, S1} = rand:uniform_s(S0),</pre> + + <p>Create a standard normal deviate:</p> + + <pre> +{SND0, S2} = rand:normal_s(S1),</pre> + + <note> + <p>This random number generator is not cryptographically + strong. If a strong cryptographic random number generator is + needed, use one of functions in the + <seealso marker="crypto:crypto"><c>crypto</c></seealso> + module, for example, <seealso marker="crypto:crypto"> + <c>crypto:strong_rand_bytes/1</c></seealso>.</p> + </note> + </description> <datatypes> <datatype> <name name="alg"/> </datatype> - <datatype> <name name="state"/> - <desc><p>Algorithm dependent state.</p></desc> + <desc><p>Algorithm-dependent state.</p></desc> </datatype> - <datatype> <name name="export_state"/> - <desc><p>Algorithm dependent state which can be printed or saved to file.</p></desc> + <desc><p>Algorithm-dependent state that can be printed or saved to + file.</p></desc> </datatype> </datatypes> <funcs> <func> - <name name="seed" arity="1"/> - <fsummary>Seed random number generator</fsummary> - <desc> - <marker id="seed-1"/> - <p>Seeds random number generation with the given algorithm and time dependent - data if <anno>AlgOrExpState</anno> is an algorithm.</p> - <p>Otherwise recreates the exported seed in the process - dictionary, and returns the state. - <em>See also:</em> <seealso marker="#export_seed-0">export_seed/0</seealso>.</p> + <name name="export_seed" arity="0"/> + <fsummary>Export the random number generation state.</fsummary> + <desc><marker id="export_seed-0"/> + <p>Returns the random number state in an external format. + To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p> </desc> </func> + <func> - <name name="seed_s" arity="1"/> - <fsummary>Seed random number generator</fsummary> - <desc> - <p>Seeds random number generation with the given algorithm and time dependent - data if <anno>AlgOrExpState</anno> is an algorithm.</p> - <p>Otherwise recreates the exported seed and returns the state. - <em>See also:</em> <seealso marker="#export_seed-0">export_seed/0</seealso>.</p> + <name name="export_seed_s" arity="1"/> + <fsummary>Export the random number generation state.</fsummary> + <desc><marker id="export_seed_s-1"/> + <p>Returns the random number generator state in an external format. + To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p> </desc> </func> + <func> - <name name="seed" arity="2"/> - <fsummary>Seed the random number generation</fsummary> + <name name="normal" arity="0"/> + <fsummary>Return a standard normal distributed random float.</fsummary> <desc> - <p>Seeds random number generation with the given algorithm and - integers in the process dictionary and returns - the state.</p> + <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="seed_s" arity="2"/> - <fsummary>Seed the random number generation</fsummary> + <name name="normal_s" arity="1"/> + <fsummary>Return a standard normal distributed random float.</fsummary> <desc> - <p>Seeds random number generation with the given algorithm and - integers and returns the state.</p> + <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="export_seed" arity="0"/> - <fsummary>Export the random number generation state</fsummary> - <desc><marker id="export_seed-0"/> - <p>Returns the random number state in an external format. - To be used with <seealso marker="#seed-1">seed/1</seealso>.</p> + <name name="seed" arity="1"/> + <fsummary>Seed random number generator.</fsummary> + <desc> + <marker id="seed-1"/> + <p>Seeds random number generation with the specifed algorithm and + time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p> + <p>Otherwise recreates the exported seed in the process dictionary, + and returns the state. See also + <seealso marker="#export_seed-0"><c>export_seed/0</c></seealso>.</p> </desc> </func> <func> - <name name="export_seed_s" arity="1"/> - <fsummary>Export the random number generation state</fsummary> - <desc><marker id="export_seed_s-1"/> - <p>Returns the random number generator state in an external format. - To be used with <seealso marker="#seed-1">seed/1</seealso>.</p> + <name name="seed" arity="2"/> + <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.</p> </desc> </func> <func> - <name name="uniform" arity="0"/> - <fsummary>Return a random float</fsummary> + <name name="seed_s" arity="1"/> + <fsummary>Seed random number generator.</fsummary> <desc> - <marker id="uniform-0"/> - <p>Returns a random float uniformly distributed in the value - range <c>0.0 < <anno>X</anno> < 1.0 </c> and - updates the state in the process dictionary.</p> + <p>Seeds random number generation with the specifed algorithm and + time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p> + <p>Otherwise recreates the exported seed and returns the state. + See also <seealso marker="#export_seed-0"> + <c>export_seed/0</c></seealso>.</p> </desc> </func> + <func> - <name name="uniform_s" arity="1"/> - <fsummary>Return a random float</fsummary> + <name name="seed_s" arity="2"/> + <fsummary>Seed the random number generation.</fsummary> <desc> - <p>Given a state, <c>uniform_s/1</c> returns a random float - uniformly distributed in the value range <c>0.0 < - <anno>X</anno> < 1.0</c> and a new state.</p> + <p>Seeds random number generation with the specified algorithm and + integers and returns the state.</p> </desc> </func> <func> - <name name="uniform" arity="1"/> - <fsummary>Return a random integer</fsummary> - <desc> - <marker id="uniform-1"/> - <p>Given an integer <c><anno>N</anno> >= 1</c>, - <c>uniform/1</c> returns a random integer uniformly - distributed in the value range - <c>1 <= <anno>X</anno> <= <anno>N</anno></c> and - updates the state in the process dictionary.</p> + <name name="uniform" arity="0"/> + <fsummary>Return a random float.</fsummary> + <desc><marker id="uniform-0"/> + <p>Returns a random float uniformly distributed in the value + range <c>0.0 < <anno>X</anno> < 1.0</c> and + updates the state in the process dictionary.</p> </desc> </func> + <func> - <name name="uniform_s" arity="2"/> - <fsummary>Return a random integer</fsummary> - <desc> - <p>Given an integer <c><anno>N</anno> >= 1</c> and a state, - <c>uniform_s/2</c> returns a random integer uniformly - distributed in the value range <c>1 <= <anno>X</anno> <= - <anno>N</anno></c> and a new state.</p> + <name name="uniform" arity="1"/> + <fsummary>Return a random integer.</fsummary> + <desc><marker id="uniform-1"/> + <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>, + a random integer uniformly distributed in the value range + <c>1 <= <anno>X</anno> <= <anno>N</anno></c> and + updates the state in the process dictionary.</p> </desc> </func> <func> - <name name="normal" arity="0"/> - <fsummary>Return a standard normal distributed random float</fsummary> + <name name="uniform_s" arity="1"/> + <fsummary>Return a 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> + <p>Returns, for a specified state, random float + uniformly distributed in the value range <c>0.0 < + <anno>X</anno> < 1.0</c> and a new state.</p> </desc> </func> + <func> - <name name="normal_s" arity="1"/> - <fsummary>Return a standard normal distributed random float</fsummary> + <name name="uniform_s" arity="2"/> + <fsummary>Return a random integer.</fsummary> <desc> - <p>Given a state, <c>normal_s/1</c> returns a standard normal - deviate float (that is, the mean is 0 and the standard - deviation is 1) and a new state.</p> + <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 <= <anno>X</anno> <= <anno>N</anno></c> and a + new state.</p> </desc> </func> - </funcs> </erlref> |