Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

lcrans (3SUNMATH)

Name

lcrans - linear congruential pseudo-random number generators

Synopsis

cc [ flag ... ] file ...  -lsunmath -lm [ library ... ]
#include <sunmath.h>
int i_lcran_(void);
float r_lcran_(void);
double d_lcran_(void);
void i_lcrans_(int *x, int *n, int *l, int *u);
void  u_lcrans_(unsigned  *x,  int *n, unsigned *l, unsigned *u);
void r_lcrans_(float *x, int *n, float *l, float *u);
void d_lcrans_(double *x, int *n, double *l, double *u);
void i_get_lcrans_(int *x);
void i_set_lcrans_(int *x);
void i_init_lcrans_(void);

Description

These functions generate uniformly distributed random numbers of types int, unsigned int, float, or double. They share a common internal generator that produces a sequence of integers between 1 and LCRAN_MODULUS - 1 using the recurrence

 
next = (multiplier * last) % LCRAN_MODULUS

LCRAN_MODULUS is defined in <sunmath.h> and has the value 2**32 - 1. The multiplier depends on which function is called as described below.

i_lcran_() returns a random integer between 1 and LCRAN_MODULUS - 1 = 2**32 - 2. It always uses the value 16807 as a multiplier.

r_lcran_() returns a random single precision floating point number between 1 / LCRAN_MODULUS and 1. It always uses the value 16807 as a multiplier.

d_lcran_() returns a random double precision floating point number between 1 / LCRAN_MODULUS and 1 - (1 / LCRAN_MODULUS). It always uses the value 16807 as a multiplier.

i_lcrans_(n, x, l, u), u_lcrans_(n, x, l, u), r_lcrans_(n, x, l, u), and d_lcrans_(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]. These functions use the multiplier supplied in the most recent call to i_set_lcrans_; the default multiplier, which is also reset by i_init_lcrans_, is 16807.

i_get_lcrans_(x) sets x[0] to the last value produced by the internal generator and x[1] to the current multiplier used by i_lcrans_, u_lcrans_, r_lcrans_, and d_lcrans_.

i_set_lcrans_(x) sets the value used by the internal generator to compute the next random number (i.e., the value of last in the recurrence above) to x[0] and the mulitplier used by i_lcrans_, u_lcrans_, r_lcrans_, and d_lcrans_ to x[1]. The value of last should be between 1 and LCRAN_MODULUS - 1. Only the least significant 22 bits of the multiplier are used.

i_init_lcrans_() resets the value of last to 1 and the multiplier to 16807.

All of the functions listed above use the same internal generator. Consequently, calling i_lcran_ immediately after calling i_init_lcrans_ will give a different result than calling i_init_lcrans_, then u_lcrans_, then i_lcran_. Different threads within a program use different generators, 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_lcran_();

The same numbers can be generated more efficiently using:

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

lb = D_LCRAN_LB; /* defined in <sunmath.h> */
ub = D_LCRAN_UB; /* defined in <sunmath.h> */
d_lcrans_(x, &n, &lb, &ub);

To generate 1000 random integers between -10 and 10:

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

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

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe
Availability
system/library/math

See Also

addrans(3SUNMATH), drand48(3C), mwcrans(3SUNMATH), rand(3C), random(3C), shufrans(3SUNMATH), attributes(7)

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(3SUNMATH) generators are faster than either the lcrans(3SUNMATH) or the mwcrans(3SUNMATH) generators.