<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) Jean-Philippe Chancelier and Bruno Pincon
 * Copyright (C) 2010-2011 - DIGITEO - Michael Baudin
 * Copyright (C) 2013 - Samuel GOUGEON : extension to hypermatrices
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2023 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<!-- module: randlib -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:lang="en" xml:id="grand">
    <refnamediv>
        <refname>grand</refname>
        <refpurpose>Generate random numbers</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            Y = grand(m, n, "bet", A, B)
            Y = grand(m, n, "bin", N, p)
            Y = grand(m, n, "nbn", N, p)
            Y = grand(m, n, "chi", Df)
            Y = grand(m, n, "nch", Df, Xnon)
            Y = grand(m, n, "exp", Av)
            Y = grand(m, n, "f", Dfn, Dfd)
            Y = grand(m, n, "nf", Dfn, Dfd, Xnon)
            Y = grand(m, n, "gam", shape, rate)
            Y = grand(m, n, "nor", Av, Sd)
            Y = grand(m, n, "geom", p)
            Y = grand(m, n, "poi", mu)
            Y = grand(m, n, "def")
            Y = grand(m, n, "unf", Low, High)
            Y = grand(m, n, "uin", Low, High)
            Y = grand(m, n, "lgi")

            Y = grand(m, n, o, …, PDFname, …)

            Y = grand(X, PDFname, …)
        </synopsis>
        <para/>
        <synopsis>
            Y = grand(n, "mn", Mean, Cov)
            Y = grand(n, "markov", P, x0)
            Y = grand(n, "mul", nb, P)
            Y = grand(n, "prm", array)
        </synopsis>
        <para/>
        <synopsis>
            S = grand("getgen")
            grand("setgen", gen)

            S = grand("getsd")
            grand("setsd", S)

            grand("setcgn", G)
            S = grand("getcgn")

            S = grand("phr2sd", phrase)

            grand("initgn", I)
            grand("setall", s1, s2, s3, s4)
            grand("advnst", K)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>m, n, o</term>
                <listitem>
                    <para>
                        integers, size of the wanted matrix / hypermatrix <varname>Y</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>X</term>
                <listitem>
                    <para>
                        a matrix or hypermatrix whom only the dimensions (say <varname>m</varname>-by-<varname>n</varname>)
                        are used.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PDFname</term>
                <listitem>
                    <para>
                        Name of the chosen probability Density Function:
                        <literal>"def", "unf", "uin", "bet", "gam","exp", "nor", "geo", "poi",
                        "bin", "chi", "nbn", "nch", "f", "nf",  "lgi"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Y</term>
                <listitem>
                    <para>
                        depending on the input, a matrix or hypermatrix, with random entries.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>output of the action (a string or a real column vector).</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function generates random numbers from various probability distributions.
        </para>
        <para>
            The syntaxes
            <screen><![CDATA[
Y = grand(m, n, "bet", A, B)
Y = grand(m, n, "bin", N, p)
Y = grand(m, n, "nbn", N, p)
Y = grand(m, n, "chi", Df)
Y = grand(m, n, "nch", Df, Xnon)
Y = grand(m, n, "exp", Av)
Y = grand(m, n, "f", Dfn, Dfd)
Y = grand(m, n, "nf", Dfn, Dfd, Xnon)
Y = grand(m, n, "gam", shape, rate)
Y = grand(m, n, "nor", Av, Sd)
Y = grand(m, n, "geom", p)
Y = grand(m, n, "poi", mu)
Y = grand(m, n, "def")
Y = grand(m, n, "unf", Low, High)
Y = grand(m, n, "uin", Low, High)
Y = grand(m, n, "lgi")
]]></screen>
            produce a <varname>m</varname>-by-<varname>n</varname> matrix with random entries.
        </para>
        <para>
            The syntax
            <screen><![CDATA[
Y = grand(m, n, o, …, PDFname, …)
]]></screen>
            produces a <varname>m</varname>-by-<varname>n</varname>-by-<varname>o</varname>-by-... hypermatrix
            with random entries.
        </para>
        <para>
            <screen><![CDATA[
Y = grand(X, PDFname, …)
]]></screen>
            produces a scalar, vector, matrix or hypermatrix of size <literal>size(X)</literal>,
            with random entries. <varname>X</varname> is used only as template to size the result.
        </para>
        <para>
            The syntaxes
        <screen><![CDATA[
Y = grand(n, "mn", Mean, Cov)
Y = grand(n, "markov", P, x0)
Y = grand(n, "mul", nb, P)
Y = grand(n, "prm", array)
]]></screen>
            produce an array with random entries, whose sizes depend on <varname>n</varname> and on
            the size of the parameters <varname>Mean</varname>, <varname>P</varname> or
            <varname>array</varname> (see below for details).
        </para>
        <para>
            The syntaxes
            <screen><![CDATA[
S = grand("getgen")
grand("setgen", gen)

S = grand("getsd")
grand("setsd", S)

grand("setcgn", G)
S = grand("getcgn")

grand("initgn", I)

grand("setall", s1, s2, s3, s4)

grand("advnst", K)
]]></screen>
            configure or query the state of the underlying random number generators.
        </para>
    </refsection>
    <refsection>
        <title>Getting random numbers from a given distribution</title>
        <variablelist>
            <varlistentry>
                <term>beta</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "bet", A, B)</code> generates
                        random variates from the beta distribution with parameters
                        <varname>A</varname> and <varname>B</varname>.  The density
                        of the beta distribution is (0 &lt; x &lt; 1):
                    </para>
                    <para>
                        <latex>
                            \dfrac{x^{A-1}(1-x)^{B-1}}{\beta(A,B)}
                        </latex>
                    </para>
                    <para>
                        <varname>A</varname> and <varname>B</varname> must be
                        reals &gt; 10<superscript>-37</superscript>.
                        Related function: <link linkend="cdfbet">cdfbet</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>binomial</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "bin", N, p)</code> generates random
                        variates from the binomial distribution with parameters
                        <varname>N</varname> (positive integer) and <varname>p</varname>
                        (<literal>real</literal> in <literal>[0,1]</literal>): number of successes in <varname>N</varname>
                        independent Bernouilli trials with probability <varname>p</varname>
                        of success.  Related functions: <link linkend="binomial">binomial</link>,
                        <link linkend="cdfbin">cdfbin</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>negative binomial</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "nbn", N, p)</code> generates random variates from the
                        negative binomial distribution with parameters <varname>N</varname> (positive integer) and <varname>p</varname> (<literal>real</literal>
                        in <literal>(0,1)</literal>) : number of failures occurring before <varname>N</varname> successes
                        in independent Bernoulli trials with probability <varname>p</varname> of success.
                        Related function: <link linkend="cdfnbn">cdfnbn</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>chi-square</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "chi", Df)</code> generates random
                        variates from the chi-square distribution with <varname>Df</varname>
                        (<literal>real</literal> &gt; <literal>0.0</literal>) degrees of freedom.  Related function:
                        <link linkend="cdfchi">cdfchi</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>non-central chi-square</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "nch", Df, Xnonc)</code> generates
                        random variates from the non-central chisquare
                        distribution with <varname>Df</varname> degrees of freedom
                        (<literal>real</literal> &gt;= <literal>1.0</literal>) and noncentrality parameter
                        <varname>Xnonc</varname> (<literal>real</literal> &gt;= <literal>0.0</literal>).  Related
                        function: <link linkend="cdfchn">cdfchn</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>exponential</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "exp", Av)</code> generates
                        random variates from the exponential distribution with mean
                        <varname>Av</varname> (<literal>real</literal> &gt; <literal>0.0</literal>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>F variance ratio</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "f", Dfn, Dfd)</code> generates
                        random variates from the F (variance ratio) distribution
                        with <varname>Dfn</varname> (<literal>real</literal> &gt; <literal>0.0</literal>) degrees of
                        freedom in the numerator and <varname>Dfd</varname> (<literal>real</literal>
                        &gt; <literal>0.0</literal>) degrees of freedom in the denominator. Related
                        function : <link linkend="cdff">cdff</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>non-central F variance ratio</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "nf", Dfn, Dfd, Xnonc)</code>
                        generates random variates from the noncentral F (variance
                        ratio) distribution with <varname>Dfn</varname> (<literal>real</literal>
                        &gt;= <literal>1</literal>) degrees of freedom in the numerator, and
                        <varname>Dfd</varname> (<literal>real</literal> &gt; <literal>0</literal>)
                        degrees of freedom in the denominator, and noncentrality parameter
                        <varname>Xnonc</varname> (<literal>real</literal> &gt;= <literal>0</literal>).
                        Related function : <link linkend="cdffnc">cdffnc</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>gamma</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "gam", shape, rate)</code>
                        generates random variates from the gamma distribution with
                        parameters <varname>shape</varname> (<literal>real</literal> &gt; <literal>0</literal>)
                        and <varname>rate</varname> (<literal>real</literal> &gt; <literal>0</literal>).
                        The density of the gamma distribution is :
                    </para>
                    <para>
                        <latex>
                            \dfrac{ \textrm{rate}^{\textrm{shape}} x^{\textrm{shape}-1} e^{-x.\textrm{rate}}}{\gamma(\textrm{shape}) }
                        </latex>
                    </para>
                    <para>
                        Related functions : <link linkend="gamma">gamma</link>,
                        <link linkend="cdfgam">cdfgam</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Gauss Laplace (normal)</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "nor", Av, Sd)</code> generates
                        random variates from the normal distribution with mean
                        <varname>Av</varname> (<literal>real</literal>) and standard deviation
                        <varname>Sd</varname> (<literal>real</literal> &gt;= <literal>0</literal>).
                        Related function: <link linkend="cdfnor">cdfnor</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>multivariate gaussian (multivariate normal)</term>
                <listitem>
                    <para>
                        <code>Y = grand(n, "mn", Mean, Cov)</code>
                        generates multivariate normal random
                        variates; <varname>Mean</varname> must be a <literal>m x 1</literal>
                        column vector, and <varname>Cov</varname> a square
                        <varname>m</varname>-by-<varname>m</varname> symmetric positive definite matrix.
                        <varname>Y</varname> is then a <varname>m</varname>-by-<varname>n</varname>
                        matrix.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>geometric</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "geom", p)</code> generates
                        random variates from the geometric distribution with
                        parameter <varname>p</varname> : number of Bernouilli trials
                        (with probability success of <varname>p</varname>) until a
                        success is met. <varname>p</varname> must be in [1.3e-307, 1]).
                    </para>
                    <para>
                        <varname>Y</varname> contains positive real numbers
                        with integer values, whiсh are the "number of trials to get
                        a success".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>markov</term>
                <listitem>
                    <para>
                        <code>Y = grand(n, "markov", P, x0)</code> generate
                        <varname>n</varname> successive states of a Markov chain
                        described by the transition matrix
                        <varname>P</varname>. A sum of each the rows in <varname>P</varname> is
                        <literal>1</literal>. Initial state is given by <varname>x0</varname>.
                        If <varname>x0</varname> is a  matrix of size <code>m=size(x0,"*")</code> then
                        <varname>Y</varname> is a matrix of size <varname>m</varname>-by-<varname>n</varname>.
                        <code>Y(i,:)</code> code the sample path  obtained from initial state
                        <code>x0(i)</code>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>multinomial</term>
                <listitem>
                    <para>
                        <code>Y = grand(n, "mul", nb, P)</code> generates
                        <varname>n</varname> observations from the Multinomial
                        distribution : class <varname>nb</varname> events in
                        <literal>m</literal> categories (put <varname>nb</varname>
                        "balls" in <literal>m</literal>
                        "boxes"). <literal>P(i)</literal> is the probability that
                        an event will be classified into category
                        <literal>i</literal>. The column vector of probabilities <varname>P</varname>
                        is of size <literal>m-1</literal> (the probability of category
                        <literal>m</literal> is <literal>1-sum(P)</literal>).
                        <varname>Y</varname> is of size <literal>m</literal>-by-<varname>n</varname>.
                        Each column <literal>Y(:,j)</literal> is an observation
                        from multinomial distribution and
                        <literal>Y(i,j)</literal> is the number of events falling in
                        category <literal>i</literal> (for the
                        <literal>j</literal>-th observation) (<literal>sum(Y(:,j)) = nb</literal>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Poisson</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "poi", mu)</code> generates
                        random variates from the Poisson distribution with mean
                        <varname>mu</varname> (<literal>real</literal> &gt;= <literal>0.0</literal>).
                        Related function:  <link linkend="cdfpoi">cdfpoi</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>random permutations</term>
                <listitem>
                    <para>
                        <code>Y = grand(n, "prm", array)</code> generates
                        <varname>n</varname> random permutations of the <varname>array</varname>
                        elements.
                        <varname>array</varname> can be a vector, matrix or hypermatrix of real or
                        complex numbers, of integers, booleans, polynomials or strings; full or sparse.
                        <itemizedlist>
                            <listitem>
                                If <varname>array</varname> is a <literal>1 x m</literal> row vector,
                                <varname>Y</varname> is a <literal>n x m</literal> matrix.
                            </listitem>
                            <listitem>
                                If <varname>array</varname> is a <literal>m x 1</literal> column vector,
                                <varname>Y</varname> is a <literal>m x n</literal> matrix.
                            </listitem>
                            <listitem>
                                If <varname>array</varname> is a <literal>m x p</literal> matrix,
                                <varname>Y</varname> is a <literal>m x p x n</literal> hypermatrix.
                            </listitem>
                            <listitem>
                                If <varname>array</varname> is a <literal>m x p x q…</literal> hypermatrix,
                                <varname>Y</varname> is a <literal>m x p x q… x n</literal> hypermatrix.
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniform (def)</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "def")</code> generates
                        random variates from the uniform distribution over
                        <literal>[0,1)</literal> (<literal>1</literal> is never returned).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniform (unf)</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "unf", Low, High)</code>
                        generates random reals uniformly distributed in
                        <literal>[Low, High)</literal> (<varname>High</varname> is never returned).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniform (uin)</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "uin", Low, High)</code>
                        generates random integers uniformly distributed between
                        <varname>Low</varname> and <varname>High</varname>
                        (included). <varname>High</varname> and
                        <varname>Low</varname> must be integers such that
                        <literal>(High-Low+1) &lt; 2,147,483,561</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniform (lgi)</term>
                <listitem>
                    <para>
                        <code>Y = grand(m, n, "lgi")</code> returns the
                        basic output of the current generator : random integers
                        following a uniform distribution over :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>[0, 2^32 - 1]</literal> for mt and kiss;
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>[0, 2^31 - 87]</literal> for clcg2;
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>[0, 2^31 - 2]</literal> for clcg4;
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>[0, 2^31 - 1]</literal> for urand.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Set/get the current generator and its state</title>
        <para>
            The user has the possibility to choose between different base
            generators (which give random integers following the "lgi" distribution, the others
            being gotten from it).
        </para>
        <variablelist>
            <varlistentry>
                <term>mt</term>
                <listitem>
                    <para>
                        The Mersenne-Twister of M. Matsumoto and T. Nishimura, period about
                        <literal>2^19937</literal>, state given by an array of <literal>624</literal>
                        integers (plus an index onto this array). This is the default generator.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>kiss</term>
                <listitem>
                    <para>
                        The "Keep It Simple Stupid" of G. Marsaglia,  period about
                        <literal>2^123</literal>, state given by four integers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clcg2</term>
                <listitem>
                    <para>
                        A Combined 2 Linear Congruential Generator of P. L'Ecuyer, period about
                        <literal>2^61</literal>, state given by <literal>2</literal> integers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clcg4</term>
                <listitem>
                    <para>
                        A Combined 4 Linear Congruential Generator of P. L'Ecuyer,
                        period about <literal>2^121</literal>, state given by 4 integers ; this one is
                        split in <literal>101</literal> different virtual (non-overlapping) generators
                        which may be useful for different tasks (see "Options specific to clcg4" and
                        "Test example for clcg4").
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>urand</term>
                <listitem>
                    <para>
                        The generator used by the scilab function <link linkend="rand">rand</link>,
                        state given by <literal>1</literal> integer, period of <literal>2^31</literal>.
                        This generator is based on "Urand, A Universal Random Number Generator" By,
                        Michael A. Malcolm, Cleve B. Moler, Stan-Cs-73-334, January 1973, Computer
                        Science Department, School Of Humanities And Sciences, Stanford University.
                        This is the faster of this list but its statistical qualities are less
                        satisfactory than the other generators.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            The different actions common to all the generators, are:
        </para>
        <variablelist>
            <varlistentry>
                <term>action = "getgen"</term>
                <listitem>
                    <para>
                        <code>S = grand("getgen")</code> returns the current base generator.
                        In this case <varname>S</varname> is
                        a string among <literal>"mt"</literal>, <literal>"kiss"</literal>,
                        <literal>"clcg2"</literal>, <literal>"clcg4"</literal>, <literal>"urand"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setgen"</term>
                <listitem>
                    <para>
                        <code>grand("setgen",gen)</code> sets the current base generator to be
                        <varname>gen</varname> a string among <literal>"mt"</literal>,
                        <literal>"kiss"</literal>,
                        <literal>"clcg2"</literal>, <literal>"clcg4"</literal>, <literal>"urand"</literal>.
                        Notice that this call returns the new current generator, i.e.
                        <varname>gen</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "getsd"</term>
                <listitem>
                    <para>
                        <code>S = grand("getsd")</code> gets the current state (the current seeds) of
                        the current base generator ; <varname>S</varname> is given as a column vector
                        (of integers) of dimension <literal>625</literal> for mt (the first being
                        an index in <literal>[1,624]</literal>), <literal>4</literal> for kiss,
                        <literal>2</literal> for clcg2,  <literal>4</literal> for clcg4 (for this
                        last one you get the current state of the current virtual generator) and
                        <literal>1</literal> for urand.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setsd"</term>
                <listitem>
                    <para>
                        <code>grand("setsd", S)</code> and <code>grand("setsd", s1[, s2, s3, s4])</code>
                        set the state of the current  base generator (the new seeds) :
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>for mt</term>
                            <listitem>
                                <para>
                                    <varname>S</varname> is a vector of integers of dim
                                    <literal>625</literal> (the first component is an index
                                    and must be in <literal>[1,624]</literal>, the
                                    <literal>624</literal> last ones must be in
                                    <literal>[0,2^32[</literal>) (but must not be all zeros).
                                    A simpler initialization may be done with only one integer
                                    <varname>s1</varname> (<varname>s1</varname> must be in
                                    <literal>[0,2^32[</literal>) ;
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>for kiss</term>
                            <listitem>
                                <para>
                                    four integers <varname>s1</varname>, <varname>s2</varname>,
                                    <varname>s3</varname>, <varname>s4</varname> in
                                    <literal>[0,2^32[</literal> must be provided ;
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>for clcg2</term>
                            <listitem>
                                <para>
                                    two integers <varname>s1</varname> in <literal>[1,2^31-86]</literal>
                                    and <varname>s2</varname> in  <literal>[1,2^31-250]</literal>
                                    must be given.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>for clcg4</term>
                            <listitem>
                                <para>
                                    four integers <varname>s1</varname> in <literal>[1,2^31-2]</literal>,
                                    <varname>s2</varname>
                                    in <literal>[1,2^31-106]</literal>, <varname>s3</varname> in
                                    <literal>[1,2^31-226]</literal>, <varname>s4</varname> in
                                    <literal>[1,2^31-326]</literal> are required.
                                </para>
                                <para>
                                    <caution>
                                        With clcg4 you set the seeds of the current virtual
                                        generator but you may lost the synchronization between this one
                                        and the others virtual generators (i.e. the sequence generated
                                        is not warranty to be non-overlapping with a sequence generated
                                        by another virtual generator) =&gt; use instead the "setall" option.
                                    </caution>
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>for urand</term>
                            <listitem>
                                <para>
                                    <literal>1</literal> integer <varname>s1</varname> in
                                    <literal>[0,2^31[</literal> must be given.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "phr2sd"</term>
                <listitem>
                    <para>
                        <literal>Sd = grand("phr2sd", phrase)</literal> given a
                        <varname>phrase</varname> (character string) generates
                        a <literal>1 x 2</literal> vector <literal>Sd</literal> which may be used as
                        seeds to change the state of a
                        base generator (initially suited for clcg2).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Options specific to clcg4</title>
        <para>
            The clcg4 generator may be used as the others generators but it offers the advantage
            to be split in several (<literal>101</literal>) virtual generators with non-overlapping
            sequences (when you use a classic generator you may change the initial state (seeds)
            in order to get another sequence but you are not warranty to get a complete  different one).
            Each virtual generator corresponds to a sequence of <literal>2^72</literal> values which is
            further split into <literal>V=2^31</literal> segments (or blocks) of length <literal>W=2^41</literal>.
            For a given virtual generator you have the possibility to return at the beginning of the
            sequence or at the beginning of the current segment or to go directly at the next segment.
            You may also change the initial state (seed) of the generator <literal>0</literal> with the
            <literal>"setall"</literal> option which then change also the initial state of the other virtual generators
            so as to get synchronization, i.e. in function of the new initial state of gen <literal>0</literal>
            the initial state of gen <literal>1..100</literal> are recomputed so as to get <literal>101</literal>
            non-overlapping sequences.
        </para>
        <variablelist>
            <varlistentry>
                <term>action = "setcgn"</term>
                <listitem>
                    <para>
                        <literal>grand("setcgn",G)</literal> sets the current virtual generator for clcg4 (when clcg4
                        is set, this is the virtual (clcg4) generator number <literal>G</literal> which is used);  the virtual clcg4
                        generators are numbered from <literal>0,1,...,100</literal> (and so <literal>G</literal> must be an integer
                        in  <literal>[0,100]</literal>) ; by default the current virtual generator is <literal>0</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "getcgn"</term>
                <listitem>
                    <para>
                        <code>S = grand("getcgn")</code> returns the number of the current virtual clcg4 generator.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "initgn"</term>
                <listitem>
                    <para>
                        <code>grand("initgn", I)</code> reinitializes the state of the current virtual generator
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>I = -1</term>
                            <listitem>
                                <para>sets the state to its initial seed</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>I = 0</term>
                            <listitem>
                                <para>sets the state to its last (previous) seed (i.e. to the beginning  of the current segment)</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>I = 1</term>
                            <listitem>
                                <para>
                                    sets the state to a new seed <literal>W</literal> values from its last seed (i.e. to the beginning
                                    of the next segment) and resets the current segment parameters.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setall"</term>
                <listitem>
                    <para>
                        <code>grand("setall", s1, s2, s3, s4)</code> sets the initial state of generator <literal>0</literal>
                        to  <varname>s1</varname>, <varname>s2</varname>, <varname>s3</varname>, <varname>s4</varname>. The initial seeds of the other generators are set accordingly
                        to have synchronization. For constraints on  <varname>s1</varname>, <varname>s2</varname>, <varname>s3</varname>, <varname>s4</varname> see the <literal>"setsd"</literal> action.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "advnst"</term>
                <listitem>
                    <para>
                        <code>grand("advnst", K)</code> advances the state of the current generator by <literal>2^K</literal> values
                        and  resets the initial seed to that value.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            In the following example, we generate random numbers from various distributions and
            plot the associated histograms.
        </para>
        <programlisting role="example"><![CDATA[
// Returns a 400 x 800 matrix of random doubles,
// with normal distribution and average 0 and standard deviation 1.
R = grand(400,800,"nor",0,1);
scf();
histplot(10,R);
xtitle("Normal random numbers from grand","X","Frequency");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400,800,"nor",0,1);
            histplot(10,R);
            xtitle("Normal random numbers from grand","X","Frequency");
        </scilab:image>

        <programlisting role="example"><![CDATA[
// Returns a 400 x 800 matrix of random doubles,
// uniform in [0,1).
R = grand(400,800,"def");
scf();
histplot(10,R);
xtitle("Uniform random numbers from grand","X","Frequency");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400,800,"def");
            histplot(10,R);
            xtitle("Uniform random numbers from grand","X","Frequency");
        </scilab:image>

        <programlisting role="example"><![CDATA[
// Returns a 400 x 800 matrix of random doubles,
// with Poisson distribution and average equal to 5.
R = grand(400,800,"poi",5);
scf();
histplot(10,R);
xtitle("Poisson random numbers from grand","X","Frequency");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400,800,"poi",5);
            histplot(10,R);
            xtitle("Poisson random numbers from grand","X","Frequency");
        </scilab:image>

        <para>
            In the following example, we generate random numbers from the exponential distribution and
            then compare the empirical with the theoretical distribution.
        </para>
        <programlisting role="example"><![CDATA[
lambda=1.6;
N=100000;
X = grand(1,N,"exp",lambda);
scf();
classes = linspace(0,12,25);
histplot(classes,X);
x=linspace(0,12,25);
y = (1/lambda)*exp(-(1/lambda)*x);
plot(x,y,"ro-");
legend(["Empirical" "Theory"]);
xtitle("Exponential random numbers from grand","X","Frequency");
 ]]></programlisting>
        <scilab:image localized="true">
            lambda=1.6;
            N=100000;
            X = grand(1,N,"exp",lambda);
            classes = linspace(0,12,25);
            histplot(classes,X)
            x=linspace(0,12,25);
            y = (1/lambda)*exp(-(1/lambda)*x);
            plot(x,y,"ro-");
            legend(["Empirical" "Theory"]);
            xtitle("Exponential random numbers from grand","X","Frequency");
        </scilab:image>
        <para>
            In the following example, we generate random numbers from the gamma distribution and
            then compare the empirical with the theoretical distribution.
        </para>
        <programlisting role="example"><![CDATA[
N=10000;
A=10;
B=4;
R=grand(1,N,"gam",A,B);
XS=gsort(R,"g","i")';
PS=(1:N)'/N;
P=cdfgam("PQ",XS,A*ones(XS),B*ones(XS));
scf();
plot(XS,PS,"b-"); // Empirical distribution
plot(XS,P,"r-"); // Theoretical distribution
legend(["Empirical" "Theory"]);
xtitle("Cumulative distribution function of Gamma random numbers","X","F");
 ]]></programlisting>
        <scilab:image localized="true">
            N=10000;
            A=10;
            B=4;
            R=grand(1,N,"gam",A,B);
            XS=gsort(R,"g","i")';
            PS=(1:N)'/N;
            P=cdfgam("PQ",XS,A*ones(XS),B*ones(XS));
            scf();
            plot(XS,PS,"b-"); // Empirical distribution
            plot(XS,P,"r-"); // Theoretical distribution
            legend(["Empirical" "Theory"]);
            xtitle("Cumulative distribution function of Gamma random numbers","X","F");
        </scilab:image>
        <para>
            In the following example, we generate 10 random integers in the [1,365] interval.
        </para>
        <programlisting role="example"><![CDATA[
grand(10,1,"uin",1,365)
 ]]></programlisting>
        <para>
            In the following example, we generate 12 permutations of the [1,2,...,7] set.
            The 12 permutations are stored column by column.
        </para>
        <programlisting role="example"><![CDATA[
grand(12,"prm",(1:7)')
 ]]></programlisting>
        <para>
            In the following example, we generate a
            <literal>10</literal>-by-<literal>10</literal>-by-<literal>10</literal>
            hypermatrix of random numbers from the "normal" distribution and plot the associated histograms.
            Showing the first and last layers.
        </para>
        <programlisting role="example"><![CDATA[
// Returns a 10 x 10 x 10 hypermatrix of random doubles,
// with normal distribution, average 0 and standard deviation 1.
// Showing the first and last layers.
R = grand(10,10,10,"nor",0,1);

subplot(1,2,1)
bar3d(R(:,:,1));
xtitle("Layer 1");
subplot(1,2,2)
bar3d(R(:,:,10));
xtitle("Layer 10");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(10,10,10,"nor",0,1);
            subplot(1,2,1)
            bar3d(R(:,:,1));
            xtitle("Layer 1");
            subplot(1,2,2)
            bar3d(R(:,:,10));
            xtitle("Layer 10");
        </scilab:image>
    </refsection>
    <refsection>
        <title>Get predictable or less predictable numbers</title>
        <para>
            The pseudo random number generators are based on deterministic sequences.
            In order to get reproducible simulations, the initial seed of the generator is constant,
            such that the sequence will remain the same from a session to the other.
            Hence, by default, the first numbers produced by <function>grand</function> are always
            the same.
        </para>
        <para>
            In some situations, we may want to initialize the seed of the generator in
            order to produce less predictable numbers.
            In this case, we may initialize the seed with the output of the <function>getdate</function> function:
        </para>
        <programlisting role="example"><![CDATA[
n=getdate("s");
grand("setsd",n)
    ]]></programlisting>
    </refsection>
    <refsection>
        <title>Test example for clcg4</title>
        <para>
            An example of  the  need of the splitting capabilities of clcg4 is as  follows.
            Two statistical techniques are being compared on  data of  different sizes. The first
            technique uses   bootstrapping  and is   thought to   be  as accurate using less data
            than the second method   which  employs only brute force.  For the first method, a data
            set of size uniformly distributed between 25 and 50 will be generated.  Then the data set
            of the specified size will be generated and analyzed.  The second method will  choose a
            data set size between 100 and 200, generate the data  and analyze it.  This process will
            be repeated 1000 times.  For  variance reduction, we  want the  random numbers  used in the
            two methods to be the  same for each of  the 1000 comparisons.  But method two will  use more
            random  numbers than   method one and  without this package, synchronization might be difficult.
            With clcg4, it is a snap.  Use generator 0 to obtain  the sample size for  method one and
            generator 1  to obtain the  data.  Then reset the state to the beginning  of the current  block
            and do the same  for the second method.  This assures that the initial data  for method two is
            that used by  method  one.  When both  have concluded,  advance the block for both generators.
        </para>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="rand">rand</link>
            </member>
            <member>
                <link linkend="sprand">sprand</link>
            </member>
            <member>
                <link linkend="ssrand">ssrand</link>
            </member>
            <member>
                <link linkend="randpencil">randpencil</link>
            </member>
            <member>
                <link linkend="genmarkov">genmarkov</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
