Module sfmt_pure

SIMD-oriented Fast Mersenne Twister (SFMT) in pure Erlang.

Copyright © 2010-2016 Kenji Rikitake, Mutsuo Saito, Makoto Matsumoto, Kyoto University, Hiroshima University, The University of Tokyo

Authors: Kenji Rikitake (kenji.rikitake@acm.org), Mutsuo Saito, Makoto Matsumoto.

Description

SIMD-oriented Fast Mersenne Twister (SFMT) in pure Erlang. The recursion algorithm for gen_rand_all and gen_rand_list32 are explained as follows:
  a[]: output array (of S w128() elements)
  i[]: internal state (of N w128() elements)
  (For gen_rand_all, S =:= N)
  (For gen_rand_list32, S >= N)
  r(a, b, c, d): do_recursion/4 function (of 4 w128() arguments)
  (The indexes are in C notation ([0 ... J-1] for J elements))
 
  a[0] = r(i[0], i[POS1],   i[N-2], i[N-1]);
  a[1] = r(i[1], i[POS1+1], i[N-1], a[0]);
  a[2] = r(i[2], i[POS1+2], a[0],   a[1]);
  ...
  a[(N-POS1)-1] = r(i[(N-POS1)-1], i[N-1], a[(N-POS1)-3], a[(N-POS1)-2]);
  a[(N-POS1)]   = r(i[(N-POS1)],   a[0],   a[(N-POS1)-2], a[(N-POS1)-1]);
  a[(N-POS1)+1] = r(i[(N-POS1)+1], a[1],   a[(N-POS1)-1], a[(N-POS1)]);
  ...
  a[N-1] = r(i[N-1], a[POS1-1], a[N-3], a[N-2]);
  % assignments from here only applicable to gen_rand_list32
  a[N]   = r(a[0],   a[POS1],   a[N-2], a[N-1]);
  a[N+1] = r(a[1],   a[POS1+1], a[N-1], a[N]);
  ...
  a[X]   = r(a[X-N], a[X-(N-POS1)], a[X-1], a[X-2]);
  ...
  a[S-1] = r(a[(S-N)-1], a[S-(N-POS1)-1], a[S-2], a[S-3]);

Use the last N w128() elements of a[] for the new internal state ni[], i.e.,

  ni[0] = a[S-N], ni[1] = a[S-N+1], ... ni[N-1] = a[S-1].
To avoid appending two lists, a and b of r(a, b, c, d) form ring buffers, e.g., Int and AccInt, IntP and AccIntP, of gen_rand_recursion/8. This makes the algorithm simpler and faster.

Data Types

intstate()

abstract datatype: intstate()

N-element list of 128-bit unsigned integers, represented as a four-element list of 32-bit integers. The number of N is 156. Each 128-bit number is represented in little endian, e.g., a 128-bit X = [X0, X1, X2, X3], where represented in programming language C:

  /* begin */
  union X {
  	uint32_t u[4];
  };
  /* end */
And the 128-bit list is a flat concatenation of 128-bit number lists,

ran_sfmt()

abstract datatype: ran_sfmt()

N-element list of 128-bit unsigned integers, represented as a list of 32-bit integers. The number of N is 156.

w128()

abstract datatype: w128()

Four-element list of 32-bit unsigned integers to represent a 128-bit integer.

Function Index

gen_rand32/1generates a 32-bit random number from the given ran_sfmt().
gen_rand_all/1filling the internal state array with SFMT PRNG.
gen_rand_list32/2generating the 32-bit integer list of PRNG, where length of the list is Size with the updated internal state.
get_idstring/0returns SFMT identification string.
get_min_array_size32/0returns array size of internal state.
init_by_list32/1generates an internal state from a list of 32-bit integers.
init_gen_rand/1generates an internal state from an integer seed.
seed/0Initialize the process dictionary with seed0/0, and return seed0/0 value.
seed/1Puts the seed computed from the given integer as a single-element list by init_by_list32/1 and puts the internal state into the process dictionary and initializes the random number list with the internal state and returns the old internal state.
seed/3Puts the seed computed from given three integers and puts the internal state into the process dictionary and initializes the random number list with the internal state and returns the old internal state.
seed0/0Returns the default internal state.
uint32_to_float/1Converts a 32-bit unsigned integer N to a float number X where 0.0 < X < 1.0; X = (N + 0.5) * (1.0/4294967296).
uniform/0Returns a uniformly-distributed float random number X where 0.0 < X < 1.0 and updates the internal state in the process dictionary.
uniform/1Returns a uniformly-distributed integer random number X where 1 =< X <= N and updates the internal state in the process dictionary.
uniform_s/1With a given state, Returns a uniformly-distributed float random number X where 0.0 < X < 1.0 and a new state.
uniform_s/2With a given state, Returns a uniformly-distributed integer random number X where 1 =< X <= N and a new state.

Function Details

gen_rand32/1

gen_rand32(L::intstate()) -> {integer(), ran_sfmt()}

generates a 32-bit random number from the given ran_sfmt().

gen_rand_all/1

gen_rand_all(Int::intstate()) -> intstate()

filling the internal state array with SFMT PRNG.

gen_rand_list32/2

gen_rand_list32(Size::integer(), Int::intstate()) -> {[integer()], intstate()}

generating the 32-bit integer list of PRNG, where length of the list is Size with the updated internal state.

get_idstring/0

get_idstring() -> string()

returns SFMT identification string.

get_min_array_size32/0

get_min_array_size32() -> integer()

returns array size of internal state.

init_by_list32/1

init_by_list32(Key::[integer()]) -> intstate()

generates an internal state from a list of 32-bit integers.

init_gen_rand/1

init_gen_rand(Seed::integer()) -> intstate()

generates an internal state from an integer seed.

seed/0

seed() -> ran_sfmt()

Initialize the process dictionary with seed0/0, and return seed0/0 value.

seed/1

seed(N::integer() | [integer()] | {integer(), integer(), integer()}) -> ran_sfmt()

Puts the seed computed from the given integer as a single-element list by init_by_list32/1 and puts the internal state into the process dictionary and initializes the random number list with the internal state and returns the old internal state.

seed/3

seed(A1::integer(), A2::integer(), A3::integer()) -> ran_sfmt()

Puts the seed computed from given three integers and puts the internal state into the process dictionary and initializes the random number list with the internal state and returns the old internal state.

seed0/0

seed0() -> ran_sfmt()

Returns the default internal state.

uint32_to_float/1

uint32_to_float(N::0..4294967295) -> float()

Converts a 32-bit unsigned integer N to a float number X where 0.0 < X < 1.0; X = (N + 0.5) * (1.0/4294967296).

uniform/0

uniform() -> float()

Returns a uniformly-distributed float random number X where 0.0 < X < 1.0 and updates the internal state in the process dictionary.

uniform/1

uniform(N::integer()) -> integer()

Returns a uniformly-distributed integer random number X where 1 =< X <= N and updates the internal state in the process dictionary. Note: the pigeonhole principle is applied to the output; this function will retry generating the base 32-bit unsigned integer number sequence if the result does not guarantee the equally-probabilistic results between the given range of integers.

uniform_s/1

uniform_s(RS::ran_sfmt()) -> {float(), ran_sfmt()}

With a given state, Returns a uniformly-distributed float random number X where 0.0 < X < 1.0 and a new state.

uniform_s/2

uniform_s(Max::integer(), RS::ran_sfmt()) -> {integer(), ran_sfmt()}

With a given state, Returns a uniformly-distributed integer random number X where 1 =< X <= N and a new state. Note: the pigeonhole principle is applied to the output; this function will retry generating the base 32-bit unsigned integer number sequence if the result does not guarantee the equally-probabilistic results between the given range of integers.


Generated by EDoc