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

  1. Ensure that you have Java Runtime Environment [JRE] 1.5 or newer installed on your machine.
  2. Download and double-click "Ascape5.0.0.jar"!
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 "Ascape5.0.0.jar" org.ascape.model.Scape
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 "Ascape5.0.0.jar" org.ascape.model.Scape edu.brook.pd.PD2D
java -cp "Ascape5.0.0.jar" org.ascape.model.Scape edu.brook.pd.PD2D mutationRate="0.2"
java -cp "Ascape5.0.0.jar" org.ascape.model.Scape 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 -- running Ascape with Ant

  1. Download and unzip AscapeRuntime[Date].zip from the Ascape web-site. 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.
  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. cd [path to AscapeRuntime]/tools
  5. 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.

Building Ascape and 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 Ant

In order to ensure that Ascape can be built in any environment and to support automated building and testing, the Ascape SDK includes complete ant scripts in the project tools directory. If you wish to use ant or test your basic environment, follow these steps. Otherwise, you can skip ahead to the next section.
  1. Ensure that you have the Java Development Kit (JDK) 1.5 or higher installed on your system.
  2. Download and unzip AscapeSDK[Date].zip from the Ascape web-site.
  3. Download and install ant. (See above.)
  4. Add junit to your classpath.
    The junit.jar is included in the Ascape SDK. If you do not already have it, see your platform documentation for setting environment variables and add [PathToAscapeSDK]/org.ascape.common/lib/junit.jar to CLASSPATH. 
  5. cd [path to AscapeSDK]/org.ascape.common/tools
  6. ant
If everything is set up properly, ant should rebuild Ascape and the included Ascape models and run a set of unit tests to ensure that Ascape is functioning properly. Note that you may see a few warning messages; this is expected. Next, to build the demo models, you can do: 
  1. cd [path to AscapeSDK]/org.ascape.models.brook/tools
  2. ant
  3. cd [path to AscapeSDK]/org.ascape.models.examples/tools
  4. ant
You could use nothing more than ant and a text editor such as emacs to write and build models. Ant can also be easily used from within many IDE's so you may simply want to use the included tools/build.xml files to build from your IDE. A full explanation of ant configuration is beyond the scope of this document, but the modular nature of the included build files makes this pretty simple. You can simply copy the directory structure of org.ascape.models.examples and alter a few lines in the build.xml file.

Building with Eclipse

  1. Install Eclipse. We recommend Europa [3.3], the latest release.
  2. Download and unzip AscapeSDK[Date].zip to a convenient location.
  3. Launch Eclipse
  4. Right-click in package explorer space and select "Import".

  5. From "General" folder, choose "Existing Projects..".

  6. Browse to your install directory and select all projects.

  7. 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.
  8. Right-click in package explorer to create a new project for your Ascape model(s).

  9. If you don't see Java project, you can select New:Other.. and Java Project.

  10. Or Select New "Other.." and Java Project.

  11. Give the project a name and leave all of the other settings as is.

  12. Click Next and select the Projects tab, and click the Add button to add the "org.ascape.common" project to the build path.

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

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

  15. The source file is created.

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

  18. 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.model.Scape as the main class.

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

  20. Click Run and launch your first Ascape model!

Building with another IDE

If you want to use an IDE other than Eclipse, set up should still be pretty simple. As we mentioned in the ant section above, you might simply want to import the project folders (e.g. org.ascape.common, org.ascape.models.brook and org.ascape.models.examples ) into your directory and then use your IDE's ant build tools. 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 Ascape or the included models, do the following:
  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 the brook and examples src directories to your main project.
  3. Add all of the jar files to your project libraries.
    Don't leave out QT.java!
  4. Add the 'src' directory(s) to your source files.
  5. Select the IDE 'build' menu item.
    If you were using Eclipse, this would happen automatically.
To build your own models::
  1. Download and unzip AscapeSDK[Date].zip and/or AscapeRuntime[Date].zip (see below).
  2. Create a new project.
  3. Add all of the jar files in org.ascape.common to your project libraries, and
  4. Add the org.ascape.common/bin directory to your build path.
  5. Or use the .jar files from AscapeRuntime, which include ascape-common.jar and ascape-models.jar.
  6. Create a source (src) directory(s) or a dependent project to manage your own model files.
  7. Select the IDE 'build' menu item.

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

    Movies appear to be broken under recent editions of Mac OS X and have not been tested extensivil under other platforms. Please let us know of yopur expereinces 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