Overview First, a few thoughts on pseudorandom number generation. It's hard to do right. There are many problems: the root cause, of course, is that computer algorithms themselves are not random. But there are also problems with defining "random", coming up with good tests for generators, and implementing algorithms correctly and efficiently. The history of pseudorandom number generation in simulation work is mostly embarassing. This library attempts to do a decent job of generating random numbers, as well as documenting how things work and what shortcomings there are. If you want to learn more about random number generation, the bibliography [See: $(SWARMHOME)/src/random/docs/SOURCES.for.0.7] has useful notes. Knuth is the main reference in this realm, but too old to describe most of the particular generators used here. |
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.
1.0.2 -> 1.0.3. Note: The new random library does not work in the same way as the old one. This means that some applications that used the random library provided with the 1.0.2 release will be broken. However, porting these applications to the new random library will be fairly easy since large efforts were made to adhere to the standard set with the last version and some backwards compatibility hooks were incorporated.
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.
Primary Author: Sven Thommsen |
<sthomme@humsci.auburn.edu> |
Notes on the use of the random number generator |
Swarm 1.0.3 (random 0.75) |
1997-09-01 |
IMPROVEMENTS over v. 0.6: |
Primary Author: Sven Thommsen |
<sthomme@humsci.auburn.edu> |
Notes on the use of the distribution objects |
Swarm 1.0 (random 0.6) |
1997-09-01 |
IMPROVEMENTS over v. 0.6: |
Unavailable
Unavailable
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:.
Different classes for generators or variants? Ref: http://www.sela.co.il:8080/swtrain/new/shai/tgp.ps .
Include non-recommended generators?
Seed vs. State for generators?
What is "state" and how do we handle it?
Larger issue of debugging support via an object reporting its own configuration via a special method and how this relates to object state reporting and object saving.
Separate classes for separate distribution types (e.g. double, integer, unsigned :: continuous/discrete)?
Problems with the transformation from generator output to distribution output.
What precision should be supported?
Should the generator underlying a distribution be visible through the distribution?
Efficiency!
What distributions to provide?
What generators to provide?
Open vs. Closed intervals?
Programmed default generators, seeds, and states?
Programming by committee? (a.k.a. Software process!)
Shorthand create methods?
Potential phase optimizations?
Random number streams, syncing limit cycles, and proper simulation vs. code debugging. (This is a HOT ONE.)
Library interchangeability.
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.
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)