blob: a519e0849bc85affdb9c1de91e341899b199c72f [file] [log] [blame]
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Modeling</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="User_Guide.html" title="User Guide">
<link rel="next" href="Building.html" title="Building">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Modeling</h1>
<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>
</body>
</html>