Writing about probeDisplays: what do you think?

[Paul Johnson]

While working on some swarm user guide material, I came to work on
probes, probe displays, and such.  I'm trying to get the clearest
possible understanding of the Swarm libs before I get too much further.
So I figured to share some material here to see what you think. Since I
plan to teach this next Spring, it is important this be clear to a
graduate student audience.

Here is the approach I'm considering. I realize this is different in
presentation strategy from previous accounts, so I'm curious to know if
its wrong.

--------------------------------------------------

Anyone who has run Heatbugs (or any of the demo programs, for that
matter) has seen a probe display.  (Note: in some swarm material, these
are called "probe maps", I don't know why/how that is different from
probe display.)  A probe display is a rectangular window that has rows
which list attributes of the object being displayed.  The object being
displayed may be a high level object, such as the observer swarm or the
model swarm, or it may be an individual agent.  Almost all Swarm
projects have a display for the observer and model swarms because
starting values for the parameters can be set with those displays. 
Probe displays for individual agents are typically created during a run
by user interaction with the Swarm program (for example, by clicking on
a "clickable ZoomRaster").

The appearance of the probeDisplay can be custom-tailored by the
programmer.  In order to understand the effect of customization, it is
probably best to begin with an understanding of the "default"
appearance.

The default probeDisplay can be created quite easily.  In the
HeatbugObserverSwarm.m file, for example, one finds these lines:

   CREATE_ARCHIVED_PROBE_DISPLAY (heatbugModelSwarm);
   CREATE_ARCHIVED_PROBE_DISPLAY (self);
 
These are macro commands that cause actions inside the Swarm kernel to
create the default probe displays for the model swarm and observer
swarm, respectively.  That is all that is required to create the default
probe displays.  

It might be a good exercuse for the user to check this for herself. 
Leave those macro lines in HeatbugObserverSwarm.m, and comment out
everything else to do with probes in that file and also in
HeatbugModelSwarm.m.  When heatbugs is executed, the user will see that
the default probe display presents a list of the instance variables of
the object and, if their values are set at start time, those values will
be displayed as well. (a figure with a snapshot of the probe display
would be included here).

This bare-bones setup will not automatically update the display as the
simulation proceeds.  It presents only a snapshot of the creation-time
settings.  Many variables that have no value set before time 0 will show
blanks or the word "nil" and that will never change.

If one wants the probeDisplay to be updated, then an update command has
to be included in the schedule.  In the buildActions method of
HeatbugObserverSwarm.m, this is the command that will cause the updating
to occur (presumably, it was commented out in the bare-bones test
described above).

    [displayActions createActionTo: probeDisplayManager message:
M(update)];

The probeDisplayManager is a global object and when it is told to update
in the observer swarm's schedule, it will update the probes of objects
in all other levels of the simulation.

All of this works because the Swarm kernel provides a great deal of
functionality that the user may never need to inspect or worry about. 
Most importantly, the object "probeDisplayManager" is not explicitly
created by the user.  Rather, it appears automatically in any Swarm
program that includes simtoolsgui.h.  (question: is that right?  I see
in simtoolsgui.m that the probeDisplayManager creation code exists, but
what triggers the actual creation of the object?)  The
probeDisplayManger is the object that receives messages to create
displays for various objects, such as the macro statements above.

The default probe display for an object includes only the probes for the
instance variables of the object.  It has no buttons to click and
execute methods inside the object (i.e., it has no message probes).  If
one wants the message probes, there are two alternatives.  While the
program is running, a right-click on the object's name button in the
top-left part of the display will cause the message probes to be
displayed.  A second alternative is to change the macro used to create
the probe displays.  Use this instead of the previous commands:

   CREATE_ARCHIVED_COMPLETE_PROBE_DISPLAY (heatbugModelSwarm);
   CREATE_ARCHIVED_COMPLETE_PROBE_DISPLAY (self);

This will cause the probe display to include all instance variables and
methods.
 
Why might one want to customize the display?  Well, frankly, the default
probe display may look ugly.  It may include lots of variables the user
does not want to see. There are some instance variables, such as C
arrays, that cannot be probed, and so their inclusion in a probe display
is uninformative.  The Swarm Toolkit is designed to allow the user to
pick and choose which variables ought to be included in the display.

At the current time, customization is achieved by writing code that
communicates with a global object called "probeLibrary".  Like
probeDisplayManager, the "probeLibrary" is provided by the kernel.  The
code in HeatbugModelSwarm.m, for example, works in the following way. 
First, a new object is created, called "probeMap".  The probeMap is
created from the Swarm class EmptyProbeMap. (It might have been better
to call that one the EmptyProbeDisplay object, I think, but you can't go
back in time....).  This probeMap object is then told, one-by-one, to
get probes for individual variables and messages from the probeLibrary
and add them to the map.  When that work is done, then the probeLibrary
is told to use the special probeMap object to control the probe display
for the model swarm.  That is to say, the default probe display no
longer appears, just the customized one.



-- 
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-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.