Google Git
Sign in
eclipse / gerrit / amp / org.eclipse.amp / fdd7b114af5d710b6655e8ca562f806df94bed83 / . / amp / documentation / contents / User_Guide.html
blob: 8700053c52308b7463533e51a65656650344abc9 [file] [log] [blame]
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter&nbsp;3.&nbsp;User Guide</title>
<link href="book.css" type="text/css" rel="stylesheet">
<meta content="DocBook XSL Stylesheets V1.76.0" name="generator">
<link rel="home" href="index.html" title="Agent Modeling Guide">
<link rel="up" href="index.html" title="Agent Modeling Guide">
<link rel="prev" href="Modeler_Guide.html" title="Chapter&nbsp;2.&nbsp;Modeler Guide">
<link rel="next" href="Tutorials.html" title="Chapter&nbsp;4.&nbsp;Tutorials">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table summary="Navigation header" width="100%">
<tr>
<th align="center" colspan="3">Chapter&nbsp;3.&nbsp;User Guide</th>
</tr>
<tr>
<td align="left" width="20%"><a accesskey="p" href="Modeler_Guide.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="Tutorials.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div class="chapter" title="Chapter&nbsp;3.&nbsp;User Guide">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="User_Guide"></a>Chapter&nbsp;3.&nbsp;User Guide</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Overview_5">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Modeling">Modeling</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Perspective">Perspective</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Creating_Projects_and_Models">Creating Projects and Models</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Menus.2C_Popups_and_Toolbar">Menus, Popups and Toolbar</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Views">Views</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Editor">Editor</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Default_Views">Default Views</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Diagnostic_Views">Diagnostic Views</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Modeling_Tree_Editor">Modeling Tree Editor</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Opening_the_Editor">Opening the Editor</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Structure_2">Structure</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Actions_3">Actions</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Building">Building</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Building_Models">Building Models</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Generating_Specialized_Model_Artifacts">Generating Specialized Model Artifacts</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Platform_Targets">Platform Targets</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Interfaces">Interfaces</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Skeleton">Skeleton</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Test_Cases">Test Cases</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Text_Documents">Text Documents</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Generate_Key_Graphics">Generate Key Graphics</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Function_Docs">Function Docs</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Executing">Executing</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Launching_a_Model_.28AMF.29">Launching a Model (AMF)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Execute">Execute</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Execute_Headless">Execute Headless</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Execute_Headless_.28Data.29">Execute Headless (Data)</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Executing_a_Model_.28Java_.2F_3D.29">Executing a Model (Java / 3D)</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Controlling_Models">Controlling Models</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Model_Execution_Controls"></a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#The_Active_Model">The Active Model</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Views_2">Views</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Properties_2">Properties</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Agent_Navigator">Agent Navigator</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Model_Manager">Model Manager</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Visualization">Visualization</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#2D_Views">2D Views</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#3D_Views">3D Views</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Graph_Views">Graph Views</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Charts">Charts</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Launching_Other_Targets">Launching Other Targets</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Model_Parameterization">Model Parameterization</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Syntax">Syntax</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Example_2">Example</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="User_Guide.html#Model_Testing">Model Testing</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="User_Guide.html#Syntax_2">Syntax</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Example_3">Example</a></span>
</dt>
<dt>
<span class="section"><a href="User_Guide.html#Model_Data">Model Data</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
</dl>
</div>
<p>In this section of the guide, we'll discuss specific aspects of the Agent Modeling tools and show you how to use them in your day to day agent development activities. We discuss only tools specific to Agent Modeling itself. For more general information about the tools, such as how to customize editors, views, and perspectives, see the
<span class="bold"><strong>Workbench User Guide</strong></span>.
</p>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="Overview_5"></a>Overview</h2>
</div>
</div>
</div>
<p>The Agent Modeling Platform provides two general modes or "perspectives" for working with Agent Models.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/Perspectives.png"></div>
<p>
</p>
<p>
<span class="bold"><strong>Agent Modeling</strong></span> supports all aspects of working with models, including editing models and automatically generating all the of your code and documentation.
<span class="bold"><strong>Agent Execution</strong></span> supports running and exploring those models. A key feature of the Agent Modeling Platform is the ability to execute models within the same environment that they are developed within -- you don't need to launch a separate environment in order to run a model. Agent Execution automatically activates when you launch a model. We'll discuss the agent modeling tools first, and then turn to agent execution.
</p>
</div>
<div class="section" title="Modeling">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="Modeling"></a>Modeling</h2>
</div>
</div>
</div>
<div class="section" title="Perspective">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Perspective"></a>Perspective</h3>
</div>
</div>
</div>
<p>The Provides a custom layout menus and tools specific to working with agent models. Because the agent modeling process also often involves Java and Eclipse Plugin development we include easy access to many of those tools here as well.</p>
</div>
<div class="section" title="Creating Projects and Models">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Creating_Projects_and_Models"></a>Creating Projects and Models</h3>
</div>
</div>
</div>
<p>You can create projects and project components using the Popup menu. Just click in a blank space within the Package Explorer. Any installed project targets are displayed in this menu. For example, if you've installed the Simphony target, you'd see that displayed in this menu as well.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/edit_tutorial/SimpleTutorial3CreateModel.png"></div>
<p>
</p>
</div>
<div class="section" title="Menus, Popups and Toolbar">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Menus.2C_Popups_and_Toolbar"></a>Menus, Popups and Toolbar</h3>
</div>
</div>
</div>
<p>The popup menus and application menus provide access to various model features and are context sensitive. Throughout these screenshots, we've customized the toolbar in order to only show the agent Modeling specific features.</p>
</div>
<div class="section" title="Views">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Views"></a>Views</h3>
</div>
</div>
</div>
<p>By default the workbench includes a number of views. See the Workbench documentation for more details on how they can be customized accessed and used.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/Workbench.png"></div>
<p>
</p>
<div class="section" title="Editor">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Editor"></a>Editor</h4>
</div>
</div>
</div>
<p>This is not technically a view in itself. It is the major focus of the workbench and contains any edit models or other files such as Java source or parameters.</p>
</div>
<div class="section" title="Default Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Default_Views"></a>Default Views</h4>
</div>
</div>
</div>
<p>The default modeling views are visible by default.</p>
<div class="section" title="Package Explorer">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Package_Explorer"></a>Package Explorer</h5>
</div>
</div>
</div>
<p>Supports navigation within projects.</p>
</div>
<div class="section" title="Properties">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Properties"></a>Properties</h5>
</div>
</div>
</div>
<p>The properties allows you to view and edit specific details for the currently selected object. For example, if you select a model context, you'll be able to edit its attributes here.</p>
</div>
<div class="section" title="Outline">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Outline"></a>Outline</h5>
</div>
</div>
</div>
<p>The outline view supports easy navigation within the edited files. See the model editing sections for more on how the outline can be used to assist exploration of Agent Models.</p>
</div>
</div>
<div class="section" title="Diagnostic Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Diagnostic_Views"></a>Diagnostic Views</h4>
</div>
</div>
</div>
<p>There are a number of views that can be used to explore issues that might come up during the modeling process. You can see them on the lower left-hand corner of the screenshot above. Click on one of the icons to view their contents.</p>
<div class="section" title="Problems">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Problems"></a>Problems</h5>
</div>
</div>
</div>
<p>This view is one that you'll become very familiar with. It is used to display specific about problems with any of the artifacts (files) in your modeling project. If you see a red or yellow marker on a file, opening the view will present a list of the issues that are currently being reported. For a usage example, please see the Tutorial.</p>
</div>
<div class="section" title="Console">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Console"></a>Console</h5>
</div>
</div>
</div>
<p>This view displays text (console) output for appropriate processes. For example, if you launch an Ascape project, this will display any output that would go to the Java console.</p>
</div>
<div class="section" title="Errors">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Errors"></a>Errors</h5>
</div>
</div>
</div>
<p>This is another view that you will find valuable in your day to day modeling activities. The error log lists everything important that happens during model execution. It's the first place to look if something mysterious goes wrong, and when you report problems it's always helpful to include anything that could be relevant in the log. Despite its name, the Errors view is not just for reporting errors -- it is also used to report progress on normal operations. For example, when models are automatically generated that is reported to the log, as we can see in the following example:</p>
</div>
</div>
</div>
<div class="section" title="Modeling Tree Editor">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Modeling_Tree_Editor"></a>Modeling Tree Editor</h3>
</div>
</div>
</div>
<p>The Eclipse Agent Modeling Framework includes a full-featured model editor based on the Eclipse Modeling Framework's Edit tools. All aspects of an AMF model can be managed from within this tool. Note that the tree editor is only one of many ways of editing a model. Other editors of AMF models include textual languages and custom editors that are part of commercial offerings.</p>
<div class="section" title="Opening the Editor">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Opening_the_Editor"></a>Opening the Editor</h4>
</div>
</div>
</div>
<p>To open a model in the editor, simply double-click on it. If the model doesn't open in the model editor (if for example it had been previously opened using another editor), you can always access the editor using
<span class="bold"><strong>Open With &gt; Other...</strong></span> and selecting "MetaABM Editor". The editor has two pages, an Editor page that we'll focus on first and a "description" page that we'll discuss at the end of this section.
</p>
</div>
<div class="section" title="Structure">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Structure_2"></a>Structure</h4>
</div>
</div>
</div>
<p>The model is composed of nodes representing specific model entities such as agents, actions and spaces. For details about any of these entities, see the Concepts section.</p>
<div class="section" title="Opening Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Opening_Components"></a>Opening Components</h5>
</div>
</div>
</div>
<p>After opening a model, you can see the contents by clicking the Triangle symbol to the left of an item. For example, opening the root context node, we see:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/Editor.png"></div>
<p>
</p>
</div>
<div class="section" title="Creating Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Creating_Components"></a>Creating Components</h5>
</div>
</div>
</div>
<p>You add nodes by right-clicking on a node, like so:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorAdd.png"></div>
<p>
</p>
</div>
<div class="section" title="Editing Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Editing_Components"></a>Editing Components</h5>
</div>
</div>
</div>
<p>To edit components, select the node you want to modify. The
<span class="bold"><strong>Properties View</strong></span> will be updated with the agent details. Use the properties view to modify the values. In the screenshot below, we're editing the values for the City space.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorEditing.png"></div>
<p>
</p>
</div>
<div class="section" title="Moving Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Moving_Components"></a>Moving Components</h5>
</div>
</div>
</div>
<p>You can often rearrange model components by dragging them from one place to another. In the following example, we're creating a model of a regional epidemic by creating a City sub-context and moving the agent into it: </p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorMoving.png"></div>
<p>
</p>
</div>
<div class="section" title="Removing Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Removing_Components"></a>Removing Components</h5>
</div>
</div>
</div>
<p>You can remove actions by deleting or cutting them using the popup menu. When you delete an entity, all of its children are deleted as well, except in some special cases (such as with actions) where other paths to that entity still exist.</p>
</div>
<div class="section" title="Copying Components">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Copying_Components"></a>Copying Components</h5>
</div>
</div>
</div>
<p>To make a copy of an entity and place it in a new location, option-drag the entity to the destination. You can make a copy in the existing location by dragging it into the same parent. The name will automatically be updated with "copy" appended to it.</p>
</div>
<div class="section" title="Editing Attributes">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Editing_Attributes"></a>Editing Attributes</h5>
</div>
</div>
</div>
<p>The attributes node -- along with the actions and styles nodes -- represents a group of components rather than an entity itself. It contains all of the attributes for the parent agent or context. In the examples below, we can see the attributes for the Epidemic route model. Note that the top level attributes in a root context act as the parameters for the model itself.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorAttributes.png"></div>
<p>
</p>
</div>
<div class="section" title="Editing Styles">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Editing_Styles"></a>Editing Styles</h5>
</div>
</div>
</div>
<p>The Styles node is another group node, in this case representing a set of styles that can be used to visualize the agents. When creating a style, you will need to create a Rule for each style as well, like so:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorStyles.png"></div>
<p>
</p>
</div>
</div>
<div class="section" title="Actions">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Actions_3"></a>Actions</h4>
</div>
</div>
</div>
<p>Actions are a key and relatively complex aspect of the model editor. Because actions are actually related in a graph structure, a tree-based editor will not be able to represent a the underlying structure of action relationships directly. (This is actually no different from most development environments -- for example, Java code is edited in a text based editor, but the call structure represents a complex graph. Advance tools developed by AMP contributors do support more sophisticated methods for action browsing and we'll have simple versions of them available in future releases of the AMF edit tools.) Therefore, it's helpful to take time to understand how action relationships appear in the editor.</p>
<p>Like attributes and styles, every agent has a single Actions nodes which contains its Root Action(s).</p>
<div class="section" title="Creating Actions">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Creating_Actions"></a>Creating Actions</h5>
</div>
</div>
</div>
<p>You create actions as with any other component, by right-clicking on the source action and choosing the new action. The menu is organized by usage.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EditorActionMenu.png"></div>
<p>
</p>
</div>
<div class="section" title="Editing Actions">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Editing_Actions"></a>Editing Actions</h5>
</div>
</div>
</div>
<p>Actions and their inputs are edited just like any other model component. Click on the action or input you want to edit and then make changes to it in the properties editor.</p>
</div>
<div class="section" title="Order">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Order"></a>Order</h5>
</div>
</div>
</div>
<p>Generally, action sources will appear above their targets. In the case where there is only one source for a given target, and that target has no other sources, they will appear directly above one another. Its important to note however that
<span class="italic">the order of the nodes does not indicate a specific source and target relationship</span>. For example, in the case where there are multiple targets for a source, they will typically follow that source immediately. To make the relationships clear, every action lists its source actions as part of the action label. Agent selections also appear as part of the label.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/ActionsExample.png"></div>
<p>
</p>
<p>In the above example, the Initialize Location "Initialize Action" is straightforward. We simply define a Select Action, a Query Action target for that selection, and then a Move Action target for the query. The "Transmission" Rule is more complicated. Note for example that the "Infectious" Union Action is the target of both the "Asymptomatic Infectious" and "Symptomatic Infectious" Query Actions. The "Vulnerable Neighbor" action has the label "Vulnerable Neighbor [Potential Exposure] &lt;- [Potential Exposure]" indicating that the "Potential Exposure" action serves as its selection as well as its source.</p>
</div>
<div class="section" title="Initial Order">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Initial_Order"></a>Initial Order</h5>
</div>
</div>
</div>
<p>A new action's initial target will be the action that you clicked on when creating it. For an action that should always act within a given root action (i.e. Rule, Schedule, etc..), add it to the root action. A root action can have more than one target.</p>
</div>
<div class="section" title="Changing Sources and Targets (Reordering)">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Changing_Sources_and_Targets_.28Reordering.29"></a>Changing Sources and Targets (Reordering)</h5>
</div>
</div>
</div>
<p>An action's target can be changed by dragging it over the new target action. Note that this is a different behavior from that of standard entity movement. You cannot make an action a target of an action that is itself a source of the modified action! (See the concepts section for why.) Using the default tree editor you cannot change an action's targets directly; instead select the action's target and move that. </p>
</div>
<div class="section" title="Adding Sources and Targets">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Adding_Sources_and_Targets"></a>Adding Sources and Targets</h5>
</div>
</div>
</div>
<p>As discussed earlier, actions often have multiple sources and targets. To make an action the target of an additional action, click on target action, hold down the control key, and drag the action to its new destination. See the tutorial for a complete example.</p>
</div>
<div class="section" title="Removing Sources and Targets">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Removing_Sources_and_Targets"></a>Removing Sources and Targets</h5>
</div>
</div>
</div>
<p>You cannot remove single sources from targets directly using the tree editor. Instead, first drag the agent to a source nodes that will be part of its changed set of sources. That will remove all existing actions sources but for the one you have just dragged it to. Then add back any of the other source and target nodes you wish to retain.</p>
</div>
<div class="section" title="Removing Actions">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Removing_Actions"></a>Removing Actions</h5>
</div>
</div>
</div>
<p>You can remove actions in the same way as with structural model components. Note that just as when you delete an agent, all of that agent's attributes, actions and styles are also deleted form the model, when you delete an Action, any of its targets will also be removed, unless there is some other source action path that connects it to the root action. And of course, any targets of such targets will be affected in the same way and so on. If you remove a node from high in the action tree a lot of nodes could disappear at once! If you have actions that you want to retain as part of the flow, you should first make them targets of a new action before deleting their parent action.</p>
</div>
<div class="section" title="Copying Actions">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Copying_Actions"></a>Copying Actions</h5>
</div>
</div>
</div>
<p>Copying actions works just as with other entities, and copies will become targets of their option-drag destination. </p>
</div>
<div class="section" title="Query and Evaluation Inputs">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Query_and_Evaluation_Inputs_2"></a>Query and Evaluation Inputs</h5>
</div>
</div>
</div>
<p>The number of inputs is determined by the selected functions. (In rare cases where a function can take an arbitrary number of arguments you may need to create additional values or delete existing ones.) In the following example, we're picking the Symptom Infectious status for a query that will affect the potentially exposed agents. Note that is instead you wanted to compare another kind of value -- for example an Integer value -- you would need to change the first input listed before changing the second input so that you will be able to get the appropriate options for the second.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/Inputs.png"></div>
<p>
</p>
</div>
<div class="section" title="Input Literals">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Input_Literals_2"></a>Input Literals</h5>
</div>
</div>
</div>
<p>To create an input value, right click on the input and select
<span class="bold"><strong>Create Member &gt; Literal</strong></span>. Then specify the actual value in the Value property in the
<span class="bold"><strong>Properties View</strong></span>.
</p>
</div>
</div>
</div>
</div>
<div class="section" title="Building">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="Building"></a>Building</h2>
</div>
</div>
</div>
<div class="section" title="Building Models">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Building_Models"></a>Building Models</h3>
</div>
</div>
</div>
<p>If you've used other development environments, you're probably used to a separate build step. For example, if you edit a set of Java files, you might invoke a compile command. Eclipse and the Agent Modeling Platform support automatic building. This means that in order to build your code, you simply save the model and the environment takes care of the rest. What gets built is defined by the project. For example, if you save a model that is contained within an Agent Modeling Escape Project, the following steps occur automatically:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>The Escape builder generates Java code for the Escape API, including support for specialized graphics and (if enabled) 3D visualization.</p>
</li>
<li class="listitem">
<p>The Documentation builder generates custom html documentation for the model.</p>
</li>
<li class="listitem">
<p>The Java builder takes the Java code generated above and compiles it.</p>
</li>
<li class="listitem">
<p>The Manifest and Schema builders package the project for use as part of the Eclipse plugin environment.</p>
</li>
</ol>
</div>
<p>So what do you do if you want to generate code for a different target, such as Repast? Here, you simply create another project and drag the model into it. You can also edit the builders for a given project (see the Workbench Documentation) but you'll only want to do that if you're making permanent changes to the project itself.</p>
</div>
<div class="section" title="Generating Specialized Model Artifacts">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Generating_Specialized_Model_Artifacts"></a>Generating Specialized Model Artifacts</h3>
</div>
</div>
</div>
<p>You can also manually generate code for models. This is useful if you want to create code for a model in a non target project and don't want the automatic build capabilities. There are also specialized targets that can be generated manually that are bundled with the tools -- AMP plugin developers can easily add custom generation targets for this menu. To generate custom artifacts, right-click on a model and select
<span class="bold"><strong>Generate</strong></span>.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/GenerateMenu.png"></div>
<p>
</p>
<p>Targets include:</p>
<div class="section" title="Platform Targets">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Platform_Targets"></a>Platform Targets</h4>
</div>
</div>
</div>
<p>Creates code for one of the installed targets, such as Ascape, Escape, and Simphony. (Again, these generators are unnecessary for projects that already have target specific builders configured.)</p>
</div>
<div class="section" title="Interfaces">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Interfaces"></a>Interfaces</h4>
</div>
</div>
</div>
<p>Creates a complete set of interfaces for the model classes. These can be very useful for development and integration in enterprise environments. Generated classes are placed in the src directory with "I" added to the name. For example, if you generate interfaces for a model with an "Individual" agent, this target will create an "IIndividual" interface that includes getters, setters and methods for all of the agent's attributes and actions.</p>
</div>
<div class="section" title="Skeleton">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Skeleton"></a>Skeleton</h4>
</div>
</div>
</div>
<p>Creates a base class for the model. This is essentially a complete implementation, but without the action implementations. Again, these classes can be useful when generating code for use in enterprise and other specialized environments.</p>
</div>
<div class="section" title="Test Cases">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Test_Cases"></a>Test Cases</h4>
</div>
</div>
</div>
<p>Generates base support (needing customization) test cases for use in JUnit tests.</p>
</div>
<div class="section" title="Text Documents">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Text_Documents"></a>Text Documents</h4>
</div>
</div>
</div>
<p>Creates simple text documentation for use in other documents.</p>
</div>
<div class="section" title="Generate Key Graphics">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Generate_Key_Graphics"></a>Generate Key Graphics</h4>
</div>
</div>
</div>
<p>This specialized target supports the creation of graphic keys for the model. To use this target:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>Generate the code.</p>
</li>
<li class="listitem">
<p>Add a dependency to the Manifest for "org.eclipse.amp.amf.gen.extras".</p>
</li>
<li class="listitem">
<p>In the srcutil directory find the Java source code for the calss {RootContext}GraphicsWriter. For example, for the Epidemic model, this would be srcutil/name.milesparker.epi/EpidemicGraphicsWriter.java.</p>
</li>
<li class="listitem">
<p>Right-click, and select
<span class="bold"><strong>Run As &gt; Java Application</strong></span>.
</p>
</li>
<li class="listitem">
<p>Refresh the project by right-clicking on it and selecting
<span class="bold"><strong>Refresh</strong></span>.
</p>
</li>
<li class="listitem">
<p>The Doc directory will now contain a number of new files, including</p>
<div class="orderedlist">
<ol class="orderedlist" type="a">
<li class="listitem">
<p>{RootContext}Key.png</p>
</li>
<li class="listitem">
<p>{RootContext}GraphicsKey.html</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
<p>Both files contain graphic representations of the model using the definitions defined by the model styles, very useful artifacts for inclusion in papers and web pages describing your model. For example, here is the EpidemicKey.png:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/tools/EpidemicKey.png"></div>
<p>
</p>
</div>
<div class="section" title="Function Docs">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Function_Docs"></a>Function Docs</h4>
</div>
</div>
</div>
<p>Generates WikiText documentation for function libraries. We use it to create the function documentation in this guide!</p>
</div>
</div>
</div>
<div class="section" title="Executing">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="Executing"></a>Executing</h2>
</div>
</div>
</div>
<div class="section" title="Launching a Model (AMF)">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Launching_a_Model_.28AMF.29"></a>Launching a Model (AMF)</h3>
</div>
</div>
</div>
<table id="N10D13">
<tr>
<td>Launching AMF and Escape models is easy. When an AMF file is selected -- in any of the perspectives -- the toolbar and Application menus are updated to reflect the file you've selected and provide convenient access to other functions. For example, when we click on a metaabm file in the package explorer, model execution buttons appear in the toolbar.</td>
<td>
<div class="mediaobject">
<img src="images/tools/EditorToolbar.png"></div>
</td>
</tr>
<tr>
<td>If you right-click on a file a pop-up menu appears like the one to the far right -- in this case we're selecting the "Execute Headless" option. To launch a model, just select one of the options. (Note that the execution framework doesn't know whether your code exists in an Escape project or another target project. If you attempt to execute a .metaabm model in an Ascape project for example, you will get an error.)</td>
<td>
<div class="mediaobject">
<img src="images/tools/EditorMenu.png"></div>
</td>
</tr>
</table>
<p>One a model has been launched, the Agent Execution Perspective automatically becomes active. The Provides a custom layout menus and tools specific to executing agent models.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicExecNew.png"></div>
<p>
</p>
<p>The execution options are:</p>
<div class="section" title="Execute">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Execute"></a>Execute</h4>
</div>
</div>
</div>
<p>Launches the model using default graphics, opening the Agent Execution perspective.</p>
</div>
<div class="section" title="Execute Headless">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Execute_Headless"></a>Execute Headless</h4>
</div>
</div>
</div>
<p>Launches the model without graphics, opening the Agent Execution perspective.</p>
</div>
<div class="section" title="Execute Headless (Data)">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Execute_Headless_.28Data.29"></a>Execute Headless (Data)</h4>
</div>
</div>
</div>
<p>Launches the model with an observer that collects data into the AMF adata model representation.</p>
</div>
</div>
<div class="section" title="Executing a Model (Java / 3D)">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Executing_a_Model_.28Java_.2F_3D.29"></a>Executing a Model (Java / 3D)</h3>
</div>
</div>
</div>
<p>You can execute any Escape model directly from its Java file by right-clicking on it. This is used for models that have been written directly in Java, or that you have created or that have been automatically generated, such as the 3D versions of AMF models. In order for the model to launch correctly, it must have as a superclass the Escape "Scape" class. In the following screenshot, we've launched a 3D version of the Epidemic model. The 3D models are automatically generated for all .metaabm models. You can also launch a model into 3D by clicking on the model file and clicking the second (Execute Model with 3D) execute button.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/Epidemic3D.png"></div>
<p>
</p>
</div>
<div class="section" title="Controlling Models">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Controlling_Models"></a>Controlling Models</h3>
</div>
</div>
</div>
<p>Once a model has been launched, the toolbar buttons allow you to control model execution.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/ExecControl.png"></div>
<p>
</p>
<div class="section">
<div class="titlepage"></div>
<div class="section" title="Model Execution Controls">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="N10D6F"></a>Model Execution Controls</h5>
</div>
</div>
</div>
<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>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicModelComparison.png"></div>
<p>
</p>
</div>
<div class="section" title="Speed Slider">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Speed_Slider"></a>Speed Slider</h5>
</div>
</div>
</div>
<p>A special feature of the modeling tools is the "Speed Slider". This allows you to dynamically "speed up" and "slow down" the model execution. You can see where you've set the current speed in the status bar in the lower left hand corner of the environment.</p>
<p>Actually, you're not controlling the speed of model
<span class="italic">execution</span> at all. Agent models are almost always constrained not by the time of model execution -- a typical model can execute many thousands of iterations a second -- but by the time it takes to draw visualizations. By updating the views less frequently we allow the model to run at full speed until the next visualization period. This gives the illusion that we're speeding up the model. When we slow the model down, we're inserting a wait period between each model iteration.
</p>
<p>To increase model execution speed, move the slider to the right. Here we're only updating the model every 56 iterations.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/SliderRight.png"></div>
<p>
</p>
<p>To decrease speed, move the slider to the left. Here, we're pausing between each iteration for 1.65 seconds.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/SliderLeft.png"></div>
<p>
</p>
</div>
</div>
<div class="section" title="The Active Model">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="The_Active_Model"></a>The Active Model</h4>
</div>
</div>
</div>
<p>An important concept in the execution workbench is the "active model". The active model is the model that is controlled by the toolbar buttons. As discussed, the Escape environment supports more than one running model at any given time. The active model is the current "focused" or front-most model, there can be only one active model at any given time and whenever any models are running one of them will be active. To make a model become the active model, you simply select a view of that model or select the model in the model manager (see below). When a model is closed, another model is automatically activated.</p>
</div>
</div>
<div class="section" title="Views">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Views_2"></a>Views</h3>
</div>
</div>
</div>
<p>There are many views specific to the Agent Execution environment that will enable you to explore and control running models.</p>
<div class="section" title="Properties">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Properties_2"></a>Properties</h4>
</div>
</div>
</div>
<p>If you want to find out more about an agent, show the properties view, and click on agent in the 2D view or any other views that support agent selection such as the tree view.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicModelAgentProperties.png"></div>
<p>
</p>
<p>You can experiment with different parameters (settings) for models by then clicking on the model in the Model Manager or by selecting a general mode area such as the gray area enclosing the 2D view.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicModelProperties.png"></div>
<p>
</p>
</div>
<div class="section" title="Agent Navigator">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Agent_Navigator"></a>Agent Navigator</h4>
</div>
</div>
</div>
<p>The
<span class="bold"><strong>Agent Navigator</strong></span> allows you to select agents from a tree view. The agent selection is coordinated across views so that for example when you select an agent in the navigator it is also selected in the 2D view. In the following screenshot you can see an agent selected in both views as well as the properties editor.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/AgentNavigator.png"></div>
<p>
</p>
</div>
<div class="section" title="Model Manager">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Model_Manager"></a>Model Manager</h4>
</div>
</div>
</div>
<p>The
<span class="bold"><strong>'Model Manager</strong></span>' allows you to examine and control the status of all running models. In the following screenshot, we've launched four separate models so that we can compare the typical model state at different periods.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/ModelManager.png"></div>
<p>
</p>
<p>The manager shows that two of the models are running and two are paused. By opening the model node, we can see the views that are currently being displayed. Note that we mean something different by "Views" in this context. Here "Views" are any thing that is monitoring the state of a running model. A view may not have a graphical component at all.</p>
<p>You can make any model the current active model by clicking on its node in this view.</p>
<div class="section" title="&quot;About this Model&quot;">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name=".22About_this_Model.22"></a>"About this Model"</h5>
</div>
</div>
</div>
<p>The
<span class="bold"><strong>'About this Model</strong></span>' view displays information about a (AMF or Java based) model if it has been provided by the developer. In order to appear in this dialog, create a file named "About[MyModel].html" where "MyModel" is the model's Scape Class Name (not the AMF model file name). The file should be placed in a "res" source folder in the model project directory in a parallel directory path to the root scape's Java class package. For example, an about file for a model defined by the scape "edu.brook.norms.Norms" should be placed at "res/edu/brook/norms/AboutNorms.html". The file should be an html fragment -- that is, without body and head tags -- and can include any valid html tags, including links.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/AboutView.png"></div>
<p>
</p>
</div>
</div>
</div>
<div class="section" title="Visualization">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Visualization"></a>Visualization</h3>
</div>
</div>
</div>
<p>The Agent Modeling Environment is designed to support many kinds of 2D or 3D visualization. AMP includes the following views for generated models. The Escape API supports a number of additional visualization to support Ascape models that aren't shown here. Look at the example org.ascape.escape.models.examples and org.ascape.escape.models.brook for examples of those.</p>
<div class="section" title="2D Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="2D_Views"></a>2D Views</h4>
</div>
</div>
</div>
<p>The
<span class="bold"><strong>Graphic 2D</strong></span> view is the most common view way to work with an Agent Model and is automatically generated and displayed for executing models.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/Epidemic2DView.png"></div>
<p>
</p>
<p>There are a number of view widgets in the upper-right hand corner that you can use to modify the view. You can:</p>
<div class="section" title="Scaling">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Scaling"></a>Scaling</h5>
</div>
</div>
</div>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>Enter or select a specific scale in the combo menu.</p>
</li>
<li class="listitem">
<p>Select a button to have the model scale either:</p>
<div class="orderedlist">
<ol class="orderedlist" type="a">
<li class="listitem">
<p>Freely</p>
</li>
<li class="listitem">
<p>Within the bounds of the view</p>
</li>
<li class="listitem">
<p>Within the vertical bounds of the view</p>
</li>
<li class="listitem">
<p>Within the horizontal bounds of the view</p>
</li>
</ol>
</div>
</li>
<li class="listitem">
<p>Zoom In</p>
</li>
<li class="listitem">
<p>Zoom Out</p>
</li>
</ol>
</div>
</div>
</div>
<div class="section" title="3D Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="3D_Views"></a>3D Views</h4>
</div>
</div>
</div>
<p>The 3D views provide a three-dimensional representation of a running model. Currently they support 2D models only, which makes them 2 1/2 D views.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/View3D.png"></div>
<p>
</p>
<p>You can navigate and customize the model with the following controls:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/View3DMenuBar.png"></div>
<p>
</p>
<p>From left to right, they are:</p>
<div class="section" title="Animation">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Animation"></a>Animation</h5>
</div>
</div>
</div>
<p>Turns on and off the interpolated (smooth) movement of agents from one cell to another. This is a unique feature of AMP and provides a very nice visualization, but it does slow down model execution. For very large models, you can switch it off -- visualization will be "jerky" but much quicker.</p>
</div>
<div class="section" title="Perspectives">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Perspectives"></a>Perspectives</h5>
</div>
</div>
</div>
<p>The three perspectives are used to control the camera location -- in other words the perspective from which the movie is being made. Note that if the camera is currently moving to a given perspective and you select a new perspective the camera may become confused! It is best to wait until the camera comes to a stop before choosing a different perspective. You can speed up camera movement by pausing the model temporarily.</p>
<div class="section" title="First Person">
<div class="titlepage">
<div>
<div>
<h6 class="title">
<a name="First_Person"></a>First Person</h6>
</div>
</div>
</div>
<p>Moves the point of view to ground level, as if the observer were in the space itself.</p>
</div>
<div class="section" title="Overhead">
<div class="titlepage">
<div>
<div>
<h6 class="title">
<a name="Overhead"></a>Overhead</h6>
</div>
</div>
</div>
<p>Moves the point of view to overhead, giving a similar view as you have with the 2D view. Note that in many cases the 3D view is actually faster than the 2D view, so this is a good way to observe any kind of 2D model.</p>
</div>
<div class="section" title="Helicopter">
<div class="titlepage">
<div>
<div>
<h6 class="title">
<a name="Helicopter"></a>Helicopter</h6>
</div>
</div>
</div>
<p>Moves the point to an oblique perspective. This is useful for getting an overall sense of model behavior.</p>
</div>
</div>
</div>
<div class="section" title="Graph Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Graph_Views"></a>Graph Views</h4>
</div>
</div>
</div>
<p>Graph views allow you to undestand the network relationships between various agents in the model. By default, a graph is creaed for all relationships, but you can customize that behavior programmatically. Graphs are also super-imposed on 2D models, as we can see in the following example running the EpidemicContact model.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/ViewGraph.png"></div>
<p>
</p>
<p>Note that complex models can take a long time to visualize and we'll be looking for opportuntites to optimize performance further in the future. If you think the visualization is stuck it is likely that it is simply calculating the next visualization step -- wait a bit before canceling the model or closing it.</p>
<p>Graph views can be customized with the following controls:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/View3DMenuBar.png"></div>
<p>
</p>
<p>From left to right, they are:</p>
<div class="section" title="Layout">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Layout"></a>Layout</h5>
</div>
</div>
</div>
<p>The layout buttons control how the nodes are placed within the graph. You can swithc between layout dynamically to gain insight into network relationships.</p>
<table id="N10E83">
<tr>
<td>
<div class="mediaobject">
<img src="images/execution/ViewGraphDown.png"></div>
</td>
<td>
<div class="mediaobject">
<img src="images/execution/ViewGraphRight.png"></div>
</td>
</tr>
<tr>
<td>
<span class="bold"><strong>Tree (Down):</strong></span> Places the graph nodes into a downward oriented tree formation. You'll find that the tree views are more effecient at visualizing, and can be very ood at representing models with an inherent hierarchical structure such as kinship diagrams, but don't always give the best insight into the model for complex network relations.
</td>
<td>
<span class="bold"><strong>Tree (Right):</strong></span> The same tree layout oriented from the root-most nodes rightward.
</td>
</tr>
<tr>
<td>
<div class="mediaobject">
<img src="images/execution/ViewGraphRadial.png"></div>
</td>
<td>
<div class="mediaobject">
<img src="images/execution/ViewGraphSpring.png"></div>
</td>
</tr>
<tr>
<td>
<span class="bold"><strong>Radial:</strong></span> Places the nodes in a radial layout with the root-most nodes at the center. This is a great way to represent semi-hierarchical models with complex structure, but is a little slower than the tree layouts.
</td>
<td>
<span class="bold"><strong>Spring:</strong></span> This layout uses a spring and strain approach that allows nodes to find their own location within the visualization. It can provide beautiful and insightful diagrams, but it is also slower than the other layouts. For more complex models it often works well to use the radial layout and then switch to the Spring layout when examining relationships in depth.
</td>
</tr>
</table>
</div>
<div class="section" title="Spring Layout Customization">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Spring_Layout_Customization"></a>Spring Layout Customization</h5>
</div>
</div>
</div>
<p>You can customize how the Spring by clicking on the customization button. This allows you to change a number of values that determine how nodes are layed out. While the default settings work well with many graph structures it can be helpful (and fun) to play with different settings to get the best visualization.
|
</p>
<div class="mediaobject">
<img src="images/execution/ViewGraphSpringDialog.png"></div>
<p>
</p>
</div>
</div>
<div class="section" title="Charts">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Charts"></a>Charts</h4>
</div>
</div>
</div>
<p>A
<span class="bold"><strong>Chart</strong></span> view is automatically created and displayed for executing models. It can display aggregate values for any of the agent attributes you have set the "gather data" value to true for. Charts can be easily modified. While the built-in view is not meant to be the sole tool for Escape model data analysis, it provides an easy to use and powerful way to explore models interactively. The Chart view widgets allow you to modify the chart with the click of a button.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicChartOptions.png"></div>
<p>
</p>
<div class="section" title="Chart Type">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Chart_Type"></a>Chart Type</h5>
</div>
</div>
</div>
<p>Several chart types are supported: The line, area, bar and pie chart. Click on one of the icons to select that type.</p>
<table id="N10EFA">
<tr>
<td>
<div class="mediaobject">
<img src="images/execution/LineChart.png"></div>
</td>
<td>
<div class="mediaobject">
<img src="images/execution/AreaChart.png"></div>
</td>
</tr>
<tr>
<td>
<span class="bold"><strong>Line</strong></span>
</td>
<td>
<span class="bold"><strong>Area</strong></span>
</td>
</tr>
<tr>
<td>
<div class="mediaobject">
<img src="images/execution/BarChart.png"></div>
</td>
<td>
<div class="mediaobject">
<img src="images/execution/PieChart.png"></div>
</td>
</tr>
<tr>
<td>
<span class="bold"><strong>Bar</strong></span>
</td>
<td>
<span class="bold"><strong>Pie</strong></span>
</td>
</tr>
</table>
</div>
<div class="section" title="Chart Legend">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Chart_Legend"></a>Chart Legend</h5>
</div>
</div>
</div>
<p>Turn the legend on and off by selecting the "T" icon.</p>
</div>
<div class="section" title="Chart Data">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="Chart_Data"></a>Chart Data</h5>
</div>
</div>
</div>
<p>To select the statistics to display, show the
<span class="bold"><strong>Chart Customizer</strong></span> view. When the customizer has been selected, select a chart to customize. The customizer presents the possible choices in a 2D format. On one axis are the attributes that have data being collected, and on the other are the measurements collected on those axes, i.e. Count, Minimum, Maximum, Variance, Standard Deviation, Sum and Average. To clear all selections, click the Gray "X" button.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicChartCustomize.png"></div>
<p>
</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>
</div>
</div>
</div>
<div class="section" title="Launching Other Targets">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Launching_Other_Targets"></a>Launching Other Targets</h3>
</div>
</div>
</div>
<p>To execute applications for other targets such as Ascape or Simphony, just right-click on the metaabm model, select Run As.. and pick the target you want to launch. In the example below, we're launching Ascape from within an ..ascape project.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/LaunchAscape.png"></div>
<p>
</p>
<p>The external tool you've selected will then open into a separate Java application.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/AscapeRunning.png"></div>
<p>
</p>
<p>
<span class="italic">Note:</span> remember that the menu options are active regardless of whether the target is actually supported within a given project. If you attempt to Run (external targets) or Execute (internal targets) models from a project that does not support that target you will get an error!
</p>
</div>
<div class="section" title="Model Parameterization">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Model_Parameterization"></a>Model Parameterization</h3>
</div>
</div>
</div>
<p>Escape provides full support for parameterization of models. This allows you to create many sets of parameters for a given model, allowing you to decouple model runtime settings from the model itself. (Support for parameter sweeps is forthcoming.) To create a new parameterization, right-click in the location you want to create the parameter file, and select
<span class="bold"><strong>New &gt; Parameters File</strong></span>.
</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/Create.png"></div>
<p>
</p>
<p>In the wizard that follows, give your parameter file a name:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/Wizard.png"></div>
<p>
</p>
<p>The edit the file. See below for file syntax. The parameter editor has built-in support for code-completion, syntax high-lighting and other editor features.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/Edit.png"></div>
<p>
</p>
<p>In the example below, we've created two separate parameter files for the epidemic model with different values for contact transmission probability.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/Example.png"></div>
<p>
</p>
<p>As with other runnable files, you can launch a parameter file simply by selecting execute in the popup menu, application menu or toolbar.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/Execute.png"></div>
<p>
</p>
<div class="section" title="Syntax">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Syntax"></a>Syntax</h4>
</div>
</div>
</div>
<p>Parameter files are quite simple. Every parameter file specifies the "model" that will be executed.The "incorporates" keyword supports including parameter values from other files. File locations are relative to the location of the parameter file, but it is usually more flexible to refer to model files relative to their project location. You can do that by inserting a "|" character at the beginning of the file name.</p>
<p>Attribute values are specified by the attribute ID (with the first character in upper-case) followed by "=" and the desired value.</p>
</div>
<div class="section" title="Example">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Example_2"></a>Example</h4>
</div>
</div>
</div>
<p>We can create a base parameters file called "EpiBase.apar".</p>
<div class="literallayout">
<p>model&nbsp;"|Epidemic.metaabm"<br>
StopPeriod=500<br>
</p>
</div>
<p>This means that we expect the Epidemic.metaabm model to be at the root of the project, and we want the model to stop at period 500. Then -- in this overly simple example -- we could create two other files, EpiHighTransmission.apar:</p>
<div class="literallayout">
<p>model&nbsp;"|Epidemic.metaabm"<br>
incorporates&nbsp;"EpiBase.apar"<br>
MinContactTransmissionProbability=0.05<br>
MaxContactTransmissionProbability=0.2<br>
</p>
</div>
<p>and EpiLowTransmission.apar:</p>
<div class="literallayout">
<p>model&nbsp;"|Epidemic.metaabm"<br>
incorporates&nbsp;"EpiBase.apar"<br>
MinContactTransmissionProbability=0.0<br>
MaxContactTransmissionProbability=0.15<br>
</p>
</div>
<p>Both of which reference the base set of parameters we've just defined and add run specific variables. Note that the incorporates reference is a parameter file relative reference so that we can easily move the set of parameter files to any location we want. With these two files defined we can click on both of them at once, select the Execute button and immediately compare the two values. (Not shown.)</p>
</div>
</div>
<div class="section" title="Model Testing">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Model_Testing"></a>Model Testing</h3>
</div>
</div>
</div>
<p>One of the most important and over-looked aspects of modeling is verification. Very loosely speaking, model
<span class="italic">validation</span> is the process of determining whether a model matches up to the "real world". Model
<span class="italic">verification</span> is the process of determining whether your model specification matches up to the model you've actually implemented. In other words, does the model do what you say it does?
</p>
<p>To help you answer this important question, the modeling tools include unique support for an approach to validation and verification called "unit testing". A thorough discussion is far beyond the scope of this manual, but this guide should give you enough information to get testing your own models. Testing might seem tedious ut its actually a real time saver, because you can quickly run a set of tests to ensure that you a new model change hasn't broken existing functionality. This peace of mind is priceless, and once you start testing, you won't know how you lived without it!</p>
<p>To create a new test, right-click at the location you want to put the test files. (Not shown.) Then we can edit the test file using the syntax shown below. It's helpful to keep them organized in sets of folders. To execute a test or set of tests, simply select the test files and click "Test Once" or "Test 5 times" to run a set of identical tests. The latter is useful for stochastic tests in which tests may create significantly different results for the same random seeds. (We'll provide more options in a future release.) If you select an entire folder, the framework will run all of the tests in the folder. This process is very similar to that for parameter files, so we won't show it here.</p>
<p>Once a test is complete, an "ares" file is created in the "test-results" folder. To see how your tests faired, open the .ares file. For the example test file below, we should see something like this:</p>
<p>
</p>
<div class="mediaobject">
<img src="images/params/TestResults.png"></div>
<p>
</p>
<p>Notice that we can view the expected values and where our results actually fall.</p>
<div class="section" title="Syntax">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Syntax_2"></a>Syntax</h4>
</div>
</div>
</div>
<p>Test files are also pretty simple. It's a good idea to provide a description of the test so you can understand why you created it and what feature you're testing. Just put quote characters around your description. Then, use the "tests" keyword to specify what parameter file you'll be using. Again you can use file or project relative references. You don not specify a model here -- that's defined by the parameter file. You can use the "contains" keyword just like the incorporates keyword for parameter files, to specify a set of test constraints that you want to include with the new tests you've defined. This is useful for including a series of "sanity checks" with other tests. Then you specify the test constraints themselves. This uses the following form:</p>
<div class="literallayout">
<p>{Measure}({TestedAttribute})&nbsp;=&nbsp;[{MinimumConstraint},&nbsp;{MaximumConstraint}]<br>
</p>
</div>
<p>The measures available are Average, Minimum, Maximum Count and Sum. In order for an attribute to be tested the "gather data" value must be set for that attribute. All Measures are not appropriate for all attribute types. Booleans, Symbols and States should only use the Count measure as they represent discrete values that can either meet some condition or not.</p>
<p>The tested attributes are qualified by their model agent definition. The constraint definition is inclusive, as implied by the square brackets. Future implementations are expected to provide richer expressions and constraints but a very wide range of cases are supported by this construct, especially when combined with derived attributes. Tested Attributes are again specified by the attribute ID (with the first character in upper-case) followed by "=" and the desired value.</p>
</div>
<div class="section" title="Example">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Example_3"></a>Example</h4>
</div>
</div>
</div>
<p>In the following simple example we want to make sure that an epidemic can't occur without disease transmission taking place. Here we're just looking to make sure that we have some very basic logic right. (This might be almost too simple for a real-world design, depending on how rigorous we want to be.) Note that some individuals are infected at the beginning of the model run so we need to account for that in our expected results. So first we have defined the EpiZeroTransmission.apar file like the other transmission rate parameterizations above except with these settings:</p>
<div class="literallayout">
<p>MinContactTransmissionProbability=0.0<br>
MaxContactTransmissionProbability=0.0<br>
</p>
</div>
<p>Then we define our ZeroTransmission.atest file:</p>
<div class="literallayout">
<p>"Test&nbsp;that&nbsp;no&nbsp;disease&nbsp;transmission&nbsp;occurs&nbsp;with&nbsp;contact&nbsp;transmission&nbsp;set&nbsp;to&nbsp;0."<br>
tests&nbsp;"|params/EpiZeroTransmission.apar"<br>
Count(Individual.Status=Dead)&nbsp;=&nbsp;[0,5]<br>
Count(Individual.Status=Exposed)&nbsp;=&nbsp;[0,10]<br>
Count(Individual.Status=SymptomInfectious)=[0,0]<br>
</p>
</div>
<p>Here we have a nice description, a reference to the parameterization we want to use, and then the set of constraints we will apply to them. After running this test, a test result file like the one above will be created and placed in our "test-results" directory.</p>
</div>
<div class="section" title="Model Data">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="Model_Data"></a>Model Data</h4>
</div>
</div>
</div>
<table id="N1101A">
<tr>
<td>As discussed above, you can collect data for any model by selecting it or a paramters file and clicking the "Execute Model with data collection" button. If you use a parameters file setting the StopPeriod parameter will cause the model to stop executing and save the model at the specified time. Or you can stop the model manually. The model data will be collected into an "adata" file and stored in the "output" directory in your project. A new run entry will be created for each execution of a model. We are currently developing tools for exporting this data to various file formats as well as providing more seemless integration to sophisticated Eclipse hosted charting and report tools. You can use BIRT to interact with the data set using an XML schema data source and there is also an Ecore driver available. Model data can also be produced by writing custom views for data output. See the Ascape programmer guide for more information on how to do that.</td>
<td>
<div class="mediaobject">
<img src="images/data/Editor.png"></div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table summary="Navigation footer" width="100%">
<tr>
<td align="left" width="40%"><a accesskey="p" href="Modeler_Guide.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="Tutorials.html">Next</a></td>
</tr>
<tr>
<td valign="top" align="left" width="40%">Chapter&nbsp;2.&nbsp;Modeler Guide&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;4.&nbsp;Tutorials</td>
</tr>
</table>
</div>
</body>
</html>