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
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 a: The sections below explain each usage.

Exploring 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.1.1.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.1.1.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.1.1.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.1.1.jar" org.ascape.runtime.swing.SwingRunner edu.brook.pd.PD2D
java -cp "Ascape_5.1.1.jar" org.ascape.runtime.swing.SwingRunner edu.brook.pd.PD2D mutationRate="0.2"
java -cp "Ascape_5.1.1.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 'Globe' button.

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.)

Analyzing Models and running Ascape with Ant

At this point, one could add the contents of the lib directory to the classpath and execute Ascape using command-line arguments as described above. But it is generally much less painful to use the included Apache ant build scripts. Ascape uses ant to support complex build and run execution support without requiring complex configuration steps.

  1. Download and unzip Ascape_SDK_5.1.1.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.1.1/org.ascape.all
    dir C:/MyAscapeDir/toolsAscape_SDK_5.1.1/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.

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. If you have any problems with this approach just use the "building Ascape itself" instructions below instead.

  1. Install Eclipse. We recommend Ganymede [3.4], the latest release.
  2. Download and unzip Ascape_Eclipse_5.1.1.zip.
  3. Copy the contents of the download into the "dropins" folder in your Eclipse install.
  4. Launch Eclipse.
  5. Right-click in Package Explorer and select New:Project..

  6. In the dialog that follows, pick "Plugin Project".

  7. Enter a name and click Next.

  8. You can deselect the plugin options on the next page and click "finish".

  9. In the new project, open up the MANIFEST.MF file.

  10. Click the Dependency tab, then the "Add.." button and select "org.ascape.ui.swing" from the long list of plugins provided. You should end up with this:

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

  12. Enter a package, a class name and org.ascape.runtime.swing.SwingRunner as the super class.

  13. The source file is created.

  14. 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());
	}
  15. Select Source:Organize Imports menu item to import referenced classes.

  16. 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.

  17. Under the Arguments tab enter your model class name (fully qualified!). It is also a good idea to make more memory available by adding the obscure vm argument -Xmx512M.

  18. Click Run and launch your first Ascape model!

Building Ascape itself in Eclipse
  1. Install Eclipse.
  2. Download and unzip Ascape_SDK_5.1.1.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 Eclipse using metaABM

A new option is to use the metaABM Ascape tools to create Ascape models. For more information, see the metaABM website.

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.1.1.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.
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 in the SDK and could be made to work with minimal modifications.

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.

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, and included in the documents download, provides an excellent introduction to Agent-Based Modeling in general including an introduction to many of the models featured here, and an extensive tutorial on developing Ascape models in particular. As with Ascape, the manual was never released when the authors had hoped. While I have tried to update code samples, the manual may be slightly out of date with respect to new features. -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.

Resources

Documentation

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

Selected Papers

Here are a few select papers. Academic work employing Ascape should reference the PNAS or JASSS papers as appropriate.
  • Overcoming design and development challenges in agent-based modeling using ASCAPE (PNAS)
  • Abstracting Complexity (Brookings Institution)
  • What is Ascape and Why Should You Care? (JASSS)

    • 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

    SourceForge.net Logo

    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.

    Brookings

    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: Gordon McDonald

    NuTech Solutions, Inc.

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

    Website: NuTech
    Contact: Contacts Page

    Metascape, LLC

    Metascape develops and supports innovative ABM software tools.

    Website: Metascape
    Contact: Miles T. Parker

    Updating from Previous Versions

    We have tried to preserve as much backward compatibility as possible. Still, this is a the first release in over eight years, and there have been many many changes to Ascape, so it is quite possible that some changes will be needed, especially is you have heavily customized Ascape views and scapes. To convert an existing model, try the follwingattempt to compile it with the new version of Ascape. .

    Version History