mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 1 | <?xml version='1.0' encoding='utf-8' ?> |
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 | <html xmlns="http://www.w3.org/1999/xhtml"> |
| 4 | <head> |
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
mparker | 5bdc3c0 | 2010-01-07 19:59:01 +0000 | [diff] [blame] | 6 | <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 7 | <title>Escape</title> |
| 8 | </head> |
| 9 | <body> |
| 10 | <h1 id="Overview">Overview</h1> |
| 11 | <p>Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based |
| 12 | API and end user modeling tools. It's based on Ascape, which has been in use for more than 10 years. The core API is |
| 13 | very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch |
| 14 | with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then |
| 15 | execute those models within the same development environment.</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 16 | <p><img src="image/AMPScreenshot.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 17 | <p>A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM |
| 18 | toolkit -- is to provide an exemplar to demonstrate how any arbitrary agent modeling framework can be integrated within |
| 19 | the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM |
| 20 | modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP |
| 21 | and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than |
| 22 | ten years ago and that has not been modified at all in order for it to work within the AMP environment.</p> |
| 23 | <p>(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit |
| 24 | of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape |
| 25 | is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and |
| 26 | AGF components.)</p> |
| 27 | <h1 id="Getting_Started">Getting Started</h1> |
| 28 | <h3 id="Documentation_and_other_Resources">Documentation and other Resources</h3> |
| 29 | <p>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation. |
| 30 | There is complete Javadoc as well as a manual and other web resources. See the <a href="http://ascape.sourceforge.net">Ascape |
| 31 | Website</a> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape |
| 32 | so ignore all of the bits about project setup, and a lot of the UI is different, but the basics apply to Escape just as |
| 33 | well. The <a href="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</a> written by Damon Centola |
| 34 | should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual |
| 35 | work under Ascape. (Converting these models is a great opportunity for a community contribution!)</p> |
| 36 | <h2 id="Installation">Installation</h2> |
| 37 | <p>Escape is <a href="http://eclipse.org/amp/installing/">installed</a> by default with the other model components. |
| 38 | If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from |
| 39 | source but in that case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site |
| 40 | if you're not actually doing AMP development.</p> |
| 41 | <h2 id="Exploring_Example_ABM_Models">Exploring Example ABM Models</h2> |
| 42 | <p>The first thing most people will want to do in AMP is to play with the example models. You don't need to do any |
| 43 | programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is <a |
| 44 | href="http://eclipse.org/amp/installing">Install AMP</a>. (You don't need any of the optional components unless you |
| 45 | want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really |
| 46 | interesting classic ABM models.</p> |
| 47 | <h3 id="AMF_Models">AMF Models</h3> |
| 48 | <p>There are a number of models developed with AMF that can automatically generate example models to run in Escape. |
| 49 | There are two ways to run the example models:</p> |
| 50 | <h4 id="Setup_Escape_Projects">Setup Escape Projects</h4> |
| 51 | <h5 id="Creating_a_New_Escape_Project">Creating a New Escape Project</h5> |
mparker | 5bdc3c0 | 2010-01-07 19:59:01 +0000 | [diff] [blame] | 52 | <p>The best option is to simply create a new Escape project and drag the models into it! Just follow this <a href='javascript:liveAction( |
| 53 | "org.eclipse.ui.cheatsheets", |
| 54 | "org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction", |
| 55 | "org.eclipse.amp.escape.intro")'>cheatsheet</a>.</p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 56 | <ol> |
| 57 | <li>If you're not already there, open the Agent Modeling Perspective. Select Window : Open Perspective : |
| 58 | Other.. and then Agent Modeling. (Or you can choose Window : Reset Perspective and the Agent Modeling perspective |
| 59 | should appear in the Open Perspective list itself.)</li> |
| 60 | <li>Next, let's create the project where we'll place our model. Select File : New : Escape AMF Project. Give it |
| 61 | a name like "escape.tutorial", then click Finish.</li> |
| 62 | <li>Finally grab the Epidemic.metaabm model at <a |
| 63 | href="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</a> |
| 64 | and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in |
| 65 | which case just right-click on the link and save it to a file.)</li> |
| 66 | </ol> |
mparker | bf34438 | 2009-12-17 07:55:54 +0000 | [diff] [blame] | 67 | <h5 id="Using_an_Pre-Built_Example_Project">Using a Pre-Built Example Project</h5> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 68 | <p>If you get really stuck somewhere, you can also get ready made projects from CVS. See <a |
| 69 | href="http://eclipse.org/amp/developers/repositoryDetails.php">this page</a> for information on CVS setup. The |
| 70 | project for Escape example models are located at:</p> |
| 71 | <pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape |
| 72 | </pre> |
| 73 | <h4 id="Run_the_Model">Run the Model</h4> |
| 74 | <p>Right-click on the model, and select "Execute"! You should see something like this:</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 75 | <p><img src="image/EpidemicModelRunning.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 76 | <p>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory. |
| 77 | The toolbar buttons allow you to control model execution.</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 78 | <p><img src="image/EpidemicModelControls.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 79 | <p>From right to left, you can start, restart, pause, step, stop and close a model. You can even run multiple models |
| 80 | and control them independently. You can also move views around, close them and so on as with any other Eclipse views. |
| 81 | Here we're running two separate models for comparison.</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 82 | <p><img src="image/EpidemicModelComparison.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 83 | <p>If you want to find out more about an agent, show the properties view, and click on agent.</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 84 | <p><img src="image/EpidemicModelAgentProperties.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 85 | <p>You can experiment with different parameters (settings) for models by then clicking in the gray area away within |
| 86 | the view.</p> |
mparker | 3a32197 | 2009-12-16 23:07:24 +0000 | [diff] [blame] | 87 | <p><img src="image/EpidemicModelProperties.png" /></p> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 88 | <p>There are a number of other things to play around with, such as zooming the agent view or selecting other chart |
| 89 | series to display using the Chart Customizer, so just explore. You can always close an active model by clicking on the |
| 90 | close toolbar button. Or if you can't access the models controls for some reason, you can open the progress view and |
| 91 | close projects form there.</p> |
| 92 | <h4 id="Next_Steps">Next Steps</h4> |
| 93 | <p>Other models are located at: (to do)</p> |
| 94 | <p>To understand the capabilities of AMF, you might also want to try out running the same models automatically |
| 95 | generated for Ascape or Repast.</p> |
| 96 | <pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape |
| 97 | org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast |
| 98 | </pre> |
| 99 | <h3 id="Classic_Java_ABM_Models">Classic Java ABM Models</h3> |
| 100 | <p>Many models have been created using Ascape over the years, including all of the classic models created at |
| 101 | Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've |
| 102 | all been converted to run in Escape. They're in Java but you can execute and explore them in exactly the same way as the |
| 103 | Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial |
| 104 | Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You |
| 105 | can get the projects in two ways:</p> |
| 106 | <h4 id="From_Project_Archive">From Project Archive</h4> |
| 107 | <ul> |
| 108 | <li>Download the Escape examples zip from the Ascape sourceforge site: <a |
| 109 | href="http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download">http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download</a> |
| 110 | </li> |
| 111 | <li>Unzip the file.</li> |
| 112 | <li>Import them into your workspace. For help, see <a |
| 113 | href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this |
| 114 | page</a>.</li> |
| 115 | </ul> |
| 116 | <h4 id="From_SVN">From SVN</h4> |
| 117 | <ul> |
| 118 | <li>Import the SVN projects from the sourceforge SVN. For help, see <a |
| 119 | href="/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page" |
| 120 | title="http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php this page">http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php |
| 121 | this page</a>.</li> |
| 122 | </ul> |
| 123 | <pre>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook |
| 124 | http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples |
| 125 | </pre> |
| 126 | <p>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models. |
| 127 | For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select |
| 128 | "Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have |
| 129 | to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</p> |
| 130 | <h2 id="Developing_Models">Developing Models</h2> |
| 131 | <p>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write |
| 132 | programs using it.To develop new models, you can:</p> |
| 133 | <ol> |
| 134 | <li>Create a new Escape project. The Escape projects are actually configured for AMF code generation so there |
| 135 | are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the |
| 136 | kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.</li> |
| 137 | <li>But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have |
| 138 | a look at the example escape project to see what you need. Note that you will likely need more dependencies then you |
| 139 | need to simply build -- this is because the class loader uses the classes from the project path and so runtime |
| 140 | classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these |
| 141 | dependencies up a bit.</li> |
| 142 | </ol> |
| 143 | <p>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</p> |
| 144 | <h1 id="Reference">Reference</h1> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 145 | <h2 id="Current_Limitations">Current Limitations</h2> |
| 146 | <ol> |
| 147 | <li>Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as |
mparker | 402223a | 2009-12-21 20:36:48 +0000 | [diff] [blame] | 148 | stable for a while as Ascape which has been around for a long time. But we haven't run into any issues recently.</li> |
| 149 | <li>Escape graphics performance is generally a little bit slower. But on the other hand you can run |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 150 | multiple models at once and the headless models should perform just as well as console launched Ascape programs. In |
mparker | 402223a | 2009-12-21 20:36:48 +0000 | [diff] [blame] | 151 | practice this shouldn't affect your normal model exploration work. Ad you can always speed ahead by using the speed slider!</li> |
mparker | 6e96f89 | 2009-12-15 22:52:46 +0000 | [diff] [blame] | 152 | </ol> |
| 153 | </body> |
| 154 | </html> |