(use eggdoc)
(define doc
`((eggdoc:begin
(name "swb-random")
(description "A random number generator based on the subtract-with-borrow (SWB) method.")
(author (url "http://chicken.wiki.br/ivan raikov" "Ivan Raikov"))
(history
(version "1.5" "Bug fix in the setup file")
(version "1.4" "Removed easyffi dependency")
(version "1.3" "Build script updated for better cross-platform compatibility")
(version "1.2" "Fixed the .meta file to include the documentation")
(version "1.1" "License upgrade to GPL v3")
(version "1.0" "Initial release"))
(requires)
(usage "(require-extension swb-random)")
(download "swb-random.egg")
(documentation
(p "The swb-random library is a port of the SML/NJ implementation of "
"a random number generator using the subtract-with-borrow (SWB) method "
"described by Marsaglia and Zaman in "
(pre "A New Class of Random Number Generators, "
"Ann. Applied Prob. 1(3), 1991, pp. 462-480. "))
(p "The SWB generator implemented in this library is a 30-bit generator with lags 48 and 8. "
"It has period " (tt "(2^1487 - 2^247)/105") " or about " (tt "10^445")
". The SWB generator acts locally like a lagged Fibonacci generator "
"and thus it is combined with a linear congruential generator "
(tt "(48271*a)mod(2^30-1)") ". ")
(subsection "Procedures"
(procedure "make-swb-random-state:: CONG-SEED SHR-SEED -> SWB-STATE"
(p "Creates an initial seed array and generator state. "
"The seed vector is filled one bit at a time by taking "
"the leading bit of the xor of a shift register and a "
"congruential sequence. The congruential generator is "
(tt "(c*48271) mod (2^30 - 1)") ". The shift register "
"generator is " (tt "c(I + L18)(I + R13)") ". "
"The same congruential generator continues to be used as a "
"mixing generator with the SWB generator."))
(procedure "swb-random!:: SWB-STATE -> FIXNUM"
(p "Computes the next random number. The output from the SWB "
"generator is xor-ed with a number from the linear "
"congruential generator. This procedure modifies its input "
"argument. "))
(procedure "swb-random-natural!:: SWB-STATE -> FIXNUM"
(p "Computes the next random number and returns its absolute value. "
"The output from the SWB generator is xor-ed with a number from the "
"linear congruential generator. This procedure modifies its input "
"argument. "))
(procedure "swb-random-real!:: SWB-STATE -> FLONUM"
(p "Computes the two next random numbers and uses them to construct "
"a real number of the range " (tt "[0..1]") ". "
"The output from the SWB generator is xor-ed with a number from the "
"linear congruential generator. This procedure modifies its input "
"argument. "))
(procedure "swb-random-range!:: (FIXNUM * FIXNUM) -> (SWB-STATE -> FIXNUM)"
(p "Given a range " (tt "[i..j], 0 <= i < j") ", returns a "
"procedure that takes in a random number generator state and "
"computes a random number in the given range. "
"The output from the SWB generator is xor-ed with a number from the "
"linear congruential generator. The returned procedure modifies its input "
"argument. "))
(procedure "swb-random:: SWB-STATE -> SWB-STATE * FIXNUM"
(p "Computes the next random number. The output from the SWB "
"generator is xor-ed with a number from the linear "
"congruential generator. The new generator state is returned along "
"with the random number. "))
(procedure "swb-random-natural:: SWB-STATE -> SWB-STATE * FIXNUM"
(p "Computes the next random number and returns its absolute values. "
"The output from the SWB generator is xor-ed with a number from the linear "
"congruential generator. The new generator state is returned along "
"with the random number. "))
(procedure "swb-random-real:: SWB-STATE -> SWB-STATE * FLONUM"
(p "Computes the two next random numbers and uses them to construct "
"a real number of the range " (tt "[0..1]") ". "
"The output from the SWB generator is xor-ed with a number from the "
"linear congruential generator. The new generator state is returned along "
"with the random number. "))
(procedure "swb-random-range:: (FIXNUM * FIXNUM) -> (SWB-STATE -> SWB-STATE * FIXNUM)"
(p "Given a range " (tt "[i..j], 0 <= i < j") ", returns a "
"procedure that takes in a random number generator state and "
"computes a random number in the given range. "
"The output from the SWB generator is xor-ed with a number from the "
"linear congruential generator. The new generator state is returned along "
"with the random number. "))))
(examples)
(license
"Copyright 2007 Ivan Raikov.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
A full copy of the GPL license can be found at
."))))
(if (eggdoc->html doc) (void))