uchicago.src.sim.parameter
Class ParameterReader

java.lang.Object
  uchicago.src.sim.parameter.ParameterReader

public class ParameterReader
extends java.lang.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 (input|output) {
  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. Parameters can be either input or output. Parameters are input by default and need not be explicitly specified. Output parameters have to be declared using the keyword output enclosed in parenthesis. For output parameters value_definition should be omitted.

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.

Version:

$Revision: 1.9 $ $Date: 2005/07/14 14:45:15 $

Author:

Nick Collier

Field Summary

static java.lang.String

XSLT_TRANSLATION_FILE_NAME the file used to translate xml parameter files to normal parameter files

Constructor Summary

ParameterReader()

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

Method Summary

java.util.Vector	getParameters() Gets the parameters read by this Parameter reader
static void	main(java.lang.String[] args)
java.util.Vector	read(java.lang.String fileName)

Methods inherited from class java.lang.Object

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

Field Detail

XSLT_TRANSLATION_FILE_NAME

public static final java.lang.String XSLT_TRANSLATION_FILE_NAME

the file used to translate xml parameter files to normal parameter files

See Also:

Constant Field Values

Constructor Detail

ParameterReader

public ParameterReader()

ParameterReader

public ParameterReader(java.lang.String fileName)
                throws java.io.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

Throws:

java.io.IOException

Method Detail

read

public java.util.Vector read(java.lang.String fileName)
                      throws java.io.IOException

Throws:

java.io.IOException

getParameters

public java.util.Vector getParameters()

Gets the parameters read by this Parameter reader

Returns:

the read parameters

main

public static void main(java.lang.String[] args)