## 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 @c{$0 \le N < M$} 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 @c{$M < N \le 0$} 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 @c{$0 \le N < M$} 0 <= N < M or @c{$M < N \le 0$} 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 @c{$m$ +/- $\sigma$} m +/- s' where m and @c{$\sigma$} s are both real numbers, the result uses a Gaussian distribution with mean m and standard deviation @c{$\sigma$} 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 section Vector/Matrix Functions.