Introduction

Ascape is an innovative tool for developing and exploring general-purpose agent-based models. It is designed to be flexible and powerful, but also approachable, easy to use and expressive. Models can be developed in Ascape using far less code than in other tools. Ascape models are easier to explore, and profound changes to the models can be made with minimal code changes. Ascape offers a broad array of modeling and visualization tools.

A high-level framework supports complex model design, while end-user tools make it possible for non-programmers to explore many aspects of model dynamics. Ascape is written entirely in Java, and should run on any Java-enabled platform. Whether you are involved in academia, industry, or government, we hope that you will find that Ascape enables your efforts to exploit the profound insights agent-based models make possible.

Ascape is released under a BSD standard open source license and thus is free to use and redistribute. The Ascape distribution includes a number of other Open Source libraries; please see the licenses directory and individual jars for more information.

Ascape is research oriented software; while it is quite mature, apis, distribution, may continue may change over time. Direct support is not provided; forums provide a much better venue for sharing information and make the most efficient use of limited resources. For support, comments, or discussion of technical and general modeling issues, please use the Ascape forum at ascape.sourceforge.org. We welcome and encourage your feedback, positive and negative. User contributions, ideas, and feature requests are also most welcome. (See below.)

Acknowledgments

First, thanks to all the users of Ascape who have provided so much valuable feedback over the years. Your enthusiasm is the primary motivation for the continuing improvement of Ascape.

Design and Development: Miles Parker
Development: Mario Inchiosa, Josh Miller and Oliver Mannion (Swing Navigator)
Models, Extensions and QA: Alan Lockard, Jason Harburger, Jim Girard, Roger Critchlow, Carl Tollander, Lisa Stuart, and many others...

Profound thanks to Joshua Epstein and Robert Axtell for the science that inspired this work and the initial support that made it possible, to Ross Hammond, David Hines, Shubha Chakravarty, Jon Parker and many others who have supported Ascape at Brookings, and to everyone else at the Center on Social and Economic Dynamics.

Ascape was supported at Bios and later NuTech by the kind of people who are both very smart and great fun to work with, especially Mario Inchiosa, Josh Miller, Mike Neely, and Mike McClain.

This work benefits greatly from the work of many software developers in the agent based modeling world. The Swarm community, especially Roger Burkhardt, Marcus Daniels and Glen Ropella provided an inspiring and helpful environment in which to explore and discuss modeling issues, and Swarm itself has inspired some Ascape features. While Ascape and Repast were developed separately, related continuing work has benefited greatly from work with Nick Collier, Tom Howe and everyone else at the Repast team.

Damon Centola wrote the excellent Model Developer's manual.

David Hines designed the Ascape logo.

Toolbar icons are are (c)1998 Dean S. Jones (dean@gallant.com www.gallant.com/icons.htm)

Special thanks to the early testers and supporters of Ascape, including Ginger Booth, Ross Hammond, Alan Lockard, Eric Verhoogen and Tim Gulden, who provided many useful comments, ideas and feedback.

Getting Started

Ascape can be downloaded at ascape.sourceforge.org and is available as: The sections below explain each usage. Please note that the Ascape version numbers listed below are generic. So for example if you have downloaded version 5.9.9 (it doesn't exist yet!) then substitute Ascape_5.m.n with Ascape_5.9.9

Running Models

Mac Users: Currently the OS X version of Java uses a default graphics implementation that is s__l__o__w. Unfortunatly, there is no way to change this from the runnable jar. If you are a Mac user, we suggest you use the Command-Line method with to set the graphics implementation to run quickly.
java -Dapple.awt.graphics.UseQuartz=true -jar Ascape_5.m.n.jar
Executable Jar
  1. Ensure that you have Java Runtime Environment [JRE] or Java Deveopment Kit [JDK] 1.5 or newer installed on your machine.
  2. Download and double-click "Ascape_5.m.n.jar"!
Command-Line
If you can't or don't wish to use the JRE you can also start Ascape from the command-line by typing: 
  1. cd [path to Ascape directory]
  2. java -cp "Ascape_5.m.n.jar" org.ascape.runtime.swing.SwingRunner
If you want to add the jar to your class-path, note that the Ascape jar includes all library dependencies, so you will probably want to use the Runtime download as described below.

Models and parameters can be specified as command-line arguments. Try:
java -cp "Ascape_5.m.n.jar" org.ascape.runtime.swing.SwingRunner edu.brook.pd.PD2D
java -cp "Ascape_5.m.n.jar" org.ascape.runtime.swing.SwingRunner edu.brook.pd.PD2D mutationRate="0.2"
java -cp "Ascape_5.m.n.jar" org.ascape.runtime.swing.SwingRunner edu.brook.pd.PD2D stopPeriod=100 displaygraphics=false autorestart=false After launching Ascape the first-time, a click-through license appears and then a model selection menu.



Select a model from the drop-down list and press 'open'. The selected model will begin automatically with its default parameters.


Controlling Ascape

Menu Bar
The menu bar contains the following features, shared with the control bar below:

File
  1. OPEN MODEL: Open a new model as specified in a Java class file.
  2. OPEN MODEL RUN: Open a saved (serialized) model run.
  3. SAVE RUN: Save the current model run for later deserialization.
  4. CLOSE MODEL: Quit the model, but not the environment.
  5. QUIT: End the Ascape session.
Views
  1. NEW TIMESERIES: Create a new time series.
  2. NEW HISTOGRAM: Create a new histogram.
  3. NEW PIECHART: Create a new pie chart.
Control
  1. START: Begin a model run.
  2. RESTART: Start a model run back at the begining.
  3. STOP: End the current run.
  4. PAUSE: Pause the current run.
  5. RESUME: Resume a paused model run where it left off.
  6. STEP: Perform one iteration of the current run while the model is in a paused state.
OPTIONS
  1. SETTINGS: Control the model settings ('globe' button). Display the initialization and run-time parameters. There are two tabs: Parameters and Rules.
  2. START RECORDING: Start recording movie of running model
  3. STOP RECORDING: Start recording movie of running model
  4. ABOUT: Display the program information ('i' button) including attributions.
Control Bar
The control bar provides an easy way to manage model execution:



From right to left, the components allow one to:
  1. Navigate between the various chart windows.
  2. Display the current model iteration.
  3. Display the current state (Running/paused/stopped)
  4. Open a new model.
  5. Open a saved model run.
  6. Save the current model run.
  7. Quit the model.
  8. Restart the model.
  9. Pause the current run ('flag' button).
  10. Step through the current run when the model is in a paused state.
  11. Stop the current run.
  12. Control the model speed ('flag' slider).
  13. Control the model settings ('globe' button). Display the initialization and run-time parameters. There are two tabs: Parameters and Rules.
  14. Create movies of running model ('camera' button).
  15. Display the program information ('i' button)
  16. Create a new time series.
  17. Create a new histogram.
  18. Create a new pie chart.

Setting Parameters and Rules

Parameters

Select the Parameters tab.

Rules

Select the Rules tab.


A rule is a behavior that can be iterated across any agent or group of agents. Rules can be selected, de-selected and ordered on the model dynamically.

Inspecting Agent State

Open an Agent Inspector by alt [option] + left-clicking on a cell. Shift-alt [option] + click sets a tracking inspector that follows a particular agent around a space.



Inspectors allow the user to delve into an agent, examining and changing its values, letting the user model on-the-fly what-if scenarios, and follow a particular agent throughout the course of the run. Those fields that are gray represent those that are read-only, and cannot be changed during runtime.

Charts

Model statistics can be easily charted.



The chart above shows a time-series of the number of cooperating (Blue) and defecting (Red) agents.

Chart Settings
To create a new chart of model results using a time series, histogram, or pie chart, click on one of the three 'Chart' icons on the control bar. The following dialog appears along with a blank chart area. This dialog can be opened at any point by double-clicking on a chart.



The chart settings dialog lists the model's statistics. Most of the statistics have a number of ways of being graphed. 'Count' lists the number of agents a statistics is being calculated over (i.e. a statistic run across a set of agents has a count equal to the number of agents in that set). 'Sum' returns the summation of the statistic across all of its agents. 'Min' and 'Max' are the minimum and maximum values of the statistic across its agents, respectively, and 'Var' and 'StD' are its variance and standard deviation. Select a statistic by checking the appropriate box.

Chart Properties
Right-clicking on a chart opens a pop-up menu (figure 6) that gives the option of printing and saving the chart, or adjusting its properties.



The three tabs of the Chart Properties window (figure 8) let the user make changes to background color, axis labels, and similar chart properties. Note that many chart properties are managed by Ascape, so these properties are typically best used for creating static charts of important results.

Capture Image

Clicking on the first camera icon produces a quick desktop snapshot in the launch directory.

Quicktime Movies

Click on the second camera icon to begin taking a movie and follow the dialog instructions. (Due to a change in the Apple QT runtime, movies are ironically currently broken under OS X.)

Building Ascape Models

Basics

It is not necessary to have an IDE (Integrated Development Environment) such as IntelliJ or Eclipse, but they are be an indispensable aid to the development process. While I hesitate to coerce anyone into using a specific software tool, I recommend Eclipse, as complete Eclipse projects are provided and future related work will rely heavily on the Eclipse platform. -Miles

Building with Eclipse

Building models with Eclipse

If you are not planning to change Ascape, the simplest way to develop models is to use the Eclipse plugins. We now have a custom wizard for creating Ascape projects! If you have any problems with this approach just use the "Building Ascape itself" instructions below instead.

  1. Install Eclipse.

  2. Install Ascape using the Eclipse Update Manager. Update site is http://ascape.sourceforge.net/eclipse. Please see the Eclipse user documentation for more details and post a support message if you have any difficulties. If this isn't working well for you for whatever reason then you can always Build Ascape directly in your workspace.

  3. Restart Eclipse and Select Window -> Reset Perspective. (Or choose "Project.." in the next menu and locate the Ascape project in the dialog.)

  4. Right click in the Package Explorer and select "Ascape (Swing AWT) Project"

  5. In the dialog that follows, just enter a project name. (It says "Escape" but it really is an Ascape project!)

  6. Click Finish. Now we can build a simple Ascape model by creating a new Scape class.

  7. Enter a package, a class name and org.ascape.model.Scape as the super class.

  8. The source file is created.

  9. Paste the following code into the class body.

    	Scape helloAgents;
	Scape helloGrid;
	
	public void createScape() {
		super.createScape();
		helloGrid = new Scape();
        helloGrid.setPrototypeAgent(new HostCell());
		helloGrid.setSpace(new Array2DMoore());
		helloGrid.setExtent(20, 20);
		
		CellOccupant helloAgent = new CellOccupant();
		helloAgent.setHostScape(helloGrid);
		
		helloAgents = new Scape();
		helloAgents.setPrototypeAgent(helloAgent);
		helloAgents.setExtent(40);

		add(helloGrid);
		add(helloAgents);
		
		helloAgents.addInitialRule(MOVE_RANDOM_LOCATION_RULE);
		helloAgents.addRule(RANDOM_WALK_RULE);
	}

	public void createGraphicViews() {
		super.createGraphicViews();
		helloGrid.addView(new Overhead2DView());
	}

  10. Select Source:Organize Imports menu item to import referenced classes.

  11. Now that we have created our model, we can launch it by selecting Run:Open Run Dialog. Create a new Java Application configuration using the "add document" button at the upper-left. Ensure that the project name is correct and set org.ascape.runtime.swing.SwingRunner as the main class.

  12. Under the Arguments tab enter your model class name (fully qualified!).

  13. Click Run and launch your first Ascape model!

Building Ascape itself in Eclipse
  1. Install Eclipse.
  2. Download and unzip Ascape_SDK_5.m.n.zip to a convenient location.
  3. Launch Eclipse
  4. Right-click in package explorer space and select "Import".
  5. Browse to the directory you installed and pick the following projects (at least) from the list: org.acsape.core, org.acape.common.lib, org.ascape.ui.swing. You will probably want the model projects as well.
  6. Ascape will build automatically.
    By default, Eclipse displays an imposing list of java source warning messages, almost all of which have to do with narrow Java 1.5 generics issues, and all of which can be safely ignored. These warning can be made less aggressive by selecting Eclipse:Preferences and modifying Java:Compiler:Errors/Warnings.
  7. If you want to build a new model project, create a new Java project by right-clicking in the Package Explorer, and selecting "New:Java Project".
  8. Give the project a name and leave all of the other settings as is.
  9. Click Next and select the Projects tab, and click the Add button to add the "org.ascape.ui.swing" project to the build path.
  10. You chould be able to continue with the instructions under building models above.
Building using the Eclipse AMP tools.

The Eclipse AMP tools provide powerful support for Ascape and much more including advanced tools that don't require programming'. AMP is a new project but it has great built-in support for Ascape, and you can even try the new Escape environment which allows you to run Ascape models within a self-hosted Eclipe environment! If you want to run models directly from within Eclipse, then install the AMP tools from http://download.eclipse.org/amp/updates/releases

Building models with another IDE

If you want to use an IDE other than Eclipse, set up should still be pretty simple. If you wish to set things up to use your IDEs build features, these are the basic steps; see you IDE documentation for more details.
To build your own models:
  1. Create a new project.
  2. Add the Ascape_5.m.n.jar to your project (usually this is placed in a 'lib' directory).
  3. Create a source (src) directory(s) or a dependent project to manage your own model files.
  4. Follow the directions above to create your first model, or place that org.acape.models.brook and org.ascape.models.examples into a source directory.
  5. Select the IDE 'build' menu item. (In Eclipse, builds happen automatically.)
To build Ascape itself:
  1. Download and unzip AscapeSDK[Date].zip.
  2. Create a new project.
    Depending on your IDE, you may want top set up separate projects for each of the included Ascape projects, or you may simply want to add all of the src and org.ascape.common.lib directories to your main project.
  3. org.ascape.common.lib includes all dependent classes (jars) in unpacked form.
  4. Project dependencies are org.ascape.ui.swing -> org.ascape.core -> org.ascape.common.lib
  5. Add the 'src' directory(s) to your source files.
  6. Select the IDE 'build' menu item.
    If you were using Eclipse, this would happen automatically.

Developing Models -- Where to Go from Here

One of the best ways to learn about Ascape is to simply explore and modify the wealth of existing models. Experimentation with exisiting models is one of the best ways to learn about the framework. Take a look at edu.brook.pd.PD2D for a well documented implementation of a model in Ascape. The bionland models, while not documented, provide a nice progression for use in a self-study tutorial.

Analyzing Models and running Ascape with Ant

Ascape has full support for runtime control from Ant. This is a great option for those who want to set up batch runs or to use Ascape without having dependencies on a specific IDE such as Eclipse. (It works well from within Eclipse and other tools as well.) Here's how to use Ascape with Ant.

Building with Ant Prior Ascape releases supported automated building with ant. As there is now good consistent build support in Eclipse and other IDEs we are no longer using or supporting ant builds. The old scripts are available in org.ascape.all on the sourceforge site and could be made to work with minimal modifications.
  1. Download and unzip Ascape_SDK_5.m.n.zip from the downlaods site.
  2. Download and install ant.
  3. Ensure that ant is available in your executable path. See the ant documentation for more details on ant configuration.
  4. Open a command line environment. On Macs and Linux this is the "Terminal", on Windows "Console".
  5. Change to the org.ascape.all directory that you installed into. For example
    cd /MyMachine/Ascape_SDK_5.m.n/org.ascape.all
    dir C:/MyAscapeDir/toolsAscape_SDK_5.m.n/org.ascape.all
  6. Invoke ant run.xml by typing: ant -f run.xml runPD
If we take a look at the run.xml file we can see that it is relatively simple. You can add or modify targets, or use run.xml as a template for your own run targets. 
    <target name="runPD" depends="run prep">
        <ascape> 
            <scape modelClass="edu.brook.pd.PD2D">
                <propertySet 
                    displayGraphics="true"
                    numberOfAgents="100" 
                    stopPeriod="100"/>
            </scape> 
        </ascape>
    </target>

We specify model class and then a set of model properties, which can include model parameters as well as run control variables. For example, if we set display graphics to false, the model will run in headless mode. But we can do much more using Ant configuration. We can turn on and off scape rules, specify agent state, and even define views, which can include graphic views: 
    <target name="runPDConfigExample" depends="run prep">
        <ascape>
            <scape modelClass="edu.brook.pd.PD2D">
                <propertySet numberOfAgents="100"/>
                <ruleSet selectAll="false"/>
                <chartView name="Defect v. Cooperate Wealth" legendShowing="false">
                    <windowBounds x="5" y="5" width="500" height="300"/>
                    <series valueName="Sum Cooperate Wealth" colorName="BLUE"/>
                    <series valueName="Sum Defect Wealth" colorHex="#FF0000"/>
                </chartView>
                <members>
                    <scape memberName="Players">
                        <ruleSet clearAll="true"
                                 randomWalk="true"/>
                    </scape>
                    <scape memberName="Environment">
                        <agentView viewName="Overhead2DView">
                            <drawSet clearAll="true"
                                     defaultFillAgent="true"/>
                        </agentView>
                    </scape>
                </members>
            </scape>
        </ascape>
    </target>
The above specifies that player's perform a random walk only, and adds a chart view with a specific position and an environment overhead view. We can also use specialized views for run control and data output. For example: 
    <target name="runPDDataOut" depends="run prep">
        <ascape>
            <scape modelClass="edu.brook.pd.PD2D">
                <propertySet
                    displayGraphics="false"
                    autoRestart="true"
                    stopPeriod="30"
                    numberOfAgents="80"/>
                <dataOutputView runFile="testPDRun.txt" periodFile="testPDPeriod.txt"/>
                <sweepView>
                    <sweepDimension parameter="deathAge" startValue="40" endValue="60" increment="10"/>
                    <sweepDimension parameter="fissionWealth" startValue="8" endValue="12" increment="1"/>
                </sweepView>
            </scape>
        </ascape>
    </target>

Here we specify data output that writes a line for each run's parameters to "testPDRun.txt" and a line for each model run's state to "runPDPeriod.txt". We also easily specify a parameter exploration by sweeping across death age and fission wealth.

The included ant.xml file can also be used with the Ascape jar. Just place the jar in the same directory with the ant file.

For the experienced programmer, Ascape is reasonably well documented internally. Ascape also includes extensive javadoc documentation and the source code is of course open and reasonably straightforward.

The Ascape Model Developers Manual, written by Damon Centola, has been newly edited and updated forthe current version of Ascape and provides an excellent introduction to Agent-Based Modeling in general including an introduction to many of the models featured here, a nice introduction to Agent-Based Modeling in general, and an extensive tutorial on developing Ascape models in particular. While I've tried to update all models, I may have missed something -- please let us know if you find any issues with the included models.-Miles

Many people will have found there way here from reading Joshua Epstein's Generative Social Science, which collects ground-breaking work over many years into a single volume. For those who wish to understand these models at the deepest level this book will be indispensable and very enjoyable.

Eclipse Help System

If you're using Eclipse and have installed the Ascape plugins, this documentation is now available directly from within Eclipse! ANd if you're using the Eclipse AMP tools you an even run the models directly from help.

Resources

Documentation

  1. The Ascape Model Developers Manual
  2. This guide!

Selected Papers

Here are a few select papers. Academic work employing Ascape should reference the PNAS or JASSS papers as appropriate.

Subversion Version Control System

Access to the source code repository is available at: https://ascape.svn.sourceforge.net/svnroot/ascape
If you would like to discuss contributing to Ascape, please contact Miles.

Known Issues

Because of changes in Apple QuickTime, movies may not work correctly under recent editions of Mac OS X and have not been tested under other platforms. Please let us know of your experiences with Linux and Windows.

Support and Contacts

Home Page

Ascape on Sourceforge

Get Ascape at SourceForge.net. Fast, secure and Free Open Source software downloads

Online Forum

Ascape requests for support and discussion should be submitted to the Ascape forums. Because of issues with spam on sourceforge, registration is required. Sourceforge Forum

Downloads

Sourceforge Forum

Sponsors

The following organizations have provided generous in-kind support and donated IP to the Open Source community. No endorsement by any of these organizations of any other organization, product or document is intended or implied.
Under no circumstances will any of the following people provide unsolicited support via direct email or phone. :)
Paid consulting and support options are available from the corporate sponsors. Otherwise please send technical questions, bug reports, etc.. to the Ascape forums.

Metascape, LLC

Metascape develops and supports innovative ABM software tools.

Website: Metascape
Contact: Miles T. Parker

NuTech Solutions, Inc. (Now Neteeza, the following information may be out of date.)

NuTech is a leader in applying ABMs to real-world industry and government problems.

Website: NuTech
Contact: Contacts Page

The Brookings Institution

The Brookings Institution is a leading national policy think tank and home to the Center on Social and Economic Dynamics, where pioneering work on Agent-Based Models continues.

Website: Brookings
Contact: CSED

In Kind Support

YourKit

YourKit is kindly supporting open source projects with its full-featured Java Profiler. YourKit, LLC is creator of innovative and intelligent tools for profiling Java and .NET applications. Take a look at YourKit's leading software products: YourKit Java Profiler and YourKit .NET Profiler.

Sourceforge
Get Ascape at SourceForge.net. Fast, secure and Free Open Source software downloads

Updating from Previous Versions

If you have a much older model (pre 4.0) you can get information about updating it here.

Version History

You can find a full history of Ascape changes (going back gten years!) here.