Artificial Stock Market (ASM-20011125

[Paul E Johnson]

All new presto-chango lisp parameter archiver and hdf5 data output. 
Several new utility classes, and all around cool improvement and
cleanup.  You need a relatively recent version of Swarm for the hdf5
data output from EZGraph to work, if you still have the old 2.1.1 you
can just comment out that part in Outcome.m

This is the third "release" of revisions on ASM. The goal, as always, is
to make the Artificial Stock Market code more object-oriented, use more
Swarm features, and, generally, to give students world wide a chance to
hack on a big model that is about important stuff.  

This is my second-to-last planned piece of work on this.  There will be
one last rip through here to eliminate where possible all direct use of
calloc, malloc, or other direct memory management, and an effort to rip
all repetitive details out of the substantive classes and move the
details into supporting files.  For example, there will be a replacement
of the complicated-looking calculations in World.m with a simple use of
a multi-purpose MovingAverage class.  Then I'm going to use Autodoc to
make some point-and-clickable documentation on this project, so this
code base doesn't seem so overwhelming.  I'm under some pressure to
finish my hobby work on this, so look for an announcement about ASM-2.2
within a few weeks.

>From the README, where I have a pretty big blah-blah-blah:


SNAP3: ASM 20011024 October 2001

The aim has been to bring this model into convenient Swarm standards.
Actually, the real aim has been to make ASM an effective teaching
tool and an example of good simulation coding practice.
Part of that is a modernization of the data handling, both the
input of parameter values, and record keeping of parameter values, as
well as the saving of data.  One of my pet peeves about Swarm is that
we do not have a standard, idiot proof way to keep records on the
settings and results are for a particular run.  We also don't have
fool proof ways to interate models and run simulations over again.
The first problem is dealt with here in the Output class, and the
second one is dealt with by the creation of a Parameter class, where
we could manage command line parameters if we wanted to.

1. Inputting Parameter Values.

First, note the big parameter input file "asm.scm".  This has the
initial values for three classes, bfParams, asmModelParms, and
asmBatchParams.  This data is "called" to create the classes, you have
to stare at it a while to get used to it.  Where we used to have the
createBegin/createEnd routine for a class, now we've got this
different thing that creates a class and initializes its ivars for us,
like so

asmModelParams =[lispAppArchiver getWithZone: self key:
"asmModelParams"])

The asmModelParms class is a new parameter-holding/setting class for
the values of the model level. The BFParams class is parameters used
by the BFAgents.

The advantage of putting these parameter settings in separate files is
that those files can be edited and the model re-run without
recompiling the program.  I've never seen a working example, but it
seems logical enough a person could write a program to pump out an
.scm file, then run the model, then write the .scm file, run the
model, etc.

It is more within my background, instead, to pass command line
arguments to the model in order to vary parameters or get runs with
different seeds.  That's why I've introduced a Parameters class, which
can handle both command line arguments and it also orchestrates the
creation of objects for BFParams and ASMModelParams. If we ever wanted
to set command line parameters with this model, we would do it here.


Both BFParams and the ASMModelParams classes are created in the
Parameters class, and are then passed to the ASMObserverSwarm, and
then into model swarm.  I did this to keep the user interface
consistent with the original ASM-Swarm model.

2. Outputting Results.

I've done my best to consolidate and simplify all data writing into
the Output class. Simply put, nothing should get written unless Output
handles it.

To show the possible data output tools, I have 3
different ways of saving the output time streams from the model.  All
three should be similar/equivalent representations of the numbers.

1) Text output of data streams.
2) HDF5 or LISP format output of object dumps from a "putShallow"
   call to a data archiver object. This dumps full snapshots of
   the world and the specialist into a LISP on hdf5 archive.
3) HDF5 output EZGraph which writes one vector per plotted line
   into an hdf5 file.

This code has a preprocessor flag to control the behavior of data
storage. If compile without any CPP flags, then the data files are
saved in the .scm format, which is "scheme".  Otherwise, use the flag
NO_LISP, and it uses hdf5 format. In Swarm, that means you type the
make command:

 make EXTRACPPFLAGS=-DNO_LISP

The buttons in the ASMObserverSwarm display turn on data saving.  Look
for "writeSimulationParams" and the other "toggleDataWrite".  These
were in the original ASM Swarm model, but I've replaced the
functionality with the newer storage methods.  The data is saved only
if you turn on the writeData option. If "toggleDataWrite" is empty or
false, hit that button and it shows "true". When the model runs,
output will be created. If you run the program in batch mode, it
automatically turns on the data writing.

Please note that if you want the simulation to save your parameter
values to a file, you can click the GUI button
"writeSimulationParams." If you push that button, the system writes
the parameter values into a file, such as

guiSettingsThu_Jun_28_23_48_00_2001.scm

if you did not compile with the NO_LISP flag.  Otherwise you get a
.hdf file.  One key change from the old ASM is that you can push that
button at time 0, and it will save a snap at that time, and any time
you stop the model, you can change parameters and punch the button
again, and it will also save a snapshot at quit time.  I believe this
works fine now, but it was a little tricky making sure the objects are
created in the right order and early enough to allow this to work.

Now, just a word about data formatting.  Because it is familiar and
compatible with existing programs, I often prefer to save data in raw
ASCII format.  In case you want text output, this shows you how to do
it.
I think filenames that have the date in them are good to
help remember when they were originally created, for example.  It
creates an ASCII file, for example,

output.data_Thu_Jun_28_23_48_00_2001

However, I understand the reasons others are pushing to use more
refined formats.  Many people are digging into hdf5 format for data
storage, and I've taken a look at that too.  I took the easy road and
just dumped the whole world and specialist class with swarm's
archiver. It seems to work great?!  The output file is called
something like

swarmDataArchiveFri_Jun_29_16_29_25_2001.hdf
or
swarmDataArchiveFri_Jun_29_16_22_59_2001.scm

You note here that output uses the current time and date to write the
output file names. Today I ran an example and ended up with these
three files of output:

output.dataWed_Oct_24_11_30_18_2001
swarmDataArchiveWed_Oct_24_11_30_18_2001.scm
hdfGraphWed_Oct_24_11_30_18_2001.hdf





-- 
Paul E. Johnson                       email: address@hidden
Dept. of Political Science            http://lark.cc.ukans.edu/~pauljohn
University of Kansas                  Office: (785) 864-9086
Lawrence, Kansas 66045                FAX: (785) 864-5700


                  ==================================
   Swarm-Modelling is for discussion of Simulation and Modelling techniques
   esp. using Swarm.  For list administration needs (esp. [un]subscribing),
   please send a message to <address@hidden> with "help" in the
   body of the message.
                  ==================================