help pages: toeplitz overhauled. diag, sparse, speye improved
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / elementarymatrices / rand.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2011 - DIGITEO - Michael Baudin
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <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">
18     <refnamediv>
19         <refname>rand</refname>
20         <refpurpose>Générateur de nombres pseudo-aléatoires</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Séquence d'appel</title>
24         <synopsis>
25             r = rand()
26             r = rand(m1,m2,...)
27             r = rand(m1,m2,...,key)
28             r = rand(x)
29             r = rand(x,key)
30
31             s = rand("seed")
32             rand("seed",s)
33
34             rand(key)
35             key = rand("info")
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>Paramètres</title>
40         <variablelist>
41             <varlistentry>
42                 <term>mi</term>
43                 <listitem>
44                     <para>entiers</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>key</term>
49                 <listitem>
50                     <para>
51                         chaîne de caractères, <literal>"uniform"</literal> ou
52                         <literal>"normal"</literal> (par défaut: <literal>key="uniform"</literal>)
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>x</term>
58                 <listitem>
59                     <para>
60                         une matrice, dont uniquement le contenu réel ou complexe et
61                         les dimensions sont prises en compte.
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>r</term>
67                 <listitem>
68                     <para>
69                         une matrice de doubles de taille m1-par-m2-par-... avec des valeurs aléatoires.
70                     </para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>s</term>
75                 <listitem>
76                     <para>
77                         un entier positif, la graine (par défaut: <literal>s=0</literal>).
78                     </para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83     <refsection>
84         <title>Description</title>
85         <para>
86             Le but de cette fonction est de retourner un tableau
87             de doubles dont les valeurs sont des nombres aléatoires
88             réels ou complexes.
89             En fonction des arguments d'entrée, la fonction peut renvoyer une
90             matrice de doubles aléatoires or peut configurer ou récupérer la distribution des nombres
91             aléatoires ou peut configurer ou récupérer la graine du générateur
92             aléatoire.
93         </para>
94     </refsection>
95     <refsection>
96         <title>Générer des nombres aléatoires</title>
97         <para>
98             Sans l'argument <literal>key</literal> la syntaxe ci-dessous produit
99             une matrice aléatoire dont chaque élément est la réalisation d'une
100             variable aléatoire suivant une loi donnée (par défaut uniforme sur
101             [0,1]).
102         </para>
103         <variablelist>
104             <varlistentry>
105                 <term>r=rand()</term>
106                 <listitem>
107                     <para>renvoit un scalaire aléatoire.</para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>r=rand(m1,m2)</term>
112                 <listitem>
113                     <para>
114                         est une matrice aléatoire de dimensions <literal>m1</literal>
115                         x <literal>m2</literal>.
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>r=rand(m1,m2,..,mn)</term>
121                 <listitem>
122                     <para>
123                         est une matrice aléatoire de dimensions <literal>m1</literal>
124                         x <literal>m2</literal>,.. x <literal>mn</literal>.
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>r=rand(a)</term>
130                 <listitem>
131                     <para>
132                         est une matrice aléatoire de mêmes dimensions que a.
133                         <literal>rand(a)</literal> est complexe si <literal>a</literal> est
134                         une matrice complexe.
135                     </para>
136                 </listitem>
137             </varlistentry>
138         </variablelist>
139     </refsection>
140     <refsection>
141         <title>Changer la distribution des nombres aléatoires</title>
142         <para>
143             S'il est présent, l'argument <literal>key</literal> permet de
144             spécifier la loi suivie par défaut par la variable aléatoire.
145         </para>
146         <variablelist>
147             <varlistentry>
148                 <term>rand("uniform")</term>
149                 <listitem>
150                     <para>La loi par défaut est uniforme sur l'intervalle [0,1].</para>
151                 </listitem>
152             </varlistentry>
153             <varlistentry>
154                 <term>rand("normal")</term>
155                 <listitem>
156                     <para>
157                         La loi par défaut est une loi normale centrée réduite (moyenne
158                         0, variance 1).
159                     </para>
160                 </listitem>
161             </varlistentry>
162             <varlistentry>
163                 <term>key=rand("info")</term>
164                 <listitem>
165                     <para>renvoie la distribution courante, c'est à dire "uniform" ou "normal".</para>
166                 </listitem>
167             </varlistentry>
168         </variablelist>
169     </refsection>
170     <refsection>
171         <title>Récupérer ou changer la graine</title>
172         <para>
173             Il est possible de réinitialiser l'état interne du générateur
174             aléatoire (spécifié par un entier de l'intervalle [0,2^31-1]) ):
175         </para>
176         <variablelist>
177             <varlistentry>
178                 <term>s=rand("seed")</term>
179                 <listitem>
180                     <para>Renvoie la valeur courante de la graine.</para>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>rand("seed",s)</term>
185                 <listitem>
186                     <para>
187                         Configure la valeur <literal>s</literal> de la graine (par
188                         défaut la graine est initialisée à <literal>s=0</literal> au premier
189                         appel).
190                     </para>
191                 </listitem>
192             </varlistentry>
193         </variablelist>
194     </refsection>
195     <refsection>
196         <title>Exemples</title>
197         <para>
198             Dans l'exemple suivant, nous générons des doubles associés à
199             différentes distributions.
200         </para>
201         <programlisting role="example"><![CDATA[
202 // Récupère un double aléatoire (sur la distribution courante)
203 r=rand()
204 // Récupère une matrice de doubles de taille 4-par-6 (sur la distribution courante)
205 r=rand(4,6)
206 // Récupère une matrice de doubles de taille 4-par-6 de distribution uniforme
207 r=rand(4,6,"uniform")
208 // Génère une matrice de doubles aléatoires normaux centrés réduits de même taille que x
209 x=rand(4,4);
210 r=rand(x,"normal")
211 // Génère un tableau de taille 2-par-2-par-2 de doubles aléatoires
212 r=rand(2,2,2)
213  ]]></programlisting>
214         <para>
215             Dans l'exemple suivant, nous changeons la distribution des nombres générés par <literal>rand</literal>.
216             Nous produisons d'abord des nombres normaux centrés réduits, puis des nombres uniformes dans [0,1).
217         </para>
218         <programlisting role="example"><![CDATA[
219     // Configure le générateur sur la loi normale
220     rand("normal")
221     r=rand(4,6)
222     // Récupère la distribution courante
223     key=rand("info")
224     // Configure le générateur sur la loi uniforme
225     rand("uniform")
226     r=rand(4,6)
227     key=rand("info")
228     ]]></programlisting>
229         <para>
230             Dans l'exemple suivant, nous générons une matrice complexe de doubles de taille 2-par-3,
231             avec une distribution normale centrée réduite.
232         </para>
233         <programlisting role="example"><![CDATA[
234     // Génère une matrice complex de doubles aléatoires de taille 2-par-3
235     x=rand(2,3)+%i*rand(2,3)
236     // Génère une matrice complexe de doubles normaux centrés réduits
237     // de la même taille que x
238     r=rand(x,"normal")
239     ]]></programlisting>
240         <para>
241             Dans l'exemple suivant, nous dessinons la distribution de 1000 nombres
242             uniformes produits par <literal>rand</literal>.
243         </para>
244         <programlisting role="example"><![CDATA[
245     r=rand(1000,1,"uniform");
246     scf();
247     histplot(10,r);
248     xtitle("Nombres uniformes par rand","X","Fréquence")
249     ]]></programlisting>
250         <para>
251             Dans l'exemple suivant, nous dessinons la distribution de nombres normaux
252             centrés réduits produits par <literal>rand</literal>.
253         </para>
254         <programlisting role="example"><![CDATA[
255     r=rand(1000,1,"normal");
256     scf();
257     histplot(10,r);
258     xtitle("Nombres normaux centrés réduits par rand","X","Fréquence")
259     ]]></programlisting>
260     </refsection>
261     <refsection>
262         <title>Obtenir des nombres aléatoires prévisibles ou moins prévisibles</title>
263         <para>
264             Le générateur pseudo-aléatoire "uniform" est une séquence déterministe
265             dont le but est de reproduire une séquence de nombres aléatoire, indépendents
266             et identiquement distribués dans l'intervalle (0,1).
267         </para>
268         <para>
269             Dans le but de pouvoir obtenir des simulations reproductibles,
270             la graine initiale du générateur est zéro, de telle sorte que la séquence est
271             la même d'une session à l'autre.
272             En d'autres termes, les premiers nombres produits
273             par <literal>rand</literal> sont toujours : 0.2113249,  0.7560439, ...
274         </para>
275         <para>
276             Dans certains cas, nous pourrions vouloir initialiser la
277             graine du générateur dans le but de produire des séquences moins prévisibles.
278             Dans cette situation, nous pouvons initialiser la graine avec la sortie de la
279             fonction <literal>getdate</literal>, comme dans l'exemple suivant:
280         </para>
281         <programlisting role="example"><![CDATA[
282 n=getdate("s");
283 rand("seed",n);
284  ]]></programlisting>
285     </refsection>
286     <refsection>
287         <title>Le générateur</title>
288         <para>
289             Le générateur de nombres aléatoires <literal>"uniform"</literal> est
290             décrit dans
291             "Urand, A Universal Random Number Generator" par
292             Michael A. Malcolm, Cleve B. Moler, Stan-Cs-73-334, January 1973, Computer
293             Science Department, School Of Humanities And Sciences, Stanford University.
294         </para>
295         <para>
296             C'est un générateur linéaire à congruence de la forme :
297         </para>
298         <para>
299             <latex>
300                 $$
301                 x = (a x + c) \textrm{mod} M
302                 $$
303             </latex>
304         </para>
305         <para>
306             pour lequel les constantes sont :
307         </para>
308         <para>
309             <latex><![CDATA[
310           \begin{eqnarray}
311       a &=& 843314861\\
312       c &=& 453816693\\
313       M &=& 2^{31}
314           \end{eqnarray}
315  ]]></latex>
316         </para>
317         <para>
318             D'après les auteurs, ce générateur est de longueur complète, c'est à dire
319             que sa période est <latex>M=2^{31}=2147483648</latex>.
320         </para>
321         <para>
322             Le générateur de nombres aléatoires <literal>"normal"</literal>
323             est fondés sur la méthode de Box-Muller, pour lequel la
324             source de nombres uniformes est Urand.
325         </para>
326     </refsection>
327     <refsection>
328         <title>Qualité statistique du générateur</title>
329         <para>
330             La fonction <link linkend="grand">grand</link> dispose de générateurs aléatoires produisant
331             des séquences de nombres qui possèdent de meilleures qualités statistiques.
332             Par conséquent, dans les situations où la qualité statistique des séquences de
333             nombres aléatoires est importante, nous devrions plutôt utiliser la fonction <literal>grand</literal>.
334             De plus, la fonction <literal>grand</literal> fournit davantage de fonctionnalités.
335         </para>
336     </refsection>
337     <refsection role="see also">
338         <title>Voir aussi</title>
339         <simplelist type="inline">
340             <member>
341                 <link linkend="grand">grand</link>
342             </member>
343             <member>
344                 <link linkend="ssrand">ssrand</link>
345             </member>
346             <member>
347                 <link linkend="sprand">sprand</link>
348             </member>
349         </simplelist>
350     </refsection>
351 </refentry>