org.eclipse.amp/doc/org.eclipse.amp.doc/wiki/Escape.html - amp/org.eclipse.amp - Gitiles

 <?xml version='1.0' encoding='utf-8' ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
 <title>Escape</title>
 </head>
 <body>
 <h1 id="Overview">Overview</h1>
 <p>Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based
 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
 very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch
 with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then
 execute those models within the same development environment.</p>
 <p><img src="image/AMPScreenshot.png" /></p>
 <p>A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM
 toolkit -- is to provide an exemplar 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.</p>
 <p>(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.)</p>
 <h1 id="Getting_Started">Getting Started</h1>
 <h3 id="Documentation_and_other_Resources">Documentation and other Resources</h3>
 <p>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation.
 There is complete Javadoc as well as a manual and other web resources. See the <a href="http://ascape.sourceforge.net">Ascape
 Website</a> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape
 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
 well. The <a href="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</a> written by Damon Centola
 should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual
 work under Ascape. (Converting these models is a great opportunity for a community contribution!)</p>
 <h2 id="Installation">Installation</h2>
 <p>Escape is <a href="http://eclipse.org/amp/installing/">installed</a> 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 that 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.</p>
 <h2 id="Exploring_Example_ABM_Models">Exploring Example ABM Models</h2>
 <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
 programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is <a
 				href="http://eclipse.org/amp/installing">Install AMP</a>. (You don't need any of the optional components unless you
 want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really
 interesting classic ABM models.</p>
 <h3 id="AMF_Models">AMF Models</h3>
 <p>There are a number of models developed with AMF that can automatically generate example models to run in Escape.
 There are two ways to run the example models:</p>
 <h4 id="Setup_Escape_Projects">Setup Escape Projects</h4>
 <h5 id="Creating_a_New_Escape_Project">Creating a New Escape Project</h5>
 <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(
 "org.eclipse.ui.cheatsheets",
 "org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction",
 "org.eclipse.amp.escape.intro")'>cheatsheet</a>.</p>
 <ol>
 				<li>If you're not already there, open the Agent Modeling Perspective. Select Window : Open Perspective :
 				Other.. and then Agent Modeling. (Or you can choose Window : Reset Perspective and the Agent Modeling perspective
 				should appear in the Open Perspective list itself.)</li>
 				<li>Next, let's create the project where we'll place our model. Select File : New : Escape AMF Project. Give it
 				a name like "escape.tutorial", then click Finish.</li>
 				<li>Finally grab the Epidemic.metaabm model at <a
 								href="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</a>
 				and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in
 				which case just right-click on the link and save it to a file.)</li>
 </ol>
 <h5 id="Using_an_Pre-Built_Example_Project">Using a Pre-Built Example Project</h5>
 <p>If you get really stuck somewhere, you can also get ready made projects from CVS. See <a
 				href="http://eclipse.org/amp/developers/repositoryDetails.php">this page</a> for information on CVS setup. The
 project for Escape example models are located at:</p>
 <pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
 </pre>
 <h4 id="Run_the_Model">Run the Model</h4>
 <p>Right-click on the model, and select "Execute"! You should see something like this:</p>
 <p><img src="image/EpidemicModelRunning.png" /></p>
 <p>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory.
 The toolbar buttons allow you to control model execution.</p>
 <p><img src="image/EpidemicModelControls.png" /></p>
 <p>From right to left, you can start, restart, pause, step, stop and close a model. You can even run multiple models
 and control them independently. You can also move views around, close them and so on as with any other Eclipse views.
 Here we're running two separate models for comparison.</p>
 <p><img src="image/EpidemicModelComparison.png" /></p>
 <p>If you want to find out more about an agent, show the properties view, and click on agent.</p>
 <p><img src="image/EpidemicModelAgentProperties.png" /></p>
 <p>You can experiment with different parameters (settings) for models by then clicking in the gray area away within
 the view.</p>
 <p><img src="image/EpidemicModelProperties.png" /></p>
 <p>There are a number of other things to play around with, such as zooming the agent view or selecting other chart
 series to display using the Chart Customizer, so just explore. You can always close an active model by clicking on the
 close toolbar button. Or if you can't access the models controls for some reason, you can open the progress view and
 close projects form there.</p>
 <h4 id="Next_Steps">Next Steps</h4>
 <p>Other models are located at: (to do)</p>
 <p>To understand the capabilities of AMF, you might also want to try out running the same models automatically
 generated for Ascape or Repast.</p>
 <pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
 org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
 </pre>
 <h3 id="Classic_Java_ABM_Models">Classic Java ABM Models</h3>
 <p>Many models have been created using Ascape over the years, including all of the classic models created at
 Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've
 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
 Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial
 Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You
 can get the projects in two ways:</p>
 <h4 id="From_Project_Archive">From Project Archive</h4>
 <ul>
 				<li>Download the Escape examples zip from the Ascape sourceforge site: <a
 								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>
 				</li>
 				<li>Unzip the file.</li>
 				<li>Import them into your workspace. For help, see <a
 								href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this
 				page</a>.</li>
 </ul>
 <h4 id="From_SVN">From SVN</h4>
 <ul>
 				<li>Import the SVN projects from the sourceforge SVN. For help, see <a
 								href="/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page"
 								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
 				this page</a>.</li>
 </ul>
 <pre>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
 http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
 </pre>
 <p>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models.
 For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select
 "Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have
 to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</p>
 <h2 id="Developing_Models">Developing Models</h2>
 <p>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write
 programs using it.To develop new models, you can:</p>
 <ol>
 				<li>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.</li>
 				<li>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.</li>
 </ol>
 <p>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</p>
 <h1 id="Reference">Reference</h1>

 <h4 id="Configuration">Configuration</h4>
 <p>Instead of using Ant, Escape has really nice support for parameterizing and testing models. See <a
 				href="/wiki/Experimenting_and_Testing" title="Experimenting and Testing">Experimenting and Testing</a> (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.</p>
 <h2 id="Current_Limitations">Current Limitations</h2>
 <ol>
 				<li>Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as
 				stable for a while as Ascape which has been around for a long time. But we haven't run into any issues recently.</li>
 				<li>Escape graphics performance is generally a little bit slower. But on the other hand you can run
 				multiple models at once and the headless models should perform just as well as console launched Ascape programs. In
 				practice this shouldn't affect your normal model exploration work. Ad you can always speed ahead by using the speed slider!</li>
 </ol>
 </body>
 </html>
	<?xml version='1.0' encoding='utf-8' ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
	<title>Escape</title>
	</head>
	<body>
	<h1 id="Overview">Overview</h1>
	<p>Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based
	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
	very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch
	with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then
	execute those models within the same development environment.</p>
	<p><img src="image/AMPScreenshot.png" /></p>
	<p>A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM
	toolkit -- is to provide an exemplar 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.</p>
	<p>(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.)</p>
	<h1 id="Getting_Started">Getting Started</h1>
	<h3 id="Documentation_and_other_Resources">Documentation and other Resources</h3>
	<p>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation.
	There is complete Javadoc as well as a manual and other web resources. See the <a href="http://ascape.sourceforge.net">Ascape
	Website</a> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape
	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
	well. The <a href="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</a> written by Damon Centola
	should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual
	work under Ascape. (Converting these models is a great opportunity for a community contribution!)</p>
	<h2 id="Installation">Installation</h2>
	<p>Escape is <a href="http://eclipse.org/amp/installing/">installed</a> 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 that 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.</p>
	<h2 id="Exploring_Example_ABM_Models">Exploring Example ABM Models</h2>
	<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
	programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is <a
	href="http://eclipse.org/amp/installing">Install AMP</a>. (You don't need any of the optional components unless you
	want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really
	interesting classic ABM models.</p>
	<h3 id="AMF_Models">AMF Models</h3>
	<p>There are a number of models developed with AMF that can automatically generate example models to run in Escape.
	There are two ways to run the example models:</p>
	<h4 id="Setup_Escape_Projects">Setup Escape Projects</h4>
	<h5 id="Creating_a_New_Escape_Project">Creating a New Escape Project</h5>
	<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(
	"org.eclipse.ui.cheatsheets",
	"org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction",
	"org.eclipse.amp.escape.intro")'>cheatsheet</a>.</p>
	<ol>
	<li>If you're not already there, open the Agent Modeling Perspective. Select Window : Open Perspective :
	Other.. and then Agent Modeling. (Or you can choose Window : Reset Perspective and the Agent Modeling perspective
	should appear in the Open Perspective list itself.)</li>
	<li>Next, let's create the project where we'll place our model. Select File : New : Escape AMF Project. Give it
	a name like "escape.tutorial", then click Finish.</li>
	<li>Finally grab the Epidemic.metaabm model at <a
	href="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</a>
	and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in
	which case just right-click on the link and save it to a file.)</li>
	</ol>
	<h5 id="Using_an_Pre-Built_Example_Project">Using a Pre-Built Example Project</h5>
	<p>If you get really stuck somewhere, you can also get ready made projects from CVS. See <a
	href="http://eclipse.org/amp/developers/repositoryDetails.php">this page</a> for information on CVS setup. The
	project for Escape example models are located at:</p>
	<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
	</pre>
	<h4 id="Run_the_Model">Run the Model</h4>
	<p>Right-click on the model, and select "Execute"! You should see something like this:</p>
	<p><img src="image/EpidemicModelRunning.png" /></p>
	<p>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory.
	The toolbar buttons allow you to control model execution.</p>
	<p><img src="image/EpidemicModelControls.png" /></p>
	<p>From right to left, you can start, restart, pause, step, stop and close a model. You can even run multiple models
	and control them independently. You can also move views around, close them and so on as with any other Eclipse views.
	Here we're running two separate models for comparison.</p>
	<p><img src="image/EpidemicModelComparison.png" /></p>
	<p>If you want to find out more about an agent, show the properties view, and click on agent.</p>
	<p><img src="image/EpidemicModelAgentProperties.png" /></p>
	<p>You can experiment with different parameters (settings) for models by then clicking in the gray area away within
	the view.</p>
	<p><img src="image/EpidemicModelProperties.png" /></p>
	<p>There are a number of other things to play around with, such as zooming the agent view or selecting other chart
	series to display using the Chart Customizer, so just explore. You can always close an active model by clicking on the
	close toolbar button. Or if you can't access the models controls for some reason, you can open the progress view and
	close projects form there.</p>
	<h4 id="Next_Steps">Next Steps</h4>
	<p>Other models are located at: (to do)</p>
	<p>To understand the capabilities of AMF, you might also want to try out running the same models automatically
	generated for Ascape or Repast.</p>
	<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
	org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
	</pre>
	<h3 id="Classic_Java_ABM_Models">Classic Java ABM Models</h3>
	<p>Many models have been created using Ascape over the years, including all of the classic models created at
	Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've
	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
	Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial
	Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You
	can get the projects in two ways:</p>
	<h4 id="From_Project_Archive">From Project Archive</h4>
	<ul>
	<li>Download the Escape examples zip from the Ascape sourceforge site: <a
	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>
	</li>
	<li>Unzip the file.</li>
	<li>Import them into your workspace. For help, see <a
	href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this
	page</a>.</li>
	</ul>
	<h4 id="From_SVN">From SVN</h4>
	<ul>
	<li>Import the SVN projects from the sourceforge SVN. For help, see <a
	href="/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page"
	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
	this page</a>.</li>
	</ul>
	<pre>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
	http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
	</pre>
	<p>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models.
	For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select
	"Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have
	to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</p>
	<h2 id="Developing_Models">Developing Models</h2>
	<p>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write
	programs using it.To develop new models, you can:</p>
	<ol>
	<li>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.</li>
	<li>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.</li>
	</ol>
	<p>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</p>
	<h1 id="Reference">Reference</h1>

	<h4 id="Configuration">Configuration</h4>
	<p>Instead of using Ant, Escape has really nice support for parameterizing and testing models. See <a
	href="/wiki/Experimenting_and_Testing" title="Experimenting and Testing">Experimenting and Testing</a> (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.</p>
	<h2 id="Current_Limitations">Current Limitations</h2>
	<ol>
	<li>Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as
	stable for a while as Ascape which has been around for a long time. But we haven't run into any issues recently.</li>
	<li>Escape graphics performance is generally a little bit slower. But on the other hand you can run
	multiple models at once and the headless models should perform just as well as console launched Ascape programs. In
	practice this shouldn't affect your normal model exploration work. Ad you can always speed ahead by using the speed slider!</li>
	</ol>
	</body>
	</html>