Swarm GUI Notes

This is a note first produced by Manor Askenazi (see a message to swarm-support sent on 8 Aug 1996). Its been updated by Rick Riolo.

In order to introduce some of the more subtle aspects of the Swarm GUI the following tutorial ensures that the user experiments with all the bells and whistles of the interface in one Heatbug session. Even if you have played with heatbugs before, we recommend that you run through this checklist - you may have missed some GUI-capabilities (especially the ones described in points 7 through 22).

1. Run the (UM version of the) heatbugs program:

        heatbugsPlus &

   The windows titled "Parameters" and "HeatbugObserverSwarm"
   are actually "probes" into those objects in the program.
   Swarm probes are analogous to real-world probes: you can
   observe the insides of the object, i.e., the instance variable
   values.  You can also change those values.
   We will also see that you can actually send the object 
   messages that cause it to execute its corresponding methods!

   /-----------------------\
   |Changing Variables     |
   \-----------------------/

2. Move the cursor onto the entry for the variable numBugs in the 
   probe into the Parameter object and click the first mousebutton 
   (the leftmost button).

   The entry should now appear selected so that if you type a replacement
   value the previous one is completely overwritten.
 
   If you only wish to change a subsection of the string simply move the
   cursor to the appropriate location and use the delete key as required.
   You can also re-select an area for deletion by pressing MB1 (the first
   mouse button) and moving the cursor over the text.

3. Press .
    
   The borders of the entry should change to red until you release the
   Return key. This is done to inform the user that the change in the
   variable has been recorded. If the user does not press return the 
   variable will not be updated!!!

4. Press Tab.

   The next variable in the list should now be selected.

5. Press Shift-Tab. 

   You should be back on numBugs.

   You can continue to change the values of the Parameters
   until they are what you want them to be for running the model.
   NOTE: the world X and Y sizes must be equal!!


   /------------------------------\
   | Start and stop model time    |
   \------------------------------/

6. Press  on the ControlPanel. Wait a while then press .


   /------------------------------\
   |Zooming/Highlighting the Graph|
   \------------------------------/

7. Go to the Unhappiness graph. Click MB1. Move the cursor diagonally,
   and click MB1 again.

   You should see that the area included within the rectangular region
   you have selected has now been zoomed into.

   You can repeat this operation to zero in on some interesting point
   in the graph, or you can press MB3 (the rightmost mousebutton to 
   return to the previous zoom level).

8. Put the cursor over the entry in the graph legend that says "unhappiness".
   
   You should see that the line in the graph has now become wider.
   This is useful when you have a graph with many lines and you want
   to inspect one of the lines and how it changes relative to the 
   others.

   /--------------------------------------------------------\
   | Getting a Probe To a Bug, a Variable or a Return Value |
   \--------------------------------------------------------/


9.  Go to the heatworld window. Click MB3 on a bug.
    (You have to get the point of the cursor right on a bug.
     If it beeps when you MB3, you missed!)

    A window should appear which is a ProbeDisplay onto the selected bug.
    This window is a "probe" into that particular bug, showing the
    state variables for that bug, including

               unhappiness  = a function of the difference between temperature 
                              at the bug's location and its ideal temperature
               x,y          = bugs location
           idealTemperature = bugs goal temperature
                 outputHeat = heat bug gives off each step
      randomMoveProbability = prob. bug will move at random each step

    A probe not only displays the values of the particular object 
    (e.g., a heatbug, a parameter object, etc);
    the instructions below show how you can change the state variable for 
    a bug.  When you change a variable, you are changing that bug,
    and its resultant behavior will usually change, too!

    There are also slots for other instance variables in the Heatbug object
    which cache's useful model and display related values:
                      world = a pointer to the world object (where bugs move)
      worldXSize,worldYSize = size of the world
                       heat = pointer to heatspace (where heat values are stored)
                   bugColor = bugs display color (as a char code)
    These values cannot be changed, with the except of the bugColor.
    Currently the only useful value is to change the 64 to 65 (keep the 'A')
    which will turn the bug white, so you can distinguish it from the other bugs.
    (It would be easy to change your own copy of heatbugs to provide for
    other colors.)
    
10. Press MB3 over the entry area for the variable "heat". 

    Since the heat variable is an object, you should now get a 
    ProbeDisplay onto a HeatSpace object.  There is nothing
    you can usefully learn or change there.  But you can change the
    evaporationRate and diffusionConstant in the super class for HeatSpace,
    which is Diffuse2d.  To get access to the superclass variables:
    - press MB3 on the "HeatSpace" in the well on the left of that probe.
      that should result in another "comple probe" into that object.
      Click on the little red square button at the top righthand corner 
      of the orignal HeatSpace probe to dismiss it. 
    - In the new HeatSpace probe, click on the button with the green
      graphic, in the upper right of the probe.
      The probe should now expand, showing the Diffuse2D class
      variables and methods.  
    - At this point you can change the diffusionConstant and/or
      evaporationRate by moving the cursor into those slots,
      changing the value, and pressing return.  
      (This works the same as described above for changing values
       of instance variables in the probe into the Parameters object.)
    You may now try running the model with different values for
    these HeatSpace instance variables, or you may dismiss the
    probe into the HeatSpace by pressing the red button in the top right.

11. On the probe you generated for the heatbug, go to the top lefthand 
    corner. You will see a well with the word heatbug in it. Press MB3
    with the cursor above that area. 

    You should get a probe onto the same heatbug, with a slightly different
    interface. In particular, you will notice an additional green button
    at the toplefthand corner of the probe. This button allows you to look
    at the methods and instance variables due to the superclasses of heatbug.

    Press this "superclass" button.

12. Before we proceed, dismiss the original ProbeDisplay onto the selected 
    heatbug (to avoid confusion later) by pressing the red button.
    You should be left with the more complete probe display you have just 
    created in step 11 (plus all the original controls, graphs, etc.)


NOTE WELL
>>> Some of the rest of this only applies if you are using the
>>> UM-HeatbugsPlus version of heatbugs.  In particular, you need
>>> to use that program to be able to create a new bug and add it
>>> to the running application.  For more information about that
>>> version, go here.
>>> To run this version, just entering:
>>>     heatbugsPlus &
>>> will start it up (it runs /common/scripts/heatbugsPlus).


13. Use the vertical scroll bar to move to the bottom of the heatbug's
    CompleteProbeDisplay.  There you will see a method called "cloneSelf".
    Press that, and you will see a return value appear 
    on the left of the button.  This value (it will appear to be the
    text "Heatbug") is a copy of the bug you have probed!
    Note that most instance values will be the same, with the 
    exception of unhappiness.  That should be zero in the new bug.
    (It isn't calculated until the bug takes a step.)

    Since this return value is an object we can probe it using the MB3
    button, so if you click MB3 over this value you should get a ProbeDisplay
    onto this object which is a copy of the original bug.

14. Once you have made a copy of the original bug, dismiss the 
    CompleteProbeDisplay to that original bug. Note that pressing on the
    red-square button on any class but the lowest in the hierarchy will 
    simply cause that particular class to be removed, not the entire window!
    So use the vertical scroll bar to go back to the top of the original
    bug probe, and press the red sqare at the very top.


   /-----------------------------------\
   | Drag&Drop Capabilities on Objects |   
   \-----------------------------------/

15. Press go on the control panel.

    Note that although the simulation is proceeding, the x and y value in
    the newly made copy of the heatbug are not changing. In other words,
    we have made a new bug but it has not been added into the simulation!

    We will now attempt to add this bug into the simulation but first we
    will make three changes on the bug so as to make it more recognizable
    when it appears in the simulation.

16. Change the x and y coordinates to be (10,10).

17. Change the bugColor entry to be 65 (which in this particular simulation
    means white).

    Note that the original value of color will have read: 64 '@'
    This is because the bugColor variable is defined as a Color type (which
    is essentially an unsigned char).

    Many programmers use chars/unsigned chars to represent small numbers.
    Therefore, by default we display both forms of the variable (as a number
    and as a character). There are ways to customize which form is required
    (see the documentation on the VarProbe class for details).

18. Now go to the 'well area' described earlier (at the toplefthandcorner
    of the ProbeDisplay. If you click MB1 on this area (and keep the button
    depressed) you will see a little rectangular representation of the but
    appear underneath your cursor.

19. Move this little object-representation over the argument-entry for the
    addHeatbug method on the HeatbugObserverSwarm. When the bug is over this
    entry the text within it should turn green. This means that if you
    release MB1 the bug will be placed as an argument to this method.

    If you do this you will see that the entry now contains a value.

20. Now, since there is an argument for the method addHeatbug, you should be
    able to press the button for this method. (If there were not
    value as an argument for the method, you would get a beep).
    You will not see any change in the world until you do the next step...

21. If you press go on the control panel you should now see this bug appear at
    the toplefthandcorner of the heatworld.

22. In general, any entry which contains an object can be MB1-clicked to get
    a drag&drop representation of the object. An MB3 click should get you a
    probe to the object.