The creation of random numbers is a surprisingly complicated affair. It is also vital to the success of a simulation exercise. Sooner or later you will want to simulate some real-life stochastic phenomenon which occurs in a manner resembling an identifiable statistical distribution, for example (to take the canonical simulation example) the time intervals between customers arriving to join a queue in front of a bank teller. Or perhaps you just want to add some controlled unpredictability to the behavior of your agents. One of the strengths of Swarm, as a simulation framework, is that it includes a number of methods for the creation of streams of random numbers that meet exacting standards.
Before we step in to the details of the Swarm random library, there is one point that needs to be made. There is no such thing as a random number, at least as far as a computer is concerned. Every number a computer creates comes from a formula. The challenge is to find a formula that makes the numbers sufficiently unpredictable that we can proceed as if they are random numbers that satisfy statistical requirements, like statistical independence of successive draws. This means that the device puts out numbers so that, even knowing all previous values, one is not able to predict the next number to come out without looking inside the program to steal the algorithm that is generating the numbers. The procedures we describe here might are more correctly be called pseudo-random number generators. With that point being clear, we often refer to them as random number generators.
In his section of the Swarm User Guide, we provide a survey of the basics of using the Swarm Random Library. A detailed technical manual has been prepared and it is included as an appendix to this guide. It goes into considerably greater depth on the technical issues that arise in generating random numbers.
Since not all users want to become experts in random (well, pseudo-random) numbers, we will start with the easy alternative. In the Swarm kernel--the code that executes at the beginning of any swarm program--there are three objects that can give useful random number streams. These objects are initialized and structured according to built-in assumptions that reflect the state-of-the-art in the creation of random number streams. The first two supply integers at random, the last one supplies numbers on a continuum.
The three built-in random number distributions are:
uniformUnsRand This object will draw a positive integer at random within a user specified interval. To get a random integer between 3 and 47, this command will work:
myUnsigned = [uniformUnsRand getUnsignedWithMin: 3 withMax: 47]; |
uniformIntRand This object will draw an ingeger at random from an interval that may include negative or positive numbers. A usage example would be:
myInteger = [uniformIntRand getUnsignedWithMin: -44 withMax: 47]; |
This object is an instance of the Swarm UniformIntegerDist, which is fully documented in the Swarm documentation.
uniformDblRand This object will draw a real number from a user-specified interval. Unlike the previous two, this distribution is not restricted to integers. If a random number from the interval [1,5] is needed, this command will work:
myDouble = [uniformDblRand getDoubleWithMin: 1 withMax: 5]; |
This object is an instance of the Swarm UniformDoubleDist.
When a Swarm program starts, it initializes these random number creators. They will deliver the same stream of numbers every time the program is run unless the user adds the "vary seed" parameter when the program is run. This parameter is -s and is added on the command line. For a full list of possible options, type the name of the application followed by --help.
These built-in random distribution objects use another built-in Swarm object that is called "randomGenerator". The object "randomGenerator" feeds input into each distribution. The meaning of the term "random generator" is explored in the next sections.