Random Library

Table of Contents
ACGgen
BernoulliDist
BooleanDistribution
C2LCGXgen
C2MRG3gen
C2TAUS1gen
C2TAUS2gen
C2TAUS3gen
C2TAUSgen
C3MWCgen
C4LCGXgen
CombinedLongGenerator
CombinedLongSplitGenerator
CombinedShortGenerator
CombinedShortSplitGenerator
DoubleDistribution
ExponentialDist
GammaDist
IntegerDistribution
InternalState
LCG1gen
LCG2gen
LCG3gen
LCGgen
LogNormalDist
MRG5gen
MRG6gen
MRG7gen
MRGgen
MT19937gen
MWCAgen
MWCBgen
MultiSeed
Normal
NormalDist
PMMLCG1gen
PMMLCG2gen
PMMLCG3gen
PMMLCG4gen
PMMLCG5gen
PMMLCG6gen
PMMLCG7gen
PMMLCG8gen
PMMLCG9gen
PMMLCGgen
PSWBgen
ProbabilityDistribution
RWC2gen
RWC8gen
RandomBitDist
SCGgen
SWB1gen
SWB2gen
SWB3gen
SWBgen
Simple
SimpleOut
SingleLongGenerator
SingleLongSplitGenerator
SingleSeed
SingleShortGenerator
SingleShortSplitGenerator
Split
SplitMultiSeed
SplitOut
SplitSingleSeed
TGFSRgen
TT403gen
TT775gen
TT800gen
UniformDoubleDist
UniformIntegerDist
UniformUnsignedDist
UnsignedDistribution
General

1. Dependencies

Following are the other header files imported by <random.h>:

#import <defobj.h>
#import <random/generators.h>
#import <random/distributions.h>
#import <random/RandomDefs.h>
#import <random/RandomVars.h>

The defobj library interface is included to provide the basic object support. RandomDefs.h contains some C preprocessor macros and typedefs used in the library.

This reference guide shows contains the object definitions for generators and distributions and also encodes the inheritance structure through the "Protocols that this protocol uses" section of each protocol. Just click on a (sub-)protocol name to see what methods it implements. (You may want to review the section on Protocols in the Objective-C book here!)

In the protocol described , any protocol that ultimately inherits from CREATABLE defines an object that you can use in your program. (This is part of the Swarm DefObj machinery.) In other words, while 'InternalState' is a normal protocol (a list of method definitions), the name 'ACGgen' refers to both a protocol and a class that implements that protocol. (You create an ACG generator by saying myGen = [ACGgen create: ....]). Similarly, 'GammaDist' defines both a protocol and a class that implements that protocol.

All generators and distributions ultimately inherit from SwarmObject.

The two files 'methods.SimpleGenerators.h' and 'methods.SplitGenerators.h' in directory /random/docs show the complete sets of methods implemented for the two most common types of generator.

2. Compatibility

3. Usage Guide

3.1. Overview

The random library basically consists of two parts, the actual pseudorandom number algorithms and the transformations that change the output of the pseudorandom number algorithms into the simulated distributions. The pseudorandom number algorithms are called generators throughout these documents and many times the "pseudo" is dropped from pseudorandom, even though there is no true random number generator implemented in Swarm.

3.2. Generator Usage Notes

Primary Author: Sven Thommsen
<>
Notes on the use of the random number generator
Swarm 1.0.3 (random 0.75)
1997-09-01

3.3. Distribution Usage Note

Primary Author: Sven Thommsen
<>
Notes on the use of the distribution objects
Swarm 1.0 (random 0.6)
1997-09-01

4. Advanced Usage Guide

Unavailable

5. Subclassing Reference

Unavailable

6. Interface Design Notes

Never has a Swarm library interface been debated as this one was (and still is). This document will attempt to provide some of the rational for the decisions made by echoing some of the controversial issues covered in the debates on the interface. (These discussions overlapped into implementation. But, the point, here, is to give people an idea of the complexity of the issues involved in useful pseudo-random number use in simulation.)

Issues:.

These are just the questions and issues. Some addition should follow (when there's time) addressing each issue and giving rationale for what we chose. But, that's a big job.

7. Implementation Notes

The code here represents an effort to implement several efficient, reasonably safe generators. The algorithms come from reading the literature [See: $(SWARMHOME)/src/random/docs/SOURCES.for.0.7]: these algorithms have been implemented as accurately as possible and run through some simple tests. There is always a chance that some algorithm here is no good - there's also the chance that it is implemented incorrectly.

For best results, library users should test these generators themselves in some domain-specific way. One easy way to do this is to run an experiment twice: once with one class of generator (say, PMMLCG), and once with another (say, SWB). If the results differ radically, then you can suspect the generator. If they don't, well, the generator still might be faulty.

There is also a tarball of test programs for the random number library on the Swarm ftp site: SwarmTests-0.7.tar.gz

The generators supplied with this release have been subjected to statistical testing using George Marsaglia's Diehard tests as well as John Walker's entropy tests (ENT). The results of these tests are summarized in the document $(SWARMHOME)/src/random/docs/doc.quality.generators. Other properties of the generators are summarized in $(SWARMHOME)/src/random/docs/generators.table. Some notes on how to choose a generator for your simulation are found in $(SWARMHOME)/src/random/docs/CHOOSING.A.GENERATOR.

The ENT test is included in the tarball of test programs found at the Swarm web site. The Diehard tests are copyright and hence are not, but they can be downloaded from the web at http://www.hku.hk/internet/randomCD.html .

The distribution objects have not been statistically tested.

Documentation and Implementation Status

This is version 0.75 of Random. It was donated by Sven Thommesen. Version 0.6 was a reimplementation of most of Nelson Minar's original random with many changes and a new interface. This version adds many more generators and distributions and changes the interface somewhat.

The implementation may be a little unstable. It hasn't been fully tested. Sven has also contributed a test suite which we will make available on the web site. But, as with any pseudo-random number generation library, results obtained from it should be examined very closely. But we are reasonably sure the generators and distributions have been correctly implemented.

Revision History (random)