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