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

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

Updated build script to use platform-dependent dynamic library suffix.

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