AMP/Escape API

Overview

The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write programs using it. Escape is the exemplar ABM environment supported by AMP. The main purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM toolkit -- is to demonstrate how any arbitrary agent modeling framework can be integrated within the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than ten years ago and that has not been modified at all in order for it to work within the AMP environment.

(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and AGF components.)

Installing

Escape is installed by default with the other model components. If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from source but in taht case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site if you're not actually doing AMP development.

Starting Out

Running Example Models

People have different learning styles, but I like to look at running code and then understand how it works. All of the Ascape example models have been converted (a straightforward process) from their intial Ascape incarnations. You can get the projects from the Ascape sourceforge site or SVN. (Link to come.) They're all released under BSD so we can't host them directly on the Eclipse site. Of course you can also run generated Escape models. They're just Java and don't rely on any other artifacts so once they have been generated to the Escape target you can modify them in Java just as with any other Escape model. Simply extract the models and import them into your workspace. To run the models, just right-click on the Java files containing the top-level model and click Run.

Developing Models

To develop new models, you can:

1. Create a new Escape project. The Escape projects are actually configured for AMF code generation so there are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.
2. But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have a look at the example escape project to see what you need. Note that you will likely need more dependencies then you need to simply build -- this is because the class loader uses the classes from the project path and so runtime classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these dependencies up a bit.

Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.

Next Steps

Escape is one component of AMP that has extensive documentation. There is complete Javadoc as well as a manual and other web resources. See the [Ascape website] to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape but the basics apply to Escape just as well.

Converting from Ascape and Escape

There are only a few changes should have to make to existing Ascape models or to use existing Ascape documentation to develop Escape models.

Model

The core model is completely API compatible. No changes!

View

Because Escape uses SWT and Ascape uses Swing, there are a few unavoidable incompatibilities. Most of these we can avoid by using the higher level APIs but here are the key changes that you're likely to have to make:

1. Convert the low-level imports from:
   1. java.awt.Color to org.eclipse.swt.graphics.Color
   2. java.awt.Graphics to org.eclipse.draw2d.Graphics
   3. etc..

The simplest way to accomplish this is to remove all of the imports and then organize imports. It's not a bad idea to specify an access rule for the project that just excludesjava.awt.* and javax.swing.* -- that will make the import process go more quickly and make it obvious if any dependencies remain.

Configuration

Instead of using Ant, Escape has really nice support for parameterizing and testing models. See Experimenting and Testing (todo). If you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape so it's not even clear it will work.