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