M A S O N

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.

MASON is open-source software licensed under the Academic Free License, version 3.0. See the LICENSE file for more information.

• Unpacking and Running MASON
• MASON Documentation and Tutorials
• Compiling MASON

Add-On Charting

1. jFreeChart. The jfreechart-1.0.1.jar and jcommon-1.0.0.jar files are located in the lib directory of the jFreeChart distribution. Move them to the mason directory.
2. iText. Move the itext-1.4.jar file to the mason directory.

Alternatively you can download the library collection on the MASON web page, which contains these libraries, and move them into MASON from there.

Add-On Movie Generation

• MacOS X users should install the "Cross-platform Java" version, and place the jmf.jar file directly into the mason directory.
• Windows and Linux users may install the custom versions of JMF Sun provides for them. But if those versions are frustrating you, you may follow the same instructions as the OS X users (which is simpler).

Alternatively you can download the library collection on the MASON web page, which contains this library, and move it into MASON from there.

Prettier OS X Experience

• Java's color chooser is poor. You might try the "quaqua-colorchooser-only.jar" file in the Quaqua look and feel distribution.

Alternatively you can download the library collection on the MASON web page, which contains this library, and move it into MASON from there.

MASON Documentation and Tutorials

Beginning Coders

If you're the kind of person who likes UML charts (or a bad approximation thereof), take a look at our Simulator Layout diagram, last updated a few versions ago and still pretty accurate.

Last but hardly least, we predict that the Class Documentation will prove useful to you. There is also an overview of the basic MASON classes.

Advanced Coders

The Notes contain vital stuff that any MASON hacker should know.

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.

Last, the app directory contains a number of example programs illustrating various MASON programs (and of varying quality!).

Lost?

Hop on the MASON mailing list and post a question! Humans are often the best documentation of all. See the MASON website for instructions.

Compiling MASON

MASON compilation presumes you are experienced with setting up CLASSPATHs (Windows example, OS X, Linux, etc.), running javac or jikes, and using a Makefile (if you're running Linux or MacOS X).

Here's what needs to go into the CLASSPATH:

1. The mason directory itself
2. All jar files located inside the mason directory, specifically the jar files for JFreeChart and JCommon, iText, and JMF.

If you're planning on using jikes, you'll also need to set up the JIKESPATH to include everything in the CLASSPATH, plus the various jar files of your java installation. See the jikes documentation for more information.

Compiling From Eclipse

On this page Steve Lytinen and Steve Railsback have written a nice tutorial for using MASON in Eclipse.

Compiling from the OS X / Linux Makefile

Make sure your CLASSPATH is set up right. Then:

     cd mason; make 3d

...will compile all the files. Try make help to see more options.

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

     cd mason; make

If you get an error about jikes not installed, you can modify the Makefile's JAVAC variable to use the javac compiler instead. Or if you'd like to try jikes (it's much faster), install it from IBM's site.

Compiling from the Windows DOS prompt

Make sure your CLASSPATH is set up right. Then try this:

     cd mason
     dir /s /B *.java > sources.txt
     javac @sources.txt

Running an App from the Command Line

Every GUI app class ends with the extension "WithUI.java". Assuming your CLASSPATH is set up properly, you can run any of them directly from the command line. For example:

     java sim.app.heatbugs.HeatBugsWithUI

You can also run MASON proper from the command line like this:

     java sim.display.Console

In certain situations you may wish to run with more memory. First, certain Java3D applications (notably Particles3D) require a lot of RAM because Java3D is a memory hog. Second, if you're running in Windows or Linux and wish to use the faster stretched image technique for drawing grids of rectangles (see the Options window -- the wrench icon ), increasing RAM will help performance. You can do this by including the -Xmx option in Java. For example, to run MASON directly using 200 megs of RAM:

     java -Xmx200M sim.display.Console

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:

(In tcsh)
     alias java /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home/bin/java
(In bash)
     alias java='/System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home/bin/java'