From 401bf07f5908137cde206f2f755af83c9a7ff71e Mon Sep 17 00:00:00 2001 From: Dan Gudmundsson Date: Tue, 28 Apr 2015 14:37:33 +0200 Subject: stdlib: Document and add normal distributed random value function It is needed in various tests. It uses the Ziggurat algorithm, which is the fastest that I know. --- lib/stdlib/doc/src/rand.xml | 246 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 lib/stdlib/doc/src/rand.xml (limited to 'lib/stdlib/doc/src/rand.xml') diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml new file mode 100644 index 0000000000..178afda5a0 --- /dev/null +++ b/lib/stdlib/doc/src/rand.xml @@ -0,0 +1,246 @@ + + + + +
+ + 2015 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + rand + + + 1 + + + + A + rand.xml +
+ rand + Pseudo random number generation + +

Random number generator.

+ +

The module contains several different algorithms and can be + extended with more in the future. The current uniform + distribution algorithms uses the + + scrambled Xorshift algorithms by Sebastiano Vigna and the + normal distribution algorithm uses the + + Ziggurat Method by Marsaglia and Tsang. +

+ +

The implemented algorithms are:

+ + exsplus Xorshift116+, 58 bits precision and period of 2^116-1. + exs64 Xorshift64*, 64 bits precision and a period of 2^64-1. + exs1024 Xorshift1024*, 64 bits precision and a period of 2^1024-1. + + +

The current default algorithm is exsplus. The default + may change in future. If a specific algorithm is required make + sure to always use seed/1 + to initialize the state. +

+ +

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. +

+ +

The functions with implicit state use the process dictionary + variable rand_seed to remember the current state.

+ +

If a process calls uniform/0 or + uniform/1 without + setting a seed first, seed/1 + is called automatically with the default algorithm and creates a + non-constant seed.

+ +

The functions with explicit state never use the process + dictionary.

+ +

Examples:

+ 
+      %% 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),
+
+ +

This random number generator is not cryptographically + strong. If a strong cryptographic random number generator is + needed, use one of functions in the + crypto + module, for example crypto:rand_bytes/1.

 + + + + + + + + +

Algorithm dependent state.

 + + + + +

Algorithm dependent state which can be printed or saved to file.

 + + + + + + + Seed random number generator + + +

Seeds random number generation with the given algorithm and time dependent + data if AlgOrExpState is an algorithm.

+

Otherwise recreates the exported seed in the process + dictionary, and returns the state. + See also: export_seed/0.

+ + + + + Seed random number generator + +

Seeds random number generation with the given algorithm and time dependent + data if AlgOrExpState is an algorithm.

+

Otherwise recreates the exported seed and returns the state. + See also: export_seed/0.

+ + + + + Seed the random number generation + +

Seeds random number generation with the given algorithm and + integers in the process dictionary and returns + the state.

+ + + + + Seed the random number generation + +

Seeds random number generation with the given algorithm and + integers and returns the state.

+ + + + + + Export the random number generation state + +

Returns the random number state in an external format. + To be used with seed/1.

+ + + + + + Export the random number generation state + +

Returns the random number generator state in an external format. + To be used with seed/1.

+ + + + + + Return a random float + + +

Returns a random float uniformly distributed in the value + range 0.0 < X < 1.0 and + updates the state in the process dictionary.

+ + + + + Return a random float + +

Given a state, uniform_s/1 returns a random float + uniformly distributed in the value range 0.0 < + X < 1.0 and a new state.

+ + + + + + Return a random integer + + +

Given an integer N >= 1, + uniform/1 returns a random integer uniformly + distributed in the value range + 1 <= X <= N and + updates the state in the process dictionary.

+ + + + + Return a random integer + +

Given an integer N >= 1 and a state, + uniform_s/2 returns a random integer uniformly + distributed in the value range 1 <= X <= + N and a new state.

+ + + + + + Return a standard normal distributed random float + +

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.

+ + + + + Return a standard normal distributed random float + +

Given a state, normal_s/1 returns a standard normal + deviate float (that is, the mean is 0 and the standard + deviation is 1) and a new state.

+ + + + + -- cgit v1.2.3