Suppose you want to draw random numbers from a Normal Distribution with a mean of 33 and variance of 10. There is no "normal distribution object" created automatically in the Swarm kernel, you have to create that in your code. In order to explain how this is done, it is important to understand the two-step nature of the process of creating random numbers from a distribution.
Mathematically speaking, numbers are created as draws from a particular distribution through a two-step process. First, one or more numbers on a given interval are drawn. If one is creating a continuous distribution, the interval is usually [0,1). Then using various formulae from the field of statistics, a draw from a particular distribution is created that depends on the draw(s) in the first step. This two-step process is documented in the literature on simulation. (A very readable and complete treatment is found in Averill M. Law and W.David Kelton, Simulation Modeling and Analysis, New York: McGraw Hill.)
The first stage in the process uses an object called a random number generator. A random number generator is a component that can generate unpredictable numbers within some interval that are "equally likely" to occur. There have been many kinds of procedures proposed for creating numbers that appear to be random. Swarm includes a great many of these. The default random generator, the one that Swarm uses to generate its built-in random number objects, is MT19337. The generator has a period close to 219937 (1 x 106001), so there is no danger of running a simulation long enough for the generator to repeat itself. At one microsecond per call, it would take about 3.2 x 105987 years to exhaust this generator. For comparison, the age of the Universe is `only' 2 x 1010 years! This generator can be asked either for a real number (a variable of type double) between [0,1) or for an integer, which will be uniformly distributed on the range [0,4294967295] = [0,232-1].
In the second stage, the output from the random number generator is used to create a random variate that meets the specificiations of a particular distribution. Of course, some are done more easily than others. If one needs a draw from a Uniform distribution, then the output of the random number generator itself can be used. On the other hand, some distributions require complicated transformations in order to create numbers that appear as if they were generated from the distribution. For many common statistical distributions, the code to transform the uniformly distributed random numbers into other distributions are provided in the Swarm library. While there are some distributions that are not currently supported, they can typically be constructed by users with the existing distributions as building blocks.
The Swarm Random library can be divided into two parts, which parallel the two-stage process we have described. There are
Generators
Distributions
The following sections will dig into the details of these libraries, but first we will offer a couple of simple usage examples.
Suppose one wants to draw numbers from a normal distribution. The normal is a well known distribution and it has known statistical properties. The object "randomGenerator" is created when the Swarm kernel is initialized, so it can be used in any distribution as the random number generator. To create a NormalDist distribution object and connect it to the predefined MT19937 generator, this code will suffice:
#import <random.h> //This includes the Swarm random library
id <NormalDist> myNormalDist; //This names your object and adopts the NormalDist protocol
myNormalDist = [NormalDist create: [self getZone]
setRandomGenerator: randomGenerator]; |
If for some reason, one does not want to use MT19937 as the generator, then one of the other Swarm generators can be selected and explicitly created. The next code example uses a generator called RWC8gen. This code will first create an instance of that generator, then it will create an object to draw normally distributed observations.
int mySeed = 123776;
id myGenerator;
id <NormalDist> myNormalDist;
myGenerator = [RWC8gen create: [self getZone]
setStateFromSeed: mySeed];
myNormalDist = [NormalDist create: [self getZone]
setRandomGenerator: myGenerator];
|
The random library is designed in a highly versatile way. Each generator must have a "seed" value, a starting place from which to spin out the random numbers. As long as one leaves the seed at the same value, then the stream of random numbers will be replicated each time the program is run. If one does not want to specify a seed, then that chore can be left up to Swarm, which will insert a seed on behalf of the user. The way to create a generator that uses the system default value for the seed is shown here:
myGenerator = [RWC8gen createWithDefaults: [self getZone]]; |
Another example of the versatility of the Swarm random library is in the design of the distribution classes themselves. We have already seen examples in which random numbers are drawn according to user specified requirements. In the case of the Normal distribution, one can draw from a distribution with a mean of 0 and variance of 1.3 with this command:
double sample;
sample = [myNormalDist getSampleWithMean: 0.0 withVariance: 1.3];
|
If one expects to want many draws from a distribution with that same set of parameters, then the distribution object can be told to set those values as the defaults. After the default values of the mean and variance are set, then values retrieved from that distribution object can be retrieved with the simpler method getDoubleSample. For example:
[myNormalDist setMean: 0.0 setVariance: 1.3];
sample = [myNormalDist getDoubleSample];
|
Of course, each distribution will have its own parameters and particular methods for setting them. These parameters can be reset at any time.