addrans(3M)

NAME
addrans - additive pseudo-random number generators

SYNOPSIS

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

#include <sunmath.h>

#define ADDRAN_SIZE 55

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 provide uniform random variates, of types integer or unsigned, single-precision floating-point, or double-precision floating-point.

Additive variates are generated one at a time by ..._addran_() using the recurrence
	addran_last = addran_table[i] - addran_table[(i-24) % ADDRAN_SIZE] ;
	addran_table[i] = addran_last;
	i = (i+1) % ADDRAN_SIZE ;
	return addran_last;
addran_table is a table containing ADDRAN_SIZE elements of type unsigned, float, or double. The variates are constrained to the following intervals (see table below) by adding, when necessary, 4294967296 for integer and unsigned, and 1.0 for float and double.
type | lower bound |  | upper bound
 | name | value | name | value
unsigned | U_ADDRAN_LB | 0 | U_ADDRAN_UB | 4294967295
integer | I_ADDRAN_LB | -2147483648 | I_ADDRAN_UB | 2147483647
float | R_ADDRAN_LB | 0 | R_ADDRAN_UB | 0.9999999403953552246
double | D_ADDRAN_LB | 0 | D_ADDRAN_UB | 0.9999999999999998890
Thus any representable 32-bit integer or unsigned is an equally likely result from i_addran_(); furthermore it hardly matters that "additive" methods are implemented by subtraction for efficiency.

Additive variates are generated *n at a time by ..._addrans_() using the recurrence
	addran_last = addran_table_[i] - addran_table_[(i-24) % ADDRAN_SIZE] ;
	addran_table[i] = addran_last;
	i = (i+1) % ADDRAN_SIZE ;
	return scale * (addran_last + offset)
where scale and offset are calculated from *l and *u so that the computed variates are uniform in [*l,*u]. u_addrans_() is available so that large unsigned bounds can be specified. u_addrans_() uses the same addran_table as i_addrans_().

The state of the additive generator, an array of ADDRAN_SIZE, may be obtained with ...get_addrans_() and set with ...set_addrans_(), or restored to the initial state with ...init_addrans_().

EXAMPLES

  to generate 1000 double-precision random variates in [0,1)

    double x[1000] ; int i, n = 1000 ; double lb = D_ADDRAN_LB, ub = D_ADDRAN_UB ;
    for (i=0;i<n;i++) x[i] = d_addran_(); /* or... */
    d_addrans_(x, &n, &lb, &ub) ;	/* same output, but more efficient */

  to generate 1000 integer random variates in [-10,+10]

    int x[1000] ; int n = 1000, lb = -10, ub = 10 ;

    i_addrans_(x, &n, &lb, &ub) ;

SEE ALSO
drand48(3), lcrans(3M), rand(3C), rand(3V), random(3), shufrans(3M).

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

The number of times your program calls a random number generator function determines when it is more efficient (faster) to use lcrans(3M) versus addrans(3M). For normal use (more than 50 calls), use addrans(3M), possibly in conjunction with shufrans(3M), rather than calls to lcrans(3M), drand48(3), rand(3C), rand(3V) and random(3). For casual use (less than 50 calls), use lcrans(3M) rather than addrans(3M). The reason for this is that the first call to addrans(3M) has the overhead cost of initializing a table of 55 elements (defined by ADDRAN_SIZE).