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