Added documentation for new features and extended docs on parameterization and testing.
diff --git a/documentation/amp.pdf b/documentation/amp.pdf
index 267a725..448a380 100644
--- a/documentation/amp.pdf
+++ b/documentation/amp.pdf
Binary files differ
diff --git a/documentation/contents/Modeler_Guide.html b/documentation/contents/Modeler_Guide.html
index 581d4b1..0485452 100644
--- a/documentation/contents/Modeler_Guide.html
+++ b/documentation/contents/Modeler_Guide.html
@@ -117,7 +117,7 @@
<span class="section"><a href="Modeler_Guide.html#Selections_2">Selections</a></span>
</dt>
<dt>
-<span class="section"><a href="Modeler_Guide.html#Roots">Roots</a></span>
+<span class="section"><a href="Modeler_Guide.html#Root_Actions">Root Actions</a></span>
</dt>
<dt>
<span class="section"><a href="Modeler_Guide.html#Builders">Builders</a></span>
@@ -511,6 +511,17 @@
</div>
<p>This value indicates whether you expect the model value to change. If you know that it won't or shouldn't, this value should be true.</p>
</div>
+<div class="section" title="Derived">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Derived"></a>Derived</h6>
+</div>
+</div>
+</div>
+<p>A derived attribute is one whose value is detemrined solely based on other agent attributes. A derived value is always associated with a Derive root action which is created automatically by the editor. See the documentation on the Derive action for more details. An attribute cannot be both derived and immutable.</p>
+</div>
<div class="section" title="Units">
<div class="titlepage">
<div>
@@ -899,10 +910,10 @@
</div>
</div>
</div>
-<table id="N102B3">
+<table id="N102B9">
<tr>
-<td>Before getting into the details of how each Actions work together, or the various kinds of Actions, it will be helpful to take a broad overview of how they all fit together. As discussed above, actions are strung together in a sequence or flow. They're always composed of two parts, though those parts can be assembled and intermixed in many different ways. First, we search for a collection of agents, and then we do something with that selection. We refer to these two parts as Selections and Commands. (For the technically minded, another useful way of looking at the Actions approach is as a Query Transformation language, as with SQL and Stored Procedures. Except again, the results of the queries along with the transformations flow through from one query to the next.) Selections find the agents we want to do something with, and the commands do it. We need some way to start the whole chain of actions off, and so we have a kind of Selection called a Root Selection, or simply a Root. Secondly, we need some way to actually make the agents exist in the model in the first place, so we have a Create Agents action. Finally, we have special commands called builders that allow us to create the spaces that the agents will occupy. The various actions are discussed in depth in the Details section.</td>
+<td>Before getting into the details of how each Actions work together, or the various kinds of Actions, it will be helpful to take a broad overview of how they all fit together. As discussed above, actions are strung together in a sequence or flow. They're always composed of two parts, though those parts can be assembled and intermixed in many different ways. First, we search for a collection of agents, and then we do something with that selection. We refer to these two parts as Selections and Commands. (For the technically minded, another useful way of looking at the Actions approach is as a Query Transformation language, as with SQL and Stored Procedures. Except again, the results of the queries along with the transformations flow through from one query to the next.) Selections find the agents we want to do something with, and the commands do it. We need some way to start the whole chain of actions off, and so we have a kind of Selection called a Root Selection, or simply a Root. Secondly, we need some way to actually make the agents exist in the model in the first place, so we have a Create Agents action. Finally, we have special commands called builders that allow us to create the spaces that the agents will occupy. The various actions are discussed in depth in the Details section. The diagram at the right depicts how actions relate to one another -- it does not include some actions that have been added more recently.</td>
<td>
<div class="mediaobject">
@@ -927,7 +938,7 @@
An important aspect of the Actions design is that loop structures are not allowed -- that is, flows are acyclic. An action can never have an ancestor target (that is targets, targets of targets, etc..) that has as one of its ancestors that same action. As you'll see, actions don't typically
<span class="italic">need</span> loop structures. By far the most common use of loops in conventional programming langauges is to loop through collections of objects. As selections (see below) refer to the entire collection of agents, any actions on a selection apply to all members of that collection. Recursive structures are needed for some particular usages and will be supported in future releases, but not through an explicit looping construct.
</p>
-<table id="N102D1">
+<table id="N102D7">
<tr>
<td>Again, behaviors in Actions are always defined by a set of
@@ -943,7 +954,7 @@
</tr>
</table>
-<table id="N102EB">
+<table id="N102F1">
<tr>
<td>The diagram to the right depicts a simple example. Here, we create a rule, and then check the results of two queries. For any agents that meet those criteria, we'll evaluate some function based on their state, and then set some value on them.</td>
@@ -956,7 +967,7 @@
</tr>
</table>
-<table id="N102FD">
+<table id="N10303">
<tr>
<td>In this next example, we'll first create the rule, and then create a new selection with a set of criteria. Finally, we'll do a move based on those queries.</td>
@@ -1020,7 +1031,7 @@
</div>
</div>
<p>Selections are a key concept in Actions. Put simply, selections define what we are searching for and where. They are defined by a combination of Select, Query and Logic Actions. Each time we create a new Select Action, we define a new selection. Queries can be used to further refine selections either immediately after or later in the Action flow, as described in the next section. Logic Actions are used to combine and organize the Action flow defined by Query Actions. In order to understand how these three pieces work together, we need to understand the idea of selection boundaries.</p>
-<table id="N10339">
+<table id="N1033F">
<tr>
<td>A selection boundary determines the set of selection actions that are used to determine what agents to apply target actions to. For example, in the following diagram, we can see the extent of the boundary for a straightforward selection.</td>
@@ -1033,7 +1044,7 @@
</tr>
</table>
-<table id="N1034B">
+<table id="N10351">
<tr>
<td>Each time we create a new selection, we define a new set of boundaries. In the diagram to the right, Selection 1 and Selection 2 eaach start with a new Select Action. </td>
@@ -1057,7 +1068,7 @@
</li>
</ol>
</div>
-<table id="N10368">
+<table id="N1036E">
<tr>
<td>In other words, as soon as a Logic Action occurs in a path leading to an Action, any following Query will define a new boundary, as shown in the example to the right. </td>
@@ -1095,7 +1106,7 @@
</div>
</div>
</div>
-<table id="N10393">
+<table id="N10399">
<tr>
<td>Now, let's put the concepts of Actions sequences and boundaries together to see how we can easily define complex interactions between multiple selections. When we define a Select, the state of its selection flows through and with any subsequent selections. So for example, if we have a Root Action rule, and then do a selection based on it, we'll have access to the agent from the original context as well as all of the subsequent selections. We can refer to any previous selection for any subsequent action. For example, instead of setting the value for the rule agent, we might instead set a value for an agent we've found in a target selection.</td>
@@ -1108,7 +1119,7 @@
</tr>
</table>
-<table id="N103A5">
+<table id="N103AB">
<tr>
<td>Inputs to functions also use selections. (We'll discuss more details in the functions section.) In the following example, we're adding the wealth of the Selection 1 agent to the wealth of the Selection 2 agent and using that value to set some other value. (Here, perhaps we are modeling an agent in a winner takes all game, in which case we'd also add a Set Action on Selection 2 and set the second agent's wealth to 0.)</td>
@@ -1121,7 +1132,7 @@
</tr>
</table>
-<table id="N103B7">
+<table id="N103BD">
<tr>
<td>But we can also use selections in defining Query Actions themselves. So in the following example, we select a neighbor agent and then compare the age of our Rule agent with the age of the Selection 2 agent. If and only if those ages are the same will we execute the target Set Action. This example also demonstrates why we refer to the data flow as weaving. Query Actions can be used to refine selections at any point in the data flow. Selections and their uses are interwoven throughout an action sequence.</td>
@@ -1134,7 +1145,7 @@
</tr>
</table>
-<table id="N103C9">
+<table id="N103CF">
<tr>
<td>Finally, we can put all of these concepts together by weaving selections together with flows. As we discussed in the flow section, if we use multiple paths in the Query, the agents that flow through from any prior Query can follow multiple paths at once. And as we discussed in the selection section, the selection and its boundaries determine what agents we will be working with at any given evaluation point in the flow. Consider the example to the right. As we'll see in the detailed explanation of each Action below, Transformation Actions such as Move or Connect take multiple selections. The first selection defines the set of agents that will be performing the action. In the case of a Move agent, this refers to the mover. The second selection, which for Move we call "destination", refers to the selection that will be receiving the action. In the case of movement this is the agent or location that the Rule agent will be moving to. If we follow the flows through, we can note two important outcomes of our model design -- a Rule agent might move twice if it meets the criteria for both the blue path and the red path and that it might move to a different location each time.</td>
@@ -1158,10 +1169,10 @@
</div>
</div>
</div>
-<table id="N103DF">
+<table id="N103E5">
<tr>
-<td>In this section, we'll dig into the specific role of each of the Actions. From the design discussion we hopefully have some sense of how these all fit together in general. Again, the block diagram to the right provides an overview of how the various actions are related. You might want to take a look at the meta-class diagrams in the referernce section as well.</td>
+<td>In this section, we'll dig into the specific role of each of the Actions. From the design discussion we hopefully have some sense of how these all fit together in general. Again, the block diagram to the right provides an overview of how the various actions are related, but it is missing some of the more recent actions such as Diffusion, Perform, Derive and Cause. You might want to take a look at the meta-class diagrams in the reference section as well.</td>
<td>
<div class="mediaobject">
@@ -1190,7 +1201,7 @@
</div>
</div>
</div>
-<p>As we discussed above, when we refer to a Select, we're actually referring to the selection as a whole leading up to the current action. The Select Action itself is used to define what we are searching for (Agent), where we are searching for it (Space), and from whose perspective we are doing it (Selection). Create Actions are a sepecial kind of Select Action that are used to create agents. See the decription in the Builders section below for more information.</p>
+<p>As we discussed above, when we refer to a Select, we're actually referring to the selection as a whole leading up to the current action. The Select Action itself is used to define what we are searching for (Agent), where we are searching for it (Space), and from whose perspective we are doing it (Selection). Create Actions are a special kind of Select Action that are used to create agents. See the description in the Builders section below for more information.</p>
<div class="section" title="Selection">
<div class="titlepage">
<div>
@@ -1326,12 +1337,12 @@
<p>A difference contains all agents that do not match any of its source actions. This essentially equivalent to a logical NOT statement, and has similarities to the Java else statement. Like the Union Action, difference implies that a given agent will only appear once in any subsequent targets. No agents that reach a Difference Action will flow through to the next action(s), and all agents (that meet the definition of the Select Action) that cannot reach that action will.</p>
</div>
</div>
-<div class="section" title="Roots">
+<div class="section" title="Root Actions">
<div class="titlepage">
<div>
<div>
<h4 class="title">
-<a name="Roots"></a>Roots</h4>
+<a name="Root_Actions"></a>Root Actions</h4>
</div>
</div>
</div>
@@ -1433,7 +1444,7 @@
</div>
</div>
</div>
-<p>A Watch action is executed any time the watched value is set for any agent. Note that the Action will be triggerred even if the state is simply set back to the value that it already has. It is important to be careful about creating Watches that might set the values of other Watch actions which might in turn trigger this watch. To clarify, if a modeler creates a Watch A for attribute a, and creates a target Set for it for attribute b, and Watch B is watching attribute b, then if Watch B has a target Set for attribute A, a circular execution could occur. This would cause the model to get stuck in its current iteration. To help model developers avoid this case, a warning will be provided if such a set of circular watch dependencies is created.</p>
+<p>A Watch is executed any time the watched value is set for any agent. Note that the Action will be triggerred even if the state is simply set back to the value that it already has. It is important to be careful about creating Watches that might set the values of other Watch actions which might in turn trigger this watch. To clarify, if a modeler creates a Watch A for attribute a, and creates a target Set for it for attribute b, and Watch B is watching attribute b, then if Watch B has a target Set for attribute A, a circular execution could occur. This would cause the model to get stuck in its current iteration. To help model developers avoid this case, a warning will be provided if such a set of circular watch dependencies is created.</p>
<div class="section" title="Attribute">
<div class="titlepage">
<div>
@@ -1446,6 +1457,84 @@
<p>The attribute that will be monitored for change.</p>
</div>
</div>
+<div class="section" title="Derive">
+<div class="titlepage">
+<div>
+<div>
+<h5 class="title">
+<a name="Derive"></a>Derive</h5>
+</div>
+</div>
+</div>
+<p>A Derive action is a unique kind of root that is used to determine that value of a derived attribute. There can be one and only one Derive action for each such attribute. One of the benefits of a derived action is that unlike a standard attribute, it only needs to be calculated when the value is actually needed and its inputs have also been changes -- allowing signifcant performance optimizations to be made. Derived actions can also make model behavior much more clear. Derive actions are especially useful for calculating dependent measures for model agents. These in turn can be used directly in charting and data output tools -- leaving no need to configure your chart view calculations seperatly. Developers need not worry about overhead and should feel free to create as many derived attributes as might be neccessary. The "gather data" value of the derived attribute can always be set to false to prevent data collection overhead when they aren't needed.</p>
+<p>The derived value will always simply be the value of the last evaluation in a particular flow. You can mix queries and even selections on seperate agents into a derived value. The only restriction is that the type of the last Evaluate actions(s) must match the type of the value. If there is no path leading to an Evalutate action for a particular agent state, the attributes default value will be used.</p>
+<div class="section" title="Attribute">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Attribute_2"></a>Attribute</h6>
+</div>
+</div>
+</div>
+<p>The attribute that will be derived.</p>
+</div>
+</div>
+<div class="section" title="Diffuse">
+<div class="titlepage">
+<div>
+<div>
+<h5 class="title">
+<a name="Diffuse"></a>Diffuse</h5>
+</div>
+</div>
+</div>
+<p>The diffuse action provides high level support for the common behavior of diffusing some value across some lattice space. For example, heat may spread over time from one grid cell to the next. (There are actually significant issues involved in implementing this through lower level actions.) To specify that a value should diffuse through a space you simply need to provide the following values. This action does not need and shouldn't include target actions. The "Heatbugs" model in the org.eclipse.amp.amf.examples.escape project provides a good example for how diffusion can be easily implemented into any grid model.</p>
+<div class="section" title="Diffused">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Diffused"></a>Diffused</h6>
+</div>
+</div>
+</div>
+<p>The attribute whose value is to be diffused.</p>
+</div>
+<div class="section" title="Diiffusion Rate=">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Diiffusion_Rate.3D"></a>Diiffusion Rate=</h6>
+</div>
+</div>
+</div>
+<p>The rate at which any given cell's attribute value is transferred to surrounding cells.</p>
+</div>
+<div class="section" title="Evaporation Rate">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Evaporation_Rate"></a>Evaporation Rate</h6>
+</div>
+</div>
+</div>
+<p>An optional rate by which each cells value is reduced for each period. This is useful for a model where agents are creating energy within the environment.</p>
+</div>
+</div>
+<div class="section" title="Perform">
+<div class="titlepage">
+<div>
+<div>
+<h5 class="title">
+<a name="Perform"></a>Perform</h5>
+</div>
+</div>
+</div>
+<p>A Perform root action simply defines a set of actions that have no independent trigger. The only way Perform actions can occur is if a Cause action specifes one as a result. Performs then are similar to sub-calls or helper methods within a traditonal procedural or OO language, and can be very helpful in organizing and simlplifying code. Note that whenever you use a Perform instead of directly specifying a set of targets you lose the context of the selection. You couldn't use a Perform to directly trigger a move as the selection source for the move would not be available.</p>
+</div>
</div>
<div class="section" title="Builders">
<div class="titlepage">
@@ -1829,14 +1918,14 @@
</div>
</div>
</div>
-<p>Here the selection refers to the agent that we want to change. This does not have to be the immediatily preceeding selection but can be any accessible selection.</p>
+<p>Here the selection refers to the agent that we want to change. This does not have to be the immediatly preceeding selection but can be any accessible selection.</p>
</div>
<div class="section" title="Attribute">
<div class="titlepage">
<div>
<div>
<h6 class="title">
-<a name="Attribute_2"></a>Attribute</h6>
+<a name="Attribute_3"></a>Attribute</h6>
</div>
</div>
</div>
@@ -1854,6 +1943,30 @@
<p>The value to assign to the attribute. Here, we can use either another agent attribute, or the results of a source evaluation. </p>
</div>
</div>
+<div class="section" title="Cause">
+<div class="titlepage">
+<div>
+<div>
+<h5 class="title">
+<a name="Cause"></a>Cause</h5>
+</div>
+</div>
+</div>
+<p>A Cause Action "causes" some Root Action to occur upon the specified selection. This action can be extremely useful for organizing model behavior and preventing the need for creating duplicate action definitions.</p>
+<p>Cause actions also support recursive functionality and "WHILE" behavior. These can be used to mimic loop strucutres. For example, you might want an agent to execute some behavior as long as that agent has energy remaining. To accomplish this, you could create a query for "energy > 0" and then create a Cause target with the root action as its results.</p>
+<p>Note that you should be cautious and thoughtful when using the Cause action. Remember that selections represent sets of agents and thus get rid of the need for collection loop strucutures -- such as Java "for each" -- common in traditional programming languages. You should be able to do almost anything that might require a loop strucutre using the selection mechanism itself. Also, just as with a traditional language, you should be careful about defining cause actions that trigger their own root actions or that cause other actions to in turn trigger the orginal root action. You can easily end up defining infinite loops in this way. (In the current implementation this will eventually trigger a stack overflow error as cause invocations are recursive, but future implementations will be able to infer target language loop strcutures to prevent stack depth issues.)</p>
+<div class="section" title="Result">
+<div class="titlepage">
+<div>
+<div>
+<h6 class="title">
+<a name="Result"></a>Result</h6>
+</div>
+</div>
+</div>
+<p>The root aciton that should be trigerred for every memeber of the current selection. This is typically a Perform action but it can be any kind of root action except for "Derived". (Which doesn't make any sense to do.)</p>
+</div>
+</div>
<div class="section" title="Move">
<div class="titlepage">
<div>
@@ -1941,12 +2054,12 @@
</div>
<p>The selection determines what space the agent to remove.</p>
</div>
-<div class="section" title="=Destination">
+<div class="section" title="Destination">
<div class="titlepage">
<div>
<div>
<h6 class="title">
-<a name=".3DDestination"></a>=Destination</h6>
+<a name="Destination_3"></a>Destination</h6>
</div>
</div>
</div>
@@ -1979,7 +2092,7 @@
<div>
<div>
<h6 class="title">
-<a name=".3DDestination_2"></a>=Destination</h6>
+<a name=".3DDestination"></a>=Destination</h6>
</div>
</div>
</div>
@@ -2034,7 +2147,7 @@
<div>
<div>
<h6 class="title">
-<a name="Destination_3"></a>Destination</h6>
+<a name="Destination_4"></a>Destination</h6>
</div>
</div>
</div>
@@ -2078,7 +2191,7 @@
<div>
<div>
<h6 class="title">
-<a name="Destination_4"></a>Destination</h6>
+<a name="Destination_5"></a>Destination</h6>
</div>
</div>
</div>
@@ -2214,7 +2327,7 @@
<div>
<div>
<h6 class="title">
-<a name="N10647"></a>Input Literals</h6>
+<a name="N10689"></a>Input Literals</h6>
</div>
</div>
</div>
diff --git a/documentation/contents/Tutorials.html b/documentation/contents/Tutorials.html
index 68c9223..a4ae4c6 100644
--- a/documentation/contents/Tutorials.html
+++ b/documentation/contents/Tutorials.html
@@ -728,7 +728,7 @@
<div>
<div>
<h5 class="title">
-<a name="N11059"></a>Create Select and Query Actions</h5>
+<a name="N110DD"></a>Create Select and Query Actions</h5>
</div>
</div>
</div>
diff --git a/documentation/contents/User_Guide.html b/documentation/contents/User_Guide.html
index 2c5dbc7..f9c4254 100644
--- a/documentation/contents/User_Guide.html
+++ b/documentation/contents/User_Guide.html
@@ -190,9 +190,29 @@
<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_5">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_6">Example</a></span>
+</dt>
+</dl>
+</dd>
</dl>
</dd>
</dl>
@@ -929,7 +949,7 @@
</div>
</div>
</div>
-<table id="N10CDB">
+<table id="N10D1D">
<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>
@@ -1361,7 +1381,7 @@
</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 lcoation you want to create the parameter file, and select
+<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 > Parameters File</strong></span>.
</p>
<p>
@@ -1408,6 +1428,54 @@
<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_5"></a>Example</h4>
+</div>
+</div>
+</div>
+<p>We can create a base parameters file called "EpiBase.apar".</p>
+<div class="literallayout">
+<p>model "|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 "|Epidemic.metaabm"<br>
+incorporates "EpiBase.apar"<br>
+MinContactTransmissionProbability=0.05<br>
+MaxContactTransmissionProbability=0.2<br>
+
+</p>
+</div>
+<p>and EpiLowTransmission.apar:</p>
+<div class="literallayout">
+<p>model "|Epidemic.metaabm"<br>
+incorporates "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">
@@ -1423,16 +1491,63 @@
<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.</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/Execute.png"></div>
+<img src="images/params/TestResults.png"></div>
<p>
</p>
-<p>It's helpful to keep them organized in sets of folders. If you select an entire folder, the framework will run </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}) = [{MinimumConstraint}, {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_6"></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 that no disease transmission occurs with contact transmission set to 0."<br>
+tests "|params/EpiZeroTransmission.apar"<br>
+Count(Individual.Status=Dead) = [0,5]<br>
+Count(Individual.Status=Exposed) = [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>
</div>
</div>
diff --git a/documentation/contents/images/params/TestResults.png b/documentation/contents/images/params/TestResults.png
new file mode 100644
index 0000000..8a98424
--- /dev/null
+++ b/documentation/contents/images/params/TestResults.png
Binary files differ
