source: project/random-swb/trunk/random-swb-eggdoc.scm @ 4878

Last change on this file since 4878 was 4878, checked in by Ivan Raikov, 13 years ago

License upgrade to GPL v3.

File size: 5.1 KB
Line 
1
2(use eggdoc)
3
4(define doc
5  `((eggdoc:begin
6     (name "swb-random")
7     (description "A random number generator based on the subtract-with-borrow (SWB) method.")
8     (author (url "mailto:iraikov@ece.gatech.edu" "Ivan Raikov"))
9
10     (history 
11      (version "1.1" "License upgrade to GPL v3")
12      (version "1.0" "Initial release"))
13
14     (requires)
15
16     (usage "(require-extension swb-random)")
17
18     (download "swb-random.egg")
19
20     (documentation
21     
22      (p "The swb-random library is a port of the SML/NJ implementation of "
23         "a random number generator using the subtract-with-borrow (SWB) method "
24         "described by Marsaglia and Zaman in " 
25         (pre "A New Class of Random Number Generators, "
26              "Ann. Applied Prob. 1(3), 1991, pp. 462-480. "))
27
28      (p "The SWB generator implemented in this library is a 30-bit generator with lags 48 and 8. "
29         "It has period " (tt "(2^1487 - 2^247)/105") " or about " (tt "10^445") 
30         ". The SWB generator acts locally like a lagged Fibonacci generator "
31         "and thus it is combined with a linear congruential generator "
32         (tt "(48271*a)mod(2^30-1)") ". ")
33
34      (subsection "Procedures"
35
36                  (procedure "make-swb-random-state:: CONG-SEED SHR-SEED -> SWB-STATE"
37                             (p "Creates an initial seed array and generator state. "
38                                "The seed vector is filled one bit at a time by taking "
39                                "the leading bit of the xor of a shift register and a "
40                                "congruential sequence.  The congruential generator is "
41                                (tt "(c*48271) mod (2^30 - 1)") ". The shift register "
42                                "generator is " (tt "c(I + L18)(I + R13)") ".  "
43                                "The same congruential generator continues to be used as a "
44                                "mixing generator with the SWB generator."))
45
46                  (procedure "swb-random!:: SWB-STATE -> FIXNUM"
47                             (p "Computes the next random number. The output from the SWB "
48                                "generator is xor-ed with a number from the linear "
49                                "congruential generator. This procedure modifies its input "
50                                "argument. "))
51
52                  (procedure "swb-random-natural!:: SWB-STATE -> FIXNUM"
53                             (p "Computes the next random number and returns its absolute value. "
54                                "The output from the SWB generator is xor-ed with a number from the "
55                                "linear congruential generator. This procedure modifies its input "
56                                "argument. "))
57
58                  (procedure "swb-random-real!:: SWB-STATE -> FLONUM"
59                             (p "Computes the two next random numbers and uses them to construct "
60                                "a real number of the range " (tt "[0..1]") ". "
61                                "The output from the SWB generator is xor-ed with a number from the "
62                                "linear congruential generator. This procedure modifies its input "
63                                "argument. "))
64
65                  (procedure "swb-random-range!:: (FIXNUM * FIXNUM) -> (SWB-STATE -> FIXNUM)"
66                             (p "Given a range " (tt "[i..j], 0 <= i < j") ",  returns a "
67                                "procedure that takes in a random number generator state and "
68                                "computes a random number in the given range. "
69                                "The output from the SWB generator is xor-ed with a number from the "
70                                "linear congruential generator. The returned procedure modifies its input "
71                                "argument. "))
72
73                  (procedure "swb-random:: SWB-STATE -> SWB-STATE * FIXNUM"
74                             (p "Computes the next random number. The output from the SWB "
75                                "generator is xor-ed with a number from the linear "
76                                "congruential generator. The new generator state is returned along "
77                                "with the random number. "))
78
79                  (procedure "swb-random-natural:: SWB-STATE -> SWB-STATE * FIXNUM"
80                             (p "Computes the next random number and returns its absolute values. "
81                                "The output from the SWB generator is xor-ed with a number from the linear "
82                                "congruential generator. The new generator state is returned along "
83                                "with the random number. "))
84
85                  (procedure "swb-random-real:: SWB-STATE -> SWB-STATE * FLONUM"
86                             (p "Computes the two next random numbers and uses them to construct "
87                                "a real number of the range " (tt "[0..1]") ". "
88                                "The output from the SWB generator is xor-ed with a number from the "
89                                "linear congruential generator. The new generator state is returned along "
90                                "with the random number. "))
91
92                  (procedure "swb-random-range:: (FIXNUM * FIXNUM) -> (SWB-STATE -> SWB-STATE * FIXNUM)"
93                             (p "Given a range " (tt "[i..j], 0 <= i < j") ",  returns a "
94                                "procedure that takes in a random number generator state and "
95                                "computes a random number in the given range. "
96                                "The output from the SWB generator is xor-ed with a number from the "
97                                "linear congruential generator. The new generator state is returned along "
98                                "with the random number. "))))
99                 
100
101     (examples)
102
103     (license
104      "Copyright 2007 Ivan Raikov.
105
106This program is free software: you can redistribute it and/or modify
107it under the terms of the GNU General Public License as published by
108the Free Software Foundation, either version 3 of the License, or (at
109your option) any later version.
110
111This program is distributed in the hope that it will be useful, but
112WITHOUT ANY WARRANTY; without even the implied warranty of
113MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
114General Public License for more details.
115
116A full copy of the GPL license can be found at
117<http://www.gnu.org/licenses/>."))))
118
119(if (eggdoc->html doc) (void))
Note: See TracBrowser for help on using the repository browser.