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