*Bug #5207 fixed - grand() can now return a hypermatrix
[scilab.git] / scilab / modules / randlib / help / en_US / grand.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) Jean-Philippe Chancelier and Bruno Pincon
5  * Copyright (C) 2010-2011 - DIGITEO - Michael Baudin
6  * Copyright (C) 2013 - Samuel GOUGEON : extension to hypermatrices
7  *
8  * This file must be used under the terms of the CeCILL.
9  * This source file is licensed as described in the file COPYING, which
10  * you should have received as part of this distribution.  The terms
11  * are also available at    
12  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
13  *
14  -->
15 <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="en" xml:id="grand">
16     <refnamediv>
17         <refname>grand</refname>
18         <refpurpose>Random numbers</refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>
23             Y = grand(m, n, "bet", A, B)
24             Y = grand(m, n, "bin", N, p)
25             Y = grand(m, n, "nbn", N, p)
26             Y = grand(m, n, "chi", Df)
27             Y = grand(m, n, "nch", Df, Xnon)
28             Y = grand(m, n, "exp", Av)
29             Y = grand(m, n, "f", Dfn, Dfd)
30             Y = grand(m, n, "nf", Dfn, Dfd, Xnon)
31             Y = grand(m, n, "gam", shape, scale)
32             Y = grand(m, n, "nor", Av, Sd)
33             Y = grand(m, n, "geom", p)
34             Y = grand(m, n, "poi", mu)
35             Y = grand(m, n, "def")
36             Y = grand(m, n, "unf", Low, High)
37             Y = grand(m, n, "uin", Low, High)
38             Y = grand(m, n, "lgi")
39             
40             Y = grand(m, n, o,..,"..",...)
41             Y = grand(X, ...)
42             
43             Y = grand(n, "mn", Mean, Cov)
44             Y = grand(n, "markov", P, x0)
45             Y = grand(n, "mul", nb, P)
46             Y = grand(n, "prm", vect)
47             
48             S = grand("getgen")
49             grand("setgen", gen)
50             
51             S = grand("getsd")
52             grand("setsd", S)
53             
54             S = grand("phr2sd", phrase)
55             
56             grand("setcgn", G)
57             S = grand("getcgn")
58             
59             grand("initgn", I)
60             
61             grand("setall", s1, s2, s3, s4)
62             
63             grand("advnst", K)
64         </synopsis>
65     </refsynopsisdiv>
66     <refsection>
67         <title>Arguments</title>
68         <variablelist>
69             <varlistentry>
70                 <term>m, n, o</term>
71                 <listitem>
72                     <para>
73                         integers, size of the wanted matrix / hypermatrix <varname>Y</varname>.
74                     </para>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>X</term>
79                 <listitem>
80                     <para>
81                         a matrix or hypermatrix whom only the dimensions (say <varname>m</varname>-by-<varname>n</varname>)
82                         are used.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>Y</term>
88                 <listitem>
89                     <para>
90                         depending on the input, a matrix or hypermatrix of doubles, with random entries.
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>S</term>
96                 <listitem>
97                     <para>output of the action (a string or a real column vector).</para>
98                 </listitem>
99             </varlistentry>
100         </variablelist>
101     </refsection>
102     <refsection>
103         <title>Description</title>
104         <para>
105             This function generates random numbers from various
106             distributions.
107         </para>
108         <para>
109             The calling sequences:
110         </para>
111         <para>
112             <programlisting role="no-scilab-exec"><![CDATA[
113                 Y = grand(m, n, "bet", A, B)
114                 Y = grand(m, n, "bin", N, p)
115                 Y = grand(m, n, "nbn", N, p)
116                 Y = grand(m, n, "chi", Df)
117                 Y = grand(m, n, "nch", Df, Xnon)
118                 Y = grand(m, n, "exp", Av)
119                 Y = grand(m, n, "f", Dfn, Dfd)
120                 Y = grand(m, n, "nf", Dfn, Dfd, Xnon)
121                 Y = grand(m, n, "gam", shape, scale)
122                 Y = grand(m, n, "nor", Av, Sd)
123                 Y = grand(m, n, "geom", p)
124                 Y = grand(m, n, "poi", mu)
125                 Y = grand(m, n, "def")
126                 Y = grand(m, n, "unf", Low, High)
127                 Y = grand(m, n, "uin", Low, High)
128                 Y = grand(m, n, "lgi")
129              ]]></programlisting>
130         </para>
131         <para>
132             produce a <varname>m</varname>-by-<varname>n</varname> matrix with random entries.
133             
134             All these calling sequences can be extended to create a random hypermatrix with more than
135             2 dimensions specified as integers listed before the type of statistical distribution:
136         </para>
137         <para>
138             <programlisting role="no-scilab-exec"><![CDATA[
139                 Y = grand(m, n, o, ..., "..", ...)
140             ]]></programlisting>
141         </para>
142         <para>
143             The sizes of the expected random vector, matrix or hypermatrix can alternatively be specified with
144         </para>
145         <para>
146             <programlisting role="no-scilab-exec"><![CDATA[
147                 Y = grand(X, ...)
148             ]]></programlisting>
149         </para>
150         <para>
151             where <literal>X</literal> of sizes <literal>m</literal>-by-<literal>n</literal>...
152             is a matrix or an hypermatrix only used as template.
153         </para>
154         <para>
155             The calling sequences:
156         </para>
157         <programlisting role="no-scilab-exec"><![CDATA[
158             Y = grand(n, "mn", Mean, Cov)
159             Y = grand(n, "markov", P, x0)
160             Y = grand(n, "mul", nb, P)
161             Y = grand(n, "prm", vect)
162         ]]></programlisting>
163         <para>
164             produce a <varname>m</varname>-by-<varname>n</varname> matrix
165             with random entries, where <varname>m</varname> is the size of the argument <varname>Mean</varname>,
166             <varname>Cov</varname>, <varname>P</varname> or <varname>vect</varname> depending
167             on the case (see below for details).
168         </para>
169         <para>
170             The calling sequences:
171         </para>
172         <programlisting role="no-scilab-exec"><![CDATA[
173             S = grand("getgen")
174             grand("setgen", gen)
175             
176             S = grand("getsd")
177             grand("setsd", S)
178             
179             grand("setcgn", G)
180             S = grand("getcgn")
181             
182             grand("initgn", I)
183             
184             grand("setall", s1, s2, s3, s4)
185             
186             grand("advnst", K)
187         ]]></programlisting>
188         <para>
189             configure or quiery the state of the underlying random number
190             generators.
191         </para>
192     </refsection>
193     <refsection>
194         <title>Getting random numbers from a given distribution</title>
195         <variablelist>
196             <varlistentry>
197                 <term>beta</term>
198                 <listitem>
199                     <para>
200                         <code>Y = grand(m, n, "bet", A, B)</code> generates
201                         random variates from the beta distribution with parameters
202                         <varname>A</varname> and <varname>B</varname>.  The density
203                         of the beta distribution is <latex><![CDATA[(0 < x < 1)]]></latex>:
204                     </para>
205                     <para>
206                         <latex>
207                             \dfrac{x^{A-1}(1-x)^{B-1}}{\beta(A,B)}
208                         </latex>
209                     </para>
210                     <para>
211                         <varname>A</varname> and <varname>B</varname> must be
212                         reals <latex><![CDATA[>10^{-37}]]></latex>.  Related function: <link linkend="cdfbet">cdfbet</link>.
213                     </para>
214                 </listitem>
215             </varlistentry>
216             <varlistentry>
217                 <term>binomial</term>
218                 <listitem>
219                     <para>
220                         <code>Y = grand(m, n, "bin", N, p)</code> generates random
221                         variates from the binomial distribution with parameters
222                         <varname>N</varname> (positive integer) and <varname>p</varname>
223                         (<literal>real</literal> in <literal>[0,1]</literal>): number of successes in <varname>N</varname>
224                         independent Bernouilli trials with probability <varname>p</varname>
225                         of success.  Related functions: <link linkend="binomial">binomial</link>,
226                         <link linkend="cdfbin">cdfbin</link>.
227                     </para>
228                 </listitem>
229             </varlistentry>
230             <varlistentry>
231                 <term>negative binomial</term>
232                 <listitem>
233                     <para>
234                         <code>Y = grand(m, n, "nbn", N, p)</code> generates random variates from the
235                         negative binomial distribution with parameters <varname>N</varname> (positive integer) and <varname>p</varname> (<literal>real</literal>
236                         in <literal>(0,1)</literal>) : number of failures occurring before <varname>N</varname> successes
237                         in independent Bernouilli trials with probability <varname>p</varname> of success.
238                         Related function: <link linkend="cdfnbn">cdfnbn</link>.
239                     </para>
240                 </listitem>
241             </varlistentry>
242             <varlistentry>
243                 <term>chi-square</term>
244                 <listitem>
245                     <para>
246                         <code>Y = grand(m, n, "chi", Df)</code> generates random
247                         variates from the chi-square distribution with <varname>Df</varname>
248                         (<literal>real</literal> &gt; <literal>0.0</literal>) degrees of freedom.  Related function:
249                         <link linkend="cdfchi">cdfchi</link>.
250                     </para>
251                 </listitem>
252             </varlistentry>
253             <varlistentry>
254                 <term>non-central chi-square</term>
255                 <listitem>
256                     <para>
257                         <code>Y = grand(m, n, "nch", Df, Xnonc)</code> generates
258                         random variates from the non-central chisquare
259                         distribution with <varname>Df</varname> degrees of freedom
260                         (<literal>real</literal> &gt;= <literal>1.0</literal>) and noncentrality parameter
261                         <varname>Xnonc</varname> (<literal>real</literal> &gt;= <literal>0.0</literal>).  Related
262                         function: <link linkend="cdfchn">cdfchn</link>.
263                     </para>
264                 </listitem>
265             </varlistentry>
266             <varlistentry>
267                 <term>exponential</term>
268                 <listitem>
269                     <para>
270                         <code>Y = grand(m, n, "exp", Av)</code> generates
271                         random variates from the exponential distribution with mean
272                         <varname>Av</varname> (<literal>real</literal> &gt; <literal>0.0</literal>).
273                     </para>
274                 </listitem>
275             </varlistentry>
276             <varlistentry>
277                 <term>F variance ratio</term>
278                 <listitem>
279                     <para>
280                         <code>Y = grand(m, n, "f", Dfn, Dfd)</code> generates
281                         random variates from the F (variance ratio) distribution
282                         with <varname>Dfn</varname> (<literal>real</literal> &gt; <literal>0.0</literal>) degrees of
283                         freedom in the numerator and <varname>Dfd</varname> (<literal>real</literal>
284                         &gt; <literal>0.0</literal>) degrees of freedom in the denominator. Related
285                         function : <link linkend="cdff">cdff</link>.
286                     </para>
287                 </listitem>
288             </varlistentry>
289             <varlistentry>
290                 <term>non-central F variance ratio</term>
291                 <listitem>
292                     <para>
293                         <code>Y = grand(m, n, "nf", Dfn, Dfd, Xnonc)</code>
294                         generates random variates from the noncentral F (variance
295                         ratio) distribution with <varname>Dfn</varname> (<literal>real</literal>
296                         &gt;= <literal>1</literal>) degrees of freedom in the numerator, and
297                         <varname>Dfd</varname> (<literal>real</literal> &gt; <literal>0</literal>) degrees of freedom in
298                         the denominator, and noncentrality parameter
299                         <varname>Xnonc</varname> (<literal>real</literal> &gt;= <literal>0</literal>).  Related
300                         function : <link linkend="cdffnc">cdffnc</link>.
301                     </para>
302                 </listitem>
303             </varlistentry>
304             <varlistentry>
305                 <term>gamma</term>
306                 <listitem>
307                     <para>
308                         <code>Y = grand(m, n, "gam", shape, scale)</code>
309                         generates random variates from the gamma distribution with
310                         parameters <varname>shape</varname> (<literal>real</literal> &gt; <literal>0</literal>) and
311                         <varname>scale</varname> (<literal>real</literal> &gt; <literal>0</literal>). The density of the
312                         gamma distribution is :
313                     </para>
314                     <para>
315                         <latex>
316                             \dfrac{ \textrm{scale}^{\textrm{shape}} x^{\textrm{shape}-1} e^{-\textrm{scale} x}}{\gamma(\textrm{shape}) }
317                         </latex>
318                     </para>
319                     <para>
320                         Related functions : <link linkend="gamma">gamma</link>,
321                         <link linkend="cdfgam">cdfgam</link>.
322                     </para>
323                 </listitem>
324             </varlistentry>
325             <varlistentry>
326                 <term>Gauss Laplace (normal)</term>
327                 <listitem>
328                     <para>
329                         <code>Y = grand(m, n, "nor", Av, Sd)</code> generates
330                         random variates from the normal distribution with mean
331                         <varname>Av</varname> (<literal>real</literal>) and standard deviation
332                         <varname>Sd</varname> (<literal>real</literal> &gt;= <literal>0</literal>). Related function
333                         : <link linkend="cdfnor">cdfnor</link>.
334                     </para>
335                 </listitem>
336             </varlistentry>
337             <varlistentry>
338                 <term>multivariate gaussian (multivariate normal)</term>
339                 <listitem>
340                     <para>   
341                         <code>Y = grand(n, "mn", Mean, Cov)</code>
342                         generates multivariate normal random         
343                         variates; <varname>Mean</varname> must be a <literal>m x 1</literal>
344                         column vector and <varname>Cov</varname> a <varname>m</varname>-by-<varname>m</varname>
345                         symmetric positive definite matrix  (<varname>Y</varname> is then
346                         a <varname>m</varname>-by-<varname>n</varname> matrix).
347                     </para>
348                 </listitem>
349             </varlistentry>
350             <varlistentry>
351                 <term>geometric</term>
352                 <listitem>
353                     <para>
354                         <code>Y = grand(m, n, "geom", p)</code> generates
355                         random variates from the geometric distribution with
356                         parameter <varname>p</varname> : number of Bernouilli trials
357                         (with probability succes of <varname>p</varname>) until a
358                         succes is met. <varname>p</varname> must be in
359                         <latex>[p_{min},1]</latex> (with <latex> p_{min} = 1{,}3\times 10^{-307} </latex>).
360                     </para>
361                     <para>
362                         <varname>Y</varname> contains positive real numbers
363                         with integer values, whiсh are the "number of trials to get
364                         a success".
365                     </para>
366                 </listitem>
367             </varlistentry>
368             <varlistentry>
369                 <term>markov</term>
370                 <listitem>
371                     <para>
372                         <code>Y = grand(n, "markov", P, x0)</code> generate
373                         <varname>n</varname> successive states of a Markov chain
374                         described by the transition matrix
375                         <varname>P</varname>. A sum of each the rows in <varname>P</varname> is <literal>1</literal>. Initial state is given by <varname>x0</varname>. If <varname>x0</varname> is a
376                         matrix of size <code>m=size(x0,"*")</code> then
377                         <varname>Y</varname> is a matrix of size <varname>m</varname>-by-<varname>n</varname>.  <code>Y(i,:)</code> code the sample path
378                         obtained from initial state <code>x0(i)</code>.
379                     </para>
380                 </listitem>
381             </varlistentry>
382             <varlistentry>
383                 <term>multinomial</term>
384                 <listitem>
385                     <para>
386                         <code>Y = grand(n, "mul", nb, P)</code> generates
387                         <varname>n</varname> observations from the Multinomial
388                         distribution : class <varname>nb</varname> events in
389                         <literal>m</literal> categories (put <varname>nb</varname>
390                         "balls" in <literal>m</literal>
391                         "boxes"). <literal>P(i)</literal> is the probability that
392                         an event will be classified into category
393                         <literal>i</literal>. The column vector of probabilities <varname>P</varname> is of
394                         size <literal>m-1</literal> (the probability of category
395                         <literal>m</literal> is <literal>1-sum(P)</literal>).
396                         <varname>Y</varname> is of size <literal>m</literal>-by-<varname>n</varname>.
397                         Each column <literal>Y(:,j)</literal> is an observation
398                         from multinomial distribution and
399                         <literal>Y(i,j)</literal> is the number of events falling in
400                         category <literal>i</literal> (for the
401                         <literal>j</literal>-th observation) (<literal>sum(Y(:,j)) = nb</literal>).
402                     </para>
403                 </listitem>
404             </varlistentry>
405             <varlistentry>
406                 <term>Poisson</term>
407                 <listitem>
408                     <para>
409                         <code>Y = grand(m, n, "poi", mu)</code> generates
410                         random variates from the Poisson distribution with mean
411                         <varname>mu</varname> (<literal>real</literal> &gt;= <literal>0.0</literal>). Related function:
412                         <link linkend="cdfpoi">cdfpoi</link>.
413                     </para>
414                 </listitem>
415             </varlistentry>
416             <varlistentry>
417                 <term>random permutations</term>
418                 <listitem>
419                     <para>
420                         <code>Y = grand(n, "prm", vect)</code> generates
421                         <varname>n</varname> random permutations of the column
422                         vector (<literal>m x 1</literal>)
423                         <varname>vect</varname>.
424                     </para>
425                 </listitem>
426             </varlistentry>
427             <varlistentry>
428                 <term>uniform (def)</term>
429                 <listitem>
430                     <para>
431                         <code>Y = grand(m, n, "def")</code> generates
432                         random variates from the uniform distribution over
433                         <literal>[0,1)</literal> (<literal>1</literal> is never return).
434                     </para>
435                 </listitem>
436             </varlistentry>
437             <varlistentry>
438                 <term>uniform (unf)</term>
439                 <listitem>
440                     <para>
441                         <code>Y = grand(m, n, "unf", Low, High)</code>
442                         generates random reals uniformly distributed in
443                         <literal>[Low, High)</literal> (<varname>High</varname> is never return).
444                     </para>
445                 </listitem>
446             </varlistentry>
447             <varlistentry>
448                 <term>uniform (uin)</term>
449                 <listitem>
450                     <para>
451                         <code>Y = grand(m, n, "uin", Low, High)</code>
452                         generates random integers uniformly distributed between
453                         <varname>Low</varname> and <varname>High</varname>
454                         (included). <varname>High</varname> and
455                         <varname>Low</varname> must be integers such that
456                         <literal>(High-Low+1) &lt; 2,147,483,561</literal>.
457                     </para>
458                 </listitem>
459             </varlistentry>
460             <varlistentry>
461                 <term>uniform (lgi)</term>
462                 <listitem>
463                     <para>
464                         <code>Y = grand(m, n, "lgi")</code> returns the
465                         basic output of the current generator : random integers
466                         following a uniform distribution over :
467                     </para>
468                     <itemizedlist>
469                         <listitem>
470                             <para>
471                                 <literal>[0, 2^32 - 1]</literal> for mt, kiss and fsultra;
472                             </para>
473                         </listitem>
474                         <listitem>
475                             <para>
476                                 <literal>[0, 2^31 - 87]</literal> for clcg2;
477                             </para>
478                         </listitem>
479                         <listitem>
480                             <para>
481                                 <literal>[0, 2^31 - 2]</literal> for clcg4;
482                             </para>
483                         </listitem>
484                         <listitem>
485                             <para>
486                                 <literal>[0, 2^31 - 1]</literal> for urand.
487                             </para>
488                         </listitem>
489                     </itemizedlist>
490                 </listitem>
491             </varlistentry>
492         </variablelist>
493     </refsection>
494     <refsection>
495         <title>Set/get the current generator and its state</title>
496         <para>
497             The user has the possibility to choose between different base
498             generators (which give random integers following the "lgi" distribution, the others
499             being gotten from it).
500         </para>
501         <variablelist>
502             <varlistentry>
503                 <term>mt</term>
504                 <listitem>
505                     <para>
506                         The Mersenne-Twister of M. Matsumoto and T. Nishimura, period about <literal>2^19937</literal>,
507                         state given by an array of <literal>624</literal> integers (plus an index onto this array); this
508                         is the default generator.
509                     </para>
510                 </listitem>
511             </varlistentry>
512             <varlistentry>
513                 <term>kiss</term>
514                 <listitem>
515                     <para>
516                         The "Keep It Simple Stupid" of G. Marsaglia,  period about <literal>2^123</literal>,
517                         state given by four integers.
518                     </para>
519                 </listitem>
520             </varlistentry>
521             <varlistentry>
522                 <term>clcg2</term>
523                 <listitem>
524                     <para>
525                         A Combined 2 Linear Congruential Generator of P. L'Ecuyer,
526                         period about <literal>2^61</literal>, state given by <literal>2</literal> integers.
527                     </para>
528                 </listitem>
529             </varlistentry>
530             <varlistentry>
531                 <term>clcg4</term>
532                 <listitem>
533                     <para>
534                         A Combined 4 Linear Congruential Generator of P. L'Ecuyer,
535                         period about <literal>2^121</literal>, state given by 4 integers ; this one is
536                         split in <literal>101</literal> different virtual (non-overlapping) generators
537                         which may be useful for different tasks (see "Options specific to clcg4" and
538                         "Test example for clcg4").
539                     </para>
540                 </listitem>
541             </varlistentry>
542             <varlistentry>
543                 <term>fsultra</term>
544                 <listitem>
545                     <para>
546                         A Subtract-with-Borrow generator mixing with a congruential
547                         generator of Arif Zaman and George Marsaglia, period more than <literal>10^356</literal>,
548                         state given by an array of <literal>37</literal> integers (plus an index onto this array, a flag (<literal>0</literal> or <literal>1</literal>)
549                         and another integer).
550                     </para>
551                 </listitem>
552             </varlistentry>
553             <varlistentry>
554                 <term>urand</term>
555                 <listitem>
556                     <para>
557                         The generator used by the scilab function <link linkend="rand">rand</link>, state
558                         given by <literal>1</literal> integer, period of <literal>2^31</literal>.
559                         This generator is based on "Urand, A Universal Random Number Generator" By,
560                         Michael A. Malcolm, Cleve B. Moler, Stan-Cs-73-334, January 1973, Computer
561                         Science Department, School Of Humanities And Sciences, Stanford University.
562                         This is the faster of this list but its statistical qualities are less
563                         satisfactory than the other generators.
564                     </para>
565                 </listitem>
566             </varlistentry>
567         </variablelist>
568         <para>
569             The different actions common to all the generators, are:
570         </para>
571         <variablelist>
572             <varlistentry>
573                 <term>action = "getgen"</term>
574                 <listitem>
575                     <para>
576                         <code>S = grand("getgen")</code> returns the current base generator.
577                         In this case <varname>S</varname> is
578                         a string among <literal>"mt"</literal>, <literal>"kiss"</literal>, <literal>"clcg2"</literal>, <literal>"clcg4"</literal>, <literal>"urand"</literal>, <literal>"fsultra"</literal>.
579                     </para>
580                 </listitem>
581             </varlistentry>
582             <varlistentry>
583                 <term>action = "setgen"</term>
584                 <listitem>
585                     <para>
586                         <code>grand("setgen",gen)</code> sets the current base generator to be <varname>gen</varname>
587                         a string among <literal>"mt"</literal>, <literal>"kiss"</literal>, <literal>"clcg2"</literal>, <literal>"clcg4"</literal>, <literal>"urand"</literal>, <literal>"fsultra"</literal>.
588                         Notice that this call returns the new current generator, i.e. <varname>gen</varname>.
589                     </para>
590                 </listitem>
591             </varlistentry>
592             <varlistentry>
593                 <term>action = "getsd"</term>
594                 <listitem>
595                     <para>
596                         <code>S = grand("getsd")</code> gets the current state (the current seeds) of the current base
597                         generator ; <varname>S</varname> is given as a column vector (of integers) of dimension <literal>625</literal>
598                         for mt (the first being an index in <literal>[1,624]</literal>), <literal>4</literal> for kiss, <literal>2</literal>
599                         for clcg2,  <literal>40</literal> for fsultra, <literal>4</literal> for clcg4
600                         (for this last one you get the current state of the current virtual generator) and <literal>1</literal>
601                         for urand.
602                     </para>
603                 </listitem>
604             </varlistentry>
605             <varlistentry>
606                 <term>action = "setsd"</term>
607                 <listitem>
608                     <para>
609                         <code>grand("setsd", S)</code> and <code>grand("setsd", s1[, s2, s3, s4])</code> set the state of the current
610                         base generator (the new seeds) :
611                     </para>
612                     <variablelist>
613                         <varlistentry>
614                             <term>for mt</term>
615                             <listitem>
616                                 <para>
617                                     <varname>S</varname> is a vector of integers of dim <literal>625</literal> (the first component is an index
618                                     and must be in <literal>[1,624]</literal>, the <literal>624</literal> last ones must be in
619                                     <literal>[0,2^32[</literal>) (but must not be all zeros) ; a simpler initialization may be done
620                                     with only one integer <varname>s1</varname> (<varname>s1</varname> must be in <literal>[0,2^32[</literal>) ;
621                                 </para>
622                             </listitem>
623                         </varlistentry>
624                         <varlistentry>
625                             <term>for kiss</term>
626                             <listitem>
627                                 <para>
628                                     four integers <varname>s1</varname>, <varname>s2</varname>, <varname>s3</varname>, <varname>s4</varname> in <literal>[0,2^32[</literal> must be provided ;
629                                 </para>
630                             </listitem>
631                         </varlistentry>
632                         <varlistentry>
633                             <term>for clcg2</term>
634                             <listitem>
635                                 <para>
636                                     two integers <varname>s1</varname> in <literal>[1,2^31-86]</literal> and <varname>s2</varname>
637                                     in  <literal>[1,2^31-250]</literal> must be given ;
638                                 </para>
639                             </listitem>
640                         </varlistentry>
641                         <varlistentry>
642                             <term>for clcg4</term>
643                             <listitem>
644                                 <para>
645                                     four integers <varname>s1</varname> in <literal>[1,2^31-2]</literal>, <varname>s2</varname>
646                                     in <literal>[1,2^31-106]</literal>, <varname>s3</varname> in <literal>[1,2^31-226]</literal>,
647                                     <varname>s4</varname> in  <literal>[1,2^31-326]</literal> are required ;
648                                 </para>
649                                 <para>
650                                     <caution>
651                                         CAUTION : with clcg4 you set the seeds of the current virtual
652                                         generator but you may lost the synchronization between this one
653                                         and the others virtual generators (i.e. the sequence generated
654                                         is not warranty to be non-overlapping with a sequence generated
655                                         by another virtual generator) =&gt; use instead the "setall" option.
656                                     </caution>
657                                 </para>
658                             </listitem>
659                         </varlistentry>
660                         <varlistentry>
661                             <term>for urand</term>
662                             <listitem>
663                                 <para>
664                                     <literal>1</literal> integer <varname>s1</varname> in  <literal>[0,2^31[</literal> must be given.
665                                 </para>
666                             </listitem>
667                         </varlistentry>
668                         <varlistentry>
669                             <term>for fsultra</term>
670                             <listitem>
671                                 <para>
672                                     <varname>S</varname> is a vector of integers of dim <literal>40</literal> (the first component
673                                     is an index and must be in <literal>[0,37]</literal>, the 2nd component is a flag (0 or 1), the 3rd component is
674                                     an integer in <literal>[1,2^32[</literal> and the 37 others integers are in <literal>[0,2^32[</literal>) ; a simpler (and recommended)
675                                     initialization may be done with two integers <varname>s1</varname> and <varname>s2</varname> in
676                                     <literal>[0,2^32[</literal>.
677                                 </para>
678                             </listitem>
679                         </varlistentry>
680                     </variablelist>
681                 </listitem>
682             </varlistentry>
683             <varlistentry>
684                 <term>action = "phr2sd"</term>
685                 <listitem>
686                     <para>
687                         <literal>Sd = grand("phr2sd", phrase)</literal> given a <varname>phrase</varname> (character string) generates
688                         a <literal>1 x 2</literal> vector <literal>Sd</literal> which may be used as seeds to change the state of a
689                         base generator (initially suited for clcg2).
690                     </para>
691                 </listitem>
692             </varlistentry>
693         </variablelist>
694     </refsection>
695     <refsection>
696         <title>Options specific to clcg4</title>
697         <para>
698             The clcg4 generator may be used as the others generators but it offers the advantage
699             to be split in several (<literal>101</literal>) virtual generators with non-overlapping
700             sequences (when you use a classic generator you may change the initial state (seeds)
701             in order to get another sequence but you are not warranty to get a complete  different one).
702             Each virtual generator corresponds to a sequence of <literal>2^72</literal> values which is
703             further split into <literal>V=2^31</literal> segments (or blocks) of length <literal>W=2^41</literal>.
704             For a given virtual generator you have the possibility to return at the beginning of the
705             sequence or at the beginning of the current segment or to go directly at the next segment.
706             You may also change the initial state (seed) of the generator <literal>0</literal> with the
707             <literal>"setall"</literal> option which then change also the initial state of the other virtual generators
708             so as to get synchronization, i.e. in function of the new initial state of gen <literal>0</literal>
709             the initial state of gen <literal>1..100</literal> are recomputed so as to get <literal>101</literal>
710             non-overlapping sequences.
711         </para>
712         <variablelist>
713             <varlistentry>
714                 <term>action = "setcgn"</term>
715                 <listitem>
716                     <para>
717                         <literal>grand("setcgn",G)</literal> sets the current virtual generator for clcg4 (when clcg4
718                         is set, this is the virtual (clcg4) generator number <literal>G</literal> which is used);  the virtual clcg4
719                         generators are numbered from <literal>0,1,...,100</literal> (and so <literal>G</literal> must be an integer
720                         in  <literal>[0,100]</literal>) ; by default the current virtual generator is <literal>0</literal>.
721                     </para>
722                 </listitem>
723             </varlistentry>
724             <varlistentry>
725                 <term>action = "getcgn"</term>
726                 <listitem>
727                     <para>
728                         <code>S = grand("getcgn")</code> returns the number of the current virtual clcg4 generator.
729                     </para>
730                 </listitem>
731             </varlistentry>
732             <varlistentry>
733                 <term>action = "initgn"</term>
734                 <listitem>
735                     <para>
736                         <code>grand("initgn", I)</code> reinitializes the state of the current virtual generator
737                     </para>
738                     <variablelist>
739                         <varlistentry>
740                             <term>I = -1</term>
741                             <listitem>  
742                                 <para>sets the state to its initial seed</para> 
743                             </listitem>
744                         </varlistentry>
745                         <varlistentry>
746                             <term>I = 0</term>
747                             <listitem>
748                                 <para>sets the state to its last (previous) seed (i.e. to the beginning  of the current segment)</para> 
749                             </listitem>
750                         </varlistentry>
751                         <varlistentry>
752                             <term>I = 1</term>
753                             <listitem>  
754                                 <para>     
755                                     sets the state to a new seed <literal>W</literal> values from its last seed (i.e. to the beginning          
756                                     of the next segment) and resets the current segment parameters.    
757                                 </para>
758                             </listitem>
759                         </varlistentry>
760                     </variablelist>
761                 </listitem>
762             </varlistentry>
763             <varlistentry>
764                 <term>action = "setall"</term>
765                 <listitem>
766                     <para>
767                         <code>grand("setall", s1, s2, s3, s4)</code> sets the initial state of generator <literal>0</literal>
768                         to  <varname>s1</varname>, <varname>s2</varname>, <varname>s3</varname>, <varname>s4</varname>. The initial seeds of the other generators are set accordingly
769                         to have synchronization. For constraints on  <varname>s1</varname>, <varname>s2</varname>, <varname>s3</varname>, <varname>s4</varname> see the <literal>"setsd"</literal> action.
770                     </para>
771                 </listitem>
772             </varlistentry>
773             <varlistentry>
774                 <term>action = "advnst"</term>
775                 <listitem>
776                     <para>
777                         <code>grand("advnst", K)</code> advances the state of the current generator by <literal>2^K</literal> values
778                         and  resets the initial seed to that value.
779                     </para>
780                 </listitem>
781             </varlistentry>
782         </variablelist>
783     </refsection>
784     <refsection>
785         <title>Examples</title>
786         <para>
787             In the following example, we generate random numbers from various distributions and
788             plot the associated histograms.
789         </para>
790         <programlisting role="example"><![CDATA[ 
791 // Returns a 400-by-800 matrix of random doubles, 
792 // with normal distribution and average 0 and standard deviation 1.
793 R = grand(400,800,"nor",0,1);
794 scf();
795 histplot(10,R);
796 xtitle("Normal random numbers from grand","X","Frequency");
797  ]]></programlisting>
798         <scilab:image localized="true">
799             R = grand(400,800,"nor",0,1);
800             histplot(10,R);
801             xtitle("Normal random numbers from grand","X","Frequency");
802         </scilab:image>
803         
804         <programlisting role="example"><![CDATA[ 
805 // Returns a 400-by-800 matrix of random doubles, 
806 // uniform in [0,1).
807 R = grand(400,800,"def");
808 scf();
809 histplot(10,R);
810 xtitle("Uniform random numbers from grand","X","Frequency");
811  ]]></programlisting>
812         <scilab:image localized="true">
813             R = grand(400,800,"def");
814             histplot(10,R);
815             xtitle("Uniform random numbers from grand","X","Frequency");
816         </scilab:image>
817         
818         <programlisting role="example"><![CDATA[ 
819 // Returns a 400-by-800 matrix of random doubles, 
820 // with Poisson distribution and average equal to 5.
821 R = grand(400,800,"poi",5);
822 scf();
823 histplot(10,R);
824 xtitle("Poisson random numbers from grand","X","Frequency");
825  ]]></programlisting>
826         <scilab:image localized="true">
827             R = grand(400,800,"poi",5);
828             histplot(10,R);
829             xtitle("Poisson random numbers from grand","X","Frequency");
830         </scilab:image>
831         
832         <para>
833             In the following example, we generate random numbers from the exponential distribution and
834             then compare the empirical with the theoretical distribution.
835         </para>
836         <programlisting role="example"><![CDATA[ 
837 lambda=1.6;
838 N=100000;
839 X = grand(1,N,"exp",lambda);
840 scf();
841 classes = linspace(0,12,25);
842 histplot(classes,X)
843 x=linspace(0,12,25);
844 y = (1/lambda)*exp(-(1/lambda)*x);
845 plot(x,y,"ro-");
846 legend(["Empirical" "Theory"]);
847 xtitle("Exponential random numbers from grand","X","Frequency");
848  ]]></programlisting>
849         <scilab:image localized="true">
850             lambda=1.6;
851             N=100000;
852             X = grand(1,N,"exp",lambda);
853             classes = linspace(0,12,25);
854             histplot(classes,X)
855             x=linspace(0,12,25);
856             y = (1/lambda)*exp(-(1/lambda)*x);
857             plot(x,y,"ro-");
858             legend(["Empirical" "Theory"]);
859             xtitle("Exponential random numbers from grand","X","Frequency");
860         </scilab:image>
861         <para>
862             In the following example, we generate random numbers from the gamma distribution and
863             then compare the empirical with the theoretical distribution.
864         </para>
865         <programlisting role="example"><![CDATA[ 
866 N=10000;
867 A=10;
868 B=4;
869 R=grand(1,N,"gam",A,B); 
870 XS=gsort(R,"g","i")';
871 PS=(1:N)'/N;
872 P=cdfgam("PQ",XS,A*ones(XS),B*ones(XS));
873 scf();
874 plot(XS,PS,"b-"); // Empirical distribution
875 plot(XS,P,"r-"); // Theoretical distribution
876 legend(["Empirical" "Theory"]);
877 xtitle("Cumulative distribution function of Gamma random numbers","X","F");
878  ]]></programlisting>
879         <scilab:image localized="true">
880             N=10000;
881             A=10;
882             B=4;
883             R=grand(1,N,"gam",A,B); 
884             XS=gsort(R,"g","i")';
885             PS=(1:N)'/N;
886             P=cdfgam("PQ",XS,A*ones(XS),B*ones(XS));
887             scf();
888             plot(XS,PS,"b-"); // Empirical distribution
889             plot(XS,P,"r-"); // Theoretical distribution
890             legend(["Empirical" "Theory"]);
891             xtitle("Cumulative distribution function of Gamma random numbers","X","F");
892         </scilab:image>
893         <para>
894             In the following example, we generate 10 random integers in the [1,365] interval.
895         </para>
896         <programlisting role="example"><![CDATA[ 
897 grand(10,1,"uin",1,365)
898  ]]></programlisting>
899         <para>
900             In the following example, we generate 12 permutations of the [1,2,...,7] set.
901             The 12 permutations are stored column-by-column.
902         </para>
903         <programlisting role="example"><![CDATA[ 
904 grand(12,"prm",(1:7)')
905  ]]></programlisting>
906         <para>
907             In the following example, we generate a <varname>10</varname>-by-<varname>10</varname>-by-<varname>10</varname>
908             hypermatrix of random numbers from the "normal" distribution and plot the associated histograms.
909             Showing the first and last layers.
910         </para>
911         <programlisting role="example"><![CDATA[ 
912 // Returns a 400-by-800-by-10 hypermatrix of random doubles,
913 // with normal distribution, average 0 and standard deviation 1.
914 // Showing the first and last layers.
915 R = grand(10,10,10,"nor",0,1);
916 subplot(1,2,1)
917 hist3d(R(:,:,1));
918 xtitle("Layer 1");
919 subplot(1,2,2)
920 hist3d(R(:,:,10));
921 xtitle("Layer 10");
922  ]]></programlisting>
923         <scilab:image localized="true">
924             R = grand(10,10,10,"nor",0,1);
925             subplot(1,2,1)
926             hist3d(R(:,:,1));
927             xtitle("Layer 1");
928             subplot(1,2,2)
929             hist3d(R(:,:,10));
930             xtitle("Layer 10");
931         </scilab:image>
932     </refsection>
933     <refsection>
934         <title>Get predictible or less predictible numbers</title>
935         <para>
936             The pseudo random number generators are based on deterministic sequences.
937             In order to get reproducible simulations, the initial seed of the generator is constant,
938             such that the sequence will remain the same from a session to the other.
939             Hence, by default, the first numbers produced by <function>grand</function> are always the same.
940         </para>
941         <para>
942             In some situations, we may want to initialize the seed of the generator in
943             order to produce less predictable numbers.
944             In this case, we may initialize the seed with the output of the <function>getdate</function> function:
945         </para>
946         <programlisting role="example"><![CDATA[
947 n=getdate("s");
948 grand("setsd",n)
949     ]]></programlisting>
950     </refsection>
951     <refsection>
952         <title>Test example for clcg4</title>
953         <para>
954             An example of  the  need of the splitting capabilities of clcg4 is as  follows.
955             Two statistical techniques are being compared on  data of  different sizes. The first
956             technique uses   bootstrapping  and is   thought to   be  as accurate using less data
957             than the second method   which  employs only brute force.  For the first method, a data
958             set of size uniformly distributed between 25 and 50 will be generated.  Then the data set
959             of the specified size will be generated and analyzed.  The second method will  choose a
960             data set size between 100 and 200, generate the data  and analyze it.  This process will
961             be repeated 1000 times.  For  variance reduction, we  want the  random numbers  used in the
962             two methods to be the  same for each of  the 1000 comparisons.  But method two will  use more
963             random  numbers than   method one and  without this package, synchronization might be difficult.
964             With clcg4, it is a snap.  Use generator 0 to obtain  the sample size for  method one and
965             generator 1  to obtain the  data.  Then reset the state to the beginning  of the current  block
966             and do the same  for the second method.  This assures that the initial data  for method two is
967             that used by  method  one.  When both  have concluded,  advance the block for both generators.
968         </para>
969     </refsection>
970     <refsection role="see also">
971         <title>See Also</title>
972         <simplelist type="inline">
973             <member>
974                 <link linkend="rand">rand</link>
975             </member>
976             <member>
977                 <link linkend="sprand">sprand</link>
978             </member>
979             <member>
980                 <link linkend="ssrand">ssrand</link>
981             </member>
982         </simplelist>
983     </refsection>
984 </refentry>