<?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) 2011 - DIGITEO - Michael Baudin
 * Copyright (C) 2013 - Samuel GOUGEON : extension aux 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="fr" xml:id="grand">
    <refnamediv>
        <refname>grand</refname>
        <refpurpose>Générateur de nombres pseudo-aléatoires</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</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>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>m, n, o</term>
                <listitem>
                    <para>
                        entiers : dimensions de la matrice de nombres aléatoires à obtenir
                        <varname>Y</varname>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>X </term>
                <listitem>
                    <para>
                        un vecteur, une matrice ou une hypermatrice dont seules les dimensions
                        (<varname>m</varname> x <varname>n</varname> x ...) sont utilisées
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PDFname</term>
                <listitem>
                    <para>
                        Nom de la fonction de densité de probabilité choisie :
                        <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>
                        Vecteur, matrice ou hypermatrice des nombres aléatoires générés, de taille <varname>m</varname> x <varname>n</varname> x ... (encodage décimal)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>
                        résultat de l'action (une chaîne ou un vecteur colonne)
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Cette fonction produit des nombres aléatoires selon différentes distributions
            de probabilité.
        </para>
        <para>
            Les séquences d'appel
            <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>
            produisent une matrice de nombres réels aléatoires, de taille
            <varname>m</varname> x <varname>n</varname>.
        </para>
        <para>
            La syntaxe
            <screen><![CDATA[
Y = grand(m, n, o, …, PDFname, …)
]]></screen>
            produit une hypermatrice de nombres réels aléatoires, de taille
            <varname>m</varname> x <varname>n</varname> x <varname>o</varname> x... .
        </para>
        <para>
            <screen><![CDATA[
Y = grand(X, PDFname, …)
]]></screen>
            produit un scalaire, vecteur, matrice ou hypermatrice de nombres réels aléatoires,
            de taille <literal>size(X)</literal>.
            <varname>X</varname> est utilisé uniquement pour dimensionner <varname>Y</varname>
            à son image.
        </para>
        <para>
            Les séquences d'appel
        <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>
            produisent un tableau aléatoire dont les dimensions dépendent de <varname>n</varname>
            et de celles des paramètres <varname>Mean</varname>, <varname>P</varname> ou
            <varname>array</varname> (voir les détails plus loin).
        </para>
        <para>
            Les séquences d'appel
            <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>
            configurent ou demandent les paramètres des générateurs aléatoires.
        </para>
    </refsection>
    <refsection>
        <title>Générer des nombres aléatoires selon une loi donnée</title>
        <variablelist>
            <varlistentry>
                <term>beta</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "bet", A, B)</literal> génère des nombres aléatoires suivant
                        la loi beta de paramètres <varname>A</varname> and <varname>B</varname>.
                        La densité de cette loi est (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> et <varname>B</varname> devant être des réels &gt;
                        10<superscript>-37</superscript>.
                        Fonction(s) associée(s) : <link linkend="cdfbet">cdfbet</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>binomiale</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "bin", N, p)</literal> génère des nombres
                        aléatoires suivant la loi binomiale de paramètres <varname>N</varname>
                        (entier &gt; 0) et <varname>p</varname> (réel dans [0,1]) : nombre de succès
                        au cours de <varname>N</varname> épreuves de Bernouilli de probabilité de
                        succès <varname>p</varname>.
                        Fonctions associées : <link linkend="binomial">binomial</link>,
                        <link linkend="cdfbin">cdfbin</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>binomiale négative</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "nbn", N, p)</literal> génère des nombres aléatoires
                        suivant la loi binomiale négative de paramètres <varname>N</varname>
                        (entier &gt; 0) et <varname>p</varname> (réel dans ]0,1[) : nombre d'échecs
                        avant d'obtenir <varname>N</varname> succès dans des épreuves de Bernouilli
                        de probabilité de succès <varname>p</varname>.
                        Fonction associée : <link linkend="cdfnbn">cdfnbn</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>chi 2</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "chi", Df)</literal> génère des nombres aléatoires
                        suivant la loi du chi 2
                        à <varname>Df</varname> (réel &gt; 0.0) degrés de liberté.
                        Fonction associée : <link linkend="cdfchi">cdfchi</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>chi 2 non centrée</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "nch", Df, Xnon)</literal> génère des nombres
                        aléatoires suivant la loi du chi 2
                        non centrée à <varname>Df</varname> degrés de liberté (réel &gt;= 1.0)
                        le paramètre de décentrage étant <varname>Xnonc</varname> (réel &gt;= 0.0).
                        Fonction associée : <link linkend="cdfchn">cdfchn</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>exponentielle</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "exp", Av)</literal> génère des nombres aléatoires
                        suivant la loi exponentielle
                        de moyenne <varname>Av</varname> (réel &gt;= 0.0).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>F variance ratio</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "f", Dfn, Dfd)</literal> génère des nombres
                        aléatoires suivant la loi F (variance ratio) à <varname>Dfn</varname>
                        (réel &gt; 0.0) degrés de liberté au numérateur et
                        <varname>Dfd</varname> (réel &gt; 0.0) degrés de liberté au dénominateur.
                        Fonction associée : <link linkend="cdff">cdff</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>non central F variance ratio</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "nf", Dfn, Dfd, Xnon)</literal> génère des nombres
                        aléatoires suivant la loi F (variance ratio) non centrée à
                        <varname>Dfn</varname> (réel &gt;= 1) degrés de liberté au numérateur,
                        et <varname>Dfd</varname> (réel &gt; 0) degrés de liberté au dénominateur,
                        <varname>Xnonc</varname> (réel &gt;= 0) étant le paramètre de décentrage.
                        Fonction associée : <link linkend="cdffnc">cdffnc</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>gamma</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "gam", shape, rate)</literal> génère des nombres
                        aléatoires suivant la loi gamma de paramètres <varname>shape</varname>
                        (réel &gt; 0) et <varname>scale</varname> (réel &gt; 0). La densité est :
                    </para>
                    <para>
                        <latex>
                            \dfrac{ \textrm{rate}^{\textrm{shape}} x^{\textrm{shape}-1} e^{-x.\textrm{rate}}}{\gamma(\textrm{shape}) }
                        </latex>
                    </para>
                    <para>
                        Fonctions associées : <link linkend="gamma">gamma</link>,
                        <link linkend="cdfgam">cdfgam</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Gauss Laplace (normale)</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "nor", Av, Sd)</literal> génère des nombres
                        aléatoires suivant la loi normale, de moyenne <varname>Av</varname> (réel)
                        et d'écart type <varname>Sd</varname> (réel &gt;= 0).
                        Fonctions associées : <link linkend="cdfnor">cdfnor</link>,
                        <link linkend="erf">erf</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>multi normale</term>
                <listitem>
                    <para>
                        <literal>Y = grand(n, "mn", Mean, Cov)</literal> génère <varname>n</varname>
                        réalisations indépendantes de la loi multi-normale ; <varname>Mean</varname>
                        doit être un vecteur colonne <literal>m</literal> x <literal>1</literal>, et
                        <varname>Cov</varname> une matrice carrée
                        <literal>m</literal> x <literal>m</literal> symétrique et définie positive.
                        <varname>Y</varname> est alors une matrice
                        <literal>m</literal> x <literal>n</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>geometrique</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "geom", p)</literal> génère des nombres aléatoires
                        suivant la loi geométrique de paramètre <varname>p</varname> : nombre
                        d'épreuves de Bernouilli (de probabilité de succès
                        <varname>p</varname>) jusqu'à obtenir un succès
                        (avec <varname>p</varname> dans [1.3e-307, 1]).
                    </para>
                    <para>
                        <varname>Y</varname> contient des nombres réels positifs à valeur entière
                        qui sont "le nombre de tentatives nécessaire pour obtenir un succès" pour
                        chaque tirage.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>markov</term>
                <listitem>
                    <para>
                        <literal>Y = grand(n, "markov", P, x0)</literal> génère <varname>n</varname>
                        états successifs d'une chaîne Markov décrite par la matrice de transition
                        <varname>P</varname>. L'état initial est donné par
                        <varname>x0</varname>. Si <varname>x0</varname> est une matrice de taille
                        <literal>m = size(x0, "*")</literal>
                        alors <varname>Y</varname> est une matrice de taille <literal>m x n</literal>.
                        <literal>Y(i,:)</literal> est le chemin à partir de l'état initial
                        <literal>x0(i)</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>multinomiale</term>
                <listitem>
                    <para>
                        <literal>Y = grand(n, "mul", nb, P)</literal> génère <varname>n</varname>
                        réalisations indépendantes de la loi multinomiale :
                        classer <varname>nb</varname> éventualités dans <literal>m</literal>
                        catégories (mettre <varname>nb</varname> "boules" dans <literal>m</literal>
                        "boites").
                        <literal>P(i)</literal> est la probabilité qu'une éventualité
                        soit de categorie i.
                        <varname>P</varname> le vecteur des probabilités est de taille
                        <literal>m-1</literal> (la probabilté de la catégorie <literal>m</literal>
                        étant <literal>1-sum(P)</literal>).
                        <varname>Y</varname> est alors de dimensions <literal>m x n</literal>,
                        chaque colonne <literal>Y(:,j)</literal> étant une réalisation de cette loi :
                        <literal>Y(i,j)</literal> est le nombre d'éventualités classées en catégorie
                        <literal>i</literal> pour la <literal>j</literal> ème
                        réalisation (<literal>sum(Y(:,j)) = nb</literal>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Poisson</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "poi", mu)</literal> génère des nombres aléatoires
                        suivant la loi de Poisson de moyenne <varname>mu</varname> (réel &gt;= 0.0).
                        Fonction associée : <link linkend="cdfpoi">cdfpoi</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>permutations aléatoires</term>
                <listitem>
                    <para>
                        <code>Y = grand(n, "prm", array)</code> produit
                        <varname>n</varname> permutations aléatoires des éléments de
                        <varname>array</varname>.
                        <varname>array</varname> peut être un vecteur, une matrice ou une
                        hypermatrice de nombres réels ou complexes, d'entiers, booléens, polynômes
                        ou textes ; dense ou creuse.
                        <itemizedlist>
                            <listitem>
                                Si <varname>array</varname> est un vecteur ligne <literal>1 x m</literal>,
                                <varname>Y</varname> est une matrice <literal>n x m</literal>.
                            </listitem>
                            <listitem>
                                Si <varname>array</varname> est un vecteur colonne <literal>m x 1</literal>,
                                <varname>Y</varname> est une matrice <literal>m x n</literal>.
                            </listitem>
                            <listitem>
                                Si <varname>array</varname> est une matrice <literal>m x p</literal>,
                                <varname>Y</varname> est une hypermatrice <literal>m x p x n</literal>.
                            </listitem>
                            <listitem>
                                If <varname>array</varname> une hypermatrice <literal>m x p x q…</literal>,
                                <varname>Y</varname> est une hypermatrice
                                <literal>m x p x q… x n</literal>.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        La fonction <literal>randperm(n)</literal> d'Octave est équivalente à
                        <literal>grand(1,'prm', 1:n)</literal>, et <literal>randperm(n, k)</literal>
                        est réalisé par Scilab avec <literal>grand(1,'prm', 1:n)(1:k)</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniforme (def)</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "def")</literal> génère des nombres aléatoires
                        suivant la loi uniforme sur <literal>[0,1[</literal> (1 n'est jamais produit).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniforme (unf)</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "unf", Low, High)</literal> génère des nombres aléatoires suivant la loi
                        uniforme sur <literal>[Low, High[</literal> (<varname>High</varname> n'est
                        jamais atteint).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniforme (uin)</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "uin", Low, High)</literal> génère des entiers aléatoires suivant la loi uniforme
                        sur <literal>[Low, High]</literal>. <varname>High</varname>
                        et <varname>Low</varname> doivent être des entiers tels que
                        <literal>(High-Low+1)  &lt; 2147483561</literal>
                        .
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>uniforme (lgi)</term>
                <listitem>
                    <para>
                        <literal>Y = grand(m, n, "lgi")</literal> retourne la sortie du générateur de base courant : des entiers
                        aléatoires suivant une loi uniforme sur :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>[0, 2^32 - 1]</literal> for mt and kiss;
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>[0, 2147483561]</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>Actions sur le(s) générateur(s) de base</title>
        <para>
            Depuis Scilab-2.7 vous avez la possibilité de choisir parmi plusieurs générateurs de base
            (donnant des entiers aléatoires suivant la loi "lgi") :
        </para>
        <variablelist>
            <varlistentry>
                <term>mt</term>
                <listitem>
                    <para>
                        Le Mersenne-Twister de M. Matsumoto and T. Nishimura, période d'environ <literal>2^19937</literal>,
                        état interne donné par <literal>624</literal> entiers (plus un index); c'est le générateur
                        par défaut.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>kiss</term>
                <listitem>
                    <para>
                        Le Keep It Simple Stupid de G. Marsaglia,  période d'environ <literal>2^123</literal>,
                        état interne donné par <literal>4</literal> entiers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clcg2</term>
                <listitem>
                    <para>
                        Une combinaison de 2 générateurs linéaires congruentiels de P. L'Ecuyer,
                        période d'environ <literal>2^61</literal>, état interne donné par <literal>2</literal> entiers ;
                        c'était le seul générateur de base utilisé auparavent par grand (cette
                        version est cependant légèrement différente de l'ancienne).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clcg4</term>
                <listitem>
                    <para>
                        Une combinaison de 4 générateurs linéaires congruentiels de P. L'Ecuyer,
                        période d'environ <literal>2^121</literal>, état interne donné par 4 entiers ; ce générateur
                        peut être partagé en <literal>101</literal> générateur virtuels (en fait la suite de
                        longueur <literal>2^121</literal> peut être découpée en <literal>101</literal> sous-suites) ce qui peut
                        être utile dans certains cas (voir 'Actions specifiques à clcg4' et
                        'Exemple d'utilisation de clcg4').
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>urand</term>
                <listitem>
                    <para>
                        Le générateur de base utilisé par la fonction
                        <link linkend="rand">rand</link>, état interne constitué d'un entier, période de
                        <literal>2^31</literal>.
                        Ce generateur est fondé sur "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.
                        C'est le plus rapide de cette liste, mais ses qualités statistiques
                        sont inférieures aux autres générateurs.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Actions</title>
        <variablelist>
            <varlistentry>
                <term>action = "getgen"</term>
                <listitem>
                    <para>
                        <literal>S = grand("getgen")</literal> retourne le nom du générateur de base actuel (<literal>S</literal> est
                        l'une des chaînes de caractères "mt", "kiss", "clcg2", "clcg4", "urand").
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setgen"</term>
                <listitem>
                    <para>
                        <literal>grand("setgen", gen)</literal> permet de changer le générateur de base : <literal>gen</literal>
                        doit être l'une des chaînes de caractères "mt", "kiss", "clcg2", "clcg4", "urand".
                        En cas de succès la fonction retourne cette même chaîne.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "getsd"</term>
                <listitem>
                    <para>
                        <literal>S = grand("getsd")</literal> retourne l'état interne actuel (les 'germes' dans l'ancienne
                        appelation quoique ce terme désigne plutôt l'état initial) du générateur de base courant ;
                        <literal>S</literal> est un vecteur colonne (d'entiers) de dimension <literal>625</literal>
                        pour mt (la première composante étant un 'index' sur l'état, c-a-d un entier de l'intervalle
                        <literal>[1,624]</literal>), <literal>4</literal>
                        pour kiss, <literal>2</literal> pour clcg2 , <literal>4</literal> pour clcg4
                        (pour ce dernier vous obtenez l'état interne du générateur virtuel courant), et <literal>1</literal>
                        pour urand.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setsd"</term>
                <listitem>
                    <para>
                        <literal>grand("setsd", S), grand("setsd", s1[, s2, s3, s4])</literal> impose l'état interne du générateur de
                        base courant :
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>pour mt</term>
                            <listitem>
                                <para>
                                    <literal>S</literal> est un vecteur d'entiers de dimension <literal>625</literal> (la première composante
                                    étant un index sur <literal>[1,624]</literal>), les <literal>624</literal> dernières composantes doivent
                                    être dans <literal>[0,2^32[</literal>) (mais ne doivent pas être toutes nulles) ; une initialisation
                                    plus simple est possible (et recommandée) en donnant un seul entier <literal>s1</literal> (<literal>s1</literal> appartenant
                                    à <literal>[0,2^32[</literal>) ;
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pour kiss</term>
                            <listitem>
                                <para>
                                    <literal>4</literal> entiers <literal>s1, s2, s3, s4</literal> dans <literal>[0,2^32[</literal> doivent être
                                    fournis ;
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pour clcg2</term>
                            <listitem>
                                <para>
                                    <literal>2</literal> entiers <literal>s1</literal> dans <literal>[1, 2147483562]</literal> et <literal>s2</literal>
                                    dans <literal>[1, 2147483398]</literal> doivent être fournis ;
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pour clcg4</term>
                            <listitem>
                                <para>
                                    <literal>4</literal> entiers <literal>s1</literal> dans <literal>[1, 2147483646]</literal>, <literal>s2</literal>
                                    dans <literal>[1, 2147483542]</literal>, <literal>s3</literal> dans <literal>[1, 2147483422]</literal>,
                                    <literal>s4</literal> dans <literal>[1, 2147483322]</literal> sont requis ;
                                    <literal>ATTENTION</literal> : avec clcg4 vous positionnez l'état interne du générateur virtuel
                                    courant mais vous perdez alors la synchronisation avec les autres générateurs virtuels.
                                    (=&gt; si vous utilisez clcg4 avec différents générateurs virtuels, il faut utiliser
                                    l'option "setall" qui permet de changer l'état interne (du générateur numéro 0) tout en
                                    recalculant l'état initial des 100 autres générateurs virtuels).
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pour urand</term>
                            <listitem>
                                <para>
                                    <literal>1</literal> entier <literal>s1</literal> appartenant à
                                    <literal>[0, 2^31[</literal> est requis.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "phr2sd"</term>
                <listitem>
                    <para>
                        <literal>Sd = grand("phr2sd", phrase)</literal> étant donnée une chaîne de caractères <literal>phrase</literal>
                        cet appel retourne un vecteur <literal>1 x 2</literal> qui peut être utilisé comme
                        état interne pour un générateur de base (initialement adapté pour clcg2).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Options specifiques à clcg4</title>
        <para>
            Le générateur clcg4 peut être utilisé comme les autres mais il offre l'avantage de pouvoir être
            découpé en (<literal>101</literal>) générateurs virtuels différents, c-a-d avec des séquences sans
            intersection (quand vous utilisez un générateur classique vous pouvez changer l'état initial
            de façon à obtenir une autre séquence mais vous n'êtes pas complètement sûr d'obtenir une
            séquence complètement différente). Chaque générateur virtuel correspond à une séquence de
            longueur <literal>2^72</literal> qui est de plus découpée en <literal>V = 2^31</literal> segments de longueur
            <literal>W = 2^41</literal>. Pour un générateur virtuel donné vous pouvez retourner au début de la séquence
            ou au début du segment ou bien au début du segment suivant.
            Vous pouvez aussi changer l'état initial du générateur <literal>0</literal> avec l'option
            "setall" qui recalcule l'état initial des autres générateurs virtuels de sorte à obtenir
            la synchronisation entre les générateurs (c-a-d qu'en fonction du nouvel état initial du générateur
            <literal>0</literal> l'état initial des générateurs <literal>1..100</literal> sont recalculés de façon à
            obtenir <literal>101</literal> séquences qui ne s'intersectent pas).
        </para>
        <variablelist>
            <varlistentry>
                <term>action = "setcgn"</term>
                <listitem>
                    <para>
                        <literal>grand("setcgn", G)</literal> sélectionne le générateur virtuel numéro <literal>G</literal> :
                        lorsque le générateur de base courant est clcg4, c'est le générateur virtuel <literal>G</literal>
                        qui sera alors utilisé ; les <literal>101</literal> générateurs virtuels sont numérotés
                        <literal>0,1,...,100</literal> (ainsi <literal>G</literal> doit être un entier de l'intervalle
                        <literal>[0, 100]</literal>) ; par défaut le générateur virtuel courant est celui de numéro
                        <literal>0</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "getcgn"</term>
                <listitem>
                    <para>
                        <literal>S = grand("getcgn")</literal> retourne le numéro du générateur
                        virtuel courant.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "initgn"</term>
                <listitem>
                    <para>
                        <literal>grand("initgn", I)</literal> réinitialise l'état du générateur virtuel courant :
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>I = -1</term>
                            <listitem>
                                <para>remet l'état à sa valeur initiale</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>I = 0</term>
                            <listitem>
                                <para>remet l'état au début du segment courant</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>I = 1</term>
                            <listitem>
                                <para>
                                    positionne l'état au début du segment suivant et met à jour les valeurs définissant
                                    le segment courant (vous ne pouvez pas revenir au début du segment précédent).
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "setall"</term>
                <listitem>
                    <para>
                        <literal>grand("setall", s1, s2, s3, s4)</literal> impose l'état interne du générateur virtuel
                        de numéro <literal>0</literal> à <literal>s1, s2, s3, s4</literal>. L'état initial des autres générateurs est
                        alors reconstruit (de façon à obtenir 101 séquences qui ne s'intersectent pas). Voir
                        l'action "setsd" pour les contraintes sur <literal>s1, s2, s3, s4</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action = "advnst"</term>
                <listitem>
                    <para>
                        <literal>grand("advnst", K)</literal> avance l'état du générateur virtuel courant de <literal>2^K</literal>
                        valeurs et réinitialise l'état initial (du générateur virtuel courant) à
                        ce nouvel état.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <para>
            Dans l'exemple suivant, nous produisons des nombres aléatoires
            associés à différentes lois de distribution et dessinons les histogrammes
            associés.
        </para>
        <programlisting role="example"><![CDATA[
// Renvoie une matrice de taille 400 x 800 de doubles aléatoires,
// avec une distribution normale de moyenne 0 et d'écart-type 1.
R = grand(400, 800, "nor", 0, 1);
scf();
histplot(10, R);
xtitle("Nombres aléatoires (loi normale) par grand", "X", "Fréquence");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400, 800, "nor", 0, 1);
            histplot(10, R);
            xtitle("Nombres aléatoires (loi normale) par grand", "X", "Fréquence");
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Renvoie une matrice de taille 400 x 800 de doubles aléatoires,
// uniformes dans [0, 1).
R = grand(400, 800, "def");
scf();
histplot(10, R);
xtitle("Nombres aléatoires uniformes par grand", "X", "Fréquence");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400, 800, "def");
            histplot(10, R);
            xtitle("Nombres aléatoires uniformes par grand", "X", "Fréquence");
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Renvoie une matrice de taille 400 x 800 de doubles aléatoires,
// avec une distribution de Poisson de moyenne 5.
R = grand(400, 800, "poi", 5);
scf();
histplot(10, R);
xtitle("Nombres aléatoires (loi de Poisson) par grand", "X", "Fréquence");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(400, 800, "poi", 5);
            histplot(10, R);
            xtitle("Nombres aléatoires (loi de Poisson) par grand", "X", "Fréquence");
        </scilab:image>
        <para>
            Dans l'exemple suivant, nous produisons des nombres aléatoires
            suivant la loi exponentielle et comparons ensuite la distribution empirique
            et la fonction de distribution théorique.
        </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(["Empirique" "Theorique"]);
xtitle("Loi exponentielle par grand", "X", "Fréquence");
 ]]></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(["Empirique" "Theorique"]);
            xtitle("Loi exponentielle par grand", "X", "Fréquence");
        </scilab:image>
        <para>
            Dans l'exemple suivant, nous générons des nombres aléatoires selon la distribution
            gamma et comparons la distribution empirique et la loi de distribution théorique.
        </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(["Empirique" "Théorique"]);
xtitle("Fonction de distribution cumulée de nombres aléatoires selon la loi Gamma", "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));
            plot(XS, PS, "b-");
            plot(XS, P, "r-");
            legend(["Empirique" "Théorique"]);
            xtitle("Fonction de distribution cumulée de nombres aléatoires selon la loi Gamma", "X", "F");
        </scilab:image>
        <para>
            Dans l'exemple suivant, nous générons 10 entiers aléatoires dans l'intervalle [1, 365].
        </para>
        <programlisting role="example"><![CDATA[
grand(10, 1, "uin", 1, 365)
 ]]></programlisting>
        <para>
            Dans l'exemple suivant, nous générons 12 permutations de l'ensemble [1,2,...,7].
            Les 12 permutations sont stockées colonne par colonne.
        </para>
        <programlisting role="example"><![CDATA[
grand(12, "prm", (1:7)')
 ]]></programlisting>
        <para>
            L'exemple suivant génère une hypermatrice <varname>10</varname>-par-<varname>10</varname>-par-<varname>10</varname>
            de nombre aléatoires provenant de la distribution "normale" et affiche les histogrammes associés.
            Le graphes montrent les première et dernière couches de la matrice.
        </para>
        <programlisting role="example"><![CDATA[
// Retourne une hypermatrice 400 x 800 x 10 de nombre aléatoires,
// avec la distribution normale, une moyenne de 0 et un écart-type de 1.
// Affichage de la première et dernière couches.
R = grand(10,10,10,"nor",0,1);
subplot(1,2,1)
bar3d(R(:,:,1));
xtitle("Couche 1");
subplot(1,2,2)
bar3d(R(:,:,10));
xtitle("Couche 10");
 ]]></programlisting>
        <scilab:image localized="true">
            R = grand(10,10,10,"nor",0,1);
            subplot(1,2,1)
            bar3d(R(:,:,1));
            xtitle("Couche 1");
            subplot(1,2,2)
            bar3d(R(:,:,10));
            xtitle("Couche 10");
        </scilab:image>
    </refsection>
    <refsection>
        <title>Produire des nombres prévisibles ou moins prévisibles</title>
        <para>
            Les générateurs pseudo aléatoires sont fondés sur des séquences déterministes.
            Pour produire des simulations reproductibles, la graine du générateur est constante,
            de telle sorte que la séquence est la même d'une session à l'autre.
            En conséquence, par défaut, les premiers nombres produis par <literal>grand</literal>
            sont toujours les mêmes.
        </para>
        <para>
            Dans certaines situations, nous peut vouloir initialiser la graine du générateur
            dans le but de produire des nombres moins prédictibles.
            Dans ce cas, on peut initialiser la graine avec la sortie de la fonction <literal>getdate</literal> :
        </para>
        <programlisting role="example"><![CDATA[
n = getdate("s");
grand("setsd", n)
    ]]></programlisting>
    </refsection>
    <refsection>
        <title>Exemple d'utilisation de clcg4</title>
        <para>
            On cherche à comparer deux techniques statistiques sur des données de tailles différentes.
            La première, utilisant le 'bootstrapping' est supposée a priori aussi précise que
            la deuxième technique (utilisant uniquement la force brute) tout en utilisant moins
            de données. Pour la première méthode, un ensemble de données de taille n1, uniformément
            distribuée entre 25 et 50 devra être généré puis analysé par la méthode.  Pour la
            seconde méthode, on procède de même avec une taille n2 à choisir entre 100 et 200. Ce processus
            est répété 1000 fois. Pour la réduction de la variance, on veut que les nombres aléatoires
            utilisés dans les deux méthodes soient les mêmes pour chacune des 1000 comparaisons.
            Comme la deuxième méthode utilise plus de nombres aléatoires, la synchronisation
            peut être difficile si l'on utilise un générateur classique. Avec un générateur
            comme clcg4 c'est par contre très simple : utilisez le générateur 0 pour obtenir
            la taille n1 du jeux de données et le générateur 1 pour obtenir les données.
            Avec le générateur 0 tirer la taille n2 puis resélectionner le générateur 1 et revenez
            au début du segment courant pour obtenir les n2 données pour la deuxième méthode : ainsi
            les données initiales (les n1 premieres) sont les mêmes pour les deux méthodes.
            Pour la comparaison suivante, il suffit d'avancer le générateur 1 au segment suivant,
            etc...
        </para>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</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>
