path: root/modules/randlib/help/en_US/grand.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://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
 *
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at
 * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
 *
 -->
<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>Random numbers</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Calling Sequence</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,..,"..",...)
            Y = grand(X, ...)
            
            Y = grand(n, "mn", Mean, Cov)
            Y = grand(n, "markov", P, x0)
            Y = grand(n, "mul", nb, P)
            Y = grand(n, "prm", vect)
            
            S = grand("getgen")
            grand("setgen", gen)
            
            S = grand("getsd")
            grand("setsd", S)
            
            S = grand("phr2sd", phrase)
            
            grand("setcgn", G)
            S = grand("getcgn")
            
            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>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
            distributions.
        </para>
        <para>
            The calling sequences:
        </para>
        <para>
            <programlisting role="no-scilab-exec"><![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")
             ]]></programlisting>
        </para>
        <para>
            produce a <varname>m</varname>-by-<varname>n</varname> matrix with random entries.
            
            All these calling sequences can be extended to create a random hypermatrix with more than
            2 dimensions specified as integers listed before the type of statistical distribution:
        </para>
        <para>
            <programlisting role="no-scilab-exec"><![CDATA[
                Y = grand(m, n, o, ..., "..", ...)
            ]]></programlisting>
        </para>
        <para>
            The sizes of the expected random vector, matrix or hypermatrix can alternatively be specified with
        </para>
        <para>
            <programlisting role="no-scilab-exec"><![CDATA[
                Y = grand(X, ...)
            ]]></programlisting>
        </para>
        <para>
            where <varname>X</varname> of sizes <varname>m</varname>-by-<varname>n</varname>...
            is a matrix or an hypermatrix only used as template.
        </para>
        <para>
            The calling sequences:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
            Y = grand(n, "mn", Mean, Cov)
            Y = grand(n, "markov", P, x0)
            Y = grand(n, "mul", nb, P)
            Y = grand(n, "prm", vect)
        ]]></programlisting>
        <para>
            produce a <varname>m</varname>-by-<varname>n</varname> matrix
            with random entries, where <varname>m</varname> is the size of the argument <varname>Mean</varname>,
            <varname>Cov</varname>, <varname>P</varname> or <varname>vect</varname> depending
            on the case (see below for details).
        </para>
        <para>
            The calling sequences:
        </para>
        <programlisting role="no-scilab-exec"><![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)
        ]]></programlisting>
        <para>
            configure or quiery 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 <latex><![CDATA[(0 < x < 1)]]></latex>:
                    </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 <latex><![CDATA[>10^{-37}]]></latex>.  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^{-\textrm{rate} x}}{\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 <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 succes of <varname>p</varname>) until a
                        succes is met. <varname>p</varname> must be in
                        <latex>[p_{min},1]</latex> (with <latex> p_{min} = 1{,}3\times 10^{-307} </latex>).
                    </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", vect)</code> generates
                        <varname>n</varname> random permutations of <varname>vect</varname>.
                        <varname>vect</varname> can be a column vector of reals, or a vector, matrix or hypermatrix of
                        complexes, integers, booleans, polynomials or strings; full or sparse.
                        Due to the stack structure, <varname>vect</varname> should not and cannot be a row vector.
                        This feature covers Matlab's <code>randperm()</code> function,
                        because <code>randperm(n)</code> is equivalent to <code>grand(1,'prm',(1:n)')</code>
                        and <code>randperm(n, k)</code> can be obtained through
                        <code>grand(1,'prm',(1:n)'); ans(1:k)</code>.
                    </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 return).
                    </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 return).
                    </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, kiss and fsultra;
                            </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>fsultra</term>
                <listitem>
                    <para>
                        A Subtract-with-Borrow generator mixing with a congruential
                        generator of Arif Zaman and George Marsaglia, period more than <literal>10^356</literal>,
                        state given by an array of <literal>37</literal> integers (plus an index onto this array, a flag (<literal>0</literal> or <literal>1</literal>)
                        and another integer).
                    </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>, <literal>"fsultra"</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>, <literal>"fsultra"</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>40</literal> for fsultra, <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>
                                        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>
                        <varlistentry>
                            <term>for fsultra</term>
                            <listitem>
                                <para>
                                    <varname>S</varname> is a vector of integers of dim <literal>40</literal> (the first component
                                    is an index and must be in <literal>[0,37]</literal>, the 2nd component is a flag (0 or 1), the 3rd component is
                                    an integer in <literal>[1,2^32[</literal> and the 37 others integers are in <literal>[0,2^32[</literal>) ; a simpler (and recommended)
                                    initialization may be done with two integers <varname>s1</varname> and <varname>s2</varname> in
                                    <literal>[0,2^32[</literal>.
                                </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-by-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-by-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-by-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 <varname>10</varname>-by-<varname>10</varname>-by-<varname>10</varname>
            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-by-10-by-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)
hist3d(R(:,:,1));
xtitle("Layer 1");
subplot(1,2,2)
hist3d(R(:,:,10));
xtitle("Layer 10");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(10,10,10,"nor",0,1);
            subplot(1,2,1)
            hist3d(R(:,:,1));
            xtitle("Layer 1");
            subplot(1,2,2)
            hist3d(R(:,:,10));
            xtitle("Layer 10");
        </scilab:image>
    </refsection>
    <refsection>
        <title>Get predictible or less predictible 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>
        </simplelist>
    </refsection>
</refentry>