blob: a04ee9770960b010dac5a581521ae789717c40a0 [file] [log] [blame]
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Exploring</title>
<link href="book.css" rel="stylesheet" type="text/css">
<meta content="DocBook XSL Stylesheets V1.75.1" name="generator">
<link rel="home" href="index.html" title="Agent Modeling Guide">
<link rel="up" href="User_Guide.html" title="User Guide">
<link rel="prev" href="Building.html" title="Building">
<link rel="next" href="Tutorials.html" title="Tutorials">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Exploring</h1>
<div class="section" title="Exploring">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="Exploring"></a>Exploring</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="N10CDB">
<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. 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/EditorToolbar.png"></div>
</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.</p>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/Epidemic3D.png"></div>
<p>
</p>
</div>
<div class="section" title="Controlling Model Execution">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Controlling_Model_Execution"></a>Controlling Model Execution</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/EpidemicModelControls.png"></div>
<p>
</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>
</p>
<div class="mediaobject">
<img src="images/execution/EpidemicModelComparison.png"></div>
<p>
</p>
<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="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>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/LineChart.png"></div>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/AreaChart.png"></div>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/BarChart.png"></div>
<p>
</p>
<div class="mediaobject">
<img src="images/execution/PieChart.png"></div>
<p>
</p>
</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="Executing Internal Targets">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="Executing_Internal_Targets"></a>Executing Internal Targets</h3>
</div>
</div>
</div>
</div>
</div>
</body>
</html>