elementary_functions: fix rand() with a single key letter after 02f1f9cd
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / random / 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"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="rand" xml:lang="en">
21     <refnamediv>
22         <refname>rand</refname>
23         <refpurpose>Random numbers</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             r = rand()
29             r = rand(m1,m2,...)
30             r = rand(m1,m2,...,key)
31             r = rand(x)
32             r = rand(x,key)
33
34             s = rand("seed")
35             rand("seed",s)
36
37             rand(key)
38             key = rand("info")
39         </synopsis>
40     </refsynopsisdiv>
41     <refsection>
42         <title>Arguments</title>
43         <variablelist>
44             <varlistentry>
45                 <term>m1, m2, ...</term>
46                 <listitem>
47                     <para>
48                         integers, the size of the random matrix <literal>r</literal>.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>key</term>
54                 <listitem>
55                     <para>
56                         a string, the distribution of random numbers (default  <literal>key="uniform" </literal>).
57                         The possible values are:
58                         <itemizedlist>
59                         <listitem>
60                         <literal>"uniform"</literal> or <literal>"u"</literal>
61                         </listitem>
62                         <listitem>
63                         <literal>"normal"</literal> or <literal>"n"</literal>
64                         </listitem>
65                         </itemizedlist>
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>x</term>
71                 <listitem>
72                     <para>
73                         a real or complex matrix.
74                         Only its real or complex content and its dimensions are taken into account.
75                     </para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>r</term>
80                 <listitem>
81                     <para>
82                         a m1-by-m2-by-... real array of doubles with random entries.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>s</term>
88                 <listitem>
89                     <para>
90                         a positive integer: the seed (default <literal>s=0</literal>).
91                     </para>
92                 </listitem>
93             </varlistentry>
94         </variablelist>
95     </refsection>
96     <refsection>
97         <title>Description</title>
98         <para>
99             The purpose of this function is to return a matrix of doubles with real or complex
100             random entries.
101             Depending on the input arguments, the function can return a random matrix of doubles,
102             or can get or set the distribution of random numbers, or can get or set the seed of
103             the random number generator.
104         </para>
105     </refsection>
106     <refsection>
107         <title>Generate random numbers</title>
108         <variablelist>
109             <varlistentry>
110                 <term>r=rand()</term>
111                 <listitem>
112                     <para>returns a 1-by-1 matrix of doubles, with one random value.</para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>r=rand(m1,m2)</term>
117                 <listitem>
118                     <para>
119                         is a random matrix with dimension <literal>m1</literal>-by-
120                         <literal>m2</literal>.
121                     </para>
122                 </listitem>
123             </varlistentry>
124             <varlistentry>
125                 <term>r=rand(m1,m2,...,mn)</term>
126                 <listitem>
127                     <para>
128                         returns a random matrix with dimension <literal>m1</literal>-by-
129                         <literal>m2</literal>-by-... -by-<literal>mn</literal>.
130                     </para>
131                 </listitem>
132             </varlistentry>
133             <varlistentry>
134                 <term>r=rand(a)</term>
135                 <listitem>
136                     <para>
137                         returns a random matrix with the same size as a.
138                         The matrix <literal>r</literal> is real if <literal>a</literal> is a
139                         real matrix and <literal>r</literal> is complex if <literal>a</literal> is a
140                         complex matrix.
141                     </para>
142                 </listitem>
143             </varlistentry>
144         </variablelist>
145     </refsection>
146     <refsection>
147         <title>Change the distribution of the random numbers</title>
148         <para>
149             The <literal>key</literal> input argument sets the distribution of the
150             generated random numbers.
151         </para>
152         <variablelist>
153             <varlistentry>
154                 <term>rand("uniform") or rand("u")</term>
155                 <listitem>
156                     <para>
157                         sets the generator to a uniform random number
158                         generator. Random numbers are uniformly distributed in the interval
159                         [0,1).
160                     </para>
161                 </listitem>
162             </varlistentry>
163             <varlistentry>
164                 <term>rand("normal") or rand("n")</term>
165                 <listitem>
166                     <para>
167                         sets the generator to a normal (Gauss-Laplace) random number generator,
168                         with mean 0 and variance 1.
169                     </para>
170                 </listitem>
171             </varlistentry>
172             <varlistentry>
173                 <term>key=rand("info")</term>
174                 <listitem>
175                     <para>
176                         return the current distribution of the random generator ("uniform" or
177                         "normal")
178                     </para>
179                 </listitem>
180             </varlistentry>
181         </variablelist>
182     </refsection>
183     <refsection>
184         <title>Get or set the seed</title>
185         <para>
186             It is possible to get or set the seed of the random number generator.
187         </para>
188         <variablelist>
189             <varlistentry>
190                 <term>s=rand("seed")</term>
191                 <listitem>
192                     <para>returns the current value of the seed.</para>
193                 </listitem>
194             </varlistentry>
195             <varlistentry>
196                 <term>rand("seed",s)</term>
197                 <listitem>
198                     <para>
199                         sets the seed to <literal>s</literal> (by default
200                         <literal>s=0</literal> at first call).
201                     </para>
202                 </listitem>
203             </varlistentry>
204         </variablelist>
205     </refsection>
206     <refsection>
207         <title>Examples</title>
208         <para>
209             In the following example, we generate random doubles with
210             various distributions.
211         </para>
212         <programlisting role="example"><![CDATA[
213 // Get one random double (based on the current distribution)
214 r=rand()
215 // Get one 4-by-6 matrix of doubles (based on the current distribution)
216 r=rand(4,6)
217 // Get one 4-by-6 matrix of doubles with uniform entries
218 r=rand(4,6,"uniform")
219 // Produce a matrix of random doubles with the same size as x
220 x=rand(4,4);
221 r=rand(x,"normal")
222 // Produce a 2-by-2-by-2 array of random doubles
223 r=rand(2,2,2)
224  ]]></programlisting>
225         <para>
226             In the following example, we change the distribution of the
227             number generated by <literal>rand</literal>.
228             We first produce normal numbers, then numbers uniform in [0,1).
229         </para>
230         <programlisting role="example"><![CDATA[
231     // Set the rand generator to normal
232     rand("normal")
233     r=rand(4,6)
234     // Get the current distribution
235     key=rand("info")
236     // Set the rand generator to uniform
237     rand("uniform")
238     r=rand(4,6)
239     key=rand("info")
240     ]]></programlisting>
241         <para>
242             In the following example, we generate a 2-by-3 complex matrix
243             of doubles, with normal distribution.
244         </para>
245         <programlisting role="example"><![CDATA[
246     // Produce a 2-by-3 matrix of random complex doubles
247     x=rand(2,3)+%i*rand(2,3)
248     // Produce a matrix of random complex doubles with
249     // normal entries and the same size as x
250     r=rand(x,"normal")
251     ]]></programlisting>
252         <para>
253             In the following example, we plot the distribution of uniform
254             numbers produced by <literal>rand</literal>.
255         </para>
256         <programlisting role="example"><![CDATA[
257     r=rand(1000,1,"uniform");
258     scf();
259     histplot(10,r);
260     xtitle("Uniform numbers from rand","X","Frequency")
261     ]]></programlisting>
262         <para>
263             In the following example, we plot the distribution of standard normal
264             numbers produced by <literal>rand</literal>.
265         </para>
266         <programlisting role="example"><![CDATA[
267     r=rand(1000,1,"normal");
268     scf();
269     histplot(10,r);
270     xtitle("Normal numbers from rand","X","Frequency")
271     ]]></programlisting>
272     </refsection>
273     <refsection>
274         <title>Get predictable or less predictable numbers</title>
275         <para>
276             The "uniform" pseudo random number generator is a deterministic sequence which aims at
277             reproducing a independent identically distributed numbers uniform in the
278             interval [0,1).
279         </para>
280         <para>
281             In order to get reproducible simulations, the initial seed of the generator is
282             zero, such that the sequence will remain the same from a session to the other.
283             In other words, the first numbers produced by <literal>rand()</literal> always are : 0.2113249,  0.7560439, ...
284         </para>
285         <para>
286             In some situations, we may want to initialize the seed of the generator in
287             order to produce less predictable sequences. In this case, we may initialize the
288             seed with the output of the <literal>getdate</literal> function:
289         </para>
290         <programlisting role="example"><![CDATA[
291 n=getdate("s");
292 rand("seed",n);
293  ]]></programlisting>
294     </refsection>
295     <refsection>
296         <title>The generator</title>
297         <para>
298             The <literal>"uniform"</literal> random number generator is described in
299             "Urand, A Universal Random Number Generator" by
300             Michael A. Malcolm, Cleve B. Moler, Stan-Cs-73-334, January 1973, Computer
301             Science Department, School Of Humanities And Sciences, Stanford University.
302         </para>
303         <para>
304             It is a linear congruential generator of the form :
305         </para>
306         <para>
307              x = (a x + c) mod M
308         </para>
309         <para>
310             where the constants are
311           <table border="0" cellpadding="0">
312              <tr><td>a = 843314861</td></tr>
313              <tr><td>c = 453816693</td></tr>
314              <tr><td>M = 2<superscript>31</superscript></td></tr>
315           </table>
316        </para>
317         <para>
318             According to the authors, this generator is a full length generator, that is to say, its
319             period is M = 2<superscript>31</superscript> = 214748364.
320         </para>
321         <para>
322             The <literal>"normal"</literal> random number generator is based on
323             the Box-Muller method, where source of the uniform random numbers is Urand.
324         </para>
325     </refsection>
326     <refsection>
327         <title>The statistical quality of the generator</title>
328         <para>
329             Better random number generators are available from
330             the <link linkend="grand">grand</link> function, in the
331             sense that they have both a larger period and better statistical properties.
332             In the case where the quality of the random numbers matters, we should
333             consider the <literal>grand</literal> function instead.
334             Moreover, the <literal>grand</literal> function has more features.
335         </para>
336     </refsection>
337     <refsection role="see also">
338         <title>See also</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>