MASON Version 3

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

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.

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.

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:

Add the mason directory to your CLASSPATH. This is where all of MASON's code is located.
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.
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.
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 at all. 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

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