**Table of Contents**- 15.1. Built-in Random Number Distributions
- 15.2. Overview of the Random Library
- 15.3. The Random Number Generators
- 15.3.1. How to use the default random generator
- 15.3.2. A list of generators in Swarm
- 15.3.3. A note on starting seeds

- 15.4. The Distributions in Swarm
- 15.5. How to Create Other Random Number Distributions

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:

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:**uniformUnsRand**

The objectmyUnsigned = [uniformUnsRand getUnsignedWithMin: 3 withMax: 47];

is an instance of the Swarm class*uniformUnsRand*`UniformUnsignedDist`. Readers can consult the documentation for a full explanation of all available options.This object will draw an ingeger at random from an interval that may include negative or positive numbers. A usage example would be:**uniformIntRand**myInteger = [uniformIntRand getUnsignedWithMin: -44 withMax: 47];

This object is an instance of the Swarm

`UniformIntegerDist`, which is fully documented in the Swarm documentation.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:**uniformDblRand**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.