addrans(3M)

Name

addrans - additive pseudo-random number generators

Synopsis

cc [ flag ... ] file ...  -lsunmath -lm [ library ... ]

#include <sunmath.h>

int i_addran_(void);

float r_addran_(void);

double d_addran_(void);

void i_addrans_(int *x, int *n, int *l, int *u);

void  u_addrans_(unsigned  *x, int *n, unsigned *l, unsigned *u);

void r_addrans_(float *x, int *n, float *l, float *u);

void d_addrans_(double *x, int *n, double *l, double *u);

void i_get_addrans_(int *x);

void r_get_addrans_(float *x);

void d_get_addrans_(double *x);

void i_set_addrans_(int *x);

void r_set_addrans_(float *x);

void d_set_addrans_(double *x);

void i_init_addrans_(void);

void r_init_addrans_(void);

void d_init_addrans_(void);

Description

These functions generate uniformly distributed random numbers of types int, unsigned int, float, or double. Each function generates the next random number in sequence using a recurrence of the form

 
next = table[i] - table[(i - 24) % ADDRAN_SIZE];
table[i] = next;
i = (i + 1) % ADDRAN_SIZE;

Internally, these functions maintain three separate tables of ADDRAN_SIZE elements for each thread in a program. ADDRAN_SIZE is defined in <sunmath.h>.

i_addran_() returns a random 32-bit integer. Successive numbers are computed in 32-bit integer arithmetic (i.e., modulo 2**32) and thus lie in the range -2147483648, ..., 2147483647.

r_addran_() returns a random single precision floating point number between 0 and 1 - 2**-24. Successive numbers are kept in this range by adding 1 when necessary.

d_addran_() returns a random double precision floating point number between 0 and 1 - 2**-53. Successive numbers are kept in this range by adding 1 when necessary.

i_addrans_(n, x, l, u), u_addrans_(n, x, l, u), r_addrans_(n, x, l, u), and d_addrans_(n, x, l, u) each fill the array elements x[0], ..., x[*n-1] with random 32-bit signed integers, 32-bit unsigned integers, single precision floating point numbers and double precision floating point numbers, respectively. The numbers are scaled and offset so as to be uniformly distributed over the interval [*l, *u].

i_get_addrans_(x) fills x[0], ..., x[ADDRAN_SIZE-1] with the current values of the table used by i_addran_. i_set_addrans_(x) fills this table with the values x[0], ..., x[ADDRAN_SIZE-1]. i_init_addrans_() resets this table to its initial state.

r_get_addrans_(x) fills x[0], ..., x[ADDRAN_SIZE-1] with the current values of the table used by r_addran_. r_set_addrans_(x) fills this table with the values x[0], ..., x[ADDRAN_SIZE-1]. r_init_addrans_() resets this table to its initial state.

d_get_addrans_(x) fills x[0], ..., x[ADDRAN_SIZE-1] with the current values of the table used by d_addran_. d_set_addrans_(x) fills this table with the values x[0], ..., x[ADDRAN_SIZE-1]. d_init_addrans_() resets this table to its initial state.

i_addrans_ and u_addrans_ use the same table as i_addran_. r_addrans_ uses the same table as r_addran_. d_addrans_ uses the same table as d_addran_. So, for example, calling i_addran_ immediately after calling i_init_addrans_ will give a different result than calling i_init_addrans_, then u_addrans_, then i_addran_. Different threads within a program use different tables, however, so calling one of these functions in one thread will not affect the values delivered when the same function is called from another thread.

Examples

To generate 1000 random double precision numbers in [0,1):

 
double x[1000];
int i;

for (i = 0; i < 1000; i++)
    x[i] = d_addran_();

The same numbers can be generated more efficiently using:

 
double x[1000], lb, ub;
int n = 1000;

lb = D_ADDRAN_LB; /* defined in <sunmath.h> */
ub = D_ADDRAN_UB; /* defined in <sunmath.h> */
d_addrans_(x, &n, &lb, &ub);

To generate 1000 random integers between -10 and 10:

int x[1000], n = 1000, lb = -10, ub = 10;
i_addrans_(x, &n, &lb, &ub);

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE Interface Stability Committed MT-Level MT-Safe

See Also

drand48(3C), lcrans(3M), mwcrans(3M), rand(3C), random(3C), shufrans(3M), attributes(5)

Knuth, Seminumerical Algorithms, 1981, Addison-Wesley.

Park and Miller, Random Number Generators: Good Ones are Hard to Find, Communications of the ACM, October 1988.

Notes

Typically, the addrans(3M) generators are faster than either the lcrans(3M) or the mwcrans(3M) generators.