## Tutorial 0: A Tour of MASON

In this zeroth tutorial we will help you get started using MASON. The tutorial includes information about installing MASON on various operating systems (MacOS, Windows, Linux). Also, we will show how to start MASON simulations with or without a graphical interface.

You do not need to know much about Java to use this Tutorial.

This tutorial teaches:

- How to install MASON
- How to run MASON from the command line
- How to interact with MASON's graphical interface

## Installing MASON

Download and unpack the MASON library. Then, add the 'mason' directory to the CLASSPATH environment variable. Windows users may find information about how to set the CLASSPATH here and here. MacOS and Unix users should modify the .bashrc, .tcshrc or .cshrc files to update the CLASSPATH variable.

MacOS X users doing 2D simulations are strongly encouraged to use Java 1.3.1 rather than 1.4.1 at this time; it is hardware-accelerated and 1.4.1 is not. However, 1.4.1 is required to do 3D. The following command will make a given terminal window use 1.3.1:

    alias java /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home/bin/java

### Installing other useful libraries

MASON can be easily connected with a number of external libraries. Upon installing MASON, it may be a good idea to also install those libraries that may seem helpful to your purposes (of course, these libraries can be installed later on as well). Here are some libraries you may want to install:

- To produce Quicktime Movies using MASON, install Sun's Java Media Framework. MacOS X users should install the "Cross-platform Java" version.

- To use MASON's 3D toolkit, install Sun's Java3D framework. Get the version "for the JDK" rather than "for the JRE". We very strongly suggest that Windows users install the OpenGL version. Linux users can get Java3D here. Java3D for MacOS X only runs under MacOS X 10.3.x (Panther) with Java 1.4.1, and can be downloaded at Apple's Download Page.

- A useful library to produce and display charts in MASON is JFreeChart.
- A useful library to output PDF files from MASON is iText.

### But I just want to run the Demos!

If you don't care about programming MASON, and you don't care about running non-GUI MASON apps, you can skip the CLASSPATH stuff and go straight to the section MASON's graphical interface.

## Running MASON from command line

Once MASON is installed and the CLASSPATH variable properly set up, we can start a simulation. For this purpose, we'll demonstrate how to run the HeatBugs application. To start it, open a new Terminal (in MacOSX and Linux) or start Windows' Command Prompt application. Simply type:

    java sim.app.heatbugs.HeatBugs

A MASON simulation should start. In HeatBugs, a number of bugs are placed in an environment, and they search for places with pleasant heat (not much, but sufficient for survival). Each bug emits some small amount of heat in the environment, but alone, bugs cannot create enough heat for them to be satisfied. Therefore, over time, the simulation presents the formation of clusters of bugs. The number of bugs per cluster is not too small (not enough heat), nor too big (too hot).

Launching the previous command should start a simulation with no graphical interface. The output shows time steps in the simulation (in increments of 100). If the run ends with any exception, it probably means your system does not have java installed and set up properly (in which case, visit java.sun.com for download and instalation instructions).

At each 500 time steps, the entire state of the simulation is saved to a file named hb.timstep.checkpoint. With this files, the simulation may be restarted from the exact state it was in, and it is guaranteed to give the exact same results, even if restarted on a different computer with another architecture and operating system. To restart the simulation from the same state it was in after 1500 time steps, type

    java sim.app.heatbugs.HeatBugs -checkpoint hb.1500.checkpoint

The checkpoint files may be used to restart the simulation with graphical interface as well. We'll see later how this can be done.

## MASON's graphical interface

Many of the MASON applications contain a WithUI java file for running with graphical interface. For example, the woims applications has the `WoimsDemo` class for simulation without interface, and the `WoimsDemoWithUI` class for simulation with graphical interface.

This section will walk you through MASON's graphical user interface. We'll use the HeatBugs application for this purpose.

The 'start' directory contains useful batch files to run MASON on a variety of operating systems: Windows (double-click on mason.bat), MacOSX (double-click on mason.1.3.1.command for 2D demos and mason.command for 3D demos), and Unix (launch mason.sh).

If you've set up your CLASSPATH, you can similarly execute:

    java sim.display.Console

From the drop-down list, select the `sim.app.heatbugs.HeatBugsWithUI` application, and press OK. The same effect may be obtained by simply executing in the terminal the command

    java sim.app.heatbugs.HeatBugsWithUI

Two new windows have automagically appeared. One has the title bar labeled "Heat Bugs Display", and it is a display window. The other one is has the title bar labeled simply "Heat Bugs", and this is a console window. We will talk about each of the two types in the next two subsections; we'll start with the console.

#### MASON's Console Window

The console for HeatBugs should look similar to this one, plus or minus minor differences depending on the operating system. There is a small menu and a tabular panel with four panels: About, Console, Displays, Inspectors and Model. Currently, the About panel is selected and displayed, and it shows some information about the application.

The Play button allows the user to start a simulation. If the simulation is paused, pressing the play button advances the simulation a single time step.

The Pause button allows one to pause the simulation. This may be quite handy for inspecting a fast simulation. Once paused, the simulation may be either advanced by a single step (by pressing the play button), or continued by pressing the pause button again.

The Stop button completely stops a simulation. Once stopped, a simulation cannot be restarted.

The other two labels on the console show the current time step of the simulation, and the frame/second rate. Due to drawing in multiple windows, Java may get slower when this information is updated. To hide it, click on either the current time step or on the frame/second rate.

Lets take a look at the Console panel.

The Console panel contains useful settings for the simulation. The first three slides allow one to insert some delay time between each time step (in case the simulation is too fast), to increase the priority of the simulation thread, and to execute any number of steps upon pressing the play button (when the simulation is paused).

Next, there are three text areas where one can specify the time step where the simulation should stop or pause (once stopped, a simulation cannot be resumed), or set the random seed for the simulation to a certain value. By default, the random seed is incremented whenever the simulation is stopped (so that the next time the simulation is played, it runs with a different seed). Setting the last check button, Repeat Play on Stop, sets MASON to automatically start a new simulation whenever the old one is stopped. This is mostly helpful for kiosk modes.

Now click on the Displays panel.

The Display panel allows one to select which displays will be shown, and which will not. Many multi-agent simulations may run much faster without the visualization component. As such, one may choose to hide the display, at least until the emergent effect occurs (for example, the agents cluster to some specific locations), and show the display later on.

Each display is identified by a unique name. To hide a display, the user needs to select it in the list of displays, and then press the Hide button. Alternatively, clicking on the display's close button will hide it. To show a display, the user needs to select it in the list of displays, and then press the Show button. The user may show/hide all displays by pressing the Show all / Hide all buttons.

The Inspectors panel allows the user to inspect objects in the simulation. We will see later on how this may be accomplished.

Some applications have a fifth Model panel in the main console window. The Model panel allows the user to modify parameters affecting the entire simulation (as opposed to the Inspectors panel which allows the modification of parameters that affect a single agent). For example, the first line allows us to modify the minimum ideal temperature for all bugs. To do that, click on the text-edit area with `17000.0`, and modify it to `20000.0`. Do not forget to press ENTER (or RETURN). Often parameters do not take effect until the next played simulation.

Other values may be only viewed, but not modified (read-only parameters). One such parameter is MaximumHeat.

OK, enough with the panels, lets take a look at the drop-down menu.

The drop-down menu allows the user to start a new simulation, to save the current simulation or to load a new one. MASON allows one to have multiple simulations running at the same time. To see how that is possible, click on the menu and select New Simulation. A small dialog will appear, asking for the name of the simulation. Type sim.app.woims.WoimsDemoWithUI or select it from the list, then press OK. You should see a new set of display/console windows popping up with the simulation. You can start/pause/stop and the application as you may want. When you had enough fun, close it and lets get back to our zeroth tutorial.

WoimsDemo contains an artificial life example of flocking: agents sense the presence and current state (location, velocity, etc) of other nearby agents, and act accordingly to give an impression of real-life flocking. They prefer not to bump into obstacles or with each other, but also prefer to stick together. The ideas behind artificial flocking were first proposed by Craig Reynolds, who got an Academy Award (Oscar!) for this work! Pretty cool, huh?

The menu also allows one to save/load the state of the simulation. This is done via the checkpointing mechanisms. More interestingly, checkpointing works with and without graphical interface. As a consequence, one may start the simulation without graphical interface, and have it save the state of the simulation periodically. Later, a MASON simulation with graphical interface may be used to visualize the progress of the multi-agent simulation. Earlier, we ran the HeatBugs application without graphics, and it saved a whole bunch of checkpointing files. Lets load one for a second. Go to the File menu, and select Open. A dialog opens to select the desired checkpoint file. Locate the the hb.1500.checkpoint file saved earlier, and click the Open button. This will load the state of the earlier simulation after 1500 timesteps. Pressing play will continue the simulation from this state on.

#### MASON's Display Window

The display window contains most of the visualization of the simulation. When you just start the HeatBugs application, you screen should look like the the snapshot to the right (most probably without the red text and lines). If you click on the start button in the console, you will be able to see a visualization of the heat bugs simulation, where white circles represent the heat bugs, and the shades of red represent the heat.

The display window contains a small but useful toolbar. The first button, Field Selection allows the user to specify which fields will be displayed. A field is a way of storing objects and associating them with locations. Click on the field selection button, and you will see a small list of names. HeatBugs contains two fields, one with agents and one with the heat. Both are checked, which means that both will be displayed. If you uncheck one of them (for example, the one marked Bugs), the heat bugs will not be displayed anymore (but they will still exist in the simulation).

MASON allows for a wide variety of fields. Aside from the simple 2-D grid field, MASON also has hexagonal and continuous fields. Check the HexaBugsWithUI and WoimsDemoWithUI applications for examples. A snapshot of the HexaBugsWithUI application is presented to the right.

With MASON, 2-D fields may also be visualized in 3-D. See the HeatBugs3DWithUI application in the sim3D library. A 2-D-in-3-D visualization is presented below.

It is really useful to demonstrate your work to others. For this purpose, we included a Record Movie and a Take Snapshot button. Movies usually fit nicely into presentations, talks, and possibly web pages. Additionaly, snapshots could improve papers and reports. Taking movies is easy: click on the record movie button, and select an encoding. The movie will contain a frame for each frame that is displayed in the MASON Display Window. Therefore, it may be a good idea to reduce the size of the movie by increasing the number of skip frames (as described later in this tutorial). To stop recording the movie, press the record movie button again (meanwhile, the icon of the record movie was slightly changed to contain a big STOP sign while the movie is being recorded). Taking snapshots works also very easy: upon pressing the take snapshot button, a small dialog pops up asking for the name and location of the snapshot.

Click on the Options icon, and you will probably see this dialog appear. We were able to significantly speed up the display of some fields by drawing to images and than splashing the images to the window. However, in some other systems, this was relatively slower than the original drawing. We tried to customize MASON to automatically detect which is the better setting. However, the options window allows the user to try both settings and see which gives better results.

Also, the user may translate the display as desired by specifying X and Y offsets. Last, the Graphics Features allow one to customize the graphics settings even more. On some machines, this may result in faster or better vizualization.

Back to the display. The user may scale up or down the visualization in order to concentrate on specific parts of the environment. To do that, he/she may either set a desired scale, or play with the arrows for halving or doubling the current scale. The scale may also be reset to 1 by pressing the belly button.

In some applications, the environment may not change drastically between consecutive time steps. However, redrawing everything may slow down the entire simulation. In such cases, it may be desirable to skip some of the frames. The Skip specifies one in how many time steps will pass between frame updates. The default value is 1 - all frames will be displayed. By setting the value to 2 for example, only every other frame will be displayed.

You do not necessarily have to pause the simulation, you may inspect it as it is running as well. For example, you may easily inspect information with fixed location (for example, the heat at a specific grid location). Nonetheless, with agents moving around very fast, it may be difficult to select them for inspection.

### Inspecting the simulation

Lets get back to our HeatBugs simulation. Start it, and let it run for a few seconds (or minutes if you want). After you see some interesting patterns (maybe some clusters), pause the simulation.

This is how the environment looks like in our simulation (yours will probably be different, depending on the random seed you are using). We took the snapshot after about 500 time steps, when we already start seeing small clusters of agents.

Now, move your cursor over one of the white dots (agents/bugs). When this is accomplished, double-click on the white circle. The Display window has not modified in any way. However, the Console window now shows the Inspectors panel which has been updated with some interesting information. It appears I have selected the grid location (75,78). In my case, the Inspector panel shows information about both the heat, and also about the single agent at that location. In your case, you will probably see information about another location. It may also be that you see more than an agent (multiple agents may occupy the same location in this problem domain). If you see no agent, you probably have not double-clicked on a white circle at the previous step. You may need more double-clicking practice, so you may want to retry that step.

The information on the heat contains the location of the grid (in this case, `75` on the X axis and `78` on the Y axis). Also, we can see the amount of heat at the specific location (in our case, about `24337`). We can modify the heat at this location: to do this, select the heat value and replace it with another value, then press ENTER. For example, we may replace `24337.667135340227` by some other value, say `0.0`. This will take effect immediately in the simulation. To see this is the case, hide the bugs from the Field Selection button. As we reset the heat to zero, you will see a black dot where the selected agent was.

Now return to the Inspectors panel, and select the sim.app.heatbugs.HeatBugs line (if multiple bugs, select the first). The snapshot on the left shows our selection. In fact, the inspector tells us that one of the objects displayed at the location we double-clicked is an instance of the sim.app.heatbugs.HeatBug class, which represents a bug.

We notive that the agent has the same location (75,78), not very surprising! Then, we see other information particular to the specific agent. For this application, the agents have a random movement probability (0.1 for this agent), an ideal temperature (what temperature it prefers in the environment), and a heat output (how much heat it contributes in the environment). You may modify each of those three values at your own will. Notice though that you may modify the random movement probability (and some other parameters) for all the agents in the simulation by simply modifying them in the Model panel.

Now, press the pause button again to continue the simulation. Automagically, the information is updated for both the heat (the heat amount) and for the heat bug (the location). This incurs a slight decrease in simulation speed, which is somewhat expected.

The Inspectors panel contains two additional buttons: Empty List and Detatch. If you wondered what they do, now it's the time to find out! The first one will empty the list of things being inspected. This will eliminate the extra cost of updating/displaying information for the inspectors, and the simulation will get faster.

The other button detaches the inspector information into a separate window. Why is this helpful? Because if you want to inspect another agent or heat grid, the inspector list automatically erases the previous inspectors. So, if you want to observe something (information about an agent, for example), it may be a good idea to detach the inspector to make sure that double-clicking (accidental or intentional) will not interfere with your inspector. Once detatched, the inspector may be closed as a regular window.

### MASON's 3D GUI

MASON may be used in combination with Java3D to display 3D models. This may be accomplished in two ways. The user may use the same 2D fields, but visualize them in 3D. The heatbugs3d application shows the heatbugs model visualized in 3D, where heat information is used for the third dimmension. A second approach involves using MASON's 3D fields: check out the woims3d application for an example.

Java3D allows one to rotate, translate and zoom in the 3D visualization. Depending on the operating system, this may be accomplished by pressing and holding the mouse button down, followed by moving the mouse cursor, possibly in combination with the CTRL or ALT keys.

With all this information, you should be able to explore the already existing MASON applications. You should also check out the tutorials for additional information on how to start coding your own MASON applications.

We hope you will enjoy our system!
The MASON Team