This year we are offering a class-wide simulation environment for use in
projects if you so choose. If you would prefer to use another simulation
package (perhaps one that you are already familiar with), that is generally fine
but please drop by Ian's office hours
at some point to discuss it. You are strongly discouraged from writing your own
simulator but if you feel a pressing need (e.g. the simulation environment
described here does not meet your needs) please come to Ian's office hours to
explain your situation.
In brief, the SSR simulator ("SSR-Swarm") is a collection of Java classes that are intended to
make it easier for people to write multi-agent simulations. An application
developer writes classes that implement certain interfaces and the core
simulation engine takes care of the rest. Simulations can be run in batch mode
(i.e. no GUI), via Swing (a command-line graphics library) or as a browser
Applet.
This page explains how to get started using the SSR-Swarm environment; how to
install, run the demo applications, use the GUI, etc. For information on how to
develop your own applications, visit this page which
describes the SSR-Swarm programming model.
Environment
SSR-Swarm is 100% pure Java. If you have experience coding in C/C++/C#, you
probably will not have much trouble picking it up, but you will want to spend
some time looking over tutorials online or in a book or something before you
dive straight into the SSR-Swarm code.
I work in a unix-style environment, but everything should work fine on Windows
or MacOS systems as well (that's the beauty of Java!). So in this document,
when I write "type this...", that means to type it at a shell if you are
on a unix-style system, at a command prompt if you are on Windows, and at the
terminal if you are on a Mac. A makefile is included to make compile and
running the applications easier, but it certainly not required. If you have
trouble getting the makefile to work on your system, contact
me for help.
Since SSR-Swarm is all Java, this simplifies installation considerably.
Essentially all you need is the Java Development Kit (JDK), version 1.5
or later. To see what version (if any) you already have installed, type:
javac -version (note the
c at the end of java!)
The first line of the response on my systems says javac 1.5.0_10. As
long as the version number starts with 1.5, then you should be ok. If it starts
with 1.4 or less, or if it doesn't run at all (e.g. javac: Command not
found.) then you need to install JDK 1.5 or later.
Installing Java (Linux/Solaris/Windows)
If you already have JDK 1.5 or later, skip this section.
You can download JDKs directly from
http://java.sun.com - but note that the naming
is confusing; version 1.5 is called "JDK 5" (not JDK 1.5) and version 1.6 is
called "JDK 6" (not JDK 1.6). Regardless, the most recent version is 1.6 so if
you want to install that, go
here and choose
the 'download' button next to JDK 6 Update 3. If you just want to stick
with JDK 1.5, which is what I run, go
here and
choose the 'download' button next to JDK 5.0 Update 13
Either way, make sure you are getting
the Java Development Kit and not the Java Runtime Environment.
Installation instructions will follow.
Installing Java (MacOS)
If you already have JDK 1.5 or later, skip this section.
Unfortunately for Mac owners, you cannot install JDKs directly from Sun's
site and Apple is rather stingy with their upgrades; it appears that depending
on what system of MacOS you have purchased, that limits you in terms of what
version of Java you are allowed to upgrade to, but I could be incorrect on
that. If you do not have Java at all, or are running a version pre-1.5, try the
download options here -
if you do not have any success, you are probably out of luck on your Mac and you
should contact me about other options.
A few simple applications are included with SSR-Swarm to serve as demos. To
run the Game of
Life application, type
make life
By default, the make commands run the applications with a GUI window, so if you
get an error something like the following
Exception in thread "main" java.awt.HeadlessException:
No X11 DISPLAY variable was set, but this program performed an operation which
requires it.
at
java.awt.GraphicsEnvironment.checkHeadless(GraphicsEnvironment.java:159)
at java.awt.Window.(Window.java:317)
at java.awt.Frame.(Frame.java:419)
at javax.swing.JFrame.(JFrame.java:194)
at edu.harvard.ssr.swarm.apps.SwarmExec.makeJFrame(SwarmExec.java:90)
at edu.harvard.ssr.swarm.apps.SwarmExec.(SwarmExec.java:27)
at edu.harvard.ssr.swarm.apps.SwarmExec.main(SwarmExec.java:75)
make: *** [life] Error 1
that means that you are running in a window that doesn't support X11 graphics
(perhaps you are SSHed into a machine from somewhere else?). You can run
the application without a GUI (not very fun, and generally only useful if you
are doing a bunch of different runs to collect data for something), you can
change to an environment with X11 support, (e.g. by logging into the machine
directly, instead of over SSH), or you can use the
Applet-version of the applications.
If you successfully run the application, you should see a window like this:
Here you can see the general layout of the SSR-Swarm GUI. Note that this is
just the GUI layout that I have provided; if you want to add extra widgets
(buttons, text fields, etc.) you can easily do that. The "time" display tells
you the current time (in milliseconds) in the simulation. Simulation
time is not the same as real time; simulation time always starts at 0, only advances when the
simulation is running (not paused), and can be sped up or slowed down by
changing the simulation's time scale (note the widget on the right - its
set to 1 by default which means the simulation runs at the same rate as real
time).
The Start and Stop buttons start and top the simulation. If stopped, the
Step button advances the simulation by 1 "event" (events are defined later).
For now, don't worry about the Step button (it doesn't happen to be
particularly useful in this application, but will in others). Take some time
now to try out the Start and Stop buttons, as well as changing the time
scale. Note that (for reasons that will be explained later) this application is
somewhat CPU intensive so at some point increasing the time scale won't do
anything because the simulation simply won't be able to keep up with the speed
that you are requesting.
Running Applets
Instead of running applications from the command line, you can also compile them
into Applets, which are java applications made to be embedded into web pages.
Each of the existing SSR-Swarm applications has been compiled into an Applet,
links are available here. Note that even though in
this case you are viewing (and interacting) with the applications through your
browser, you still need Java installed for your browser to know how run the
Applets. In general, developing with Applets is a little more annoying
(you have to make a web page to display them, browsers like to cache the code
they download which is annoying when you make changes, etc.) so I recommend you
use them only when you don't otherwise have access to an X11 environment.