Random numbers

(directly go to documentation on : Random, RandomSeed, RngCreate, RngSeed, Rng, RandomIntegerMatrix, RandomIntegerVector, RandomPoly. )

# 5. Random numbers

Random, RandomSeed | (pseudo-) random number generator
RngCreate | manipulate random number generators as objects
RngSeed | manipulate random number generators as objects
Rng | manipulate random number generators as objects
RandomIntegerMatrix | generate a matrix of random integers
RandomIntegerVector | generate a vector of random integers
RandomPoly | construct a random polynomial

###

Random, RandomSeed -- (pseudo-) random number generator

##### Standard library

##### Calling format:

    Random()
    RandomSeed(init)

*PARAMS `init` -- positive integer, initial random seed

##### Description:

The function `Random` returns a random number, uniformly distributed in the interval between 0 and 1. The same sequence of random numbers is generated in every Yacas session.

The random number generator can be initialized by calling `RandomSeed` with an integer value. Each seed value will result in the same sequence of pseudo-random numbers.

##### See also:

RandomInteger , RandomPoly , Rng .

###

RngCreate -- manipulate random number generators as objects

###

RngSeed -- manipulate random number generators as objects

###

Rng -- manipulate random number generators as objects

##### Standard library

##### Calling format:

    RngCreate()
    RngCreate(init)
    RngCreate(option==value,...)
    RngSeed(r, init)
    Rng(r)

##### Parameters:

`init` -- integer, initial seed value

`option` -- atom, option name

`value` -- atom, option value

`r` -- a list, RNG object

##### Description:

These commands are an object-oriented interface to (pseudo-)random number generators (RNGs).

`RngCreate` returns a list which is a well-formed RNG object. Its value should be saved in a variable and used to call `Rng` and `RngSeed`.

`Rng(r)` returns a floating-point random number between 0 and 1 and updates the RNG object `r`. (Currently, the Gaussian option makes a RNG return a complex random number instead of a real random number.)

`RngSeed(r,init)` re-initializes the RNG object `r` with the seed value `init`. The seed value should be a positive integer.

The `RngCreate` function accepts several options as arguments. Currently the following options are available:

`seed` -- specify initial seed value, must be a positive integer
`dist` -- specify the distribution of the random number; currently `flat` and `gauss` are implemented, and the default is the flat (uniform) distribution
`engine` -- specify the RNG engine; currently `default` and `advanced` are available ("advanced" is slower but has much longer period)

If the initial seed is not specified, the value of 76544321 will be used.

The `gauss` option will create a RNG object that generates pairs of Gaussian distributed random numbers as a complex random number. The real and the imaginary parts of this number are independent random numbers taken from a Gaussian (i.e. "normal") distribution with unit variance.

For the Gaussian distribution, the Box-Muller transform method is used. A good description of this method, along with the proof that the method generates normally distributed random numbers, can be found in Knuth, "The Art of Computer Programming", Volume 2 (Seminumerical algorithms, third edition), section 3.4.1

Note that unlike the global `Random` function, the RNG objects created with `RngCreate` are independent RNGs and do not affect each other. They generate independent streams of pseudo-random numbers. However, the `Random` function is slightly faster.

##### Examples:

    In> r1:=RngCreate(seed=1,dist=gauss)
    Out> {"GaussianRNGDist","RNGEngine'LCG'2",{1}}
    In> Rng(r1)
    Out> Complex(-1.6668466417,0.228904004);
    In> Rng(r1);
    Out> Complex(0.0279296109,-0.5382405341);

The second RNG gives a uniform distribution (default option) but uses a more complicated algorithm:

    In> [r2:=RngCreate(engine=advanced);Rng(r2);]
    Out> 0.3653615377;

The generator `r1` can be re-initialized with seed 1 again to obtain the same sequence:

    In> RngSeed(r1, 1)
    Out> True;
    In> Rng(r1)
    Out> Complex(-1.6668466417,0.228904004);

##### See also:

Random .

###

RandomIntegerMatrix -- generate a matrix of random integers

##### Standard library

##### Calling format:

    RandomIntegerMatrix(rows,cols,from,to)

##### Parameters:

`rows` -- number of rows in matrix

`cols` -- number of cols in matrix

`from` -- lower bound

`to` -- upper bound

##### Description:

This function generates a `rows x cols` matrix of random integers. All entries lie between "from" and "to", including the boundaries, and are uniformly distributed in this interval.

##### Examples:

    In> PrettyForm( RandomIntegerMatrix(5,5,-2^10,2^10) )

    /                                               \
    | ( -506 ) ( 749 )  ( -574 ) ( -674 ) ( -106 )  |
    |                                               |
    | ( 301 )  ( 151 )  ( -326 ) ( -56 )  ( -277 )  |
    |                                               |
    | ( 777 )  ( -761 ) ( -161 ) ( -918 ) ( -417 )  |
    |                                               |
    | ( -518 ) ( 127 )  ( 136 )  ( 797 )  ( -406 )  |
    |                                               |
    | ( 679 )  ( 854 )  ( -78 )  ( 503 )  ( 772 )   |
    \                                               /

##### See also:

RandomIntegerVector , RandomPoly .

###

RandomIntegerVector -- generate a vector of random integers

##### Standard library

##### Calling format:

    RandomIntegerVector(nr, from, to)

##### Parameters:

`nr` -- number of integers to generate

`from` -- lower bound

`to` -- upper bound

##### Description:

This function generates a list with "nr" random integers. All entries lie between "from" and "to", including the boundaries, and are uniformly distributed in this interval.

##### Examples:

    In> RandomIntegerVector(4,-3,3)
    Out> {0,3,2,-2};

##### See also:

Random , RandomPoly .

###

RandomPoly -- construct a random polynomial

##### Standard library

##### Calling format:

    RandomPoly(var,deg,coefmin,coefmax)

##### Parameters:

`var` -- free variable for resulting univariate polynomial

`deg` -- degree of resulting univariate polynomial

`coefmin` -- minimum value for coefficients

`coefmax` -- maximum value for coefficients

##### Description:

RandomPoly generates a random polynomial in variable "var", of degree "deg", with integer coefficients ranging from "coefmin" to "coefmax" (inclusive). The coefficients are uniformly distributed in this interval, and are independent of each other.

##### Examples:

    In> RandomPoly(x,3,-10,10)
    Out> 3*x^3+10*x^2-4*x-6;
    In> RandomPoly(x,3,-10,10)
    Out> -2*x^3-8*x^2+8;

##### See also:

Random , RandomIntegerVector .