.TH LIBRAN 3ran
.SH NAME
arcsin, beta, cauchy, corrand, expn, frand, gamma, gauss, hyper,
lin, logist, onefrand, plapla, randfi, randfc \- stochastic functions
.SH SYNOPSIS
.nf
.B #include <carl/libran.h>
.PP
.B double arcsin(rfunc)
.B 	double (*rfunc)();
.B double beta(rfun, a, b)
.B 	double (*rfun)();
.B 	double a, b;
.B double cauchy(rfun, tau, iopt)
.B 	double (*rfun)();
.B 	double tau, iopt;
.B double corrand(lb, ub)
.B 	double lb, ub;
.B extern double cor_factor;
.B double expn(rfun, delta)
.B 	double (*rfun)();
.B 	double delta;
.B double frand(lb, ub)
.B 	double lb, ub;
.B double gamma(rfun, nu)
.B 	double (*rfun)();
.B 	double nu;
.B double gauss(rfun, sigma, xmu)
.B 	double (*rfun)();
.B 	double xmu, sigma;
.B double hyper(rfun, tau, xmu)
.B 	double (*rfun)();
.B 	double tau, xmu;
.B double lin(rfun, g)
.B 	double (*rfun)();
.B 	double g;
.B double logist(rfun, alpha, beta)
.B 	double (*rfun)();
.B 	double alpha, beta;
.B double onefrand(lb, ub)
.B 	double lb, ub;
.B double plapla(rfun, tau, xmu)
.B 	double (*rfun)();
.B 	double tau, xmu;
.B double randfc(rfun, sRate, freq)
.B	double (*rfun)();
.B	double sRate, freq;
.B double randfi(rfun, sRate, freq)
.B	double (*rfun)();
.B	double sRate, freq;
.fi
.SH DESCRIPTION
These subroutines implement a set of stochastic functions described
as 
.I cannons
by [Lorrain].  They are in two basic groups, 
noise 
.I generators
and noise
.I modifiers.
The three generator routines are 
.I frand(),
.I corrand(),
and
.I onefrand().
The
.I generator 
subroutines take two arguments of a lower and upper bound within
which to generate their numbers.
.PP
All other subroutines are
\fImodifiers\fR
and take as their first argument a pointer to one of these
.I generator
subroutines.
The 
.I modifier
subroutines call the
.I generator
subroutines internally to get random values which they then transform
according to their function.
Some distribution functions such as \fIgauss()\fR
will require several calls on their
.I generator
per call.
Any source of random numbers may be substituted for the three
basic
.I generator
subroutines.
The substituted
.I generator
subroutine must obey the calling sequence:
.br
.nf
.B double function_name(lower_bound, upper_bound)
.B	double lower_bound, upper_bound;
.fi
and provide return values between those ranges.
.SH THE FUNCTIONS
In the description below, 
.I Us
stands for the value obtained by the
.I modifier
subroutine from its
.I generator.
.TP
.I Arcsin:
arcsin(rfun)
returns square(sin(pi * Us / 2)).
.TP
.I Beta:
beta(rfun, a, b)
produces various "U-shaped" distributions within the range
[0,1].  In general, as a and b go from 1 to 0, the U gets deeper.
.TP
.I Cauchy:
cauchy(rfun, tau, iopt)
returns Xs = tau * tan(pi * Us).  
If iopt=1, 
the distribution is folded into the positive range only.
.TP
.I Correlated noise:
corrand(lb, ub)
produces noise that goes from white to increasingly more
correlated (to a dc constant) as the external double
.I cor_factor 
goes from 0 to 1.
.TP
.I Exponential:
expn(rfun, delta)
returns -log(Us) / delta.
.TP
.I Uniform noise:
frand(lb, ub)
 returns a random number within the interval [lb,ub].
.TP
.I Gamma:
gamma(rfun, nu)
produces an asymmetrical distribution that is 0 at x=0, reaches
its mode at nu - 1, with the mean at nu.  
The whole number value of nu is used.  Nu must be 
greater than 0.  Any fractional part is truncated.  
.TP
.I Gaussian
gauss(rfun, sigma, xmu)
Using sigma=1.0, xmu=0.0, an approximated
standard gaussian distribution
is produced.  
.TP
.I Hyperbolic:
hyper(rfun, tau, xmu)
returns tau * log(tan(pi*Us/2)) + xmu.  
.TP
.I Linear:
lin(rfun, g)
returns g(1 - sqrt(Us).
.TP
.I Logistic:
logist(rfun, alpha, beta)
returns (-beta - log(1/Us -1))/alpha.
.TP
.I 1/f noise generator:
onefrand(lb, ub)
returns a random number within the [lb,ub] interval according to
the pseudo 1/f distribution algorhythm described by Voss.
.IP
.I Laplace:
plapla(rfun, tau, xmu)
Cannon formula first selects Us in the range [0,2], then for Us > 1.0,
it applies Xs = -tau * log(2.0 - Us) + xmu.  For Us <= 1.0, it applies
Xs = tau * log(Us) + xmu.
.TP Linear incremental noise:
.I 
randfi(rfun, sRate, freq),
linearly interpolating random function,
produced at frequency 
.B freq 
of sampling rate 
.B sRate.
A continuous function is generated by linearly interpolating between
successive random values, where the frequency of new random values to
interpolate between is set by
.B freq.
This is the equivalent of the RAN unit generator of MUSIC V.
.TP Cosine incremental noise:
.I randfc(rfun, sRate, freq),
cosine interpolating random function,
produced at frequency 
.B freq 
of sampling rate 
.B sRate.
Like randfi(), but it interpolates with the cosine
function between 0 and pi.  This produces a 
smoother effect in the transitions than
.B randfi(),
and its spectrum shows a smoother high frequency rolloff.
.fi
.SH References
These routines use the standard
.I random(3)
random number generator routines.
.PP
These routines are all used in 
.I cannon(1CARL),
and described in slightly more detail there.  
Note, there are some name differences between 
.I cannon's 
names and those of the subroutines here.
.SH SEE ALSO
Martin Gardner, "Mathematical Games", Scientific American,
March, 1979.
.br
Denis Lorrain, "A Panoply of Stochastic 'Cannons'", Computer
Music Journal, V. 4 #1, p. 53.
.br
.SH AUTHOR
Gareth Loy
