V. Random Library

1. Dependencies

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

#import <objectbase.h>
#import <random/generators.h>
#import <random/distributions.h>
#import <random/randomdefs.h>
#import <random/randomvars.h>

The objectbase 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 contains the object definitions for generators and distributions (see the list above) 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 protocols 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. Similarly, 'GammaDist' defines both a protocol and a class that implements that protocol.

All generators and distributions ultimately inherit from SwarmObject.

2. Compatibility

  • 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.

  • 1.0, 1.1, 1.2, 1.3, 1.3.1, 1.4. There were no major compatibility issues in these releases.

3. Usage Guide

3.1. Overview

The random library contains two kinds of objects, the generators which implement different pseudo-random-number algorithms, and the distributions which transform the (uniform) output from the generators into the desired simulated statistical distributions. (The Swarm random library does not implement any true random number generators at this time.)

3.2. User Guide for Beginners

Please see the Random Appendix. This section may go away in the future to be relocated in the Swarm User Guide.

5. Subclassing Reference

Random library objects do not do anything exotic during the create phase. The competent programmer may subclass these objects in the normal manner.

Table of Contents
ACGgen — Additive Congruential Generator
BernoulliDist — Bernoulli Distribution
BooleanDistribution — Boolean Distribution
C2LCGXgen — A short component based generator with splitting facilities. Recommended. This combined random generator uses 2 (PMM)LGC generators.
C2MRG3gen — Combined Multiple Recursive Generator. A combination of 2 multiple recursive LCG generators.
C2TAUS1gen — Combined Tausworthe generator 1
C2TAUS2gen — Combined Tausworthe generator 2
C2TAUS3gen — Combined Tausworthe generator 3
C2TAUSgen — Combined Tausworthe generator
C3MWCgen — Combined Multiply With Carry generator
C4LCGXgen — Combined random generator using 4 (PMM)LGC generators.
DoubleDistribution — Double Distribution
ExponentialDist — Exponential distribuiton
GammaDist — Gamma distribution
IntegerDistribution — Integer Distribution
InternalState — Archiving routines for internal generator and distribution state.
LCG1gen — Linear Congruential Generator 1
LCG2gen — Linear Congruential Generator 2
LCG3gen — Linear Congruential Generator 3
LCGgen — Linear Congruential Generator
LogNormalDist — Log-Normal distribution
MRG5gen — Multiple Recursive [LCG] Generator 5
MRG6gen — Multiple Recursive [LCG] Generator 6
MRG7gen — Multiple Recursive [LCG] Generator 7
MRGgen — Multiple Recursive [LCG] Generator
MT19937gen — 'Mersenne Twister' Twisted GFSR generator
MWCAgen — Multiply-With-Carry generator
MWCBgen — Multiply-With-Carry generator
MultiSeed — Internal
Normal — Internal
NormalDist — Normal (Gaussian) distribution
PMMLCG1gen — Prime Modulus Multiplicative Linear Congruential Generator 1
PMMLCG2gen — Prime Modulus Multiplicative Linear Congruential Generator 2
PMMLCG3gen — Prime Modulus Multiplicative Linear Congruential Generator 3
PMMLCG4gen — Prime Modulus Multiplicative Linear Congruential Generator 4
PMMLCG5gen — Prime Modulus Multiplicative Linear Congruential Generator 5
PMMLCG6gen — Prime Modulus Multiplicative Linear Congruential Generator 6
PMMLCG7gen — Prime Modulus Multiplicative Linear Congruential Generator 7
PMMLCG8gen — Prime Modulus Multiplicative Linear Congruential Generator 8
PMMLCG9gen — Prime Modulus Multiplicative Linear Congruential Generator 9
PMMLCGgen — Prime Modulus Multiplicative Linear Congruential Generator
PSWBgen — Subtract-with-borrow Congruential Generator with prime modulus
ProbabilityDistribution — Probability Distribution
RWC2gen — 2-lag Recursion With Carry generator
RWC8gen — Multiply With Carry generator ("The Mother of all RNG's")
RandomBitDist — Random Bit Distribution
SCGgen — Subtractive Congruential Generator
SWB1gen — Subtract-with-borrow Congruential Generator 1
SWB2gen — Subtract-with-borrow Congruential Generator 2
SWB3gen — Subtract-with-borrow Congruential Generator 3
SWBgen — Subtract-with-borrow Congruential Generator
Simple — Internal
SimpleOut — Internal
SimpleRandomGenerator — A Simple (non-split) generator.
SingleSeed — Internal
Split — Internal
SplitMultiSeed — Internal
SplitOut — Internal
SplitRandomGenerator — A Split generator.
SplitSingleSeed — Internal
TGFSRgen — Twisted GFSR generator
TT403gen — A single long generator recommended for use.
TT775gen — A single long generator recommended for use.
TT800gen — A single long generator recommended for use.
UniformDoubleDist — Uniform Double Distribution
UniformIntegerDist — Uniform Integer Distribution
UniformUnsignedDist — Uniform Unsigned Distribution
UnsignedDistribution — Unsigned Distribution
General — Module for random number generation

Documentation and Implementation Status

This is version 0.8 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. Versions 0.7 and 0.75 added many more generators and distributions and changed the interface somewhat. This version cleaned up the protocol interface definitions and fixed a few small bugs. The documentation was also improved a bit.

We are reasonably sure that the generators and distributions included here have been correctly implemented. The generators have been subjected to a battery of statistical tests, and the results are described in the documentation. The distributions have not been subjected to statistical tests yet. As with any pseudo-random number generation library, the results obtained should be examined closely. A set of test programs which exercises the objects is available on the Swarm web site, and the statistical tests are also available on the web.

Revision History (random)