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

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

random-swb imported in the repository

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