uchicago.src.sim.engine
Class ParameterReader

java.lang.Object
  |
  +--uchicago.src.sim.engine.ParameterReader

public class ParameterReader

extends Object

Reads a model's parameters from a parameter file for a batch run. A typical user should have no need to use this class directly.

A parameter file has the following format:

 runs: x
 Parameter {
  value_definition
 }
 

where x is some number and Parameter is the name of some model parameter accessible through get and set methods. Runs specifies the number of runs to execute for the current parameter value. The value_definition is composed of one or more keywords and corresponding values.

The multi-keyword value definitions:

• start: the starting numerical value of a parameter.
• end: the ending numerical value of a parameter.
• incr: the amount to increment the current value of the parameter.

The start, end, and incr keywords together provide a value defintion and must always occur together. For a batch simulation they define a parameter space which will be automatically iterated through. start: defines the initial parameter. end: the parameter up to and including ending parameter, and incr: the amount to increment the start: value and any succeeding values to reach the end: parameters. For a gui simulation the start: value is taken as the default parameter and the remaining keywords are ignored.

Single keyword value_definitions:

• set: defines a single numerical value as a constant for the entire collection of batch runs.
• set_list: defines a space separated list of numerical values. A batch simluation will iterate through the list.
• set_boolean: defines a boolean value as a constant for the entire batch simulation. Allowed values are "true" and "false" (without the quotes).
• set_string: defines a string value as a constant for the entire batch simluation. The string value must not contain any white space.
• set_boolean_list: same as set_list but list of boolean values (true or false).
• set_string_list: same as set_list but list of string values.

All these work using the get and set accessor method pattern. So regardless of how the value is defined, the model must have the appropriate get and set methods matching the parameter name.

Some examples,

 runs: 10
 Food {
  start: 10
  end: 30
  incr: 10
 }
 

This means start with a food value of 10 and run the simulation 10 times using this value. Increment the food value by 10 and run the simulation 10 times with a food value of 20 (start 10 + incr 10). Increment the food value by another 10, and run another 10 times with the food value of 30 (start 10 + incr 10 + incr 10). This example assumes that the model has getFood() and setFood() methods.

More than one parameter can be specified, so for example,

 runs: 10
 Food {
  start: 10
  end: 30
  incr: 10
 }

 MaxAge {
  start: 10
  end: 30
  incr: 10
 }
 

Where both food and max age are incremented as described above. If using more than one parameter it is important to synchronize them, as whenever a parameter's current value is greater than its end value, the simulation will exit.

Parameters can also be nested. For example,

 runs: 1
 Food {
  start: 10
  end: 30
  incr: 10
  {
    runs: 10
    MaxAge {
      start: 0
      end: 40
      incr: 1
    }
  }
 }
 

This example means starting with a food value of 10 run the simulation 10 times with a MaxAge of 0. Increment MaxAge by 1 and run the simulation 10 times, and so on until the value of MaxAge is greater than 40. At this point, increment Food by 10 and run the simulation 10 times with a MaxAge of 0. Increment MaxAge by 1 and run the simulation 10 times. This continues until the value of Food is greater than 30. Multiple levels of nesting are possible.

 runs: 1
 Food {
  start: 10
  end: 30
  incr: 10
  {
    runs: 10
    MaxAge {
      start: 0
      end: 40
      incr: 1
    }
  }
 }
 RngSeed {
  set: 1
 }
 

RngSeed is parameter of every model and can be manipulated like any other parameter. And here it is set to one and this value will remain constant over all the individual batch runs.

 runs: 1
 Food {
  start: 10
  end: 30
  incr: 10
  {
    runs: 10
    MaxAge {
      set_list: 1.2 3 10 12 84
    }
  }
 }
 RngSeed {
  set: 1
 }
 

This is the same as above except that maxAge will be incremented via the list. So first run with maxAge as 1.2, do this for 10 runs. Then set maxAge to 3 and run with this value for 10 times. Continue until the end of the list, then increment Food and start and the beginning of the MaxAge list, and so on until the Food parameter is greater than 30.

The boolean and string keywords work in the identical manner, but set boolean and string values instead of numeric ones.

Parameter files can contain comments delimited by the standard c/c++/java comment markers: '//' and so on.

Constructor Summary

ParameterReader()

ParameterReader(String fileName)
Constructs a ParameterReader with specified parameter file.

Method Summary

Vector	getParameters() Gets the parameters read by this Parameter reader
Vector	read(String fileName)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParameterReader

public ParameterReader()

ParameterReader

public ParameterReader(String fileName)
                throws IOException

Constructs a ParameterReader with specified parameter file. If the reader cannot read the file for some reason, the simulation will exit.

Parameters:

fileName - the name of the parameter file

Method Detail

read

public Vector read(String fileName)
            throws IOException

IOException

getParameters

public Vector getParameters()

Gets the parameters read by this Parameter reader

Returns:

the read parameters