re: "parameter" processing (long)

[Rick Riolo]

Warning...this is longish...

Given all the earlier comments on "parameters," including
a very broad view of what are parameters, I've been
unsure how to approach this issue.

Here is one crack at it: I tried to come up with
three functionality levels, from simple to complicated.
(I ended up with 4..."you never know what to expect
from the spanish inquisition"...) 

I include some description on how I've done it, not because I
see them as "the best way" but just as another data point.

A note: I still am unsure about how one should approach
supplying "standard" utilities...I can imagine that many
(most?) sims, especially more complicated ones, will differ
just enough that any higher level functionality will always
be not quite right.  So to help those folks, it would seem
the approach of supplying useful low/medium level tools that can be
assembled in many ways might be best. 
But I also think providing some basic, ready to use
higher level tools is also useful.
Thus I guess I am saying the approach should be like that
used for the Swarm graphing tools. 

1. Simple version.

   This is what woytek described in his message about parameters.
   I think we'll be distributing a version
   soon which isn't quite what we want, but is close
   enough and documented enough to maybe be useful to others.

   One goal is that it be *really, really* easy for a sim-writer 
   (especially a new user working on a simple sim) to add a new parameter, 
   i.e. it should be like adding a table entry that simply specifies
     - name, alias, data type
     - range checks for numeric types
     - a short line to appear if user enters -h
   and only slightly more work to specify something like extra
   consistency checks, data processing (eg pass the value to some
   "class variable", etc)
   A parameter added in this way should automatically be processed on command 
line
   or in the input file, and should be written to the report file
   header for history or for re-running.
   It also seems like there are some parameters and related functionality
   common to so many many sims that is should be "pre built."

   Wojtek described our current implementation aimed at the above goals.
   In addition, our base parameter class provides a set of parameters
   that many (most?) simulations will need (which I think is important
   to provide for novice users, since they have enough to worry about),
   including (besides an inputFileName):
     reportFileName    reportNumber  reportFrequency  outputDirectory
     stopT                seed
     progName  progVersion  startTime startDate
   The Parameter class also provides some other generally useful functionality:
    - start a RNG and some common distributions using the seed,
      or using process*clock if the seed is 0 (the default)
    - start a report file by writing out all the parameter values
      in a format that can serve as input, for easy re-runs.
      The report file header looks like:
          # Program heatbugsPlus, Version 0.9, run on 03/08/97 at 11:39:47
          @begin
          reportFileName = report
          reportFrequency = 1
          ...more pars...
          @end
          ...data starts here...
    - set start time and date, and write that along with a program
      name and version number into the report file header

2. More complicated parameter processing.

This level should include the features in (1), but also
make it easy to initialize multiple model "agents" from an input file.
Clearly there are many models for which this is never needed
(eg, when the model's initial agents are generated using some
random distribution.)
So far I've done this for one simple model in swarm.
Wojtek has done it for our classifier system (soon to be released)
which is more complicated (and maybe he will comment on it).

Basically I just use the tools from the Parameters/Parameter
classes described above, but then go into a loop to read any
additional initial objects, formated in the input file like
   ClassNameForObject1
   @begin
   ID 1
   ivar value
   ivar value
   ...
   @end
 
   ClassNameForObject2
   @begin
   ID 2
   ivar value
   ivar value
   ...
   @end
   ... and more objects...
   #endMarker  --- to tell it to stop looking for more objects to load

and so on. The ID values are needed in this model because
the objects need to be linked to each other in a particular way.
So basically we:
  - read them all in
  - do a pass over them telling each to link itself up 
  - do a final pass to do any checks needed

Again, this is one way to handle simple cases.
I know wojtek has done more complicated things for loading
classifier system rules, messages, detectors and effectors.
I can imagine other people do even more complicated things
(especially for models with multiple swarms in 
a complicated architectures...I shudder when I think about it...)

One thing seems certain: One shoe can't fit all.

3. More complicated version

   This version of the utilities includes ways to specify
   "commands" to execute at various times in the run.
   I've not done this with swarm models.

   I have built this into other non-swarm models and basically I just
   wrote a little command processor, and gave the model a file
   of commands to execute, each command having a simple format
       commandname  parameters
   including a redirection command
       <  commandFile
   The commands would be like
       set par=value
       run 1000
       display this and that
       load this and that
       run 1000
   and so on.

4. More complicated yet.
   This "command processor" (ie model control script/protocol processor)
   would allow looping, conditional execution and so on.

   Recall that this is exactly what the original motivation
   for Tcl was....to write a scripting language for controlling
   execution of various bits of (modeling) software.
   Maybe Swarm should try to use Tcl facilities to 
   provide these advanced sim control capabilities?

   (Not that I'm a fan of Tcl's syntax...I really dislike it, actually!)

   For some tasks that require these features I lean toward doing 
   this outside of Swarm, i.e., using an approach like Drone
   to do something like using an Evolutionary Algorithm to 
   explore a parameter space.  One reason I favor this is that I can
   imagine using the same tools (eg Drone) for things not written in Swarm,
   including "legacy" models.    (But I can see reasons to try
   to do it in Swarm, as well.)

A final note:

It would be useful, no matter what is developed, to have some
fairly clean standards about error and warning handling.
For example, when we use Drone it is convenient to know that
if a file that receives stderr output from a run is not empty, we
know there were some kind of "errors" (eg illegal parameter values,
or some other problem deemed a serious error by the sim author).

---------------------------
- r

Rick Riolo                       address@hidden
Program for Study of Complex Systems (PSCS)
1061 Randall Lab     University of Michigan
Ann Arbor MI 48109-1120
http://pscs.physics.lsa.umich.edu/PEOPLE/rlr-home.html


                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.
                  ==================================