randlib: Fixed bug #8560
[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) 2008 - INRIA
5  * Copyright (C) 2010 - 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" 
15           xmlns:xlink="http://www.w3.org/1999/xlink" 
16           xmlns:svg="http://www.w3.org/2000/svg" 
17           xmlns:mml="http://www.w3.org/1998/Math/MathML" 
18           xmlns:db="http://docbook.org/ns/docbook" 
19           version="5.0-subset Scilab" xml:lang="en" xml:id="grand">
20
21   <refnamediv>
22     <refname>grand</refname>
23     <refpurpose> Random number generator(s)   </refpurpose>
24   </refnamediv>
25   <refsynopsisdiv>
26     <title>Calling Sequence</title>
27     <synopsis>
28       Y=grand(m,n,'bet',A,B)
29       Y=grand(m,n,'bin',N,p)
30       Y=grand(m,n,'nbn',N,p)
31       Y=grand(m,n,'chi', Df)
32       Y=grand(m,n,'nch',Df,Xnon)
33       Y=grand(m,n,'exp',Av)
34       Y=grand(m,n,'f',Dfn,Dfd)
35       Y=grand(m,n,'nf',Dfn,Dfd,Xnon)
36       Y=grand(m,n,'gam',shape,scale)
37       Y=grand(m,n,'nor',Av,Sd)
38       Y=grand(n,'mn',Mean,Cov)
39       Y=grand(m,n,'geom', p)
40       Y=grand(n,'markov',P,x0)
41       Y=grand(n,'mul',nb,P)
42       Y=grand(m,n,'poi',mu)
43       Y=grand(n,'prm',vect)
44       Y=grand(m,n,'def')
45       Y=grand(m,n,'unf',Low,High)
46       Y=grand(m,n,'uin',Low,High)
47       Y=grand(m,n,'lgi')
48       S=grand('getgen')
49       grand('setgen',gen)
50       S=grand('getsd')
51       grand('setsd',S)
52       grand('setcgn',G)
53       S=grand('getcgn')
54       grand('initgn',I)
55       grand('setall',s1,s2,s3,s4)
56       grand('advnst',K)
57     </synopsis>
58   </refsynopsisdiv>
59   <refsection>
60     <title>Arguments</title>
61     <variablelist>
62       <varlistentry>
63         <term>m, n</term>
64         <listitem>
65           <para>integers, size of the wanted matrix <literal>Y</literal></para>
66         </listitem>
67       </varlistentry>
68       <varlistentry>
69         <term>X</term>
70         <listitem>
71           <para>a matrix whom only the dimensions (say <literal>m x
72               n</literal>) are used</para>
73         </listitem>
74       </varlistentry>
75       <varlistentry>
76         <term>dist_type</term>
77         <listitem>
78           <para>a string given the distribution which (independants)
79             variates are to be generated ('bin', 'nor', 'poi', etc
80             ...)</para>
81         </listitem>
82       </varlistentry>
83       <varlistentry>
84         <term>p1, ..., pk</term>
85         <listitem>
86           <para>the parameters (reals or integers) required to define
87             completly the distribution
88             <literal>dist_type</literal></para>
89         </listitem>
90       </varlistentry>
91       <varlistentry>
92         <term>Y</term>
93         <listitem>
94           <para>the resulting <literal>m x n</literal> random matrix</para>
95         </listitem>
96       </varlistentry>
97       <varlistentry>
98         <term>action</term>
99         <listitem>
100           <para>a string given the action onto the base generator(s)
101             ('setgen' to change the current base generator, 'getgen' to
102             retrieve the current base generator name, 'getsd' to
103             retrieve the state (seeds) of the current base generator,
104             etc ...)</para>
105         </listitem>
106       </varlistentry>
107       <varlistentry>
108         <term>q1, ..., ql</term>
109         <listitem>
110           <para>the parameters (generally one string) needed to define the action</para>
111         </listitem>
112       </varlistentry>
113       <varlistentry>
114         <term>S</term>
115         <listitem>
116           <para>output of the action (generaly a string or a real column vector)</para>
117         </listitem>
118       </varlistentry>
119     </variablelist>
120   </refsection>
121   <refsection>
122     <title>Description</title>
123     
124     <para>
125       This function may be used to generate random numbers from various
126       distributions. In this case you must apply one of the
127       <literal>three first forms</literal> of the possible calling
128       sequences to get an <literal>m x n</literal> matrix.  The two
129       firsts are equivalent if <literal>X</literal> is a <literal>m x
130         n</literal> matrix, and the third form corresponds to
131       'multivalued' distributions (e.g. multinomial, multivariate
132       gaussian, etc...) where a sample is a column vector (says of dim
133       <literal>m</literal>) and you get then <literal>n</literal> such
134       random vectors (as an <literal> m x n</literal> matrix).
135     </para>
136     <para>
137       The last form is used to undertake various
138       manipulations onto the base generators like changing the base
139       generator (since v 2.7 you may choose between several base
140       generators), changing or retrieving its internal state (seeds),
141       etc ... These base generators give random integers following a
142       uniform distribution on a large integer interval (lgi), all the
143       others distributions being gotten from it (in general via a
144       scheme lgi -&gt; U([0,1)) -&gt; wanted distribution).
145     </para>
146   </refsection>
147   <refsection>
148     <title>Getting random numbers from a given distribution</title>
149     <variablelist>
150       <varlistentry>
151         <term>beta</term>
152         <listitem>
153           <para><literal>Y=grand(m,n,'bet',A,B)</literal> generates
154             random variates from the beta distribution with parameters
155             <literal>A</literal> and <literal>B</literal>.  The density
156             of the beta is (<literal>0 &lt; x &lt; 1</literal>) :</para>
157           <programlisting role=""><![CDATA[ 
158  A-1    B-1
159 x   (1-x)   / beta(A,B) 
160  ]]></programlisting>
161           <para><literal>A</literal> and <literal>B</literal> must be
162             reals &gt;<literal>10^(-37)</literal>.  Related function(s)
163             : <link linkend="cdfbet">cdfbet</link>.
164           </para>
165         </listitem>
166       </varlistentry>
167       <varlistentry>
168         <term>binomial</term>
169         <listitem>
170           <para>
171             <literal>Y=grand(m,n,'bin',N,p)</literal> generates random
172             variates from the binomial distribution with parameters
173             <literal>N</literal> (positive integer) and <literal>p</literal>
174             (real in [0,1]) : number of successes in <literal>N</literal>
175             independant Bernouilli trials with probability <literal>p</literal>
176             of success.  Related function(s) : <link linkend="binomial">binomial</link>,
177             <link  linkend="cdfbin">cdfbin</link>.
178           </para>
179         </listitem>
180       </varlistentry>
181       <varlistentry>
182         <term>negative binomial</term>
183         <listitem>
184           <para>
185             <literal>Y=grand(m,n,'nbn',N,p)</literal> generates random variates from the negative binomial 
186             distribution with parameters <literal>N</literal> (positive integer) and <literal>p</literal> (real 
187             in (0,1)) : number of failures occurring before <literal>N</literal> successes 
188             in independant Bernouilli trials with probability <literal>p</literal> of success.
189             Related function(s) : <link linkend="cdfnbn">cdfnbn</link>.
190           </para>
191         </listitem>
192       </varlistentry>
193       <varlistentry>
194         <term>chisquare</term>
195         <listitem>
196           <para>
197             <literal>Y=grand(m,n,'chi', Df)</literal> generates random
198             variates from the chisquare distribution with <literal>Df</literal>
199             (real &gt; 0.0) degrees of freedom.  Related function(s) : 
200             <link linkend="cdfchi">cdfchi</link>.
201           </para>
202         </listitem>
203       </varlistentry>
204       <varlistentry>
205         <term>non central chisquare</term>
206         <listitem>
207           <para>
208             <literal>Y=grand(m,n,'nch',Df,Xnon)</literal> generates
209             random variates from the non central chisquare
210             distribution with <literal>Df</literal> degrees of freedom
211             (real &gt;= 1.0) and noncentrality parameter
212             <literal>Xnonc</literal> (real &gt;= 0.0).  Related
213             function(s) : <link linkend="cdfchn">cdfchn</link>.
214           </para>
215         </listitem>
216       </varlistentry>
217       <varlistentry>
218         <term>exponential</term>
219         <listitem>
220           <para><literal>Y=grand(m,n,'exp',Av)</literal> generates
221             random variates from the exponential distribution with mean
222             <literal>Av</literal> (real &gt;= 0.0).</para>
223         </listitem>
224       </varlistentry>
225       <varlistentry>
226         <term>F variance ratio</term>
227         <listitem>
228           <para>
229             <literal>Y=grand(m,n,'f',Dfn,Dfd)</literal> generates
230             random variates from the F (variance ratio) distribution
231             with <literal>Dfn</literal> (real &gt; 0.0) degrees of
232             freedom in the numerator and <literal>Dfd</literal> (real
233             &gt; 0.0) degrees of freedom in the denominator. Related
234             function(s) : <link linkend="cdff">cdff</link>.
235           </para>
236         </listitem>
237       </varlistentry>
238       <varlistentry>
239         <term>non central F variance ratio</term>
240         <listitem>
241           <para>
242             <literal>Y=grand(m,n,'nf',Dfn,Dfd,Xnon)</literal>
243             generates random variates from the noncentral F (variance
244             ratio) distribution with <literal>Dfn</literal> (real
245             &gt;= 1) degrees of freedom in the numerator, and
246             <literal>Dfd</literal> (real &gt; 0) degrees of freedom in
247             the denominator, and noncentrality parameter
248             <literal>Xnonc</literal> (real &gt;= 0).  Related
249             function(s) : <link linkend="cdffnc">cdffnc</link>.
250           </para>
251         </listitem>
252       </varlistentry>
253       <varlistentry>
254         <term>gamma</term>
255         <listitem>
256           <para><literal>Y=grand(m,n,'gam',shape,scale)</literal>
257             generates random variates from the gamma distribution with
258             parameters <literal>shape</literal> (real &gt; 0) and
259             <literal>scale</literal> (real &gt; 0). The density of the
260             gamma is :</para>
261           <programlisting role=""><![CDATA[ 
262      shape  (shape-1)   -scale x
263 scale       x          e          /  gamma(shape) 
264  ]]></programlisting>
265           <para>
266             Related function(s) : <link linkend="gamma">gamma</link>,
267             <link linkend="cdfgam">cdfgam</link>.
268           </para>
269         </listitem>
270       </varlistentry>
271       <varlistentry>
272         <term>Gauss Laplace (normal)</term>
273         <listitem>
274           <para>
275             <literal>Y=grand(m,n,'nor',Av,Sd)</literal> generates
276             random variates from the normal distribution with mean
277             <literal>Av</literal> (real) and standard deviation
278             <literal>Sd</literal> (real &gt;= 0). Related function(s)
279             : <link linkend="cdfnor">cdfnor</link>.
280           </para>
281         </listitem>
282       </varlistentry>
283       <varlistentry>
284         <term>multivariate gaussian (multivariate normal)</term>
285         <listitem>
286           <para><literal>Y=grand(n,'mn',Mean,Cov)</literal>
287             generates <literal>n</literal> multivariate normal random
288             variates ; <literal>Mean</literal> must be a <literal>m x
289               1</literal> matrix and <literal>Cov</literal> a <literal>m x
290               m</literal> symmetric positive definite matrix
291             (<literal>Y</literal> is then a <literal>m x n</literal>
292             matrix).</para>
293         </listitem>
294       </varlistentry>
295       <varlistentry>
296         <term>geometric</term>
297         <listitem>
298           <para><literal>Y=grand(m,n,'geom', p)</literal> generates
299             random variates from the geometric distribution with
300             parameter <literal>p</literal> : number of Bernouilli trials
301             (with probability succes of <literal>p</literal>) until a
302             succes is met. <literal>p</literal> must be in
303             <literal>[pmin,1]</literal> (with <literal>pmin = 1.3
304               10^(-307)</literal>).</para>
305           <para><literal>Y</literal> contains positive real numbers
306             with integer values, with are the "number of trials to get
307             a success".</para>
308         </listitem>
309       </varlistentry>
310       <varlistentry>
311         <term>markov</term>
312         <listitem>
313           <para>
314             <literal>Y=grand(n,'markov',P,x0)</literal> generate
315             <literal>n</literal> successive states of a Markov chain
316             described by the transition matrix
317             <literal>P</literal>. Initial state is given by
318             <literal>x0</literal>. If <literal>x0</literal> is a
319             matrix of size <literal>m=size(x0,'*')</literal> then
320             <literal>Y</literal> is a matrix of size <literal>m x
321               n</literal>. <literal>Y(i,:)</literal> is the sample path
322             obtained from initial state <literal>x0(i)</literal>.
323           </para>
324         </listitem>
325       </varlistentry>
326       <varlistentry>
327         <term>multinomial</term>
328         <listitem>
329           <para>
330             <literal>Y=grand(n,'mul',nb,P)</literal> generates
331             <literal>n</literal> observations from the Multinomial
332             distribution : class <literal>nb</literal> events in
333             <literal>m</literal> categories (put <literal>nb</literal>
334             "balls" in <literal>m</literal>
335             "boxes"). <literal>P(i)</literal> is the probability that
336             an event will be classified into category
337             i. <literal>P</literal> the vector of probabilities is of
338             size <literal>m-1</literal> (the probability of category
339             <literal>m</literal> being <literal>1-sum(P)</literal>).
340             <literal>Y</literal> is of size <literal>m x n</literal>,
341             each column <literal>Y(:,j)</literal> being an observation
342             from multinomial distribution and
343             <literal>Y(i,j)</literal> the number of events falling in
344             category <literal>i</literal> (for the
345             <literal>j</literal> th observation) (<literal>sum(Y(:,j))
346               = nb</literal>).
347           </para>
348         </listitem>
349       </varlistentry>
350       <varlistentry>
351         <term>Poisson</term>
352         <listitem>
353           <para><literal>Y=grand(m,n,'poi',mu)</literal> generates
354           random variates from the Poisson distribution with mean
355             <literal>mu (real &gt;= 0.0)</literal>. Related function(s)
356             : <link linkend="cdfpoi">cdfpoi</link>.</para>
357         </listitem>
358       </varlistentry>
359       <varlistentry>
360         <term>random permutations</term>
361         <listitem>
362           <para><literal>Y=grand(n,'prm',vect)</literal> generate
363             <literal>n</literal> random permutations of the column
364             vector (<literal>m x 1</literal>)
365             <literal>vect</literal>.</para>
366         </listitem>
367       </varlistentry>
368       <varlistentry>
369         <term>uniform (def)</term>
370         <listitem>
371           <para><literal>Y=grand(m,n,'def')</literal> generates
372             random variates from the uniform distribution over
373             <literal>[0,1)</literal> (1 is never return).</para>
374         </listitem>
375       </varlistentry>
376       <varlistentry>
377         <term>uniform (unf)</term>
378         <listitem>
379           <para><literal>Y=grand(m,n,'unf',Low,High)</literal>
380             generates random reals uniformly distributed in
381             <literal>[Low, High)</literal>.</para>
382         </listitem>
383       </varlistentry>
384       <varlistentry>
385         <term>uniform (uin)</term>
386         <listitem>
387           <para><literal>Y=grand(m,n,'uin',Low,High)</literal>
388             generates random integers uniformly distributed between
389             <literal>Low</literal> and <literal>High</literal>
390             (included). <literal>High</literal> and
391             <literal>Low</literal> must be integers such that
392             <literal>(High-Low+1) &lt; 2,147,483,561</literal>.</para>
393         </listitem>
394       </varlistentry>
395       <varlistentry>
396         <term>uniform (lgi)</term>
397         <listitem>
398           <para><literal>Y=grand(m,n,'lgi')</literal> returns the
399             basic output of the current generator : random integers
400             following a uniform distribution over :</para>
401           <itemizedlist>
402             <listitem>
403               <para><literal>[0, 2^32 - 1]</literal> for mt, kiss and fsultra</para>
404             </listitem>
405             <listitem>
406               <para><literal>[0, 2147483561]</literal> for clcg2</para>
407             </listitem>
408             <listitem>
409               <para><literal>[0, 2^31 - 2]</literal> for clcg4</para>
410             </listitem>
411             <listitem>
412               <para><literal>[0, 2^31 - 1]</literal> for urand.</para>
413             </listitem>
414           </itemizedlist>
415         </listitem>
416       </varlistentry>
417     </variablelist>
418   </refsection>
419   <refsection>
420     <title>Set/get the current generator and its state</title>
421     <para> The user has the possibility to choose between different base 
422       generators (which give random integers following the 'lgi' distribution, the others 
423       being gotten from it).
424     </para>
425     <variablelist>
426       <varlistentry>
427         <term>mt</term>
428         <listitem>
429           <para>the Mersenne-Twister of M. Matsumoto and T. Nishimura, period about <literal>2^19937</literal>, 
430             state given by an array of <literal>624</literal> integers (plus an index onto this array); this  
431             is the default generator.</para>
432         </listitem>
433       </varlistentry>
434       <varlistentry>
435         <term>kiss</term>
436         <listitem>
437           <para>The Keep It Simple Stupid of G. Marsaglia,  period about <literal>2^123</literal>,
438             state given by <literal>4</literal> integers.</para>
439         </listitem>
440       </varlistentry>
441       <varlistentry>
442         <term>clcg2</term>
443         <listitem>
444           <para>a Combined 2 Linear Congruential Generator of P. L'Ecuyer,
445             period about <literal>2^61</literal>, state given by <literal>2</literal> integers ; this was 
446             the only generator previously used by grand (but slightly modified).</para>
447         </listitem>
448       </varlistentry>
449       <varlistentry>
450         <term>clcg4</term>
451         <listitem>
452           <para>a Combined 4 Linear Congruential Generator of P. L'Ecuyer,
453             period about <literal>2^121</literal>, state given by 4 integers ; this one is 
454             splitted in <literal>101</literal> different virtual (non over-lapping) generators 
455             which may be useful for different tasks (see 'Actions specific to clcg4' and
456             'Test example for clcg4').</para>
457         </listitem>
458       </varlistentry>
459       <varlistentry>
460         <term>urand</term>
461         <listitem>
462           <para>the generator used by the scilab function <link linkend="rand">rand</link>, state
463             given by <literal>1</literal> integer, period of <literal>2^31</literal> (based  on  theory  
464             and suggestions  given  in  d.e. knuth (1969),  vol  2. State). This
465             is the faster of this list but a little outdated (do not use it for
466             serious simulations).</para>
467         </listitem>
468       </varlistentry>
469       <varlistentry>
470         <term>fsultra</term>
471         <listitem>
472           <para>a Subtract-with-Borrow generator mixing with a congruential
473             generator of Arif Zaman and George Marsaglia, period more than <literal>10^356</literal>,
474             state given by an array of 37 integers (plus an index onto this array, a flag (0 or 1)
475             and another integer).</para>
476         </listitem>
477       </varlistentry>
478     </variablelist>
479     <para>The differents actions common to all the generators, are:
480     </para>
481     <variablelist>
482       <varlistentry>
483         <term>action= 'getgen'</term>
484         <listitem>
485           <para><literal>S=grand('getgen')</literal> returns the current base generator ( <literal>S</literal> is
486             a string among 'mt', 'kiss', 'clcg2', 'clcg4', 'urand', 'fsultra'.</para>
487         </listitem>
488       </varlistentry>
489       <varlistentry>
490         <term>action= 'setgen'</term>
491         <listitem>
492           <para><literal>grand('setgen',gen)</literal> sets the current base generator to be <literal>gen</literal>
493             a string among 'mt', 'kiss', 'clcg2', 'clcg4', 'urand', 'fsultra' (notes that this call 
494             returns the new current generator, ie gen).</para>
495         </listitem>
496       </varlistentry>
497       <varlistentry>
498         <term>action= 'getsd'</term>
499         <listitem>
500           <para><literal>S=grand('getsd')</literal> gets the current state (the current seeds) of the current base
501             generator ; <literal>S</literal> is given as a column vector (of integers) of dimension <literal>625</literal> 
502             for mt (the first being an index in <literal>[1,624]</literal>), <literal>4</literal> for kiss, <literal>2</literal> 
503             for clcg2,  <literal>40</literal> for fsultra, <literal>4</literal> for clcg4 
504             (for this last one you get the current state of the current virtual generator) and <literal>1</literal> 
505             for urand.</para>
506         </listitem>
507       </varlistentry>
508       <varlistentry>
509         <term>action= 'setsd'</term>
510         <listitem>
511           <para><literal>grand('setsd',S), grand('setsd',s1[,s2,s3,s4])</literal> sets the state of the current 
512             base generator (the new seeds) :</para>
513           <variablelist>
514             <varlistentry>
515               <term>for mt</term>
516               <listitem>
517                 <para><literal>S</literal> is a vector of integers of dim <literal>625</literal> (the first component is an index
518                   and must be in <literal>[1,624]</literal>, the <literal>624</literal> last ones must be in 
519                   <literal>[0,2^32[</literal>) (but must not be all zeros) ; a simpler initialisation may be done 
520                   with only one integer <literal>s1</literal> (<literal>s1</literal> must be in <literal>[0,2^32[</literal>) ;</para>
521               </listitem>
522             </varlistentry>
523             <varlistentry>
524               <term>for kiss</term>
525               <listitem>
526                 <para><literal>4</literal> integers <literal>s1,s2, s3,s4</literal> in <literal>[0,2^32[</literal> must be provided ;</para>
527               </listitem>
528             </varlistentry>
529             <varlistentry>
530               <term>for clcg2</term>
531               <listitem>
532                 <para><literal>2</literal> integers <literal>s1</literal> in <literal>[1,2147483562]</literal> and <literal>s2</literal> 
533                   in  <literal>[1,2147483398]</literal> must be given ;</para>
534               </listitem>
535             </varlistentry>
536             <varlistentry>
537               <term>for clcg4</term>
538               <listitem>
539                 <para><literal>4</literal> integers <literal>s1</literal> in <literal>[1,2147483646]</literal>, <literal>s2</literal> 
540                   in <literal>[1,2147483542]</literal>, <literal>s3</literal> in <literal>[1,2147483422]</literal>, 
541                   <literal>s4</literal> in  <literal>[1,2147483322]</literal> are required ;
542                   <literal>CAUTION</literal> : with clcg4 you set the seeds of the current virtual
543                   generator but you may lost the synchronisation between this one
544                   and the others virtuals generators (ie the sequence generated
545                   is not warranty to be non over-lapping with a sequence generated
546                   by another virtual generator)=&gt; use instead the 'setall' option.
547                 </para>
548               </listitem>
549             </varlistentry>
550             <varlistentry>
551               <term>for urand</term>
552               <listitem>
553                 <para><literal>1</literal> integer <literal>s1</literal> in  <literal>[0,2^31</literal>[ must be given.</para>
554               </listitem>
555             </varlistentry>
556             <varlistentry>
557               <term>for fsultra</term>
558               <listitem>
559                 <para>  <literal>S</literal> is a vector of integers of dim <literal>40</literal> (the first component 
560                   is an index and must be in <literal>[0,37]</literal>, the 2d component is a flag (0 or 1), the 3d
561                   an integer in [1,2^32[ and the 37 others integers in [0,2^32[) ; a simpler (and recommanded) 
562                   initialisation may be done with two integers <literal>s1</literal> and <literal>s2</literal> in 
563                   <literal>[0,2^32[</literal>.</para>
564               </listitem>
565             </varlistentry>
566           </variablelist>
567         </listitem>
568       </varlistentry>
569       <varlistentry>
570         <term>action= 'phr2sd'</term>
571         <listitem>
572           <para><literal>Sd=grand('phr2sd', phrase)</literal> given a <literal>phrase</literal> (character string) generates 
573             a <literal>1 x 2</literal> vector <literal>Sd</literal> which may be used as seeds to change the state of a 
574             base generator (initialy suited for clcg2).</para>
575         </listitem>
576       </varlistentry>
577     </variablelist>
578   </refsection>
579   <refsection>
580     <title>Options specific to clcg4</title>
581     <para>
582       The clcg4 generator may be used as the others generators but it offers the advantage 
583       to be splitted in several (<literal>101</literal>) virtual generators with non over-lapping 
584       sequences (when you use a classic generator you may change the initial state (seeds) 
585       in order to get another sequence but you are not warranty to get a complete  different one). 
586       Each virtual generator corresponds to a sequence of <literal>2^72</literal> values which is 
587       further split into <literal>V=2^31</literal> segments (or blocks) of length <literal>W=2^41</literal>.
588       For a given virtual generator you have the possibility to return at the beginning of the 
589       sequence or at the beginning of the current segment or to go directly at the next segment. 
590       You may also change the initial state (seed) of the generator <literal>0</literal> with the 
591       'setall' option which then change also the initial state of the other virtual generators 
592       so as to get synchronisation (ie in function of the new initial state of gen <literal>0</literal> 
593       the initial state of gen <literal>1..100</literal> are recomputed so as to get <literal>101</literal> 
594       non over-lapping sequences.   
595     </para>
596     <variablelist>
597       <varlistentry>
598         <term>action= 'setcgn'</term>
599         <listitem>
600           <para><literal>grand('setcgn',G)</literal> sets the current virtual generator for clcg4 (when clcg4
601             is set, this is the virtual (clcg4) generator number <literal>G</literal> which is used);  the virtual clcg4 
602             generators are numbered from <literal>0,1,..,100</literal> (and so <literal>G</literal> must be an integer 
603             in  <literal>[0,100]</literal>) ; by default the current virtual generator is <literal>0</literal>.</para>
604         </listitem>
605       </varlistentry>
606       <varlistentry>
607         <term>action= 'getcgn'</term>
608         <listitem>
609           <para><literal>S=grand('getcgn')</literal> returns the number of the current virtual clcg4 generator.</para>
610         </listitem>
611       </varlistentry>
612       <varlistentry>
613         <term>action= 'initgn'</term>
614         <listitem>
615           <para><literal>grand('initgn',I)</literal> reinitializes the state of the current virtual generator</para>
616           <variablelist>
617             <varlistentry>
618               <term>I = -1</term>
619               <listitem>
620                 <para>sets the state to its initial seed</para>
621               </listitem>
622             </varlistentry>
623             <varlistentry>
624               <term>I = 0</term>
625               <listitem>
626                 <para>sets the state to its last (previous) seed (i.e. to the beginning  of the current segment)</para>
627               </listitem>
628             </varlistentry>
629             <varlistentry>
630               <term>I = 1</term>
631               <listitem>
632                 <para>sets the state to a new seed <literal>W</literal> values from its last seed (i.e. to the beginning 
633                   of the next segment) and resets the current segment parameters.</para>
634               </listitem>
635             </varlistentry>
636           </variablelist>
637         </listitem>
638       </varlistentry>
639       <varlistentry>
640         <term>action= 'setall'</term>
641         <listitem>
642           <para><literal>grand('setall',s1,s2,s3,s4)</literal> sets the initial state of generator <literal>0</literal> 
643             to <literal>s1,s2,s3,s4</literal>. The initial seeds of the other generators are set accordingly 
644             to have synchronisation. For constraints on <literal>s1, s2, s3, s4</literal> see the 'setsd' action.</para>
645         </listitem>
646       </varlistentry>
647       <varlistentry>
648         <term>action= 'advnst'</term>
649         <listitem>
650           <para><literal>grand('advnst',K)</literal> advances the state of the current generator by <literal>2^K</literal> values 
651             and  resets the initial seed to that value.</para>
652         </listitem>
653       </varlistentry>
654     </variablelist>
655   </refsection>
656   <refsection>
657     <title>Test example for clcg4</title>
658     <para>
659       An example of  the  need of the splitting capabilities of clcg4 is as  follows. 
660       Two statistical techniques are being compared on  data of  different sizes. The first 
661       technique uses   bootstrapping  and is   thought to   be  as accurate using less data   
662       than the second method   which  employs only brute force.  For the first method, a data
663       set of size uniformly distributed between 25 and 50 will be generated.  Then the data set  
664       of the specified size will be generated and analyzed.  The second method will  choose a 
665       data set size between 100 and 200, generate the data  and analyze it.  This process will 
666       be repeated 1000 times.  For  variance reduction, we  want the  random numbers  used in the 
667       two methods to be the  same for each of  the 1000 comparisons.  But method two will  use more
668       random  numbers than   method one and  without this package, synchronization might be difficult.  
669       With clcg4, it is a snap.  Use generator 0 to obtain  the sample size for  method one and 
670       generator 1  to obtain the  data.  Then reset the state to the beginning  of the current  block
671       and do the same  for the second method.  This assures that the initial data  for method two is 
672       that used by  method  one.  When both  have concluded,  advance the block for both generators.</para>
673   </refsection>
674
675   <refsection>
676     <title>Examples</title>
677
678     <para>
679     In the following example, we generate random numbers from various distributions and 
680     plot the associated histograms.
681     </para>
682
683     <programlisting role="example">
684 <![CDATA[ 
685 // Normal
686 R = grand(400,800,"nor",0,1);
687 histplot(10,R)
688 // Uniform
689 R = grand(400,800,"def");
690 histplot(10,R)
691 // Poisson
692 R = grand(400,800,"poi",2);
693 histplot(10,R)
694  ]]>
695 </programlisting>
696
697     <para>
698     In the following example, we generate random numbers from the exponential distribution and 
699     then compare the empirical with the theoretical distribution.
700     </para>
701
702     <programlisting role="example">
703 <![CDATA[ 
704 lambda=1.6;
705 N=100000;
706 X = grand(1,100000,"exp",lambda);
707 clf();
708 classes = linspace(0,12,25);
709 histplot(classes,X)
710 x=linspace(0,12,25);
711 y = (1/lambda)*exp(-(1/lambda)*x);
712 plot(x,y,"ro-");
713 legend(["Empirical" "Theory"]);
714  ]]>
715 </programlisting>
716
717     <para>
718     In the following example, we generate random numbers from the gamma distribution and 
719     then compare the empirical with the theoretical distribution.
720     </para>
721
722     <programlisting role="example">
723 <![CDATA[ 
724     N=10000;
725     A=10;
726     B=4;
727     R=grand(1,N,'gam',A,B); 
728     XS=gsort(R,"g","i")';
729     PS=(1:N)'/N;
730     P=cdfgam("PQ",XS,A*ones(XS),B*ones(XS));
731     plot(XS,PS,"b-"); // Empirical distribution
732     plot(XS,P,"r-"); // Theoretical distribution
733     legend(["Empirical" "Theory"]);
734  ]]>
735 </programlisting>
736
737     <para>
738     In the following example, we generate 10 random integers in the [1,365] interval.
739     </para>
740
741     <programlisting role="example">
742 <![CDATA[ 
743     grand(10,1,"uin",1,365)
744  ]]>
745 </programlisting>
746
747     <para>
748     In the following example, we generate 12 permutations of the [1,2,...,7] set. 
749     The 12 permutations are stored column-by-column.
750     </para>
751
752     <programlisting role="example">
753 <![CDATA[ 
754     grand(12,"prm",(1:7)')
755  ]]>
756 </programlisting>
757
758     <para>
759     This pseudo random number generator is a deterministic sequence which aims at 
760     reproducing a independent identically distributed numbers.
761     In order to get reproducible simulations, the initial seed of the generator is constant, 
762     such that the sequence will remain the same from a session to the other. 
763     The first numbers produced by grand always are the same. 
764     In some situations, we may want to initialize the seed of the generator in 
765     order to produce less reproducible numbers. 
766     In this case, we may initialize the seed with the output of the getdate function:
767     </para>
768
769     <programlisting role="example">
770     <![CDATA[
771 grand("setsd",getdate("s"))
772     ]]>
773     </programlisting>
774
775   </refsection>
776
777   <refsection>
778     <title>See Also</title>
779     <simplelist type="inline">
780       <member>
781         <link linkend="rand">rand</link>
782       </member>
783     </simplelist>
784   </refsection>
785   <refsection>
786     <title>Authors</title>
787     <variablelist>
788       <varlistentry>
789         <term>randlib</term>
790         <listitem>
791           <para>
792             The codes to generate sequences following other distributions than def, unf, lgi,  uin and geom are
793             from "Library of Fortran Routines for Random Number  Generation", by Barry W. Brown 
794             and James Lovato, Department of Biomathematics, The University of Texas, Houston.
795             The source code is available at : http://www.netlib.org/random/ranlib.f.tar.gz
796           </para>
797         </listitem>
798       </varlistentry>
799       <varlistentry>
800         <term>mt</term>
801         <listitem>
802           <para>
803             The code is the mt19937int.c by M. Matsumoto and  T. Nishimura, "Mersenne Twister: 
804             A 623-dimensionally equidistributed  uniform pseudorandom number generator", 
805             ACM Trans. on Modeling and  Computer Simulation Vol. 8, No. 1, January, pp.3-30 1998.
806           </para>
807         </listitem>
808       </varlistentry>
809       <varlistentry>
810         <term>kiss</term>
811         <listitem>
812           <para>
813             The code was given by G. Marsaglia at the end of a thread concerning RNG in C in several 
814             newsgroups (whom sci.math.num-analysis) "My offer of  RNG's for C was an invitation 
815             to dance..." only kiss have been included in Scilab (kiss is made of a combinaison of 
816             severals others which are not visible at the scilab level).
817           </para>
818         </listitem>
819       </varlistentry>
820       <varlistentry>
821         <term>clcg2</term>
822         <listitem>
823           <para>
824             The method is from P. L'Ecuyer but the C code is provided at Luc Devroye's home page 
825             (<ulink url="http://cg.scs.carleton.ca/~luc/rng.html">http://cg.scs.carleton.ca/~luc/rng.html</ulink> See "lecuyer.c".).
826             This generator is made of two linear congruential sequences s1 = a1*s1 mod m1, 
827             with a1 = 40014, m1 = 2147483563 and s2 = a2*s2 mod m2 , with a2 = 40692, m2 = 2147483399.
828             The output is computed from output =  s1-s2 mod (m1 - 1).
829             Therefore, output is in [0, 2147483561]. The perido is about 2.3 10^18.
830             The state is given by (s1, s2). In case of a user modification of the state we must have :
831             s1 in [1, m1-1] and s2 in [1, m2-1].
832             The default initial seeds are s1 = 1234567890  and s2 = 123456789.
833           </para>
834         </listitem>
835       </varlistentry>
836       <varlistentry>
837         <term>clcg4</term>
838         <listitem>
839           <para>
840             The code is from P. L'Ecuyer and Terry H.Andres and provided at the P. L'Ecuyer
841             home page ( <ulink url="http://www.iro.umontreal.ca/~lecuyer/papers.html">http://www.iro.umontreal.ca/~lecuyer/papers.html</ulink>) A paper is also provided 
842             and this new package is the logical successor of an old 's one from : P.  L'Ecuyer
843             and S. Cote.
844             Implementing a Random   Number Package with Splitting Facilities.  ACM Transactions
845             on Mathematical  Software 17:1,pp 98-111.
846           </para>
847         </listitem>
848       </varlistentry>
849       <varlistentry>
850         <term>fsultra</term>
851         <listitem>
852           <para>
853             code from Arif Zaman (arif@stat.fsu.edu) and George Marsaglia (geo@stat.fsu.edu)
854           </para>
855         </listitem>
856       </varlistentry>
857       <varlistentry>
858         <term>scilab packaging</term>
859         <listitem>
860           <para>
861             By Jean-Philippe Chancelier and Bruno Pincon  
862           </para>
863         </listitem>
864       </varlistentry>
865       <varlistentry>
866         <term>This help page</term>
867         <listitem>
868           <para>
869              Copyright (C) 2010 - DIGITEO - Michael Baudin
870           </para>
871         </listitem>
872       </varlistentry>
873     </variablelist>
874   </refsection>
875 </refentry>