Random Numbers
==============

The `k r' (`calc-random') [`random'] command produces random numbers
of various sorts.

Given a positive numeric prefix argument `M', it produces a random
integer `N' in the range `0 <= N < M'.  Each of the `M' values appears
with equal probability.

With no numeric prefix argument, the `k r' command takes its argument
from the stack instead.  Once again, if this is a positive integer `M'
the result is a random integer less than `M'.  However, note that
while numeric prefix arguments are limited to six digits or so, an `M'
taken from the stack can be arbitrarily large.  If `M' is negative,
the result is a random integer in the range `M < N <= 0'.

If the value on the stack is a floating-point number `M', the result
is a random floating-point number `N' in the range `0 <= N < M' or `M
< N <= 0', according to the sign of `M'.

If `M' is zero, the result is a Gaussian-distributed random real
number; the distribution has a mean of zero and a standard deviation
of one.  The algorithm used generates random numbers in pairs; thus,
every other call to this function will be especially fast.

If `M' is an error form `m +/- s' where m and s are both real numbers,
the result uses a Gaussian distribution with mean m and standard
deviation s.

If `M' is an interval form, the lower and upper bounds specify the
acceptable limits of the random numbers.  If both bounds are integers,
the result is a random integer in the specified range.  If either
bound is floating-point, the result is a random real number in the
specified range.  If the interval is open at either end, the result
will be sure not to equal that end value.  (This makes a big
difference for integer intervals, but for floating-point intervals
it's relatively minor: with a precision of 6, `random([1.0..2.0))'
will return any of one million numbers from 1.00000 to 1.99999;
`random([1.0..2.0])' may additionally return 2.00000, but the
probability of this happening is extremely small.)

If `M' is a vector, the result is one element taken at random from the
vector.  All elements of the vector are given equal probabilities.

The sequence of numbers produced by `k r' is completely random by
default, i.e., the sequence is seeded each time you start Calc using
the current time and other information.  You can get a reproducible
sequence by storing a particular "seed value" in the Calc variable
`RandSeed'.  Any integer will do for a seed; integers of from 1 to 12
digits are good.  If you later store a different integer into
`RandSeed', Calc will switch to a different pseudo-random sequence.
If you "unstore" `RandSeed', Calc will re-seed itself from the current
time.  If you store the same integer that you used before back into
`RandSeed', you will get the exact same sequence of random numbers as
before.

The `calc-rrandom' command (not on any key) produces a random real
number between zero and one.  It is equivalent to `random(1.0)'.

The `k a' (`calc-random-again') command produces another random
number, re-using the most recent value of `M'.  With a numeric prefix
argument N, it produces N more random numbers using that value of `M'.

The `k h' (`calc-shuffle') command produces a vector of several random
values with no duplicates.  The value on the top of the stack
specifies the set from which the random values are drawn, and may be
any of the `M' formats described above.  The numeric prefix argument
gives the length of the desired list.  (If you do not provide a
numeric prefix argument, the length of the list is taken from the top
of the stack, and `M' from second-to-top.)

If `M' is a floating-point number, zero, or an error form (so that the
random values are being drawn from the set of real numbers) there is
little practical difference between using `k h' and using `k r'
several times.  But if the set of possible values consists of just a
few integers, or the elements of a vector, then there is a very real
chance that multiple `k r''s will produce the same number more than
once.  The `k h' command produces a vector whose elements are always
distinct.  (Actually, there is a slight exception: If `M' is a vector,
no given vector element will be drawn more than once, but if several
elements of `M' are equal, they may each make it into the result
vector.)

One use of `k h' is to rearrange a list at random.  This happens if
the prefix argument is equal to the number of values in the list: `[1,
1.5, 2, 2.5, 3] 5 k h' might produce the permuted list `[2.5, 1, 1.5,
3, 2]'.  As a convenient feature, if the argument N is negative it is
replaced by the size of the set represented by `M'.  Naturally, this
is allowed only when `M' specifies a small discrete set of
possibilities.

To do the equivalent of `k h' but with duplications allowed, given `M'
on the stack and with N just entered as a numeric prefix, use `v b' to
build a vector of copies of `M', then use `V M k r' to "map" the
normal `k r' function over the elements of this vector.  *Note Matrix
Functions::.

Menu

Random Number Generator

(Complete description of Calc's algorithm)