15.4. The Distributions in Swarm

All distributions are created through the two-step process outlined above. First one needs a random number generator. Then one initializes the distribution, optionally setting its parameters at the time of creation.

15.4.1. Classes that adopt the ProbabilityDistribution Protocol

The distributions currently offered in the Swarm library are

15.4.2. Matching generator and distribution objects

Each distribution object must have a generator associated with it. You may create a new generator for each distribution. Or, you may connect multiple distribution objects to one generator, so that they end up drawing output from the generator in an interleaved fashion. (This is what has been done with the predefined distributions.)

There is a method called createWithDefaults that can be uses to streamline the creation process. Here is a usage example:

	myNormalDist = [NormalDist createWithDefaults: [self getZone]];

If you create distribution objects using the createWithDefaults method Distribution Usage Guide, each distribution object is assigned its own, newly created, private random generator. Each distribution class uses a different class of default random generator, just to keep things as statistically independent as possible.

You can assign a seed for the private generator with code like this:

      
      [[myNormalDist getGenerator] setStateFromSeed: 9874321];
      
    

The usage of createWithDefaults is not without its dangers, however. If createWithDefaults is used to create two distributions of the same type, say two NormalDistributions, then (obviously) then each will have the same kind of private generator created for it. And, unless the simulation is started with the --varyseed option, then both private generators will start with the same seed and the two distributions will generate identical numbers.

15.4.3. Setting numerical parameters of distribution objects

Each distribution has its own set of key parameters. You may deal with these parameters in three different ways:

  1. Assign "default parameter values" when the distribution object is created For example:
    	    
    	    #import <random.h>
    	    id <NormalDist> myNormalDist;
    	    double sample;
    
    	    myNormalDist = [NormalDist create: [self getZone]
    	    setGenerator: randomGenerator];
    	    [myNormalDist setMean: 0.0 setVariance: 2.1];
    	    sample = [myNormalDist getDoubleSample];
    	    
    	  

  2. Specify parameters when random numbers are drawn. These values do not override or change the defaults that were set when the distribution was created.
    	    
    	    #import <random.h>
    	    id <NormalDist> myNormalDist;
    	    double sample;
    
    	    myNormalDist = [NormalDist create: [self getZone]
    	    setGenerator: randomGenerator];
    	    sample = [myNormalDist getSampleWithMean: 0.0 withVariance: 1.3];
    	    
    	  

  3. Re-set the parameters anytime. For example,
    	    
    	    [myNormalDist setMean: 0.0 setVariance: 2.1];
    	    sample = [myNormalDist getDoubleSample];	// from N[0.0,2.1]
    	    
    	  

For a more detailed description of the methods available from distribution objects, see the Distribution Usage Guide.