### MASON

MASON is a single-process discrete-event simulation core and visualization library aimed at multiagent simulations with large numbers of agents. The system is written in pure Java and is intended for experienced Java coders who want something general and easily hackable to start with, rather than a domain-specific simulation environment. Some features:

- Simulations can be serialized to checkpoints (freeze-dried and written to disk), which can be recovered from at any time, even to different Java platforms and new MASON visualization toolkits.
- MASON can be set up to be guaranteed duplicatable, meaning that the same simulation parameters will produce the same results regardless of platform.
- Libraries are provided for visualizing in 2D and in 3D (using Java3D), to manipulate the model graphically, to take screenshots, and to generate movies (using Java Media Framework).
- While the visualization toolkits are fairly large, the core simulation model is intentionally very small, fast, and easy to understand.

You must agree to the MASON Open Source License to use the software. This license may change for future versions of the code.

### MASON Documentation and Tutorials

You might begin with Tutorial 0, which is a tour through various features of MASON's GUI code, and doesn't require much knowledge of Java.

When you're ready to start coding, go through our seven tutorials located in the `mason/sim/app` directory. Each has an early HTML file walking through the tutorial, plus completed tutorial class files. Walking through these tutorials will help in learning to code with MASON more than anything else, we think.

After the Tutorials, you should check out the How-Tos for answers to common things (parallelizing MASON, building an applet, etc.)

The Notes contain vital stuff that any MASON hacker should know. There is also an overview of the basic MASON classes. The Simulator Layout PDF file shows most important non-3D visualization class relationships. The OmniGraffle original is at SimulatorLayout.graffle.

If you're interested in grokking the internal scenegraphs of the Java3D code (which admittedly can get hairy), we have provided you with a graphical depiction of the important scenegraph structures. Likewise the Omnigraffle original.

Last but hardly least, we predict that the Class Docs will prove useful to you.

### Setting up and Compiling MASON

This version of MASON presumes that you are experienced with setting up CLASSPATHs, running javac or jikes, and using a Makefile (if you're running Linux or MacOS X). Windows users will need to have appropriate tools to compile all the java files. Steps:

1. Add the `mason` directory to your CLASSPATH. This is where all of MASON's code is located.
2. If you wish to produce Quicktime Movies using MASON, you must install Sun's Java Media Framework. MacOS X users should install the "Cross-platform Java" version; at any rate, you need to make certain that the `jmf.jar` file in Sun's package is also located in your CLASSPATH. MASON applications can be run without the JMF installed, but to compile one particular class (`sim/util/media/MovieEncoder.java`) the JMF must be present. If you've not installed JMF, you can move this file out of the way and MASON will still compile and run.
3. If you wish to use MASON's 3D toolkit, you need to 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.
4. MASON usually comes with all of its class files pre-built. But if not, you'll need to compile the code. MASON should compile cleanly with no warnings (except if you turn off --nowarn in the Makefile, then new versions of the `jikes` compiler will make obnoxious style warnings). We're MacOS X and Linux users primarily: so a Makefile is provided. To use it you first need to set up your CLASSPATH as described below. Typing `make help` will give you all the Makefile target options. If have installed Java3D and JMF and you want to build the whole system, try:

   cd mason; make 3d; make docs

   If you've not installed Java3D and just want to play with the 2D stuff, try:

   cd mason; make; make docs

   If you don't have jikes installed, you may need to first change the JAVAC variable in the Makefile to `javac`.

### Running MASON Applications

MASON is a library, not an application. Each application which uses it will probably be run with a different command.

Here are two such applications. MASON is running successfully if you can run:

               java sim.app.heatbugs.HeatBugsWithUI

To test the 3D system, you might try:

               java sim.app.mousetraps3d.MouseTraps3DWithUI

You can also select classes from a predefined list (in the `sim/display/simulation.classes` file, which you're welcome to edit). Normally this list is displayed when you choose "New Simulation" from the menu. But you can also go straight to the list when you launch MASON like this (try it!):

               java sim.display.Console

Provided MASON applications are located in the folder. Many of these applications have two versions: a model application, which runs the model on the command line, occasionally checkpointing it out; and a visualizer application which calls up the visualizer toolkits and runs the model under a GUI. If a model application is run as `java sim.app.foo.Foo`, then the visualizer application is usually run as `java sim.app.foo.FooWithUI`.

Visualizer applications contain at least two windows: at least one Display and a Console (where the play/stop/etc. buttons are). The Console's menu lets you call forth another visualizer application (running in the same process) by providing the class name; load from checkpoints with Open... ; and save checkpoints with Save and Save As.

In most cases you can start up a model application to start running at a checkpoint by including the argument `-checkpoint mycheckpointfile.checkpoint` on the command line.

If you close a visualizer window, it is "hidden" and can be recovered in the Console's Displays tab. If you close the Console, the simulation is quit.

Grids of rectangles can be displayed in two ways; either by drawing all the rectangles separately, or by creating an image and stretching it. The former is faster on Windows usually. The latter is faster on MacOS X always. The latter is also faster on Linux if you give the application lots (50-100 Megs?) of memory, because it will do lots of garbage-collects otherwise. Otherwise the former is faster. We've set the default on Linux to the former, but you can change that in the Options pane (the wrench icon). Java3D applications also tend to run better with lots of memory. For example, you can set the application to 100 Megs with something along the lines of `java -Xmx100M -Xms100M ...` You can see how often garbage-collection happens with the `-verbose:gc` option (only the "Full" collects matter).

MacOS X presents a special gotcha. The 2D MASON code runs much faster on MacOS X when using Java 1.3.1, as 1.4.1 is not presently hardware accelerated on the Mac. But the 3D MASON code only runs on 1.4.1. So if you're doing a MASON 3D app you must run 1.4.1 on the Mac; but if you're doing a MASON 2D app, you'll probably be much happier running 1.3.1. Sorry about that!

If you've upgraded to the latest Java on the Mac, you're running 1.4.1 or later. You can make a given Terminal window use 1.3.1 instead of 1.4.1 `java` with the command:

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

### MASON apps to try

In most cases, the command-line (model application) version is shown first, followed by the visualizer version.

2D Apps
    sim.app.antsforage.AntsForage
    sim.app.antsforage.AntsForageWithUI

    sim.app.cto.CooperativeObservation
    sim.app.cto.CooperativeObservationWithUI

    sim.app.heatbugs.HeatBugs
    sim.app.heatbugs.HeatBugsWithUI

    sim.app.hexabugs.HexaBugs
    sim.app.hexabugs.HexaBugsWithUI

    sim.app.keepaway.Keepaway
    sim.app.keepaway.KeepawayWithUI

    sim.app.lightcycles.LightCycles
    sim.app.lightcycles.LightCyclesWithUI

    sim.app.lsystem.Lsystem
    sim.app.lsystem.LsystemWithUI

    sim.app.mav.MavDemo
    sim.app.mav.MavDemoWIthUI

    sim.app.networktest.NetworkTest
    sim.app.networktest.NetworkTestWithUI

    sim.app.virus.VirusInfectionDemo
    sim.app.virus.VirusInfectionDemoWithUI

    sim.app.woims.WoimsDemo
    sim.app.woims.WoimsDemoWithUI

    sim.app.tutorial1and2.Tutorial1
    sim.app.tutorial1and2.Tutorial2

    sim.app.tutorial3.Tutorial3WithUI

    sim.app.tutorial4.Tutorial4WithUI

    sim.app.tutorial5.Tutorial5WithUI
| 3D Apps
    sim.app.crowd3d.Boids3dWithUI

    sim.app.heatbugs3d.HeatBugs3DWithUI

    sim.app.mousetraps3d.MouseTraps3DWithUI

    sim.app.woims3d.WoimsDemo3DWithUI

    sim.app.tutorial6.Tutorial6WithUI

    sim.app.tutorial7.Tutorial7WithUI