'\" t
.\" @(#)lcrans.3m 1.18 98/02/04 SMI; 
.TH lcrans 3M "1 Sep 1993"
.SH NAME
lcrans \- linear congruential pseudo-random number generators
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lsunmath -lm
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.B #include <sunmath.h>
.LP
.B #define LCRAN_MULTIPLIER 16807
.LP
.B #define LCRAN_MODULUS 2147483647L
.LP
.B int i_lcran_(void);
.LP
.B float r_lcran_(void);
.LP
.B double d_lcran_(void);
.LP
.BI "void i_lcrans_(int *" "x" ,
.BI "int *" "n" ,
.BI "int *" "l" ,
.BI "int *" "u" );
.LP
.BI "void u_lcrans_(unsigned *" "x" ,
.BI "int *" "n" ,
.BI "unsigned *" "l" ,
.BI "unsigned *" "u" );
.LP
.BI "void r_lcrans_(float *" "x" ,
.BI "int *" "n" ,
.BI "float *" "l" ,
.BI "float *" "u" );
.LP
.BI "void d_lcrans_(double *" "x" ,
.BI "int *" "n" ,
.BI "double *" "l" ,
.BI "double *" "u" );
.LP
.BI "void i_get_lcrans_(int *" "x" );
.LP
.BI "void i_set_lcrans_(int *" "x" );
.LP
.B void i_init_lcrans_(void);
.SH DESCRIPTION
.\".IX "_1st_index_term_" "_2nd_index_term_" "_format_of_1st_" "_format_of_2nd_"
.LP
These functions provide uniform random variates, of types integer,
single-precision floating-point, or double-precision floating-point.
.LP
Linear congruential variates are generated one at a time by
.B ..._lcran_(\|)
using the recurrence 
.ft I
.nf

	lcran_last = (LCRAN_MULTIPLIER * lcran_last) % LCRAN_MODULUS

.fi
.ft R
.B i_lcran_(\|)
returns
.IR lcran_last ,
while
.B r_lcran_(\|)
and
.B d_lcran_(\|)
return
.IR "lcran_last / LCRAN_MODULUS" ,
so that the variates are contained in the following intervals:

.ne 7
.TS
center;
l | l r | l r.
type	lower bound		upper bound
	name	value	name	value
_
integer	I_LCRAN_LB	1	I_LCRAN_UB	2147483646
float	R_LCRAN_LB	4.656612873077392578E-10	R_LCRAN_UB	1
double	D_LCRAN_LB	4.656612875245796923E-10	D_LCRAN_UB	0.9999999995343387127
.TE

.I lcran_last
should satisfy 1 <=
.I lcran_last
<= 2147483646, but for efficiency
.B ..._lcran_(\|)
does not check that.
.LP
Linear congruential variates are generated
.I *n
at a time by
.B ..._lcrans_(\|)
using the recurrence
.ft I
.nf

	lcran_last = (lcran_multiplier * lcran_last) % LCRAN_MODULUS ; 
	return scale * (lcran_last + offset) ; 

.fi
.ft R
where
.I scale
and
.I offset
are calculated from
.I *l
and
.I *u
so that the computed
variates are uniform in
.RI [ *l , *u ].
Thus changing
.I lcran_multiplier
changes the variates produced by
.BR ..._lcrans_(\|) ,
but for efficiency
.B ..._lcran_(\|)
uses the fixed
.BR LCRAN_MULTIPLIER ,
16807.
The fixed modulus
.BR LCRAN_MODULUS ,
2147483647L, is intentionally not
a power of two to avoid the defects in
.BR rand (3C).
On entry,
.B ..._lcrans_(\|)
does check that 1 <=
.I lcran_last
<= 2147483646
and modifies
.I lcran_last
if necessary.
.LP
The state of the linear congruential generator (an array of two ints
containing
.I lcran_last
and
.IR lcran_multiplier )
may be obtained with
.B i_get_lcrans_(\|)
and set with
.BR i_set_lcrans_(\|) .
The initial state may be restored with
.BR i_init_lcrans_(\|) .
.SH EXAMPLES
.SS to\0generate\01000\0double-precision\0random variates in (0,1)
.LP
.RS
.ft B
.nf
double x[1000] ; int i, n = 1000 ;
double lb = D_LCRAN_LB, ub = D_LCRAN_UB ; 

for (i=0;i<n;i++) x[i] = d_lcran_();	/* or... */

d_lcrans_(x, &n, &lb, &ub) ;	/* same output, but more efficient */
.fi
.ft
.RE
.SS to\0generate\01000\0integer\0random\0variates in [-10,+10]
.LP
.RS
.ft B
.nf 
int x[1000] ; int n = 1000, lb = \-10, ub = 10 ;
 
i_lcrans_(x, &n, &lb, &ub) ;
.fi
.ft
.RE
.SH "SEE ALSO"
.BR addrans (3M),
.BR drand48 (3),
.BR mwcrans (3M),
.BR rand (3C),
.BR rand (3V),
.BR random (3),
.BR shufrans (3M).
.LP
Knuth,
.I "Seminumerical Algorithms,"
1981, Addison-Wesley.
.LP
Park and Miller,
.I "Random Number Generators: Good Ones are Hard to Find,"
Communications of the ACM, October 1988.
.SH NOTES
.LP
The number of times your program calls a random
number generator function determines when
it is more efficient (faster) to use
.BR lcrans (3M)
versus
.BR addrans (3M).
For normal use (more than 50 calls), use
.BR addrans (3M),
possibly in conjunction with
.BR shufrans (3M),
rather than calls to
.BR lcrans (3M),
.BR drand48 (3),
.BR rand (3C),
.BR rand (3V)
and
.BR random (3).
For casual use (less than 50 calls), use
.BR lcrans (3M)
rather than
.BR addrans (3M).
The reason for this is that
the first call to
.BR addrans (3M)
has the overhead cost of initializing
a table of 55 elements (defined by ADDRAN_SIZE).