.TH CANNON 1carl CARL
.SH NAME
cannon \- continuous distribution function generator
.SH SYNOPSIS
.B cannon 
[
.B -LN
] [
.B -S[N]
] [
.B -I
] [
.B -F
] [
.B -CN
]
function arg1 arg2 < floatsams > floatsams
.SH DESCRIPTION
flags: (default)
.TP
.B -L
set N output floatsams (1024)
.TP
.B -S
set seed for random number generator to N
(or to time of day if no N)
(no S flag uses default constant seed)
.TP
.B -I
use standard input instead of internally generated noise
.TP
.B -F
use 1/f noise instead of white noise as input to cannons
.TP
.B -C
use correlated noise; N=correlation factor: 0=white, -> 1=brownian
.PP
functions:  args: (default value)
.TP "\w'exponential  'u"
.B arcsin
no args
.TP
.B beta
a (0.25) b (0.25)
.TP
.B cauchy
tau (0.01272) iopt (0.0)
.TP
.B exponential
delta (2.0)
.TP
.B gamma
nu (2.0)
.TP
.B gauss
sigma (1.0) xmu (0.0)
.TP
.B hyperbolic
tau (0.48732) xmu (0.0)
.TP
.B linear
g (1.0)
.TP
.B logistic
alpha (2.2021) beta (0.0)
.TP
.B laplace
tau (0.50723) xmu (0.0)
.TP
.B urand
lb (0.0) ub (1.0)
.TP
.B frand
lb (0.0) ub (1.0)
.TP
.B crand
lb (0.0) ub (1.0)
.TP
.B randfi
srate(16384) freq(440)
.TP
.B randfc
srate(16384) freq(440)
.PP
.B cannon
produces a stream of random numbers constrained by the chosen
continuous distribution function.
This program conforms to the
.B cmusic
.B gen
command syntax, and can be used to fill
.B cmusic
function tables.
This example,
.RS .5i
% cannon -L1024 gauss > file
.RE
writes 1024 binary floating point samples into
.I file
which conform to a gaussian distribution function.
A simple histogram of a
.B cannon
can be produced by using
.B stochist(1carl).
For example:
.RS .5i
% cannon gauss | stochist
.RE
.br
Here is a cmusic example:
.RS .5i
var 0 s1 "gauss";
gen 0 cannon f3 s1;
.RE
.PP
The best description of these functions is obtained from [Lorrain],
but here is a brief discussion.
.PP
The distribution of the output of
.B cannon
is determined by which distribution function is named.
Ordinarily, by naming a distribution function, the output of a
noise generator
is passed to the named distribution function, which then applies its
characteristic distribution pattern to these numbers.
.PP
By default, the
.I urand
generator is used.  The -F flag uses the
.I frand
generator.
There is also a variable-correlation noise generator,
.I crand.
.I crand
is invoked by -CN, where N is a number from 0 to 1
specifying the degree of correlation in the noise.
The -I flag
causes
.B cannon
to read
.I floatsams
from its standard input which are used to drive the
distribution functions, so if these three noise generators aren't
enough, you can roll your own.  (Reading in a ramp from -1 to +1,
for instance, produces a neat picture of the actual transform of the
cannons).
Besides providing random values to the distribution functions, the
output of
.I urand, frand and crand
can be had directly by naming them instead of a distribution function
in the proper place on the command line.
.PP
.RS 1i
.I ``Cannon
is a term Xenakis coined to name algorithms 'shooting' random values
according to a specific probability distribution.  (In French we say
.I tirer au hasard
for 'choose at random,' literally 'shoot at random.')''
.br
.ti 1.5i
-[Lorrain]
.RE
.RS 1i
Thus, with this program, it is possible to ``compose with serialism
shot from guns.''
.ti 1.5i
-[Zvonar]
.PP
.SH Normalized Symmetrical Distribution Functions
A terse description of the individual distribution function cannons follows.
For more details, see [Lorrain].
.PP
NOTE: the default arguments for the following four distribution functions
have been chosen to adjust them to a common characteristic.
F(3), the probability the value of 3, of the gaussian distribution
is taken as a standard, and the other three are normalized
to have a probability for F(3) that agrees with this.
Thus, these four distributions can be
used effectively together to produce distributions of the same ``size'' but
of different shape.  Although the remaining functions do not submit to the
same normalization, normal values for the Cauchy distribution are given
by [Lorrain] which are also used by default.
.PP
.I gauss:
sigma (1.0), xmu (0.0).
Using the defaults, an approximated
standard gaussian distribution
is produced - the classic ``bell curve''.  Sigma is a scaler controlling
dispersion, or range, and xmu is
an offset.  The mean can be moved away from 0 by varying xmu, and the
extension of the distribution function can be affected by sigma.
The cannon approximation algorithm is:
.sp
.RS .5i
for (i = 0; i < 12; i++) sum += Us; Xs = sigma * (sum - 6) + xmu;
.RE
.sp
.PP
.I hyperbolic:
tau (0.48732), xmu(0.0).
Hyperbolic cosine,
symmetrical, like gauss, but although it is centered on zero, it has no
mean.  Thus, it can be viewed as a somewhat civilized Cauchy distribution.
The cannon formula is
.sp
.RS .5i
.EQ
Xs = tau * log ( tan ( pi * Us over 2 ) ).
.EN
.RE
.sp
Tau is a scaler, xmu an offset.
.PP
.I logistic:
alpha (2.2021), beta (0.0).
Another symmetrical distribution of mean \-beta/alpha and mode alpha/4.
(Mode is the point of highest probability).
Alpha and beta thus control the mean and dispersion of the distribution.
The cannon formula is
.sp
.RS .5i
.EQ
Xs = { -beta - log ( 1 / Us -1 ) } over "alpha" .
.EN
.RE
.sp
.PP
.I laplace:
tau (0.50723), xmu (0.0).
First Law of Laplace.  This is a bilateral exponential distribution (see
.I exponential,
below for a unilateral distribution).
The distribution function has the shape of
two exponential slopes back to back
intersecting at 0.  Tau and xmu are scale and offset.
Cannon formula first selects Us in the range [0,2], then for Us > 1.0,
it applies
.EQ
Xs = -tau * log ( 2.0 - Us ) + xmu.
.EN
For Us <= 1.0, it applies
.EQ
Xs = tau * log ( Us ) + xmu.
.EN
.PP
.SH Asymmetrical Distribution Functions
.I linear:
g (1.0).
The distribution function goes linearly from 2/g to 0 as x goes from
0 to g.  The cannon formula is Xs = g(1 - sqrt(Us).
Small values are favored because sqrt(Us) > Us, which tends
to make 1 - sqrt(Us) always nearer 0.
.PP
.I exponential:
delta (2.0).
This is a unilateral exponential distribution.  Delta controls the
density near 0, with greater values of delta producing greater
density near 0, smaller values producing less steep curves.
The cannon is
.sp
.RS .5i
.EQ
Xs = { -log ( Us ) } over delta;
.EN
.RE
.sp
.PP
.I gamma:
nu (2.0).
This produces an asymmetrical distribution that is 0 at x=0, reaches
its mode at nu - 1, with the mean at nu.  The values of nu are integers,
greater than 0.  Any fractional part is truncated.
For nu = 8, it resembles the gaussian function, except that
the probability of x at 0 is always 0; this means that for smaller values
of nu, the skirt to the left of the mode is very steep, whereas the skirt
on the right is roughly exponential.
The cannon algorithm
is 
.sp
.RS .5i
for (i = 0; i < nu; i++) sum *= Us;
Xs = - log(sum);
.RE
.sp
The
.I Poisson
distribution can be approximated by the
.I gamma
function.
.PP
.I cauchy:
tau (0.01272), iopt (0.0).
Cauchy is a symmetrical distribution function centered
around zero, related to hyperbolic cosine.  The
Cauchy distribution has the property of having no mean and generating
very heterogeneous values, explaining why it is listed under asymmetrical
functions.  The histogram of this function resembles
the gaussian distribution, but the skirts approach the x axis so slowly
as to make extremely distant values likely.  The cannon formula is
.sp
.RS .5i
.EQ
Xs = tau * tan ( pi * Us ).
.EN
.RE
.sp
If iopt=1,
the distribution is folded into the positive range only.
.PP
.I beta: 
a (0.25) b (0.25).
This cannon 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.
For a = b = 1, it produces a
.I continuous uniform
distribution.  As a and b go to 0, the probabilities are
more and more restricted to the region around 0 and 1.
For a = b = .5, we get the
.I arc
.I sine
distribution (see below).
For cases where a != b,  the larger value tends to reduce the density
in that region.  Thus, the values a = .75, b = .5 produces a function that
is deeper near 0 than near 1.
.PP
.I arcsin
The
.I arc
.I sine
distribution is the same as the
.I beta
distribution for values of a=.5, b=.5.
The cannon is
.EQ
Xs = sqrt { ( sin ( pi * Us / 2 ) ) } .
.EN
.PP
.SH Random Functions
The random number generators used to provide values for the distribution
functions can be called directly.  They are
.I urand:
lb (0.0) ub (1.0),
.I frand:
lb (0.0) ub (1.0),
and
.I crand:
lb (0.0) ub (1.0),
for
.I uniform,
.I 1/f,
and
.I correlated
noise, respectively.
The
.I urand
generator is simply the UNIX math library rand() function, scaled into
the appropriate range as follows:
.sp
.RS .5i
.EQ
Us = ( ub - lb ) * ("rand()" over { pow ( 2.0, 31.0 ) - 1.0 } + lb .
.EN
.RE
.sp
.I frand,
the
.I 1/f
generator, is an implementation of Voss' algorithm as given
by [Gardner], which involves
summing the output of a collection of rand() generators. New values
are then obtained from these generators in a binary-weighted order,
that is, one in which successive values are weighted by inverse
exponent.
.PP
The
.I crand
generator produces correlated noise by constraining the next value of
the generator to lie within a window of the previous value.  This window
is not to be confused with the upper and lower bounds, which are
static boundaries.  The size of the dynamic window is scaled by the
argument supplied to the -C flag.  As the -C flag value, N,  goes from 0 to
1, the size of the dynamic window goes from the size of the static window to 0.
Thus, as N goes to 1, the range of the next random number lies closer to
the previous one, producing the correlated effect.  Informal experiments
have shown that -C.96 produces roughly the same spectrum as
.I 1/f
noise.  The character of the noise is quite different, however.
.PP
.SH Other Functions
.PP
.I randfi:
srate (16384), freq (440).
produces a
linearly interpolating random function,
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.
.PP
.I randfc:
srate (16384), freq (440).
produces a
cosine interpolating random function,
at frequency
.B freq
of sampling rate
.B srate.
It is
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.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
.br
[Gardner]: Martin Gardner, ``Mathematical Games'', Scientific American,
March, 1978.
.br
[Lorrain]: Denis Lorrain, ``A Panoply of Stochastic "Cannons"'', Computer
Music Journal, V. 4 #1, p. 53.
.br
[Zvonar]: Richard Zvonar, private communication, 1982.
.br
libran(3carl), stochist(1carl)
.SH DIAGNOSTICS
When using the -I mode of reading in values from the standard input for
driving the distribution functions, care must be taken that the source
of random numbers is inexhaustable, since some of the cannons use
more than one random number to create one output value.
\f3cannon\f1
will say ``cannon: ran out of standard input'' if this happens, and exit.
