easy_rng.h File Reference

The random number generator API. More...

Data Structures
struct	easy_rng_type

Typedefs
typedef struct _easy_rng	easy_rng

Functions
easy_rng *	easy_rng_alloc (const easy_rng_type *T)
void	easy_rng_set (const easy_rng *r, unsigned long int s)
void	easy_rng_free (easy_rng *r)
unsigned long int	easy_rng_get (const easy_rng *r)
double	easy_rng_uniform (const easy_rng *r)
double	easy_rng_uniform_pos (const easy_rng *r)
unsigned long int	easy_rng_uniform_int (const easy_rng *r, unsigned long int n)
const char *	easy_rng_name (const easy_rng *r)
unsigned long int	easy_rng_max (const easy_rng *r)
unsigned long int	easy_rng_min (const easy_rng *r)
const easy_rng_type **	easy_rng_types_setup (void)
const easy_rng_type *	easy_rng_env_setup (void)
int	easy_rng_memcpy (easy_rng *dest, const easy_rng *src)
easy_rng *	easy_rng_clone (const easy_rng *r)
int	easy_rng_equal (const easy_rng *ra, const easy_rng *rb)
int	easy_rng_fwrite (FILE *stream, const easy_rng *r)
int	easy_rng_fread (FILE *stream, easy_rng *r)

Variables
const easy_rng_type *	easy_rng_minstd_rand0
const easy_rng_type *	easy_rng_minstd_rand
const easy_rng_type *	easy_rng_mt19937
const easy_rng_type *	easy_rng_mt19937_64
const easy_rng_type *	easy_rng_ranlux24_base
const easy_rng_type *	easy_rng_ranlux48_base
const easy_rng_type *	easy_rng_ranlux24
const easy_rng_type *	easy_rng_ranlux48
const easy_rng_type *	easy_rng_knuth_b
const easy_rng_type *	easy_rng_default
unsigned long int	easy_rng_default_seed

Detailed Description

The random number generator API.

Author

Tom Schoonjans

This header contains all functions and definitions that are necessary to instantiate a random number generator, as well as to obtain uniformly distributed random numbers. The API is strongly modelled after the GNU Scientific Library's gsl_rng.h header, with some notable exceptions:

• easy_rng_state() and easy_rng_size() are not implemented as the required information is not accessible in the C++11 templates
• easy_rng_equal() has been added to compare two random number generators for equality
• easy_rng_fwrite and easy_rng_fread write a string (ASCII) representation of the state to file, instead of a binary stream.
• Only 9 types of random number generators are offered here, in accordance with the C++11 standard. The GNU Scientific library offers dozens more. It should be noted though that the GNU Scientific library does not have the 64-bit implementation of the Mersenne-Twister (easy_rng_mt19937_64)

Note

the description of the different types of random number generators on this page was sourced from cppreference.com. Please consult this website for more information.

---

Data Structure Documentation

easy_rng_type

struct easy_rng_type

A struct whose instances represent the different types of random number generators that are offered by easyRNG

There is never a need to instantiate this class yourself. Instead use the global variables to pass to easy_rng_alloc() when constructing a random number generator.

Data Fields
const char *	name	The name of the random number generate type, as a string.
unsigned long int	max	The maximum value that can be generated by this type.
unsigned long int	min	The minimum value that can be generated by this type.

Typedef Documentation

easy_rng

typedef struct _easy_rng easy_rng

A random number generator instance

Pointers to these instances are returned by easy_rng_alloc() and should be freed with easy_rng_free(). Its contents are intentionally not accessible.

Function Documentation

easy_rng_alloc()

easy_rng* easy_rng_alloc

(

const easy_rng_type *

T

)

Create a new random number generator instance

Parameters

T	The type of a random number generator to use

Returns

A newly allocated random number generator that has been seeded with the default seed.

easy_rng_set()

void easy_rng_set	(	const easy_rng *	r,
		unsigned long int	s
	)

Set the current seed.

Changes the current seed of the random number generator to s. This will change the generated sequence from this point onwards.

Parameters

r	The random number generator instance
s	The new seed

easy_rng_free()

void easy_rng_free

(

easy_rng *

r

)

Frees the memory associated with a random number generator instance

After calling this function, do not attempt to pass the random number generator instance to any other function!

Parameters

r	The random number generator instance

easy_rng_get()

unsigned long int easy_rng_get

(

const easy_rng *

r

)

Generate a random, uniformally distributed unsigned long int.

This value will be within the interval defined by easy_rng_min() and easy_rng_max().

Parameters

r	The random number generator instance

Returns

A unsigned long int

easy_rng_uniform()

double easy_rng_uniform

(

const easy_rng *

r

)

Generate a random, uniformally distributed double precision floating point number in the interval [0,1)

This interval includes 0, but excludes 1

Parameters

r	The random number generator instance

Returns

A double precision floating point number between 0 and 1

easy_rng_uniform_pos()

double easy_rng_uniform_pos

(

const easy_rng *

r

)

Generate a random, uniformally distributed double precision floating point number in the interval (0,1)

This interval excludes both 0 and 1

Parameters

r	The random number generator instance

Returns

A double precision floating point number between 0 and 1

easy_rng_uniform_int()

unsigned long int easy_rng_uniform_int	(	const easy_rng *	r,
		unsigned long int	n
	)

Generate a random, uniformally distributed unsigned long int in the interval [0, n)

This interval includes 0, but excluded n, so the highest possibly generated value is n-1

Parameters

r	The random number generator instance
n	The upper limit (exclusive) of the generated values

Returns

An unsigned long int between 0 and n-1

easy_rng_name()

const char* easy_rng_name

(

const easy_rng *

r

)

Return the name of the random generator type as string

Do not attempt to free the string!

Parameters

r	The random number generator instance

Returns

The name of the random generator type

easy_rng_max()

unsigned long int easy_rng_max

(

const easy_rng *

r

)

Return the maximum value that can be returned by easy_rng_get()

This value depends on the random number generator type that was used to initialize the random number generator instance with easy_rng_alloc().

Parameters

r	The random number generator instance

Returns

The maximum value that can be returned by easy_rng_get()

easy_rng_min()

unsigned long int easy_rng_min

(

const easy_rng *

r

)

Return the minimum value that can be returned by easy_rng_get()

This value depends on the random number generator type that was used to initialize the random number generator instance with easy_rng_alloc().

Parameters

r	The random number generator instance

Returns

The minimum value that can be returned by easy_rng_get()

easy_rng_types_setup()

const easy_rng_type** easy_rng_types_setup

(

void

)

Return a NULL terminated array with all available random number generator types

This array must not be freed!

Returns

the array

easy_rng_env_setup()

const easy_rng_type* easy_rng_env_setup

(

void

)

Set the default seed and/or default random number generator type

This method parses the environment variables EASY_RNG_TYPE and EASY_RNG_SEED to extract resp. the random number generator type and seed that will be used when using easy_rng_alloc() with easy_rng_default to instantiate and seed a new random number generator.

Returns

easy_rng_default

easy_rng_memcpy()

int easy_rng_memcpy	(	easy_rng *	dest,
		const easy_rng *	src
	)

Copy the state of a random number generator src into another random number generator dest

Afterwards, src and dest will produce identical sequences of random numbers. dest must have been allocated with the exact same random number generator src!

Parameters

dest	The destination random number generator
src	The source random number generator

Returns

0 on success, -1 on failure

easy_rng_clone()

easy_rng* easy_rng_clone

(

const easy_rng *

r

)

Creates an exact copy of the random number generator c.

c and its freshly created clone will produce identical sequences of random numbers from now onwards. Free the clone using easy_rng_free().

Parameters

r	The random number generator instance

Returns

The cloned random number generator

easy_rng_equal()

int easy_rng_equal	(	const easy_rng *	ra,
		const easy_rng *	rb
	)

Test if two random number generator instances are identical

This test will verify both type and state for equality.

Parameters

ra	The first random number generator instance
rb	The second random number generator instance

Returns

1 if equal, 0 otherwise

easy_rng_fwrite()

int easy_rng_fwrite	(	FILE *	stream,
		const easy_rng *	r
	)

Write the state of the random number generator to a file

This writes only the state, not the type of the generator!

Parameters

stream	Filehandle to write the state to
r	The random number generator instance

Returns

0 on success, -1 otherwise

easy_rng_fread()

int easy_rng_fread	(	FILE *	stream,
		easy_rng *	r
	)

Read the state of the random number generator from a file

This reads only the state, not the type of the generator!

Parameters

stream	Filehandle to read the state from
r	The random number generator instance

Returns

0 on success, -1 otherwise

Variable Documentation

easy_rng_minstd_rand0

const easy_rng_type* easy_rng_minstd_rand0

Linear congruential engine, discovered in 1969 by Lewis, Goodman and Miller, adopted as "Minimal standard" in 1988 by Park and Miller

easy_rng_minstd_rand

const easy_rng_type* easy_rng_minstd_rand

Linear congruential engine, newer "Minimum standard", recommended by Park, Miller, and Stockmeyer in 1993

easy_rng_mt19937

const easy_rng_type* easy_rng_mt19937

32-bit Mersenne Twister engine, published by Matsumoto and Nishimura, 1998

This is also the type that easy_rng_default maps to, unless overridden by EASY_RNG_TYPE and easy_rng_env_setup() is called. In case of doubt, always use this type.

easy_rng_mt19937_64

const easy_rng_type* easy_rng_mt19937_64

64-bit Mersenne Twister engine, published by Matsumoto and Nishimura, 2000

easy_rng_ranlux24_base

const easy_rng_type* easy_rng_ranlux24_base

A subtract with carry engine

easy_rng_ranlux48_base

const easy_rng_type* easy_rng_ranlux48_base

A subtract with carry engine

easy_rng_ranlux24

const easy_rng_type* easy_rng_ranlux24

A subtract with carry engine, that discards a certain amount of data produced by the base engine.

easy_rng_ranlux48

const easy_rng_type* easy_rng_ranlux48

A subtract with carry engine, that discards a certain amount of data produced by the base engine.

easy_rng_knuth_b

const easy_rng_type* easy_rng_knuth_b

A shuffle order engine

easy_rng_default

const easy_rng_type* easy_rng_default

The default random number generator type

Maps by default to easy_rng_mt19937

easy_rng_default_seed

unsigned long int easy_rng_default_seed

The seed that will be used to initialize newly allocated random number generators