A pseudorandom number generator with good statistical properties. More...

#include "randomWH.h"

Functions
void	Congruence_init (Congruence *self, long int x, long int y, long int z, long int t)
	Initialise the generator with four values of type `long` `int`. More...

void	randomWH_error (const char *message)
	A very basic error handling function. More...

long int *	Congruence_read (Congruence *self)
	Read the current state of the pseudo-random number generator. More...

double	randomWH_null (Congruence *self)
	Generate an error message and triggers a program exit if the calling struct has not been initialised properly. More...

double	randomWH_32 (Congruence *self)
	Generate a (pseudo-)random number drawn from the U(0,1) distribution using the 32-bit W-H algorithm . More...

double	randomWH_64 (Congruence *self)
	Generate a (pseudo-)random number drawn from the U(0,1) distribution using the 64-bit W-H algorithm . More...

long int	randomWH_geometric (Congruence *self, double prob)
	Generate a geometrically distributed random variate. More...

enum BOOLEAN	randomWH_bernoulli (Congruence *self, double prob)
	Generate a Bernoulli random variate. More...

long int	randomWH_binomial (Congruence *self, long int trials, double prob)
	Generate a binomially distributed random variate. More...

long int	randomWH_fairdie (Congruence *self, long int lower_inclusive, long int upper_inclusive)
	Generate a discrete-valued uniformly distributed random variate drawn from a specified range. More...

Variables
Congruence	congruent

Detailed Description

A pseudorandom number generator with good statistical properties.

Author: Martin Collier

Date: 11 February 2014

See Also: http://www.sciencedirect.com/science/article/pii/S0167947306001836?np=y; http://www.viva64.com/en/a/0004/

Version: 0.3 Alpha

Details

This implements the algorithm described by Wichmann and Hill in

B.A. Wichmann and I.D. Hill, "Generating good pseudo-random numbers", Computational Statistics & Data Analysis, vol. 51, no. 3., pp. 1614-1622, Dec. 2006.

Two implementations are provided. One is for compilers that use 32 bits to store variables of the long int type. A faster algorithm is also provided for use with compilers that feature a 64-bit long int type. The algorithm to be used is determined automatically at run time.

Definition in file randomWH.c.

Function Documentation

void Congruence_init	(	Congruence *	self,
		long int	x,
		long int	y,
		long int	z,
		long int	t
	)

Initialise the generator with four values of type long int.

We need to populate the congruent structure with seed values before calling randomWH(). This function isolates the initialisation from the implementation.

Usage

see Congruence.init()

 #include "randomWH.h"
.
.
.
     Congruence_init(&congruent,1L,2L,3L,4L);

Parameters

x	The seed for the first generator
y	The seed for the second generator
z	The seed for the third generator
t	The seed for the fourth generator
self	A pointer to the calling `struct` (required since C does not support the this keyword).

Note: Initialising the generator with the same seeds from program run to program run will produce exactly the same sequence . Usually in simulation programs (particularly when testing and debugging them), this is exactly what you want.

Warning: Private function. Do not call it directly.

Definition at line 52 of file randomWH.c.

long int* Congruence_read ( Congruence * self)

Read the current state of the pseudo-random number generator.

Usage

see Congruence.read()

 #include <stdio.h>
 #include "randomWH.h"
.
.
.
        long int* read_con;
        int count;
        read_con=Congruence_read(&congruent);
        for(count=0;count<4;count++)
            printf("%ld\n", read_con[count]);

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).

Returns: A pointer to an array of four long int values .

See Also: Congruence_init()

Note: This function can be used immediately prior to program shutdown to read the current seed values prior to saving them in persistent storage. Loading these values from persistent storage during program initialisation and using them as the arguments in a call to Congruence_init() will allow execution to resume exactly as if the previous program run had continued.

Warning: Only four values are returned. Do not use an index greater than 3 to access the array.; Private function. Do not call it directly.

Definition at line 125 of file randomWH.c.

double randomWH_32 ( Congruence * self)

Generate a (pseudo-)random number drawn from the U(0,1) distribution using the 32-bit W-H algorithm .

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).

Returns: a double value drawn (to a good approximation) from a uniform distribution in the range [0,1]

See Also: Congruence_init(); Congruence_read(); http://www.sciencedirect.com/science/article/pii/S0167947306001836?np=y

Warning: Never call this function directly as it requires struct initialisation before use. No test is made for correct initialisation here in the interest of performance. Bad things will happen if you bypass initialisation.

Definition at line 161 of file randomWH.c.

double randomWH_64 ( Congruence * self)

Generate a (pseudo-)random number drawn from the U(0,1) distribution using the 64-bit W-H algorithm .

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).

Returns: a double value drawn (to a good approximation) from a uniform distribution in the range [0,1]

See Also: Congruence_init(); Congruence_read(); http://www.sciencedirect.com/science/article/pii/S0167947306001836?np=y

Warning: Never call this function directly as it requires struct initialisation before use. No test is made for correct initialisation here in the interest of performance. Bad things will happen if you bypass initialisation.

Definition at line 198 of file randomWH.c.

enum BOOLEAN randomWH_bernoulli	(	Congruence *	self,
		double	prob
	)

Generate a Bernoulli random variate.

Usage

see Congruence.bernoulli()

 #include <stdio.h>
 #include "randomWH.h"
 Congruence generatorX={
   .x=0,
   .y=0,
   .z=0,
   .t=0,
   .initialised=isfalse,
   .init=Congruence_init,
   .randomWH=randomWH_null,
   .read=Congruence_read,
   .bernoulli=randomWH_bernoulli,
   .geometric=randomWH_geometric,
   .binomial=randomWH_binomial,
   .fairdie=randomWH_fairdie,
};
.
.
.
    if (generatorX.bernoulli(&generatorX,0.5)
         printf("Heads!\n");
     else
         printf("Tails!\n");

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).
prob	The probability of success

Returns: a BOOLEAN variable indicating an outcome of success or failure

Definition at line 268 of file randomWH.c.

long int randomWH_binomial	(	Congruence *	self,
		long int	trials,
		double	prob
	)

Generate a binomially distributed random variate.

Usage

see Congruence.binomial()

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).
prob	The probability of success in each trial
trials	The number of trials

Definition at line 288 of file randomWH.c.

void randomWH_error ( const char * message)

A very basic error handling function.

This just prints an error message to stderr and then exits.

Usage

 #include "randomWH.h"
.
.
.
        randomWH_error("A pertinent error message");

Parameters

message A byte string containing a message about the error.

Returns: The function never returns. The program is exited with status EXIT_FAILURE.

Definition at line 90 of file randomWH.c.

long int randomWH_fairdie	(	Congruence *	self,
		long int	lower_inclusive,
		long int	upper_inclusive
	)

Generate a discrete-valued uniformly distributed random variate drawn from a specified range.

Usage

see Congruence.fairdie()

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).
lower_inclusive	the lowest value of variate that can be returned
upper_inclusive	the highest value of variate that can be returned

Definition at line 307 of file randomWH.c.

long int randomWH_geometric	(	Congruence *	self,
		double	prob
	)

Generate a geometrically distributed random variate.

Usage

see Congruence.geometric()

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).
prob	The probability of success in each trial

Definition at line 223 of file randomWH.c.

double randomWH_null ( Congruence * self)

Generate an error message and triggers a program exit if the calling struct has not been initialised properly.

This simulates exception handling for the exception "you forgot to read the documentation".

Parameters

self	A pointer to the calling `struct` (required since C does not support the this keyword).

Returns: nothing - the program will exit, returning EXIT_FAILURE.

See Also: Congruence_init(); Congruence_read()

Definition at line 141 of file randomWH.c.

Variable Documentation

Congruence congruent

Initial value:

={
    .x=0,
    .y=0,
    .z=0,
    .t=0,
    .initialised=isfalse,
    .init=Congruence_init,
    .randomWH=randomWH_null,
    .read=Congruence_read,
    .bernoulli=randomWH_bernoulli,
    .geometric=randomWH_geometric,
    .binomial=randomWH_binomial,
    .fairdie=randomWH_fairdie,
}

The initialised congruent struct -

See Also: congruent

Definition at line 12 of file randomWH.c.

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation