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