## swb-random

A random number generator based on the subtract-with-borrow (SWB) method.

## Usage

(require-extension swb-random)

## Documentation

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

A New Class of Random Number Generators, Ann. Applied Prob. 1(3), 1991, pp. 462-480.

The SWB generator implemented in this library is a 30-bit generator with lags 48 and 8. It has period `(2^1487 - 2^247)/105` or about `10^445`. The SWB generator acts locally like a lagged Fibonacci generator and thus it is combined with a linear congruential generator `(48271*a)mod(2^30-1)`.

### Procedures

*[procedure]*

`make-swb-random-state:: CONG-SEED SHR-SEED -> SWB-STATE`

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 `(c*48271) mod (2^30 - 1)`. The shift register generator is `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`

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`

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`

Computes the two next random numbers and uses them to construct a real number of the range `[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)`

Given a range `[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`

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`

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`

Computes the two next random numbers and uses them to construct a real number of the range `[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)`

Given a range `[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.

## About this egg

### Author

### Version history

- 1.12
- Documentation converted to wiki format
- 1.11
- Added import of foreign library [thanks to felix]
- 1.9
- Added matchable as a dependency
- 1.8
- Bug fix in interface to cminus function
- 1.7
- Ported to Chicken 4
- 1.5
- Bug fix in the setup file
- 1.4
- Removed easyffi dependency
- 1.3
- Build script updated for better cross-platform compatibility
- 1.2
- Fixed the .meta file to include the documentation
- 1.1
- License upgrade to GPL v3
- 1.0
- Initial release

### License

Copyright 2007-2010 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 <http://www.gnu.org/licenses/>.