<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2011 - DIGITEO - Michael Baudin
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="rand" xml:lang="fr">
    <refnamediv>
        <refname>rand</refname>
        <refpurpose>Générateur de nombres pseudo-aléatoires</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            r = rand()
            r = rand(m1,m2,...)
            r = rand(m1,m2,...,key)
            r = rand(x)
            r = rand(x,key)

            s = rand("seed")
            rand("seed",s)

            rand(key)
            key = rand("info")
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>mi</term>
                <listitem>
                    <para>entiers</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>key</term>
                <listitem>
                    <para>
                        chaîne de caractères, <literal>"uniform"</literal> ou
                        <literal>"normal"</literal> (par défaut: <literal>key="uniform"</literal>)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        tableau (vecteur, matrice, hypermatrice) de booléens, nombres, ou polynomes,
                        dont uniquement les dimensions et le caractère réel ou complexes sont pris
                        en compte.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r</term>
                <listitem>
                    <para>
                        tableau de nombres décimaux ou complexes, de taille m1-par-m2-par-...
                        avec des valeurs aléatoires.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>s</term>
                <listitem>
                    <para>
                        un entier positif, la graine (par défaut: <literal>s=0</literal>).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Le but de cette fonction est de retourner un tableau de nombres dont les valeurs sont
            des nombres aléatoires réels ou complexes.
            En fonction des arguments d'entrée, la fonction peut renvoyer une
            matrice de doubles aléatoires or peut configurer ou récupérer la distribution des nombres
            aléatoires ou peut configurer ou récupérer la graine du générateur
            aléatoire.
        </para>
    </refsection>
    <refsection>
        <title>Générer des nombres aléatoires</title>
        <para>
            Sans l'argument <literal>key</literal> la syntaxe ci-dessous produit
            une matrice aléatoire dont chaque élément est la réalisation d'une
            variable aléatoire suivant une loi donnée (par défaut uniforme sur
            [0,1]).
        </para>
        <variablelist>
            <varlistentry>
                <term>r=rand()</term>
                <listitem>
                    <para>renvoit un scalaire aléatoire.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r=rand(m1,m2)</term>
                <listitem>
                    <para>
                        est une matrice aléatoire de dimensions <literal>m1</literal>
                        x <literal>m2</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r=rand(m1,m2,..,mn)</term>
                <listitem>
                    <para>
                        est une matrice aléatoire de dimensions <literal>m1</literal>
                        x <literal>m2</literal>,.. x <literal>mn</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>r=rand(a)</term>
                <listitem>
                    <para>
                        est une matrice aléatoire de mêmes dimensions que a.
                        <literal>rand(a)</literal> est complexe si <literal>a</literal> est
                        une matrice complexe.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Changer la distribution des nombres aléatoires</title>
        <para>
            S'il est présent, l'argument <literal>key</literal> permet de
            spécifier la loi suivie par défaut par la variable aléatoire.
        </para>
        <variablelist>
            <varlistentry>
                <term>rand("uniform")</term>
                <listitem>
                    <para>La loi par défaut est uniforme sur l'intervalle [0,1].</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rand("normal")</term>
                <listitem>
                    <para>
                        La loi par défaut est une loi normale centrée réduite (moyenne
                        0, variance 1).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>key=rand("info")</term>
                <listitem>
                    <para>renvoie la distribution courante, c'est à dire "uniform" ou "normal".</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Récupérer ou changer la graine</title>
        <para>
            Il est possible de réinitialiser l'état interne du générateur
            aléatoire (spécifié par un entier de l'intervalle [0,2^31-1]) ):
        </para>
        <variablelist>
            <varlistentry>
                <term>s=rand("seed")</term>
                <listitem>
                    <para>Renvoie la valeur courante de la graine.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rand("seed",s)</term>
                <listitem>
                    <para>
                        Configure la valeur <literal>s</literal> de la graine (par
                        défaut la graine est initialisée à <literal>s=0</literal> au premier
                        appel).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <para>
            Dans l'exemple suivant, nous générons des doubles associés à
            différentes distributions.
        </para>
        <programlisting role="example"><![CDATA[
// Récupère un double aléatoire (sur la distribution courante)
r=rand()
// Récupère une matrice de doubles de taille 4-par-6 (sur la distribution courante)
r=rand(4,6)
// Récupère une matrice de doubles de taille 4-par-6 de distribution uniforme
r=rand(4,6,"uniform")
// Génère une matrice de doubles aléatoires normaux centrés réduits de même taille que x
x=rand(4,4);
r=rand(x,"normal")
// Génère un tableau de taille 2-par-2-par-2 de doubles aléatoires
r=rand(2,2,2)
 ]]></programlisting>
        <para>
            Dans l'exemple suivant, nous changeons la distribution des nombres générés par <literal>rand</literal>.
            Nous produisons d'abord des nombres normaux centrés réduits, puis des nombres uniformes dans [0,1[.
        </para>
        <programlisting role="example"><![CDATA[
    // Configure le générateur sur la loi normale
    rand("normal")
    r=rand(4,6)
    // Récupère la distribution courante
    key=rand("info")
    // Configure le générateur sur la loi uniforme
    rand("uniform")
    r=rand(4,6)
    key=rand("info")
    ]]></programlisting>
        <para>
            Dans l'exemple suivant, nous générons une matrice complexe de doubles de taille 2-par-3,
            avec une distribution normale centrée réduite.
        </para>
        <programlisting role="example"><![CDATA[
    // Génère une matrice complex de doubles aléatoires de taille 2-par-3
    x=rand(2,3)+%i*rand(2,3)
    // Génère une matrice complexe de doubles normaux centrés réduits
    // de la même taille que x
    r=rand(x,"normal")
    ]]></programlisting>
        <para>
            Dans l'exemple suivant, nous dessinons la distribution de 1000 nombres
            uniformes produits par <literal>rand</literal>.
        </para>
        <programlisting role="example"><![CDATA[
    r=rand(1000,1,"uniform");
    scf();
    histplot(10,r);
    xtitle("Nombres uniformes par rand","X","Fréquence")
    ]]></programlisting>
        <para>
            Dans l'exemple suivant, nous dessinons la distribution de nombres normaux
            centrés réduits produits par <literal>rand</literal>.
        </para>
        <programlisting role="example"><![CDATA[
    r=rand(1000,1,"normal");
    scf();
    histplot(10,r);
    xtitle("Nombres normaux centrés réduits par rand","X","Fréquence")
    ]]></programlisting>
    </refsection>
    <refsection>
        <title>Obtenir des nombres aléatoires prévisibles ou moins prévisibles</title>
        <para>
            Le générateur pseudo-aléatoire "uniform" est une séquence déterministe
            dont le but est de reproduire une séquence de nombres aléatoire, indépendents
            et identiquement distribués dans l'intervalle [0,1[.
        </para>
        <para>
            Dans le but de pouvoir obtenir des simulations reproductibles,
            la graine initiale du générateur est zéro, de telle sorte que la séquence est
            la même d'une session à l'autre.
            En d'autres termes, les premiers nombres produits
            par <literal>rand</literal> sont toujours : 0.2113249,  0.7560439, ...
        </para>
        <para>
            Dans certains cas, nous pourrions vouloir initialiser la
            graine du générateur dans le but de produire des séquences moins prévisibles.
            Dans cette situation, nous pouvons initialiser la graine avec la sortie de la
            fonction <literal>getdate</literal>, comme dans l'exemple suivant:
        </para>
        <programlisting role="example"><![CDATA[
n=getdate("s");
rand("seed",n);
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>Le générateur</title>
        <para>
            Le générateur de nombres aléatoires <literal>"uniform"</literal> est
            décrit dans
            "Urand, A Universal Random Number Generator" par
            Michael A. Malcolm, Cleve B. Moler, Stan-Cs-73-334, January 1973, Computer
            Science Department, School Of Humanities And Sciences, Stanford University.
        </para>
        <para>
            C'est un générateur linéaire à congruence de la forme :
        </para>
        <para>
             x = (a x + c) mod M
        </para>
        <para>
            pour lequel les constantes sont :
          <table border="0" cellpadding="0">
             <tr><td>a = 843314861</td></tr>
             <tr><td>c = 453816693</td></tr>
             <tr><td>M = 2<superscript>31</superscript></td></tr>
          </table>
        </para>
        <para>
            D'après les auteurs, ce générateur est de longueur complète, c'est à dire
            que sa période est M = 2<superscript>31</superscript> = 2147483648.
        </para>
        <para>
            Le générateur de nombres aléatoires <literal>"normal"</literal>
            est fondés sur la méthode de Box-Muller, pour lequel la
            source de nombres uniformes est Urand.
        </para>
    </refsection>
    <refsection>
        <title>Qualité statistique du générateur</title>
        <para>
            La fonction <link linkend="grand">grand</link> dispose de générateurs aléatoires produisant
            des séquences de nombres qui possèdent de meilleures qualités statistiques.
            Par conséquent, dans les situations où la qualité statistique des séquences de
            nombres aléatoires est importante, nous devrions plutôt utiliser la fonction <literal>grand</literal>.
            De plus, la fonction <literal>grand</literal> fournit davantage de fonctionnalités.
        </para>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="grand">grand</link>
            </member>
            <member>
                <link linkend="ssrand">ssrand</link>
            </member>
            <member>
                <link linkend="sprand">sprand</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
