Next: Combinatorial Functions, Previous: Branch Cuts, Up: Scientific Functions

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 possible value ‘`N`’ 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. See Matrix Functions.