Base Generator APIs#
Initialization Functions#
randinitialize()#
-
void SRANDINITIALIZE(rng_int_t *genid, rng_int_t *subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void DRANDINITIALIZE(rng_int_t *genid, rng_int_t *subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitialize_(rng_int_t *genid, rng_int_t *subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitialize_(rng_int_t *genid, rng_int_t *subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitialize(rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitialize(rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
Initialize RNG supplied Base Random Number Generators (BRNG)
Note
If lstate = -1, or lseed = -1 then function returns without initialising the generator.
If both lstate = -1 and lseed = -1 then both are set to their before returning.
- Parameters:
genid – [in]
Generator ID
(1 <= genid <= 7)
1 = NAG Basic generator
2 = Wichmann-Hill generator
3 = Mersenne Twister generator
4 = L’Ecuyers Combined Recursive generator
5 = Blum-Blum Shub generator
6 = SIMD based Fast Mersenne Twister generator
7 = Sobol generatorsubid – [in]
Sub-generator ID
(if genid=2, 1 <= subid <= 273)
If genid = 2, then subid indicates which of the 273 independent generators to use.
Otherwise subid is not referenced.
seed – [in]
Seed vector
Vector holding the seeds/initial state of the generator, seed(lseed) If GENID ≠ 5, then SEED is a vector of initial values for the base generator.
These values must be positive integers. The number of values required depends on the base generator being used. The NAG basic generator requires one initial value, the Wichmann-Hill generator requires four initial values, the L’Ecuyer Combined Recursive Generator requires six initial values, the Mersenne Twister and SFMT requires 624 initial values.
If the number of seeds required by the chosen generator is > LSEED, then SEED(1) is used to initialize the NAG basic generator. This is then used to generate all of the remaining seed values required.
In general, it is best not to set all the elements of SEED to anything too obvious, such as a single repeated value or a simple sequence. Using such a seed array may lead to several similar values being created in a row when the generator is subsequently called. This is particularly true for the Mersenne Twister and SFMT generators.
If GENID=7, SEED is used as single element array which is used to provide dimension value. Sobol generator (QRNG) is using dimension value to generate multidimensional sequences.
In order to initialize the Blum-Blum-Shub generator (i.e. if GENID = 5), two large prime values, p and q are required, as well as an initial value s. As p, q and s can be of an arbitrary size, these values are expressed as a polynomial in B, where B = 224. For example, p can be factored into a polynomial of order lp, with p = p1 + p2B + p3B2 + · · · + pl Blp−1.
The elements of SEED should then be set to the following:
SEED(1) = lp
SEED(2) to SEED(lp + 1) = p1 to plp
SEED(lp + 2) = lq
SEED(lp + 3) to SEED(lp + lq + 2) = q1 to qlq
SEED(lp + lq + 3) = ls
SEED(lp + lq + 4) to SEED(lp + lq + ls + 3) = s1 to sls
Constraint: If GENID ≠ 5, then SEED(i) > 0, i = 1, 2, …
If GENID = 5 then, SEED must take the values described above.
lseed – [inout]
Length of the seed vector
Value of lseed is dependent on the generator being used.
If , then lseed is set to the value required by currently selected generator and the function returns.state – [out]
State vector
Vector that will define the generator and hold its current state, state(lstate).
lstate – [inout]
Length of the state vector
Value of lstate is dependent on the generator being used.
If , then lstate is set to the value required by the currently selected generator and the function returns.info – [out]
Error code
1 = Everything OK, but generator is not initialized (as lstate or lseed were -1)
0 = Everything OK
-1 to -5 = Error in parameter, abs(info)
Initialize Mersenne Twister with SecureRNG#
randinitialize_secrng()#
-
void drandinitialize_secrng(rng_int_t genid, rng_int_t subid, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
Initialize RNG supplied BRNG using hardware generated random seed values.
- Parameters:
genid – [in]
Generator ID
(genid = 3)
3 = Mersenne Twister generatorsubid – [in] Sub-generator ID, Not referenced
state – [out]
State vector
Vector that will define the generator and hold its current state, state(lstate).
lstate – [inout]
Length of the state vector
Value of lstate is dependent on the generator being used.
If lstate = -1, then lstate is set to the value required by the currently selected generator and the function returns.info – [out]
Error code
1 = Everything OK, but generator not initialized (as lstate were -1)
2 = Non supported OS
0 = Everything OK
-1 to -5 = Error in parameter, abs(info)
User’s own Base Generator Hooks#
randinitializeuser()#
-
void SRANDINITIALIZEUSER(RNG_SRANDINITIALIZEUSER_UINI uini, RNG_SRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void DRANDINITIALIZEUSER(RNG_DRANDINITIALIZEUSER_UINI uini, RNG_DRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitializeuser_(RNG_SRANDINITIALIZEUSER_UINI uini, RNG_SRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitializeuser_(RNG_DRANDINITIALIZEUSER_UINI uini, RNG_DRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitializeuser(RNG_SRANDINITIALIZEUSER_UINI uini, RNG_SRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitializeuser(RNG_DRANDINITIALIZEUSER_UINI uini, RNG_DRANDINITIALIZEUSER_UGEN ugen, rng_int_t genid, rng_int_t subid, rng_int_t *seed, rng_int_t *lseed, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
typedef void (*RNG_DRANDINITIALIZEUSER_UINI)(rng_int_t*, rng_int_t*, rng_int_t*, rng_int_t*, rng_int_t*, rng_int_t*, rng_int_t*)#
-
typedef void (*RNG_DRANDINITIALIZEUSER_UGEN)(rng_int_t*, rng_int_t*, double*, rng_int_t*)#
Blum-Blum-Shub Generator Functions#
randinitializebbs()#
-
void SRANDINITIALIZEBBS(rng_int_t *nbits, rng_int_t *lp, rng_int_t *p, rng_int_t *lq, rng_int_t *q, rng_int_t *ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void DRANDINITIALIZEBBS(rng_int_t *nbits, rng_int_t *lp, rng_int_t *p, rng_int_t *lq, rng_int_t *q, rng_int_t *ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitializebbs_(rng_int_t *nbits, rng_int_t *lp, rng_int_t *p, rng_int_t *lq, rng_int_t *q, rng_int_t *ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitializebbs_(rng_int_t *nbits, rng_int_t *lp, rng_int_t *p, rng_int_t *lq, rng_int_t *q, rng_int_t *ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void srandinitializebbs(rng_int_t nbits, rng_int_t lp, rng_int_t *p, rng_int_t lq, rng_int_t *q, rng_int_t ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
-
void drandinitializebbs(rng_int_t nbits, rng_int_t lp, rng_int_t *p, rng_int_t lq, rng_int_t *q, rng_int_t ls, rng_int_t *s, rng_int_t *state, rng_int_t *lstate, rng_int_t *info)#
Alternative initialisation routine for the Blum-Blum-Shub generator.
- Parameters:
nbits – [in]
The number of bits to use from each iteration
if
nbits < 1, then nbits = 1,
if
nbits > 15, then nbits = 15 (i.e. between 1 and 15 bits can be used)lp – [in] The number of digits in the first prime p, lp <= 25
p – [in]
The first prime value
This integer is stored in an array.
Each element of the array is a digit, and the integer is stored
base B2, where B2 = 2**30, i.e.
p = p(1) + p(2)*B2 + p(3)*B2**2 + … + p(lp)*B2**(lp-1), p(lp).
p mod 4 = 3
lq – [in] The number of digits in the second prime q, lq <= 25
q – [in]
The first prime value
This integer is stored in an array.
Each element of the array is a digit, and the integer is stored
base B2, where B2 = 2**30, i.e.
q = p(1) + q(2)*B2 + q(3)*B2**2 + … + q(lq)*B2**(lq-1), q(lq).
q mod 4 = 3
ls – [in] The number of digits in the initial state s, ls <= 25
s – [in]
The first prime value
This integer is stored in an array.
Each element of the array is a digit, and the integer is stored
base B2, where B2 = 2**30, i.e.
s = s(1) + s(2)*B2 + s(3)*B2**2 + … + s(lp)*B2**(ls-1), s(ls).state – [out]
Array holding information about the generator:
1 = Amount of state used = 310
2 = ‘Magic’ number = 5010
3 = GENID
4 = SUBID (the number of bits to use)
5 = PN, the location in state of N
6 = PX, the location in state of X
PX = LX, the number of digits of X
PX+1 to PX+LX = The digits of X
PN+1 to PN+LN = The digits of N
310 = ‘Magic’ number = 5010lstate – [inout] Length of array state, lstate >= If lstate < 1, then lstate is set to 310 and the function returns.
info – [out]
Error code
1 = Everything OK, but generator not initialized (returned when values of LSEED or lstate given)
0 = Everything OK
-1 to -8 = Error in parameter, abs(info).
randblumblumshub()#
-
void SRANDBLUMBLUMSHUB(rng_int_t *n, rng_int_t *state, float *x, rng_int_t *info)#
-
void DRANDBLUMBLUMSHUB(rng_int_t *n, rng_int_t *state, double *x, rng_int_t *info)#
-
void srandblumblumshub_(rng_int_t *n, rng_int_t *state, float *x, rng_int_t *info)#
-
void drandblumblumshub_(rng_int_t *n, rng_int_t *state, double *x, rng_int_t *info)#
-
void srandblumblumshub(rng_int_t n, rng_int_t *state, float *x, rng_int_t *info)#
-
void drandblumblumshub(rng_int_t n, rng_int_t *state, double *x, rng_int_t *info)#
Alternative interface to Blum-Blum-Shub generator.
- Parameters:
n – [in] Number of values to generate, n >= 0
state – [inout]
On Entry: State of generator before values are generated
On Exit : State of generator after values have been generated
x – [out]
Vector of values, x(n)
The least-significant 30-bits of
x are generated via BBS generator.info – [out]
Error code
0 = Everything OK
-1 to -2 = Error in parameter, abs(info).