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