Docs update.
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/build.properties b/org.eclipse.amp/doc/org.eclipse.amp.doc/build.properties
index 24618c1..7bd0873 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/build.properties
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/build.properties
@@ -8,4 +8,5 @@
toc.xml,\
about.html,\
about.ini,\
- modeling32.png
+ modeling32.png,\
+ master_toc.xml
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.mediawiki
index 1a47a33..7950132 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.mediawiki
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.mediawiki
@@ -1,10 +1,54 @@
-=Introduction=
+=Overview=
+
+The Eclipse Agent Modeling Project (AMP) provides extensible frameworks and exemplary tools for representing, editing, generating,
+executing and visualizing agent-based models (ABMs) and any other domain requiring spatial, behavioral and functional features.
+
+==Architecture==
+
+AMP has two main themes that complement but don't depend on one another:
+
+The overall AMP architecture and Eclipse project dependencies are summarized below:
+
+[[image:AMPArchitectureDiagram.jpg]]
+
+=Getting Started=
+
+AMP has many potential facets and use cases. Here are a few ways to get started with it.
+
+First, if you aren't using a full download version of AMP, you'll need to [http://eclipse.org/amp/installing/ install it]. Then...
+
+==ABM Modelers==
+
+Experiment with example Java and AMF based models without writing code.
+
+[[AMP/Running_Examples|Run Example Models]]
+
+==ABM Researchers==
+
+Create Agent-Based models using simple visual tools and deploy them to a number of popular ABM platforms, including Escape.
+
+[[AMP/UserGuide/AMF#Getting Started|Modeling with AMF]]
+
+==ABM Java Developers==
+
+Write POJO Java models within a full-featured agent-based modeling framework.
+
+[[AMP/UserGuide/Escape#Getting_Started|Programming with Escape]]
+
+==Eclipse Plugin Developers==
+
+AXF and AGF provide a number of features based around Eclipse technologies such as GEF, GEF3D, BIRT Charts and Zest. For example, AGF supports dynamic visualization of objects in space, and AXF supports managed UI and headless execution for models of any kind.
+
+[[AMP/AGF_AXF_API|Programming with AXF and AGF]] (todo)
+=Modeler's Guide=
+
+==Introduction==
In this Modeler's Guide we provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design one. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Attributes, Spaces, and Actions. The first three refer to structural components, whereas Actions define behavior. Agent models also have styles, which are a special kind of Action used to determine how to portray an agent in a visualization. Finally Actions make use of Functions. We'll describe of these components in a separate section.
But first, we'll give a quick overview at what agent-based modeling is is and how the Agent Modeling Framework can help you to develop models for ABM or other problem domains.
-==Agent-Based Modeling==
+===Agent-Based Modeling===
The primary focus of the Agent Modeling Platform tools is "Agent-Based Modeling" (ABM). ABM is an innovative technique used to explore complex phenomenon in many domains, including economics, social sciences, biomedicine, ecology and business operations. ABMs share characteristics with object models, but are:
@@ -25,93 +69,102 @@
Agent-Based Models (ABMs) seek to represent important real-world dynamics by designing communities of software agents that mimic real entities. Rather than make simplifying assumptions about such systems and then representing them in equation form or as off the shelf algorithmic constructs, the ABM researcher aims to identify key agent state, interaction spaces, and behaviors. Agents are then "let loose" on our computers and we explore what happens next. The computational horsepower exists today to simulate large numbers (e.g. >>10) of interacting, adaptive and autonomous agents but often desktop computers are all we need to explore significant domains. ABMs have been designed to represent all kinds of important natural systems, at scales reaching from cellular mechanics to international trade and are being used to solve truly hard problems in government, business, and academia. ABMs are not a solution to every problem, but they can help us to appreciate and gain unique insight into many systems, and often they can help us to come up with better practical decisions than we might using classic approaches.
-==Agent Modeling Framework==
+===Agent Modeling Framework===
The Eclipse Platform provides many unique features that make it ideal for an ABM platform. AMF provides easy to use and powerful tools and techniques for designing Agent-Based Models, including a common representation, editors, generators and development environment.
-The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level. For those familiar with Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. The AMF meta-model (currently "MetaABM", but in the process of evolving to a new compatible "Acore" specification) is defined in Ecore but provides a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms.
+The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level.
+
+The foundation of the Agent Modeling Framework is "Acore". The current version uses an interim version of Acore called "MetaABM". We refer to the AMF models as "meta-models" because they are used to define ''how'' Agent-Based Models are themselves modeled. For those familiar with Eclipse Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. Acore and MetaABM are defined in Ecore but provide a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms. AMF is fully integrated with the Eclipse IDE platform, but Acore models themselves need have no dependencies on any particular technology beyond XML/XSD.
Models designed in AMF are transparently converted to Java code for leading Agent-Based Modeling tools, such as the Escape tools which are included in AMP and allow direct execution of models within the AMP environment, and Repast Simphony, another popular Java based ABM tool. These tools create Java code that can then be compiled, executed and event modified in these environments just as with any other Java program. AMF's generative capability is designed to be pluggable and modular so that other developers can create AMF generators for their own tools. In fact, targets can be designed that have no inherent dependencies on Eclipse or even on a traditional platform.
-==Other Uses==
+The Acore / MetaABM meta-model is made up of three main packages. This is all based on MetaABM, and while names and important details will change for Acore, the core design should be quite similar.
+
+===Other Uses===
Many kinds of objects share characteristics of ABM agents -- after all, software agents are used in many other contexts. The Agent Modeling Framework meta-modeling support is potentially suitable (or extendible) for a number of approaches outside of ABM; for example business rules, object interactions, systems dynamics models and traditional discrete event models. Similarly, AMP execution and graphic support can be used for modeling natural systems but could also be used to manage other software agents -- for example independent reasoning tasks or dynamic visualization support.
We hope you enjoy using the tool, and we look forward to your comments and feedback and most of all participation!
-=Structure=
+===Credits===
-==Design==
+The AMF meta-model started life as [[http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf|"score"]], a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continues development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009.
+
+Miles Parker is a consultant and software developer with over ten years of experience in the agent-based modeling field and twenty years developing object-oriented tools and frameworks. Metascape, LLC provides Agent-Based Modeling tools, including sophisticated tools based on the AMF platform, and comprehensive consulting services. For more information on Metascape products and services visit http://metascapeabm.com.
+==Structure==
+
+===Overview===
The basic structure of an agent-based model can be quite simple. While there are many subtle complexities -- beyond the scope of this manual -- we can construct most models following some straightforward and elegant design principles. And in fact, one of the main goals of the Agent Modeling Framework is to provide a consistent framework that can support using those principles to support the creation of models that can be easily understood, shared, and that can be used interchangeably as components in other models.
Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents.
-==Details==
+===Details===
-===General===
+====General====
Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore -- including Actions and Functions which we describe in the next two sections -- have a number of shared values.
-====Named Entities====
+=====Named Entities=====
-=====Label=====
+======Label======
A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Exchange Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.
-=====ID=====
+======ID======
An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)
And most entities also define:
-=====Description=====
+======Description======
A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.
-=====Plural Label=====
+======Plural Label======
The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".
-===Agents===
+====Agents====
-====Simple Agents====
+=====Simple Agents=====
An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.
-=====Attributes=====
+======Attributes======
As described in the attribute sections above.
-=====Actions======
+======Actions======
Described in the "Actions" section.
-=====Styles=====
+======Styles======
Special actions that are used to define how to draw an agent graphically as also described in the "Actions" section and detailed in the "Functions" section.
-====Context Agents (Contexts)====
+=====Context Agents (Contexts)=====
As detailed above, agents also form the basic structural component of an agent-based model. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".
-=====Agents=====
+======Agents======
The agents that are contained within this context. For example, a context representing a city might contain an Individual Agent for defining all individuals in the model, and a Vehicle agent defining all vehicles. Note that when we refer to an agent in this context, we mean a general type or class of agent, not the agent itself.
-=====Spaces=====
+======Spaces======
The set of all spaces contained or subsumed by the agent. For example, a context representing a city might contain a geographical space and a transportation network space.
-===Attributes===
+====Attributes====
Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.
Here are the basic types of attributes available in Acore models:
-====Basic Attributes====
+=====Basic Attributes=====
Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. In this section we go over the values you can set for the attributes. For those with a tecnical bent, note that we are technically describing the meta-attributes for the meta-class "SAttribute". But it is far too confusing to refer to the attributes of attributes! So we'll just refer to the attributes that any of our model components as "values".
-=====Type=====
+======Type======
These can be anyone of the following:
-{| cellpadding="10" cellspacing="0" border="1"
+{| cellpadding=="10" cellspacing=="0" border=="1"
|Boolean
|A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.
|-
@@ -128,116 +181,109 @@
(Undefined and Numeric types should not be used within a well-defined model.)
-=====Default Value=====
+======Default Value======
The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.
-=====Gather Data=====
+======Gather Data======
Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.
-=====Immutable=====
+======Immutable======
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.
-=====Units=====
+======Units======
Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.
-====Arrays====
+=====Arrays=====
Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to what is defined above, arrays specify:
-=====Size=====
+======Size======
The number of values that the array attribute will contain.
-====States====
+=====States=====
States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".
-=====State Options=====
+======State Options======
Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have
-=====Default Option=====
+======Default Option======
unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.
-===Spaces===
+====Spaces====
All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:
-====Space (Continuous)====
+=====Space (Continuous)=====
In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.
-=====Border Rule=====
+======Border Rule======
A value representing what happens to an agent when that agent is asked to move beyond its extent.
-{| cellpadding="10" cellspacing="0" border="1"
-|Periodic
-|When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location [1,2] (0-based) within a Moore space (see grid discussion below) of size [10,10] is asked to find some other agent within distance 3, the agent look in the square defined between [8,9] and [4,5]. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.
-|-
-|APeriodic
-|When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location [1,2] is asked to find some other agent within distance 3, the agent look between [0,0] and [4,5]. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.
-|}
+;Periodic
+: When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location {1,2} (0-based) within a Moore space (see grid discussion below) of size {10,10} is asked to find some other agent within distance 3, the agent look in the square defined between {8,9} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.
+;APeriodic
+: When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location {1,2} is asked to find some other agent within distance 3, the agent look between {0,0} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.
The "Strict" and "Bouncy" values are obsolete and should not be used.
- =====Dimensionality=====
+ ======Dimensionality======
The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attribute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.
-====Grid====
+=====Grid=====
A grid is technically a regular lattice structure. Currently, only rectilinear structures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platforms support n-d spaces yet.)
Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:
-=====Multi-Occupant=====
+======Multi-Occupant======
Does the grid allow more than one agent to occupy it at a time? This value may be replaced with another mechanism in future releases.
-=====Neighborhood=====
+======Neighborhood======
This value determines what constitutes a region within a particular distance from the agent. The value for this is often critical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:
-{| cellpadding="10" cellspacing="0" border="1"
-|Euclidian
-|The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.
-|-
-|Moore
-|Here, the distance between any two cells is defined by the number of edge <i>or</i> corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.
-|-
-|Von-Neumann
-|Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.
-|}
+;Euclidean
+: The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.
+;Moore
+:Here, the distance between any two cells is defined by the number of edge ''or'' corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.
+;Von-Neumann
+: Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.
-====Network====
+=====Network=====
A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.
A network has only one value to specify:
-=====Directed=====
+======Directed======
This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)
-====Geography====
+=====Geography=====
A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.
-==Reference==
+===Reference===
-===Diagrams===
+====Diagrams====
For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.
-====Meta-Classes====
+=====Meta-Classes=====
Our first diagram depicts the core structural design of the model.
@@ -245,13 +291,13 @@
There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
-====Key Collaborations====
+=====Key Collaborations=====
[[Image:images/StructureSimpleDiagram.png]]
Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-====Details====
+=====Details=====
#Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally).
#(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.
@@ -259,13 +305,11 @@
#Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidean) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.
#Agents are Actable and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.
#Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actable. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".
-
-
-=Actions=
+==Actions==
Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.
-==Background==
+===Overview===
Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.
@@ -280,11 +324,11 @@
But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.
-==Design==
+===Design===
In this section, we'll describe how modelers can assemble actions into sets of behavior that accomplish complex tasks on interrelated agents and spaces over time.
-===Kinds of Actions===
+====Kinds of Actions====
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. All of these are discussed in detail in the section that follows this one.
@@ -292,7 +336,7 @@
[[Image:images/ActionsBlocks.png]]
-===Flow===
+====Flow====
First, let's look at how actions define the basic path that agents take during a model run. As with any programming language, the path we take through the program specification is what determines our state when we get there. In a pure object oriented program, the path just defines the control flow -- what we are doing. The actual state of our model is defined within the object itself. If we call a method B from another method A, we'll be relying on method A to set the values that we need into the object state itself. In a purely functional program the path defines how we are going to deal with whatever has been explicitly passed in to a function that has been called, that is the function parameters. In fact, most languages such as Java combine aspects of both approaches.
@@ -335,7 +379,7 @@
This is a simple example, but with multiple branches such code design issues can quickly grow complex. The flow approach allows us to express things in a way that is often more natural and expressive. The important thing to keep in mind when desiging action flows is to see the flow as representing a selection of agents moving through streams independently. In the Actions example we expressed both approaches in nearly the same way, except in the case on the left we used a Union Action to bring the two branches of flow back together.
-===Selections===
+====Selections====
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.
@@ -358,13 +402,13 @@
Note that we refer to "Selection 1" and Selection 1A". This is because Selection 1A is a refinement of Selection 1 along its particular path of flow. When a query appears for the same selection but past a particular boundary, you can think of it as a sort of filter on the selection contents. We don't have a "Selection 2" here because any Actions that refer to "Selection 1" along the current path of flow will be acting on the selection defined by Selection 1 and Selection 1A.
-These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a = x and attribute b = y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a = x, and ''then'' taking those agents and choosing those agents with b=y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
+These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a == x and attribute b == y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a == x, and ''then'' taking those agents and choosing those agents with b==y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
[[Image:images/ActionsSelBoundaryComplex.png]]
In the first case, we execute a search for all agents that meet the two criteria. This means that if there are ''any'' neighboring cells which are available, we're guaranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all. This then becomes an important aspect of model design. For example, if one were defining a model where neighbors played a game with each other, one might want to instruct agents to play the game only with neighbors that have a certain wealth threshold. In the real-world situation that we are modeling, we might simply search for neighbors who are over a given wealth threshold and then play the game with them. This would imply that information about other agent's wealth is open knowledge. Or, we might simply select a random neighbor, and ask that neighbor to play a game with us. Upon discovering that our neighbor does not meet our wealth criteria, we would then choose not to play with them. Here we are modeling a cost in time to obtain information about another agent's wealth, because we might miss an opportunity to play the game with another agent on that round.
-===Weaving===
+====Weaving====
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.
@@ -384,7 +428,7 @@
Before going into further details we need to introduce one more important concept. 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.
-==Details==
+===Details===
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.
Let's look at the overall view again amd then dig into the details.
@@ -392,131 +436,131 @@
[[Image:images/ActionsBlocks.png]]
-===Selections===
+====Selections====
A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.
-====Select====
+=====Select=====
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):
-=====Selection=====
+======Selection======
The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.
-=====Agent=====
+======Agent======
Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.
-=====Space=====
+======Space======
The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.
Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.
-=====For=====
+======For======
This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.
-====Query====
+=====Query=====
A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions.
-=====Function=====
+======Function======
-A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age = Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.
+A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age == Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.
-====Logic====
+=====Logic=====
These Actions provide us with the ability to combine queries with one another, and follow the basic rules of set logic. But as we've seen above, it is important to understand that there are important differences between Logic Actions and typical programming logic. Most importantly, they apply not to individual agents per se, but to the set of agents that move through them. Also, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together because of the action flow design.
-====Intersection====
+=====Intersection=====
An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. An agent must be able to flow through all incoming actions in order to flow out of an Intersection Action.
-====Union====
+=====Union=====
A union contains all agents that match any of its source actions. This shares similiarities to a logical OR statement and the || operator in a java "if" statement. It does mroe than that however, as it acts to join multiple flows of action. That is, as set logic implies, an agent will never appear in the result of a union more than once.
-====Difference====
+=====Difference=====
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.
-====Roots====
+=====Roots=====
Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.
-====Build====
+=====Build=====
The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined whether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.
-====Initialize====
+=====Initialize=====
An Initialize action is executed once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guaranteed to execute before any other non-builder action occurs.
-====Rule====
+=====Rule=====
A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.
-====Schedule====
+=====Schedule=====
-A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time = t.
+A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time == t.
-=====Start=====
+======Start======
The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..
-=====Interval=====
+======Interval======
How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..
-=====Priority=====
+======Priority======
Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.
-=====Pick=====
+======Pick======
Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be replaced by another approach.
-====Watch====
+=====Watch=====
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.
-=====Attribute=====
+======Attribute======
The attribute that will be monitored for change.
-===Commands===
+====Commands====
-====Evaluate====
+=====Evaluate=====
Evaluate Actions define some calculation on a function based on the model state and a set of input(s). The inputs that an Evaluate Action can take is determined by its functions and can be either agent attributes, prior evaluations or literals. The result is then determined based on those inputs. In some cases Evaluate functions can be used to determine some action indirectly, such as with a graphics fill, but they can never be used to directly change model state.
-=====Selection=====
+======Selection======
As with all other actions, evaluations specify a selection, and just as with the other actions, this determines the set of agents that the evaluation occurs for, but the input selections determine what agent is used for the calculation itself.
-=====Function=====
+======Function======
A with queries, a function is evaluated against its input set. Functions can represent simple operators as well as complex functions. See the functions section for more information on specific functions.
-=====Inputs=====
+======Inputs======
The set of values that will be used to determine the result, in the order of the function prototype. Inputs can specify any source evaluation and any agent state or agent parent context state. The selection determines which agent's will be used to determine the value, and different inputs can specify different selections.
-====Move====
+=====Move=====
The Move Action causes an agent to change its location in some space or network. The agent will leave whatever location it was in before within the selection space, and move to its new destination.
-=====Selection=====
+======Selection======
As with any
-====Set====
+=====Set=====
The Set Action assigns some value to another value.
-==Example==
+===Example===
In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:
@@ -544,7 +588,7 @@
##The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.
##We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.
#Create two child Query Actions:
-##We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.
+##We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by the rule agent's partner for the first input and by the rule agent for the second. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.
##We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner.
#Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.
#Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.
@@ -556,17 +600,17 @@
##The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and
##The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.
-==Reference==
+===Reference===
-===Diagrams===
+====Diagrams====
The following diagram may be helpful to readers familiar with UML and Meta-modeling:
-====Meta-Classes====
+=====Meta-Classes=====
[[Image:images/ActionsDiagram.png|800px]]
-====Details====
+=====Details=====
In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.
#An Act is anything that might happen during the execution of an Agent-Based Model.
@@ -576,9 +620,9 @@
#Controls determine whether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.
#Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).
#Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.
+==Functions==
-
-=Functions=
+===Overview===
Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:
@@ -590,269 +634,330 @@
#Generics can return any value and are used in Evaluate actions.
#Logicals return some boolean result and are used by Query actions to decide whether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.
-These overlap, so we have operators, logical operators, functions and logical functions.
+These overlap, so we have operators, logical operators, functions and logical functions. Functions are also divided into categories. We'll go through each of these in depth below.
-Functions are also divided into categories, as we'll see.
+The most important thing to point out about functions is that - as we've seen with other Acore concepts -- they provide richer sets of functionality than traditional approaches. Many functions are designed to collaborate with one another as we'll see when looking at Spatial and Graphical functions. Functions can also trigger the creation of related model artifacts as we'll see with the Distribution functions.
A technical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.
+===Details===
-==Reference==
-
-===Function Library===
-====Operators====
-====Logical Operators====
-=====Not=====
+====General Functions====
+
+Naturally, the Modeling tools provide general functions for performing calculations, comparisons and more complex mathematical expressions. The function library can be easily extended, and we'll be adding additional capabilities over time. As always, we welcome feedback and we'd like to hear what functions you need that aren't covered here.
+
+=====Logical Operators=====
+======Not======
The result of the expression !X.
-=====Equal=====
+======Equal======
The result of the expression X==Y.
-=====Identical=====
+======Identical======
The result of the expression X==Y.
-=====Greater=====
+======Greater======
The result of the expression X>Y.
-=====Lesser=====
+======Lesser======
The result of the expression X<Y.
-=====Greater or Equal=====
+======Greater or Equal======
The result of the expression X>=Y.
-=====Lesser or Equal=====
+======Lesser or Equal======
The result of the expression X<=Y.
-=====True=====
+======True======
The result of the expression true.
-=====False=====
+======False======
The result of the expression false.
-=====Identity=====
+======Identity======
The result of the expression X.
-=====Different=====
+======Different======
The result of the expression X!=Y.
-====Numeric Operators====
-=====Negative Value=====
+=====Numeric Operators=====
+======Negative Value======
The result of the expression -X.
-=====Add=====
+======Add======
The result of the expression X+Y.
-=====Subtract=====
+======Subtract======
The result of the expression X-Y.
-=====Multiply=====
+======Multiply======
The result of the expression X*Y.
-=====Divide=====
+======Divide======
The result of the expression X/Y.
-=====Power=====
+======Power======
The result of the expression X^Y.
-=====Modulo=====
+======Modulo======
The result of the expression X%Y.
-=====Increment=====
+======Increment======
The result of the expression ++X.
-=====Decrement=====
+======Decrement======
The result of the expression --X.
-=====Unit Value=====
+======Unit Value======
The result of the expression 1.
-=====Zero Value=====
+======Zero Value======
The result of the expression 0.
-=====Original Value=====
+======Original Value======
The result of the expression o.
-====Spatial====
-=====Nearest =====
-Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.
-=====Toward=====
-Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.
-=====Within=====
-Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.
- Inputs:
- [Numeral]
-=====Neighbor=====
-Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.
-=====Include Self=====
-Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.
-=====Within 2D Boundary=====
-Represents agents or locations that exist within the boundary specified by the inputs.
- Inputs:
- [Numeral]
-=====Here=====
-Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used.
-=====Available=====
-Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.
-=====Distance=====
-The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.
- Outputs:
- [Real]
-=====Away=====
-Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.
-=====Minimize=====
-This function is not currently supported.
-=====Maximize=====
-This function is not currently supported.
-=====Location 2D=====
-Represents the location of the current agent for use in subsequent selections.
- Inputs:
- [Real]
- [Real]
-=====Boundary 2D=====
-Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)
- Outputs:
- [Real]
- [Real]
+
+=====Math=====
+
+The math functions use the extremely well specified and tested routines form the Java Math library. (Because of copyright restrictions, we aren't able to include the exact definitions here. Click on the links to get more details on each function.)
+
+======Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)]
+======Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)]
+======Tangent======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)]
+======Arc Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)]
+======Arc Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)]
+======Arc Tangent======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)]
+======Convert Degree to Radians======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)]
+======Convert Radians to Degrees======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)]
+======Exp======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)]
+======Log======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)]
+======Log b10======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)]
+======Square Root======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)]
+======Cube Root======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)]
+======Remainder======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)]
+======Ceiling======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)]
+======Floor======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)]
+======Rount======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)]
+======Arc Tangent Rectangular======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)]
+======Power======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)]
+======Absolute Value======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)]
+======Maximum======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)]
+======Minimum======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)]
+======ULP======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)]
+======Sign======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)]
+======Hyperbolic Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)]
+======Hyperbolic Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)]
+======Hyperbolic Tan======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)]
+======Hypotuneuse======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)]
+======Expm1======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)]
+======Log1p======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)]
+
====Random====
-=====Random In Range=====
+
+=====Design=====
+
+Random functions are especially significant for agent models. Of particular interest are the weighted membership and random state and boolean value functions. You should be familiar with these functions so that you don't have to create more complex Action flows to accomplish the same thing.
+
+Note that we only have support for uniform distributions as of this release. We're working on a collaborative design for evaluations that allow easy mixing and matching of random functions and distributions.
+
+=====Details=====
+
+======Random In Range======
A pseudo-random value within that numeric range specified as drawn from a uniform distribution. The minimum values are inclusive. The maximum values are inclusive for integer inputs and exclusive for Real inputs.
Inputs:
[Numeral] The minimum value (inclusive).
[Numeral] The maximum value (inclusive).
Outputs:
[Numeral] The random number.
-=====Random To Limit=====
+======Random To Limit======
A pseudo-random value between zero and the value specified by the (non-zero) input and drawn from a uniform range. That value is inclusive for Integers and exclusive for Reals. (Note that as with the random in range function in the context of real numbers the distinction between an exclusive and inclusive limit is essentially meaningless.)
Inputs:
[Numeral] The maximum value (inclusive).
Outputs:
[Numeral] The result.
-=====Random Unit=====
+======Random Unit======
A pseudo-random Real value between 0 and 1 drawn from a uniform distribution. (The distinction between inclusive and exclusive range is essentially meaningless in this context and we can assume that the result will never be greater or equal to 1.)
Outputs:
[Real]
-=====Random Boolean=====
+======Random Boolean======
A value that is randomly true or false, i.e. a fair coin toss.
-=====Random Weighted=====
+======Random Weighted======
An indexed value weighted against a probability distribution. The total probability must sum to 1.0. For example, an input of {.1,.2,.7} under a uniform distribution would would have 10% probability of producing "0" , 20% for "1" and 70% for "2". This function can then be used with Item to return a biased result from another list.
Inputs:
[Real] A list of values that will determine the resulting weighted index.
Outputs:
[Integer] A resulting indexed value bounded by 0 and the length of the input list - 1.
-=====Random Member=====
+======Random Member======
Represents a random value drawn from the set of Real values specified.
Inputs:
[Real] Returns a random member of the supplied list of numbers.
Outputs:
[Generic] The value of the item at a random index.
-=====Random State=====
+======Random State======
A random specified value (option) from the specified state.
Inputs:
[Generic] The state to select items from. All items are included.
Outputs:
[Boolean] The resulting option.
-====Graphic====
-=====Shape Oval=====
+
+====Space====
+
+=====Design=====
+
+Spatial functions provide the core functionality for Agent Models. Spatial functions are polymorphic, which basically means that they don't care what space they are operating on as long as that space is suitable for them. Spatial functions are designed to collaborate with one another. For example, by intersecting the "Neighbor", "Available" and "Toward" functions, we can design a rule that causes the agent to move to the next neighboring cell that get's it closer to some target agent. See the function details for more information.
+
+=====Details=====
+
+======Nearest ======
+Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.
+======Toward======
+Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.
+======Within======
+Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.
+ Inputs:
+ [Numeral]
+======Neighbor======
+Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.
+======Include Self======
+Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.
+======Within 2D Boundary======
+Represents agents or locations that exist within the boundary specified by the inputs.
+ Inputs:
+ [Numeral]
+======Here======
+Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used.
+======Available======
+Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.
+======Distance======
+The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.
+ Outputs:
+ [Real]
+======Away======
+Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.
+======Minimize======
+This function is not currently supported.
+======Maximize======
+This function is not currently supported.
+======Location 2D======
+Represents the location of the current agent for use in subsequent selections.
+ Inputs:
+ [Real]
+ [Real]
+======Boundary 2D======
+Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)
+ Outputs:
+ [Real]
+ [Real]
+
+=====Example=====
+
+For examples of how spatial functions can be used within action flows to provide agents with complex movement behaviors, see the Modelers Guide actions examples. In the following example from that section, we define an action that causes a partner agent to move to an available neighboring space.
+
+[[Image:images/ActionsExampleNew.png|800px]]
+
+====Time====
+=====Details=====
+
+======Now======
+The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.
+ Outputs:
+ [Integer] The current period.
+
+====Graphics====
+
+=====Design=====
+
+Graphic functions are combined within Style Evaluate Actions to determine how to draw an agent within a visualization. One nice aspect of this approach is that the same style definition can be used in multiple places without changing any code. For example, the same style could be used to draw an agent on a two-dimensional grid within Escape, a three-dimensional shape within Escape, a Java Swing based visualization in Ascape, and an XML configured visualizaiton in Repast Simphony.
+
+To define a graphic style for an agent, design a flow in which you create Evaluate Actions for color and shape, and then create an Evaluate Action with the graphic fill or outline function as a target of these.
+
+=====Details=====
+
+======Shape Oval======
Draw a generic oval.
-=====Shape Rectangle=====
+======Shape Rectangle======
Draws a rectangular shape.
-=====Shape Inset=====
+======Shape Inset======
Shrinks the current shape by the input amount. (The overall scale is currently unspecified, but in most implementations should be 20.)
Inputs:
[Integer] Number of nominal pixels to inset.
-=====Shape Marker=====
-Draw a marker, that is a graphical indicator that can be used to add an additional que about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape.
-=====Shape Marker 2=====
+======Shape Marker======
+Draw a marker, that is a graphical indicator that can be used to add an additional cue about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape.
+======Shape Marker 2======
Represents a marker placed in a different location from the other shape markers.
-=====Shape Marker 3=====
+======Shape Marker 3======
Represents a marker placed in a different location from the other shape markers.
-=====Color RGB=====
+======Color RGB======
A color specified by the three inputs for Red, Green and Blue color components. Those inputs are expected to be in the range 0..1.
Inputs:
[Real] A value from 0.0 to 1.0.
[Real] A value from 0.0 to 1.0.
[Real] A value from 0.0 to 1.0.
-=====Color Red=====
+======Color Red======
The color red.
-=====Color Yellow=====
+======Color Yellow======
The color yellow.
-=====Color Blue=====
+======Color Blue======
The color blue.
-=====Color Orange=====
+======Color Orange======
The color orange.
-=====Color Green=====
+======Color Green======
The color green.
-=====Color Purple=====
+======Color Purple======
The color purple.
-=====Color Black=====
+======Color Black======
The color black.
-=====Color White=====
+======Color White======
The color white.
-=====Color Gray=====
+======Color Gray======
The color gray.
-=====Graphic Outline=====
+======Graphic Outline======
Draws an outline of the last evaluated shape, using the last specified color or the default color (usually black) if none has been specified.
-=====Graphic Fill=====
+======Graphic Fill======
Fills the last evaluated shape with the last specified color or the default color (usually black) if none has been specified.
-====Time====
-=====Now=====
-The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.
- Outputs:
- [Integer] The current period.
-====Math====
-=====Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)]
-=====Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)]
-=====Tangent=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)]
-=====Arc Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)]
-=====Arc Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)]
-=====Arc Tangent=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)]
-=====Convert Degree to Radians=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)]
-=====Convert Radians to Degrees=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)]
-=====Exp=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)]
-=====Log=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)]
-=====Log b10=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)]
-=====Square Root=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)]
-=====Cube Root=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)]
-=====Remainder=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)]
-=====Ceiling=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)]
-=====Floor=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)]
-=====Rount=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)]
-=====Arc Tangent Rectangular=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)]
-=====Power=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)]
-=====Absolute Value=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)]
-=====Maximum=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)]
-=====Minimum=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)]
-=====ULP=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)]
-=====Sign=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)]
-=====Hyperbolic Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)]
-=====Hyperbolic Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)]
-=====Hyperbolic Tan=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)]
-=====Hypotuneuse=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)]
-=====Expm1=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)]
-=====Log1p=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)]
-====List====
-=====Item=====
+
+=====Example=====
+
+In the following action flow for the epidemic style, we've create Query Actions to determine each agent's current state, picked a color based on that, and then used a shared target to select a shape for the agent style and fill it:
+
+[[Image:images/GraphicsFunctionExampleDesign.png]]
+
+After saving the model we can execute the two and three dimensional visualizations. Note something really nice -- even the charts have used the colors we've defined!
+
+[[Image:images/GraphicsFunctionExampleRun.png]]
+
+====Lists====
+
+=====Details=====
+
+======Item======
Returns the item at the specified index from the list of items provided. Those items will typically be input primitives such as Integer or Real values.
Inputs:
[Generic]
[Integer]
Outputs:
[Generic]
-=====Length=====
+======Length======
The number of items in the provided list of items.
Inputs:
[Generic]
Outputs:
[Integer]
-====Distribution====
-=====Uniform Cross Distribution=====
+
+====Attribute Distributions====
+
+One of the most common tasks in the Agent Modeling process is the creation of agents with particular states drawn from a distribution. For example, you might want to create a number of agents with wealth randomly distributed between some minimum and maximum values. The distribution functions greatly ease the process of setting up those initializations and their associated parameters.
+
+=====Distribution=====
+======Uniform Cross Distribution======
A random number taken from a distribution of values as defined by a cross of all values. (See Cross Distribution.) This funciton then returns a value drawn from the minimum and maximum values as determined by the current agent state. In the cross distribution, each of the values is treated independently so that an input attribute is created for every potential combination of states.
Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
@@ -860,7 +965,7 @@
[Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting random number based on the current agent state and the input parameters.
-=====Uniform Additive Distribution=====
+======Uniform Additive Distribution======
A random number taken from a distribution of values in which each of the minimum and maximum values are added to determine a total minimum and maximum value. (See Additive Distribution.) In the additive distribution, each of the values is treated as dependent on the others so that an input attribute is only created for each seperate state.
Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
@@ -868,14 +973,14 @@
[Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting random number based on the current agent state and the input parameters.
-=====Cross Distribution=====
+======Cross Distribution======
A value taken from a set of (auto-generated) attributes based on the value of each state included. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create separate input attributes for AI, AII, BI and BII. Then for an agent with States A and II this function would return the value specified by the AII input attribute.
Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
[Real] The set of attributes that when multiplied against each other will determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting value based on the current agent state and the input parameters.
-=====Additive Distribution=====
+======Additive Distribution======
A value taken from a set of (auto-generated) attributes based on the combined values of the states provided. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create input attributes for A, B, I and II. Those values would then be added together, so that for an Agent with state A and II this function would return A + II.
Inputs:
[Generic] The states to include in the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
@@ -883,10 +988,195 @@
Outputs:
[Real] The resulting value based on the current agent state and the input parameters.
-===Diagrams===
+=====Example=====
+
+In the following example, we walk through the process of using a distribution functions, demonstrating how we can easily modify the Epidemic model so that instead of simply setting an initial exposed population, we can define factors that take together will determine an individuals initial exposure state. We simply:
+
+# Create an Evaluate Action called "Initial Status".
+# Set the function to "Cross Distribution"
+# Opened the "Multiple Value" node in the editor, and clicked the "Multiple Values" item within it.
+# Selected the "Status" attribute.
+
+[[Image:images/DistributionDesignChoice.png]]
+
+The appropriate attributes are automatically added to the model, as you can see below.
+
+[[Image:images/DistributionDesign.png]]
+
+In order to assign these values to the agent, we'd simply need to assign the results of this Evaluate Action to the agent.
+
+====Diagrams====
The following diagram may be helpful to readers familiar with UML and Meta-modeling:
-====Meta-Classes====
+=====Meta-Classes=====
[[Image:images/FunctionsDiagram.png]]
+=Creating Agent Models=
+
+==Getting Started==
+
+=Exploring Agent Models=
+=Programer's Guide=
+
+==Overview==
+
+Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based API and end user modeling tools. It's based on Ascape, which has been in use for more than 10 years. The core API is very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then execute those models within the same development environment.
+
+[[image:EscapeExecutionScreenshot.png]]
+
+A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM toolkit -- is to provide an exemplar to demonstrate how any arbitrary agent modeling framework can be integrated within the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than ten years ago and that has not been modified at all in order for it to work within the AMP environment.
+
+(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and AGF components.)
+
+==Getting Started==
+
+===Documentation and other Resources===
+
+Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation. There is complete Javadoc as well as a manual and other web resources. See the [http://ascape.sourceforge.net Ascape Website] to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape so ignore all of the bits about project setup, and a lot of the UI is different, but the basics apply to Escape just as well. The [http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf Ascape Manual] written by Damon Centola should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual work under Ascape. (Converting these models is a great opportunity for a community contribution!)
+
+==Installation==
+
+Escape is [http://eclipse.org/amp/installing/ installed] by default with the other model components. If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from source but in that case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site if you're not actually doing AMP development.
+
+
+==Exploring Example ABM Models==
+
+The first thing most people will want to do in AMP is to play with the example models. You don't need to do any programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is [http://eclipse.org/amp/installing Install AMP]. (You don't need any of the optional components unless you want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really interesting classic ABM models.
+
+===AMF Models===
+
+There are a number of models developed with AMF that can automatically generate example models to run in Escape. There are two ways to run the example models:
+
+====Setup Escape Projects====
+
+=====Creating a New Escape Project=====
+
+The best option is to simply create a new Escape project and drag the models into it! We're working on a simple cheat sheet for this, but until then, just follow these simple steps:
+
+#If you're not already there, open the Agent Modeling Perspective. Select Window > Open Perspective > Other.. and then Agent Modeling. (Or you can choose Window > Reset Perspective and the Agent Modeling perspective should appear in the Open Perspective list itself.)
+#Next, let's create the project where we'll place our model. Select File > New > Escape AMF Project. Give it a name like "escape.tutorial", then click Finish.
+#Finally grab the Epidemic.metaabm model at http://download.eclipse.org/amp/models/Epidemic.metaabm and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in which case just right-click on the link and save it to a file.)
+
+=====Using an Pre-Built Example Project=====
+
+If you get really stuck somewhere, you can also get ready made projects from CVS. See [http://eclipse.org/amp/developers/repositoryDetails.php this page] for information on CVS setup. The project for Escape example models are located at:
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
+
+====Run the Model====
+
+Right-click on the model, and select "Execute"! You should see something like this:
+
+[[image:EpidemicModelRunning.png]]
+
+We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory. The toolbar buttons allow you to control model execution.
+
+[[image:EpidemicModelControls.png]]
+
+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.
+
+[[image:EpidemicModelComparison.png]]
+
+If you want to find out more about an agent, show the properties view, and click on agent.
+
+[[image:EpidemicModelAgentProperties.png]]
+
+You can experiment with different parameters (settings) for models by then clicking in the gray area away within the view.
+
+[[image:EpidemicModelProperties.png]]
+
+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.
+
+====Next Steps====
+
+Other models are located at: (to do)
+
+To understand the capabilities of AMF, you might also want to try out running the same models automatically generated for Ascape or Repast.
+
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
+
+===Classic Java ABM Models===
+
+Many models have been created using Ascape over the years, including all of the classic models created at Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've all been converted to run in Escape. They're in Java but you can execute and explore them in exactly the same way as the Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You can get the projects in two ways:
+
+====From Project Archive====
+*Download the Escape examples zip from the Ascape sourceforge site: [http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download]
+*Unzip the file.
+*Import them into your workspace. For help, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html this page].
+====From SVN====
+*Import the SVN projects from the sourceforge SVN. For help, see [[http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php this page]].
+ http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
+ http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
+
+Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models. For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select "Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)
+
+==Developing Models==
+
+The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write programs using it.To develop new models, you can:
+
+# Create a new Escape project. The Escape projects are actually configured for AMF code generation so there are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.
+# But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have a look at the example escape project to see what you need. Note that you will likely need more dependencies then you need to simply build -- this is because the class loader uses the classes from the project path and so runtime classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these dependencies up a bit.
+
+Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.
+
+=Reference=
+
+==Converting Existing Ascape models==
+
+There are only a few changes should have to make to existing Ascape models or to use existing Ascape documentation to develop Escape models.
+
+====Model====
+
+The core model is completely API compatible. No changes!
+
+====View====
+
+Because Escape uses SWT and Ascape uses Swing, there are a few unavoidable incompatibilities. Most of these we avoid by using higher level APIs but here are the key changes that you're likely to have to make:
+
+=====Convert the low-level imports from AWT and Swing to SWT=====
+The simplest way to accomplish this is to remove all of the imports and then organize imports. For example:
+ java.awt.Color => org.eclipse.swt.graphics.Color
+ java.awt.Graphics => org.eclipse.draw2d.Graphics
+Then just do a global find for all of the imports and replace them with nothing. This is a great place for a regexp. Try:
+ find: import java\.awt\.(.*);
+ replace: [nothing]
+You don't have to replace these with the SWT equivalents, just click on the project, right-click and choose "Source:Organize Imports.."
+By the way, a great way to avoid having to select the right entries in optimize imports and to alert you when you have missed anything is to prevent the awt and swing classes from being used at all. Right-click on project, choose "Build Path:Configure Build Path", go to Libraries tab, open JRE System Library, choose "Access Rules", edit, and then add entries for java/awt/** and javax/swing/**. The code will regenerate and you'll have error markers for all of the stuff that won't work with Escape and Eclipse.
+=====Convert color features=====
+You can't use AWT colors either so you'll need to replace any colors. AMP provides a convenience classes for Colors called ColorFeature and ColorFeatureConcrete. You can use these or any of the other ways to define SWT colors. For example:
+ Color.lightGray => ColorFeature.LIGHT_GRAY
+ new Color(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy) =>
+ ColorFeatureConcrete.create(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy)
+=====Change agent color getters=====
+If you've defined colors through overriding Agents as in most models, you'll need to change the method signature. You could just do a global replace for this one.
+ public Color getColor( => public Object getPlatformColor(
+=====Get rid of image features=====
+Escape doesn't support them. In practice they haven't been used a lot. At some point perhaps we'll have nice sprite support instead. :)
+ public Image getImage() {**} => ""
+=====Modify usages of DrawFeatures=====
+If you've created any of your own draw features, you'll need to change them slightly to accommodate the differences between the AWT and SWT / Draw2D APIs. This should be pretty straightforwrd. For example:
+ g.setColor(...
+ g.fillOval(..
+ becomes:
+ g.setBackgroundColor(
+ g.fillOval(..
+
+That's about it, though it's probable that we've missed something. Please post a message on the amp newsgroup if you run into any other conversion issues.
+
+====Configuration====
+
+Instead of using Ant, Escape has really nice support for parameterizing and testing models. See [[Experimenting and Testing]] (todo). If you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape so it's not even clear it will work.
+=More Information=
+
+==Obtaining Example Models==
+
+There is a cheat-sheet available for obtaining the example models. If you would rather obtain them yourself, here is the CVS information:
+
+====Import from CVS====
+*Import the CVS projects from the AMP project repository. For help, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm this page]. For repository details, see [http://eclipse.org/amp/developers/repositoryDetails.php http://eclipse.org/amp/developers/repositoryDetails.php]. These are the example projects:
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
+*Right-click on the models to execute them.
+*Play around with the model attribute settings and behavior (Acts).
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.xml
index b3d16fd..8e63885 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.xml
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/build/amp.xml
@@ -1,360 +1,590 @@
<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<title>Agent Modeling Guide</title>
- <chapter id="Introduction">
- <title>Introduction</title>
- <para>In this Modeler's Guide we provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design one. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Attributes, Spaces, and Actions. The first three refer to structural components, whereas Actions define behavior. Agent models also have styles, which are a special kind of Action used to determine how to portray an agent in a visualization. Finally Actions make use of Functions. We'll describe of these components in a separate section.</para>
- <para>But first, we'll give a quick overview at what agent-based modeling is is and how the Agent Modeling Framework can help you to develop models for ABM or other problem domains.</para>
- <section id="Agent-Based_Modeling">
- <title>Agent-Based Modeling</title>
- <para>The primary focus of the Agent Modeling Platform tools is "Agent-Based Modeling" (ABM). ABM is an innovative technique used to explore complex phenomenon in many domains, including economics, social sciences, biomedicine, ecology and business operations. ABMs share characteristics with object models, but are:</para>
- <variablelist>
- <varlistentry>
- <term>Spatial</term>
- <listitem>
- <para>Models have explicit environment(s) in which agents interact. (An environment need not be a physical landscape; other examples of spatial relationships include social networks or positions within a logic system.)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Temporal</term>
- <listitem>
- <para>Models change over discrete units of time.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Autonomous</term>
- <listitem>
- <para>Agent behaviors are activated independently from other object requests.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Heterogeneous</term>
- <listitem>
- <para>Agents may share behavior definitions but have apparent and distinct states and behaviors.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Collective</term>
- <listitem>
- <para>Models contain large communities of agents which exhibit collaborative and competitive behaviors.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Emergent</term>
- <listitem>
- <para>Agents have collective macro-behaviors that are non-obvious from agent micro-specifications.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Existing scientific models are very good at representing relatively simple systems, but generally speaking aren't very good at representing complex systems. The world is full of complex systems, and our misunderstanding of these systems has prevented us from addressing many of the key challenges facing the world, including the global financial crisis and climate change -- in fact once could argue that our misunderstanding of these systems has strongly contributed to these crises.</para>
- <para>Agent-Based Models (ABMs) seek to represent important real-world dynamics by designing communities of software agents that mimic real entities. Rather than make simplifying assumptions about such systems and then representing them in equation form or as off the shelf algorithmic constructs, the ABM researcher aims to identify key agent state, interaction spaces, and behaviors. Agents are then "let loose" on our computers and we explore what happens next. The computational horsepower exists today to simulate large numbers (e.g. >>10) of interacting, adaptive and autonomous agents but often desktop computers are all we need to explore significant domains. ABMs have been designed to represent all kinds of important natural systems, at scales reaching from cellular mechanics to international trade and are being used to solve truly hard problems in government, business, and academia. ABMs are not a solution to every problem, but they can help us to appreciate and gain unique insight into many systems, and often they can help us to come up with better practical decisions than we might using classic approaches.</para>
- </section>
- <section id="Agent_Modeling_Framework">
- <title>Agent Modeling Framework</title>
- <para>The Eclipse Platform provides many unique features that make it ideal for an ABM platform. AMF provides easy to use and powerful tools and techniques for designing Agent-Based Models, including a common representation, editors, generators and development environment.</para>
- <para>The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level. For those familiar with Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. The AMF meta-model (currently "MetaABM", but in the process of evolving to a new compatible "Acore" specification) is defined in Ecore but provides a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms.</para>
- <para>Models designed in AMF are transparently converted to Java code for leading Agent-Based Modeling tools, such as the Escape tools which are included in AMP and allow direct execution of models within the AMP environment, and Repast Simphony, another popular Java based ABM tool. These tools create Java code that can then be compiled, executed and event modified in these environments just as with any other Java program. AMF's generative capability is designed to be pluggable and modular so that other developers can create AMF generators for their own tools. In fact, targets can be designed that have no inherent dependencies on Eclipse or even on a traditional platform.</para>
- </section>
- <section id="Other_Uses">
- <title>Other Uses</title>
- <para>Many kinds of objects share characteristics of ABM agents -- after all, software agents are used in many other contexts. The Agent Modeling Framework meta-modeling support is potentially suitable (or extendible) for a number of approaches outside of ABM; for example business rules, object interactions, systems dynamics models and traditional discrete event models. Similarly, AMP execution and graphic support can be used for modeling natural systems but could also be used to manage other software agents -- for example independent reasoning tasks or dynamic visualization support.</para>
- <para>We hope you enjoy using the tool, and we look forward to your comments and feedback and most of all participation!</para>
+ <chapter id="Overview">
+ <title>Overview</title>
+ <para>The Eclipse Agent Modeling Project (AMP) provides extensible frameworks and exemplary tools for representing, editing, generating,
+ executing and visualizing agent-based models (ABMs) and any other domain requiring spatial, behavioral and functional features. </para>
+ <section id="Architecture">
+ <title>Architecture</title>
+ <para>AMP has two main themes that complement but don't depend on one another: </para>
+ <para>The overall AMP architecture and Eclipse project dependencies are summarized below:</para>
+ <para>
+ <ulink url="/wiki/image:AMPArchitectureDiagram.jpg">image:AMPArchitectureDiagram.jpg</ulink>
+ </para>
</section>
</chapter>
- <chapter id="Structure">
- <title>Structure</title>
- <section id="Design">
- <title>Design</title>
- <para>The basic structure of an agent-based model can be quite simple. While there are many subtle complexities -- beyond the scope of this manual -- we can construct most models following some straightforward and elegant design principles. And in fact, one of the main goals of the Agent Modeling Framework is to provide a consistent framework that can support using those principles to support the creation of models that can be easily understood, shared, and that can be used interchangeably as components in other models.</para>
- <para>Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents.</para>
+ <chapter id="Getting_Started">
+ <title>Getting Started</title>
+ <para>AMP has many potential facets and use cases. Here are a few ways to get started with it.</para>
+ <para>First, if you aren't using a full download version of AMP, you'll need to
+ <ulink url="http://eclipse.org/amp/installing/">install it</ulink>. Then...
+ </para>
+ <section id="ABM_Modelers">
+ <title>ABM Modelers</title>
+ <para>Experiment with example Java and AMF based models without writing code.</para>
+ <para>
+ <ulink url="/wiki/AMP/Running_Examples">Run Example Models</ulink>
+ </para>
</section>
- <section id="Details">
- <title>Details</title>
- <section id="General">
- <title>General</title>
- <para>Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore -- including Actions and Functions which we describe in the next two sections -- have a number of shared values.</para>
- <section id="Named_Entities">
- <title>Named Entities</title>
- <section id="Label">
- <title>Label</title>
- <para>A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Exchange Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.</para>
+ <section id="ABM_Researchers">
+ <title>ABM Researchers</title>
+ <para>Create Agent-Based models using simple visual tools and deploy them to a number of popular ABM platforms, including Escape.</para>
+ <para>
+ <ulink url="/wiki/AMP/UserGuide/AMF#Getting_Started">Modeling with AMF</ulink>
+ </para>
+ </section>
+ <section id="ABM_Java_Developers">
+ <title>ABM Java Developers</title>
+ <para>Write POJO Java models within a full-featured agent-based modeling framework.</para>
+ <para>
+ <ulink url="/wiki/AMP/UserGuide/Escape#Getting_Started">Programming with Escape</ulink>
+ </para>
+ </section>
+ <section id="Eclipse_Plugin_Developers">
+ <title>Eclipse Plugin Developers</title>
+ <para>AXF and AGF provide a number of features based around Eclipse technologies such as GEF, GEF3D, BIRT Charts and Zest. For example, AGF supports dynamic visualization of objects in space, and AXF supports managed UI and headless execution for models of any kind.</para>
+ <para>
+ <ulink url="/wiki/AMP/AGF_AXF_API">Programming with AXF and AGF</ulink> (todo)
+ </para>
+ </section>
+ </chapter>
+ <chapter id="Modeler.27s_Guide">
+ <title>Modeler's Guide</title>
+ <section id="Introduction">
+ <title>Introduction</title>
+ <para>In this Modeler's Guide we provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design one. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Attributes, Spaces, and Actions. The first three refer to structural components, whereas Actions define behavior. Agent models also have styles, which are a special kind of Action used to determine how to portray an agent in a visualization. Finally Actions make use of Functions. We'll describe of these components in a separate section.</para>
+ <para>But first, we'll give a quick overview at what agent-based modeling is is and how the Agent Modeling Framework can help you to develop models for ABM or other problem domains.</para>
+ <section id="Agent-Based_Modeling">
+ <title>Agent-Based Modeling</title>
+ <para>The primary focus of the Agent Modeling Platform tools is "Agent-Based Modeling" (ABM). ABM is an innovative technique used to explore complex phenomenon in many domains, including economics, social sciences, biomedicine, ecology and business operations. ABMs share characteristics with object models, but are:</para>
+ <variablelist>
+ <varlistentry>
+ <term>Spatial</term>
+ <listitem>
+ <para>Models have explicit environment(s) in which agents interact. (An environment need not be a physical landscape; other examples of spatial relationships include social networks or positions within a logic system.)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Temporal</term>
+ <listitem>
+ <para>Models change over discrete units of time.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Autonomous</term>
+ <listitem>
+ <para>Agent behaviors are activated independently from other object requests.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Heterogeneous</term>
+ <listitem>
+ <para>Agents may share behavior definitions but have apparent and distinct states and behaviors.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Collective</term>
+ <listitem>
+ <para>Models contain large communities of agents which exhibit collaborative and competitive behaviors.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Emergent</term>
+ <listitem>
+ <para>Agents have collective macro-behaviors that are non-obvious from agent micro-specifications.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Existing scientific models are very good at representing relatively simple systems, but generally speaking aren't very good at representing complex systems. The world is full of complex systems, and our misunderstanding of these systems has prevented us from addressing many of the key challenges facing the world, including the global financial crisis and climate change -- in fact once could argue that our misunderstanding of these systems has strongly contributed to these crises.</para>
+ <para>Agent-Based Models (ABMs) seek to represent important real-world dynamics by designing communities of software agents that mimic real entities. Rather than make simplifying assumptions about such systems and then representing them in equation form or as off the shelf algorithmic constructs, the ABM researcher aims to identify key agent state, interaction spaces, and behaviors. Agents are then "let loose" on our computers and we explore what happens next. The computational horsepower exists today to simulate large numbers (e.g. >>10) of interacting, adaptive and autonomous agents but often desktop computers are all we need to explore significant domains. ABMs have been designed to represent all kinds of important natural systems, at scales reaching from cellular mechanics to international trade and are being used to solve truly hard problems in government, business, and academia. ABMs are not a solution to every problem, but they can help us to appreciate and gain unique insight into many systems, and often they can help us to come up with better practical decisions than we might using classic approaches.</para>
+ </section>
+ <section id="Agent_Modeling_Framework">
+ <title>Agent Modeling Framework</title>
+ <para>The Eclipse Platform provides many unique features that make it ideal for an ABM platform. AMF provides easy to use and powerful tools and techniques for designing Agent-Based Models, including a common representation, editors, generators and development environment.</para>
+ <para>The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level. </para>
+ <para>The foundation of the Agent Modeling Framework is "Acore". The current version uses an interim version of Acore called "MetaABM". We refer to the AMF models as "meta-models" because they are used to define
+ <emphasis role="italic">how</emphasis> Agent-Based Models are themselves modeled. For those familiar with Eclipse Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. Acore and MetaABM are defined in Ecore but provide a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms. AMF is fully integrated with the Eclipse IDE platform, but Acore models themselves need have no dependencies on any particular technology beyond XML/XSD.
+ </para>
+ <para>Models designed in AMF are transparently converted to Java code for leading Agent-Based Modeling tools, such as the Escape tools which are included in AMP and allow direct execution of models within the AMP environment, and Repast Simphony, another popular Java based ABM tool. These tools create Java code that can then be compiled, executed and event modified in these environments just as with any other Java program. AMF's generative capability is designed to be pluggable and modular so that other developers can create AMF generators for their own tools. In fact, targets can be designed that have no inherent dependencies on Eclipse or even on a traditional platform.</para>
+ <para>The Acore / MetaABM meta-model is made up of three main packages. This is all based on MetaABM, and while names and important details will change for Acore, the core design should be quite similar.</para>
+ </section>
+ <section id="Other_Uses">
+ <title>Other Uses</title>
+ <para>Many kinds of objects share characteristics of ABM agents -- after all, software agents are used in many other contexts. The Agent Modeling Framework meta-modeling support is potentially suitable (or extendible) for a number of approaches outside of ABM; for example business rules, object interactions, systems dynamics models and traditional discrete event models. Similarly, AMP execution and graphic support can be used for modeling natural systems but could also be used to manage other software agents -- for example independent reasoning tasks or dynamic visualization support.</para>
+ <para>We hope you enjoy using the tool, and we look forward to your comments and feedback and most of all participation!</para>
+ </section>
+ <section id="Credits">
+ <title>Credits</title>
+ <para>The AMF meta-model started life as
+ <ulink url="/wiki/http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf">"score"</ulink>, a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continues development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009.
+ </para>
+ <para>Miles Parker is a consultant and software developer with over ten years of experience in the agent-based modeling field and twenty years developing object-oriented tools and frameworks. Metascape, LLC provides Agent-Based Modeling tools, including sophisticated tools based on the AMF platform, and comprehensive consulting services. For more information on Metascape products and services visit
+ <ulink url="http://metascapeabm.com">http://metascapeabm.com</ulink>.
+ </para>
+ </section>
+ </section>
+ <section id="Structure">
+ <title>Structure</title>
+ <section id="Overview_2">
+ <title>Overview</title>
+ <para>The basic structure of an agent-based model can be quite simple. While there are many subtle complexities -- beyond the scope of this manual -- we can construct most models following some straightforward and elegant design principles. And in fact, one of the main goals of the Agent Modeling Framework is to provide a consistent framework that can support using those principles to support the creation of models that can be easily understood, shared, and that can be used interchangeably as components in other models.</para>
+ <para>Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents.</para>
+ </section>
+ <section id="Details">
+ <title>Details</title>
+ <section id="General">
+ <title>General</title>
+ <para>Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore -- including Actions and Functions which we describe in the next two sections -- have a number of shared values.</para>
+ <section id="Named_Entities">
+ <title>Named Entities</title>
+ <section id="Label">
+ <title>Label</title>
+ <para>A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Exchange Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.</para>
+ </section>
+ <section id="ID">
+ <title>ID</title>
+ <para>An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)</para>
+ <para>And most entities also define:</para>
+ </section>
+ <section id="Description">
+ <title>Description</title>
+ <para>A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.</para>
+ </section>
+ <section id="Plural_Label">
+ <title>Plural Label</title>
+ <para>The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".</para>
+ </section>
</section>
- <section id="ID">
- <title>ID</title>
- <para>An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)</para>
- <para>And most entities also define:</para>
+ </section>
+ <section id="Agents">
+ <title>Agents</title>
+ <section id="Simple_Agents">
+ <title>Simple Agents</title>
+ <para>An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.</para>
+ <section id="Attributes">
+ <title>Attributes</title>
+ <para>As described in the attribute sections above.</para>
+ </section>
+ <section id="Actions">
+ <title>Actions</title>
+ <para>Described in the "Actions" section.</para>
+ </section>
+ <section id="Styles">
+ <title>Styles</title>
+ <para>Special actions that are used to define how to draw an agent graphically as also described in the "Actions" section and detailed in the "Functions" section.</para>
+ </section>
</section>
- <section id="Description">
- <title>Description</title>
- <para>A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.</para>
+ <section id="Context_Agents_.28Contexts.29">
+ <title>Context Agents (Contexts)</title>
+ <para>As detailed above, agents also form the basic structural component of an agent-based model. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".</para>
+ <section id="Agents_2">
+ <title>Agents</title>
+ <para>The agents that are contained within this context. For example, a context representing a city might contain an Individual Agent for defining all individuals in the model, and a Vehicle agent defining all vehicles. Note that when we refer to an agent in this context, we mean a general type or class of agent, not the agent itself.</para>
+ </section>
+ <section id="Spaces">
+ <title>Spaces</title>
+ <para>The set of all spaces contained or subsumed by the agent. For example, a context representing a city might contain a geographical space and a transportation network space.</para>
+ </section>
</section>
- <section id="Plural_Label">
- <title>Plural Label</title>
- <para>The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".</para>
+ </section>
+ <section id="Attributes_2">
+ <title>Attributes</title>
+ <para>Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.</para>
+ <para>Here are the basic types of attributes available in Acore models:</para>
+ <section id="Basic_Attributes">
+ <title>Basic Attributes</title>
+ <para>Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. In this section we go over the values you can set for the attributes. For those with a tecnical bent, note that we are technically describing the meta-attributes for the meta-class "SAttribute". But it is far too confusing to refer to the attributes of attributes! So we'll just refer to the attributes that any of our model components as "values".</para>
+ <section id="Type">
+ <title>Type</title>
+ <para>These can be anyone of the following: </para>
+ <informaltable>
+ <tr>
+ <td>Boolean</td>
+ <td>A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.</td>
+ </tr>
+ <tr>
+ <td>Integer</td>
+ <td>A discrete whole number value, such as "100", "-1", "10029920". It's generally a good idea to represent any value that can never have a decimal value as an integer.</td>
+ </tr>
+ <tr>
+ <td>Real</td>
+ <td>A continuous number value. While these are typically represented in software as floating point numbers, they can conceivably represent numbers at any arbitrary precision and in any scheme. Note that while technically speaking we should be representing irrational numbers, this is not currently supported for default values and users should simply use the closest decimal approximation.</td>
+ </tr>
+ <tr>
+ <td>Symbol</td>
+ <td>A string representing some state. More precisely, a computationally arbitrary value with contextual meaning. This could be any kind of identifier. For example, you might use it to store some kind of input coding from data that is then converted into an object state. Or it could simply be an agent's name. But theoretically (though this is not currently supported) one could imagine a symbol using an idiogram, an icon or even a sound that identifies or represents the agent in question.</td>
+ </tr>
+ </informaltable>
+ <para>(Undefined and Numeric types should not be used within a well-defined model.)</para>
+ </section>
+ <section id="Default_Value">
+ <title>Default Value</title>
+ <para>The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.</para>
+ </section>
+ <section id="Gather_Data">
+ <title>Gather Data</title>
+ <para>Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.</para>
+ </section>
+ <section id="Immutable">
+ <title>Immutable</title>
+ <para>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.</para>
+ </section>
+ <section id="Units">
+ <title>Units</title>
+ <para>Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.</para>
+ </section>
+ </section>
+ <section id="Arrays">
+ <title>Arrays</title>
+ <para>Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to what is defined above, arrays specify:</para>
+ <section id="Size">
+ <title>Size</title>
+ <para>The number of values that the array attribute will contain.</para>
+ </section>
+ </section>
+ <section id="States">
+ <title>States</title>
+ <para>States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".</para>
+ <section id="State_Options">
+ <title>State Options</title>
+ <para>Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have</para>
+ </section>
+ <section id="Default_Option">
+ <title>Default Option</title>
+ <para>unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.</para>
+ </section>
+ </section>
+ </section>
+ <section id="Spaces_2">
+ <title>Spaces</title>
+ <para>All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:</para>
+ <section id="Space_.28Continuous.29">
+ <title>Space (Continuous)</title>
+ <para>In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.</para>
+ <section id="Border_Rule">
+ <title>Border Rule</title>
+ <para>A value representing what happens to an agent when that agent is asked to move beyond its extent.</para>
+ <variablelist>
+ <varlistentry>
+ <term>Periodic</term>
+ <listitem>
+ <para>When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location {1,2} (0-based) within a Moore space (see grid discussion below) of size {10,10} is asked to find some other agent within distance 3, the agent look in the square defined between {8,9} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>APeriodic</term>
+ <listitem>
+ <para>When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location {1,2} is asked to find some other agent within distance 3, the agent look between {0,0} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>The "Strict" and "Bouncy" values are obsolete and should not be used.</para>
+ </section>
+ <section id="Dimensionality">
+ <title>Dimensionality</title>
+ <para>The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attribute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.</para>
+ </section>
+ </section>
+ <section id="Grid">
+ <title>Grid</title>
+ <para>A grid is technically a regular lattice structure. Currently, only rectilinear structures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platforms support n-d spaces yet.) </para>
+ <para>Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:</para>
+ <section id="Multi-Occupant">
+ <title>Multi-Occupant</title>
+ <para>Does the grid allow more than one agent to occupy it at a time? This value may be replaced with another mechanism in future releases.</para>
+ </section>
+ <section id="Neighborhood">
+ <title>Neighborhood</title>
+ <para>This value determines what constitutes a region within a particular distance from the agent. The value for this is often critical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:</para>
+ <variablelist>
+ <varlistentry>
+ <term>Euclidean</term>
+ <listitem>
+ <para>The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Moore</term>
+ <listitem>
+ <para>Here, the distance between any two cells is defined by the number of edge
+ <emphasis role="italic">or</emphasis> corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Von-Neumann</term>
+ <listitem>
+ <para>Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </section>
+ <section id="Network">
+ <title>Network</title>
+ <para>A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.</para>
+ <para>A network has only one value to specify:</para>
+ <section id="Directed">
+ <title>Directed</title>
+ <para>This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)</para>
+ </section>
+ </section>
+ <section id="Geography">
+ <title>Geography</title>
+ <para>A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.</para>
</section>
</section>
</section>
- <section id="Agents">
- <title>Agents</title>
- <section id="Simple_Agents">
- <title>Simple Agents</title>
- <para>An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.</para>
- <section id="Attributes">
- <title>Attributes</title>
- <para>As described in the attribute sections above.</para>
+ <section id="Reference">
+ <title>Reference</title>
+ <section id="Diagrams">
+ <title>Diagrams</title>
+ <para>For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.</para>
+ <section id="Meta-Classes">
+ <title>Meta-Classes</title>
+ <para>Our first diagram depicts the core structural design of the model. </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/StructureComplexDiagram.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <literallayout>There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
+</literallayout>
</section>
- <section id="Actions.3D">
- <title>Actions=</title>
- <para>Described in the "Actions" section.</para>
+ <section id="Key_Collaborations">
+ <title>Key Collaborations</title>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/StructureSimpleDiagram.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <literallayout>Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
+</literallayout>
</section>
- <section id="Styles">
- <title>Styles</title>
- <para>Special actions that are used to define how to draw an agent graphically as also described in the "Actions" section and detailed in the "Functions" section.</para>
+ <section id="Details_2">
+ <title>Details</title>
+ <orderedlist>
+ <listitem>
+ <para>Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally). </para>
+ </listitem>
+ <listitem>
+ <para>(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.</para>
+ </listitem>
+ <listitem>
+ <para>Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.</para>
+ </listitem>
+ <listitem>
+ <para>Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidean) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.</para>
+ </listitem>
+ <listitem>
+ <para>Agents are Actable and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.</para>
+ </listitem>
+ <listitem>
+ <para>Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actable. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".</para>
+ </listitem>
+ </orderedlist>
</section>
</section>
- <section id="Context_Agents_.28Contexts.29">
- <title>Context Agents (Contexts)</title>
- <para>As detailed above, agents also form the basic structural component of an agent-based model. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".</para>
- <section id="Agents_2">
- <title>Agents</title>
- <para>The agents that are contained within this context. For example, a context representing a city might contain an Individual Agent for defining all individuals in the model, and a Vehicle agent defining all vehicles. Note that when we refer to an agent in this context, we mean a general type or class of agent, not the agent itself.</para>
- </section>
- <section id="Spaces">
- <title>Spaces</title>
- <para>The set of all spaces contained or subsumed by the agent. For example, a context representing a city might contain a geographical space and a transportation network space.</para>
- </section>
- </section>
- </section>
- <section id="Attributes_2">
- <title>Attributes</title>
- <para>Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.</para>
- <para>Here are the basic types of attributes available in Acore models:</para>
- <section id="Basic_Attributes">
- <title>Basic Attributes</title>
- <para>Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. In this section we go over the values you can set for the attributes. For those with a tecnical bent, note that we are technically describing the meta-attributes for the meta-class "SAttribute". But it is far too confusing to refer to the attributes of attributes! So we'll just refer to the attributes that any of our model components as "values".</para>
- <section id="Type">
- <title>Type</title>
- <para>These can be anyone of the following: </para>
- <informaltable>
- <tr>
- <td>Boolean</td>
- <td>A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.</td>
- </tr>
- <tr>
- <td>Integer</td>
- <td>A discrete whole number value, such as "100", "-1", "10029920". It's generally a good idea to represent any value that can never have a decimal value as an integer.</td>
- </tr>
- <tr>
- <td>Real</td>
- <td>A continuous number value. While these are typically represented in software as floating point numbers, they can conceivably represent numbers at any arbitrary precision and in any scheme. Note that while technically speaking we should be representing irrational numbers, this is not currently supported for default values and users should simply use the closest decimal approximation.</td>
- </tr>
- <tr>
- <td>Symbol</td>
- <td>A string representing some state. More precisely, a computationally arbitrary value with contextual meaning. This could be any kind of identifier. For example, you might use it to store some kind of input coding from data that is then converted into an object state. Or it could simply be an agent's name. But theoretically (though this is not currently supported) one could imagine a symbol using an idiogram, an icon or even a sound that identifies or represents the agent in question.</td>
- </tr>
- </informaltable>
- <para>(Undefined and Numeric types should not be used within a well-defined model.)</para>
- </section>
- <section id="Default_Value">
- <title>Default Value</title>
- <para>The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.</para>
- </section>
- <section id="Gather_Data">
- <title>Gather Data</title>
- <para>Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.</para>
- </section>
- <section id="Immutable">
- <title>Immutable</title>
- <para>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.</para>
- </section>
- <section id="Units">
- <title>Units</title>
- <para>Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.</para>
- </section>
- </section>
- <section id="Arrays">
- <title>Arrays</title>
- <para>Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to what is defined above, arrays specify:</para>
- <section id="Size">
- <title>Size</title>
- <para>The number of values that the array attribute will contain.</para>
- </section>
- </section>
- <section id="States">
- <title>States</title>
- <para>States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".</para>
- <section id="State_Options">
- <title>State Options</title>
- <para>Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have</para>
- </section>
- <section id="Default_Option">
- <title>Default Option</title>
- <para>unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.</para>
- </section>
- </section>
- </section>
- <section id="Spaces_2">
- <title>Spaces</title>
- <para>All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:</para>
- <section id="Space_.28Continuous.29">
- <title>Space (Continuous)</title>
- <para>In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.</para>
- <section id="Border_Rule">
- <title>Border Rule</title>
- <para>A value representing what happens to an agent when that agent is asked to move beyond its extent.</para>
- <informaltable>
- <tr>
- <td>Periodic</td>
- <td>When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location
- <ulink url="1,2">1,2</ulink> (0-based) within a Moore space (see grid discussion below) of size
- <ulink url="10,10">10,10</ulink> is asked to find some other agent within distance 3, the agent look in the square defined between
- <ulink url="8,9">8,9</ulink> and
- <ulink url="4,5">4,5</ulink>. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.
- </td>
- </tr>
- <tr>
- <td>APeriodic</td>
- <td>When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location
- <ulink url="1,2">1,2</ulink> is asked to find some other agent within distance 3, the agent look between
- <ulink url="0,0">0,0</ulink> and
- <ulink url="4,5">4,5</ulink>. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.
- </td>
- </tr>
- </informaltable>
- <para>The "Strict" and "Bouncy" values are obsolete and should not be used.</para>
- </section>
- <section id="Dimensionality">
- <title>Dimensionality</title>
- <para>The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attribute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.</para>
- </section>
- </section>
- <section id="Grid">
- <title>Grid</title>
- <para>A grid is technically a regular lattice structure. Currently, only rectilinear structures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platforms support n-d spaces yet.) </para>
- <para>Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:</para>
- <section id="Multi-Occupant">
- <title>Multi-Occupant</title>
- <para>Does the grid allow more than one agent to occupy it at a time? This value may be replaced with another mechanism in future releases.</para>
- </section>
- <section id="Neighborhood">
- <title>Neighborhood</title>
- <para>This value determines what constitutes a region within a particular distance from the agent. The value for this is often critical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:</para>
- <informaltable>
- <tr>
- <td>Euclidian</td>
- <td>The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.</td>
- </tr>
- <tr>
- <td>Moore</td>
- <td>Here, the distance between any two cells is defined by the number of edge <i>or</i> corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.</td>
- </tr>
- <tr>
- <td>Von-Neumann</td>
- <td>Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.</td>
- </tr>
- </informaltable>
- </section>
- </section>
- <section id="Network">
- <title>Network</title>
- <para>A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.</para>
- <para>A network has only one value to specify:</para>
- <section id="Directed">
- <title>Directed</title>
- <para>This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)</para>
- </section>
- </section>
- <section id="Geography">
- <title>Geography</title>
- <para>A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.</para>
- </section>
</section>
</section>
- <section id="Reference">
- <title>Reference</title>
- <section id="Diagrams">
- <title>Diagrams</title>
- <para>For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.</para>
- <section id="Meta-Classes">
- <title>Meta-Classes</title>
- <para>Our first diagram depicts the core structural design of the model. </para>
+ <section id="Actions_2">
+ <title>Actions</title>
+ <para>Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.</para>
+ <section id="Overview_3">
+ <title>Overview</title>
+ <para>Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.</para>
+ <para>An action provides simple, well-defined details that a model can use to determine what steps to take in model execution. That definition seems general enough to be almost useless, but its important to understand that an action is not equivalent to an instruction, a method or a query. In fact, actions can have aspects of all of these. But an action is not in itself an instruction specifying exactly
+ <emphasis role="italic">how</emphasis> the modeling engine should do something -- instead an action represents
+ <emphasis role="italic">what</emphasis> the modeler intends for the agents to do. (Technically, we might say that Actions takes a "declarative" approach instead of an 'imperative' approach, but that's not quite true, because actions do allow us to define behavior in a richer way than most declarative approaches, and many action constructs map directly to imperative approaches.)
+ </para>
+ <para>Actions are connected together in a series of sources and targets. (Technically, an acyclic directed graph.) In an abstract sense that is similar to the way any programming language is defined although that structure isn't usually obvious because of the constraints of textual representations. But unlike a typical programming language, in Actions it is not the execution thread (the processor) that moves from one instruction to the next, but the result of the previous action. In this way, action results "flow" from the output of one action into the next action.</para>
+ <para>Why are these distinctions between traditional Object-Oriented and the Action approaches important? They give us the advantages of simplicity, clarity and flexibility that
+ <ulink url="/wiki/http://en.wikipedia.org/wiki/Dataflow_programming">data-flow approaches</ulink> like spreadsheets and some query languages have, but with less restrictions. At the same time, they can bring us much of the power and expressiveness of
+ <ulink url="/wiki/http://en.wikipedia.org/wiki/Functional_programming">functional languages</ulink> like Lisp or
+ <ulink url="/wiki/http://en.wikipedia.org/wiki/Logical_programming">logical languages</ulink> like Prolog, but without the level of complexity and obscurity that such languages can have.
+ </para>
+ <para>We can get a better idea for how Actions work by thinking about how a spreadsheet works. In a spreadsheet, we might define a cell A that adds up a row of data, say "Income". We might define another cell C ("Profit") that takes A and adds it to another cell B that adds up another row of data ("Expenses"). Now, if we change a value in any of the rows, all of the other rows are added up and we get the results in A and B updated automatically. We never had to write code that said something like "for each cell in row X, where...". In fact, we don't really care
+ <emphasis role="italic">how</emphasis> our Spreadsheet program adds up the numbers -- it could have added them all up at once but in backward order, or stored a running total somewhere and updated just the difference in value for the cell we changed -- what we care about is
+ <emphasis role="italic">what</emphasis> the result is, and whether it is correct.
+ </para>
+ <para>But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.</para>
+ </section>
+ <section id="Design">
+ <title>Design</title>
+ <para>In this section, we'll describe how modelers can assemble actions into sets of behavior that accomplish complex tasks on interrelated agents and spaces over time.</para>
+ <section id="Kinds_of_Actions">
+ <title>Kinds of Actions</title>
+ <para>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. All of these are discussed in detail in the section that follows this one.</para>
+ <para>These are all summarized in the diagram below:</para>
<para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/StructureComplexDiagram.png"/>
+ <imagedata fileref="images/ActionsBlocks.png"/>
</imageobject>
</mediaobject>
</para>
- <literallayout>There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
-</literallayout>
</section>
- <section id="Key_Collaborations">
- <title>Key Collaborations</title>
+ <section id="Flow">
+ <title>Flow</title>
+ <para>First, let's look at how actions define the basic path that agents take during a model run. As with any programming language, the path we take through the program specification is what determines our state when we get there. In a pure object oriented program, the path just defines the control flow -- what we are doing. The actual state of our model is defined within the object itself. If we call a method B from another method A, we'll be relying on method A to set the values that we need into the object state itself. In a purely functional program the path defines how we are going to deal with whatever has been explicitly passed in to a function that has been called, that is the function parameters. In fact, most languages such as Java combine aspects of both approaches.</para>
+ <para>In Actions, the path itself implicitly carries all of the context of prior execution with it. This means that we don't have to worry about storing context in the object -- as we would in an object-oriented language -- or passing the correct values from one method call to the next as we would in a functional language. Instead, Actions can use the implicit context of the path of flow to determine what the current state of execution is.</para>
+ <para>Again, behaviors in Actions are always defined by a set of
+ <emphasis role="italic">selections</emphasis> and
+ <emphasis role="italic">queries</emphasis>. In the following diagram, we can see the pattern.
+ </para>
<para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/StructureSimpleDiagram.png"/>
+ <imagedata fileref="images/ActionsSequence.png"/>
</imageobject>
</mediaobject>
</para>
- <literallayout>Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
+ <para>First, we define a Root Selection for a Rule, Schedule or other triggering event. Then, we might add a series of Query and Logic Actions to define the specific agents that we are interested in. These are all part of the Selection. Next, we might define a series of Commands to determine what to do with those agents. Or, we could use the result of that selection to immediately define another selection, for example if we are searching for an agent that is near another agent. The next diagram depicts a simple example.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSimpleSequence.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>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. In the 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.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSimpleSequence2.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>In the following example, we've defined a set of actions and their relationships. We have a selection, a few queries and a couple of logic operators leading to a Set Action. We'll describe in detail below how Logic Actions are used in conjunction with other actions to assemble any kind of query structure needed. But for now, we'll focus on the control flow itself.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsFlowSimple.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>As you have probably already guessed, the agents that have the Set Action applied to them could take one of two paths through the Action flow. Readers with experience with programming or formal logic will note that this looks just like a parse tree, and while that's basically what it is, there are important differences. For example, if we looked at the following structure as a definition of control flow for a single agent we'd take them to be equivalent. Both would evaluate the statement (Query 1 AND Query 2) OR Query 3 for each agent.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsFlowUnion.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Within Actions in many cases these two approaches will also act equivalently. If we are simply setting a value, it doesn't matter how an agent gets to that Set Action, as long as it gets there. All sources that flow into a given target Action act like a logical union since any of the paths might reach that target. But note that we have two flows moving in parallel in the flow on the right. What happens when the conditions for
+ <emphasis role="italic">both</emphasis> branches are true? As the set of agents flow through each branch the Set Action on the left will be evaluated once, while the one on the right will be evaluated twice. Again, this often ends up with the same behavior, but not always. If for example, the evaluate Action uses the value of the attribute that we are setting as input, we can get different results. Of course, you can write code in any language that accomplishes the same thing, but the code will look quite different. For example, if we wrote the same basic logic in Java, in the first case we'd have something like:
+ </para>
+ <literallayout>if ((query1.evaluate() && query2.evaluate()) || query3.evaluate()) {
+ doSomething();
+}
</literallayout>
+ <para>In the second we'd have:</para>
+ <literallayout>if (query1.evaluate() && query2.evaluate()) {
+ doSomething();
+}
+if (query3.evaluate()) {
+ doSomething();
+}
+</literallayout>
+ <para>This is a simple example, but with multiple branches such code design issues can quickly grow complex. The flow approach allows us to express things in a way that is often more natural and expressive. The important thing to keep in mind when desiging action flows is to see the flow as representing a selection of agents moving through streams independently. In the Actions example we expressed both approaches in nearly the same way, except in the case on the left we used a Union Action to bring the two branches of flow back together.</para>
</section>
- <section id="Details_2">
- <title>Details</title>
+ <section id="Selections">
+ <title>Selections</title>
+ <para>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.</para>
+ <para>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.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSelBoundarySimple.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Each time we create a new selection, we define a new set of boundaries.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSelBoundary2Parts.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>A very important aspect of boundaries is that they apply to a group of actions that begin with a Query Action, and not just such a group that begins with a Select Action. This is because Query Actions can be directly part of a selection definition, but they can also refine selections, as we'll see. So where does one selection boundary end and the next one begin? The simple rule is that the end of the boundary is defined for a given Action by the place where:</para>
<orderedlist>
<listitem>
- <para>Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally). </para>
+ <para>A Query Action is not followed by a Logic Action, or</para>
</listitem>
<listitem>
- <para>(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.</para>
- </listitem>
- <listitem>
- <para>Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.</para>
- </listitem>
- <listitem>
- <para>Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidean) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.</para>
- </listitem>
- <listitem>
- <para>Agents are Actable and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.</para>
- </listitem>
- <listitem>
- <para>Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actable. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".</para>
+ <para>A Logic Action is not followed by another Logic Action</para>
</listitem>
</orderedlist>
+ <para>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 we can see in the following example. </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSelBoundary11A.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Note that we refer to "Selection 1" and Selection 1A". This is because Selection 1A is a refinement of Selection 1 along its particular path of flow. When a query appears for the same selection but past a particular boundary, you can think of it as a sort of filter on the selection contents. We don't have a "Selection 2" here because any Actions that refer to "Selection 1" along the current path of flow will be acting on the selection defined by Selection 1 and Selection 1A.</para>
+ <para>These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a == x and attribute b == y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a == x, and
+ <emphasis role="italic">then</emphasis> taking those agents and choosing those agents with b==y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsSelBoundaryComplex.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>In the first case, we execute a search for all agents that meet the two criteria. This means that if there are
+ <emphasis role="italic">any</emphasis> neighboring cells which are available, we're guaranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all. This then becomes an important aspect of model design. For example, if one were defining a model where neighbors played a game with each other, one might want to instruct agents to play the game only with neighbors that have a certain wealth threshold. In the real-world situation that we are modeling, we might simply search for neighbors who are over a given wealth threshold and then play the game with them. This would imply that information about other agent's wealth is open knowledge. Or, we might simply select a random neighbor, and ask that neighbor to play a game with us. Upon discovering that our neighbor does not meet our wealth criteria, we would then choose not to play with them. Here we are modeling a cost in time to obtain information about another agent's wealth, because we might miss an opportunity to play the game with another agent on that round.
+ </para>
+ </section>
+ <section id="Weaving">
+ <title>Weaving</title>
+ <para>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.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsWeavingSetAnother.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>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.)</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsWeavingEvaluate.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>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.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsWeaving1A.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>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. Now, consider the following example:</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsWeaving2.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Before going into further details we need to introduce one more important concept. 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.</para>
</section>
</section>
- </section>
- </chapter>
- <chapter id="Actions">
- <title>Actions</title>
- <para>Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.</para>
- <section id="Background">
- <title>Background</title>
- <para>Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.</para>
- <para>An action provides simple, well-defined details that a model can use to determine what steps to take in model execution. That definition seems general enough to be almost useless, but its important to understand that an action is not equivalent to an instruction, a method or a query. In fact, actions can have aspects of all of these. But an action is not in itself an instruction specifying exactly
- <emphasis role="italic">how</emphasis> the modeling engine should do something -- instead an action represents
- <emphasis role="italic">what</emphasis> the modeler intends for the agents to do. (Technically, we might say that Actions takes a "declarative" approach instead of an 'imperative' approach, but that's not quite true, because actions do allow us to define behavior in a richer way than most declarative approaches, and many action constructs map directly to imperative approaches.)
- </para>
- <para>Actions are connected together in a series of sources and targets. (Technically, an acyclic directed graph.) In an abstract sense that is similar to the way any programming language is defined although that structure isn't usually obvious because of the constraints of textual representations. But unlike a typical programming language, in Actions it is not the execution thread (the processor) that moves from one instruction to the next, but the result of the previous action. In this way, action results "flow" from the output of one action into the next action.</para>
- <para>Why are these distinctions between traditional Object-Oriented and the Action approaches important? They give us the advantages of simplicity, clarity and flexibility that
- <ulink url="/wiki/http://en.wikipedia.org/wiki/Dataflow_programming">data-flow approaches</ulink> like spreadsheets and some query languages have, but with less restrictions. At the same time, they can bring us much of the power and expressiveness of
- <ulink url="/wiki/http://en.wikipedia.org/wiki/Functional_programming">functional languages</ulink> like Lisp or
- <ulink url="/wiki/http://en.wikipedia.org/wiki/Logical_programming">logical languages</ulink> like Prolog, but without the level of complexity and obscurity that such languages can have.
- </para>
- <para>We can get a better idea for how Actions work by thinking about how a spreadsheet works. In a spreadsheet, we might define a cell A that adds up a row of data, say "Income". We might define another cell C ("Profit") that takes A and adds it to another cell B that adds up another row of data ("Expenses"). Now, if we change a value in any of the rows, all of the other rows are added up and we get the results in A and B updated automatically. We never had to write code that said something like "for each cell in row X, where...". In fact, we don't really care
- <emphasis role="italic">how</emphasis> our Spreadsheet program adds up the numbers -- it could have added them all up at once but in backward order, or stored a running total somewhere and updated just the difference in value for the cell we changed -- what we care about is
- <emphasis role="italic">what</emphasis> the result is, and whether it is correct.
- </para>
- <para>But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.</para>
- </section>
- <section id="Design_2">
- <title>Design</title>
- <para>In this section, we'll describe how modelers can assemble actions into sets of behavior that accomplish complex tasks on interrelated agents and spaces over time.</para>
- <section id="Kinds_of_Actions">
- <title>Kinds of Actions</title>
- <para>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. All of these are discussed in detail in the section that follows this one.</para>
- <para>These are all summarized in the diagram below:</para>
+ <section id="Details_3">
+ <title>Details</title>
+ <para>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.
+ Let's look at the overall view again amd then dig into the details.</para>
<para>
<mediaobject>
<imageobject>
@@ -362,1056 +592,1247 @@
</imageobject>
</mediaobject>
</para>
+ <section id="Selections_2">
+ <title>Selections</title>
+ <para>A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.</para>
+ <section id="Select">
+ <title>Select</title>
+ <para>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):</para>
+ <section id="Selection">
+ <title>Selection</title>
+ <para>The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.</para>
+ </section>
+ <section id="Agent">
+ <title>Agent</title>
+ <para>Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.</para>
+ </section>
+ <section id="Space">
+ <title>Space</title>
+ <para>The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.</para>
+ <para>Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.</para>
+ </section>
+ <section id="For">
+ <title>For</title>
+ <para>This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.</para>
+ </section>
+ </section>
+ <section id="Query">
+ <title>Query</title>
+ <para>A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions. </para>
+ <section id="Function">
+ <title>Function</title>
+ <para>A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age == Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.</para>
+ </section>
+ </section>
+ <section id="Logic">
+ <title>Logic</title>
+ <para>These Actions provide us with the ability to combine queries with one another, and follow the basic rules of set logic. But as we've seen above, it is important to understand that there are important differences between Logic Actions and typical programming logic. Most importantly, they apply not to individual agents per se, but to the set of agents that move through them. Also, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together because of the action flow design.</para>
+ </section>
+ <section id="Intersection">
+ <title>Intersection</title>
+ <para>An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. An agent must be able to flow through all incoming actions in order to flow out of an Intersection Action.</para>
+ </section>
+ <section id="Union">
+ <title>Union</title>
+ <para>A union contains all agents that match any of its source actions. This shares similiarities to a logical OR statement and the || operator in a java "if" statement. It does mroe than that however, as it acts to join multiple flows of action. That is, as set logic implies, an agent will never appear in the result of a union more than once.</para>
+ </section>
+ <section id="Difference">
+ <title>Difference</title>
+ <para>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.</para>
+ </section>
+ <section id="Roots">
+ <title>Roots</title>
+ <para>Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.</para>
+ </section>
+ <section id="Build">
+ <title>Build</title>
+ <para>The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined whether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.</para>
+ </section>
+ <section id="Initialize">
+ <title>Initialize</title>
+ <para>An Initialize action is executed once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guaranteed to execute before any other non-builder action occurs.</para>
+ </section>
+ <section id="Rule">
+ <title>Rule</title>
+ <para>A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.</para>
+ </section>
+ <section id="Schedule">
+ <title>Schedule</title>
+ <para>A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time == t.</para>
+ <section id="Start">
+ <title>Start</title>
+ <para>The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..</para>
+ </section>
+ <section id="Interval">
+ <title>Interval</title>
+ <para>How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..</para>
+ </section>
+ <section id="Priority">
+ <title>Priority</title>
+ <para>Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.</para>
+ </section>
+ <section id="Pick">
+ <title>Pick</title>
+ <para>Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be replaced by another approach.</para>
+ </section>
+ </section>
+ <section id="Watch">
+ <title>Watch</title>
+ <para>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.</para>
+ <section id="Attribute">
+ <title>Attribute</title>
+ <para>The attribute that will be monitored for change.</para>
+ </section>
+ </section>
+ </section>
+ <section id="Commands">
+ <title>Commands</title>
+ <section id="Evaluate">
+ <title>Evaluate</title>
+ <para>Evaluate Actions define some calculation on a function based on the model state and a set of input(s). The inputs that an Evaluate Action can take is determined by its functions and can be either agent attributes, prior evaluations or literals. The result is then determined based on those inputs. In some cases Evaluate functions can be used to determine some action indirectly, such as with a graphics fill, but they can never be used to directly change model state.</para>
+ <section id="Selection_2">
+ <title>Selection</title>
+ <para>As with all other actions, evaluations specify a selection, and just as with the other actions, this determines the set of agents that the evaluation occurs for, but the input selections determine what agent is used for the calculation itself.</para>
+ </section>
+ <section id="Function_2">
+ <title>Function</title>
+ <para>A with queries, a function is evaluated against its input set. Functions can represent simple operators as well as complex functions. See the functions section for more information on specific functions.</para>
+ </section>
+ <section id="Inputs">
+ <title>Inputs</title>
+ <para>The set of values that will be used to determine the result, in the order of the function prototype. Inputs can specify any source evaluation and any agent state or agent parent context state. The selection determines which agent's will be used to determine the value, and different inputs can specify different selections.</para>
+ </section>
+ </section>
+ <section id="Move">
+ <title>Move</title>
+ <para>The Move Action causes an agent to change its location in some space or network. The agent will leave whatever location it was in before within the selection space, and move to its new destination.</para>
+ <section id="Selection_3">
+ <title>Selection</title>
+ <para>As with any </para>
+ </section>
+ </section>
+ <section id="Set">
+ <title>Set</title>
+ <para>The Set Action assigns some value to another value.</para>
+ </section>
+ </section>
</section>
- <section id="Flow">
- <title>Flow</title>
- <para>First, let's look at how actions define the basic path that agents take during a model run. As with any programming language, the path we take through the program specification is what determines our state when we get there. In a pure object oriented program, the path just defines the control flow -- what we are doing. The actual state of our model is defined within the object itself. If we call a method B from another method A, we'll be relying on method A to set the values that we need into the object state itself. In a purely functional program the path defines how we are going to deal with whatever has been explicitly passed in to a function that has been called, that is the function parameters. In fact, most languages such as Java combine aspects of both approaches.</para>
- <para>In Actions, the path itself implicitly carries all of the context of prior execution with it. This means that we don't have to worry about storing context in the object -- as we would in an object-oriented language -- or passing the correct values from one method call to the next as we would in a functional language. Instead, Actions can use the implicit context of the path of flow to determine what the current state of execution is.</para>
- <para>Again, behaviors in Actions are always defined by a set of
- <emphasis role="italic">selections</emphasis> and
- <emphasis role="italic">queries</emphasis>. In the following diagram, we can see the pattern.
- </para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsSequence.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>First, we define a Root Selection for a Rule, Schedule or other triggering event. Then, we might add a series of Query and Logic Actions to define the specific agents that we are interested in. These are all part of the Selection. Next, we might define a series of Commands to determine what to do with those agents. Or, we could use the result of that selection to immediately define another selection, for example if we are searching for an agent that is near another agent. The next diagram depicts a simple example.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsSimpleSequence.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>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. In the 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.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsSimpleSequence2.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>In the following example, we've defined a set of actions and their relationships. We have a selection, a few queries and a couple of logic operators leading to a Set Action. We'll describe in detail below how Logic Actions are used in conjunction with other actions to assemble any kind of query structure needed. But for now, we'll focus on the control flow itself.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsFlowSimple.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>As you have probably already guessed, the agents that have the Set Action applied to them could take one of two paths through the Action flow. Readers with experience with programming or formal logic will note that this looks just like a parse tree, and while that's basically what it is, there are important differences. For example, if we looked at the following structure as a definition of control flow for a single agent we'd take them to be equivalent. Both would evaluate the statement (Query 1 AND Query 2) OR Query 3 for each agent.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsFlowUnion.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>Within Actions in many cases these two approaches will also act equivalently. If we are simply setting a value, it doesn't matter how an agent gets to that Set Action, as long as it gets there. All sources that flow into a given target Action act like a logical union since any of the paths might reach that target. But note that we have two flows moving in parallel in the flow on the right. What happens when the conditions for
- <emphasis role="italic">both</emphasis> branches are true? As the set of agents flow through each branch the Set Action on the left will be evaluated once, while the one on the right will be evaluated twice. Again, this often ends up with the same behavior, but not always. If for example, the evaluate Action uses the value of the attribute that we are setting as input, we can get different results. Of course, you can write code in any language that accomplishes the same thing, but the code will look quite different. For example, if we wrote the same basic logic in Java, in the first case we'd have something like:
- </para>
- <literallayout>if ((query1.evaluate() && query2.evaluate()) || query3.evaluate()) {
- doSomething();
-}
+ <section id="Example">
+ <title>Example</title>
+ <para>In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:</para>
+ <literallayout>"Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
</literallayout>
- <para>In the second we'd have:</para>
- <literallayout>if (query1.evaluate() && query2.evaluate()) {
- doSomething();
-}
-if (query3.evaluate()) {
- doSomething();
-}
-</literallayout>
- <para>This is a simple example, but with multiple branches such code design issues can quickly grow complex. The flow approach allows us to express things in a way that is often more natural and expressive. The important thing to keep in mind when desiging action flows is to see the flow as representing a selection of agents moving through streams independently. In the Actions example we expressed both approaches in nearly the same way, except in the case on the left we used a Union Action to bring the two branches of flow back together.</para>
- </section>
- <section id="Selections">
- <title>Selections</title>
- <para>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.</para>
- <para>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.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsSelBoundarySimple.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>Each time we create a new selection, we define a new set of boundaries.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsSelBoundary2Parts.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>A very important aspect of boundaries is that they apply to a group of actions that begin with a Query Action, and not just such a group that begins with a Select Action. This is because Query Actions can be directly part of a selection definition, but they can also refine selections, as we'll see. So where does one selection boundary end and the next one begin? The simple rule is that the end of the boundary is defined for a given Action by the place where:</para>
+ <para>Here, we create a sequence of actions like so:</para>
<orderedlist>
<listitem>
- <para>A Query Action is not followed by a Logic Action, or</para>
+ <para>Select every agent for every period of the model. ("Find Partner" Rule)</para>
</listitem>
<listitem>
- <para>A Logic Action is not followed by another Logic Action</para>
+ <para>For every member of that selection, search for other agents of the same age within vision distance. ("Partner" selection.)</para>
+ </listitem>
+ <listitem>
+ <para>From "Partners" find a random member and search for a neighboring locations. ("Partner Neighbor" selection.)</para>
+ </listitem>
+ <listitem>
+ <para>Finally, move the agent in "Find Partner" to the "Partner Neighbor" location.</para>
</listitem>
</orderedlist>
- <para>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 we can see in the following example. </para>
+ <para>Now, notice that although it's convenient to speak as if there is only one "Find Partner" and one "Partner Neighbor" in step 4 above, in fact selections are flowing through for each of the results of each of the previous action sequences, and we can refer to each of the directly. We could represent these behaviors in many different ways. For example, we might want to specify the model in a (hand-drawn) graphical language or in a (made-up) textual language:</para>
<para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/ActionsSelBoundary11A.png"/>
+ <imagedata fileref="images/ActionsExample.png"/>
</imageobject>
</mediaobject>
</para>
- <para>Note that we refer to "Selection 1" and Selection 1A". This is because Selection 1A is a refinement of Selection 1 along its particular path of flow. When a query appears for the same selection but past a particular boundary, you can think of it as a sort of filter on the selection contents. We don't have a "Selection 2" here because any Actions that refer to "Selection 1" along the current path of flow will be acting on the selection defined by Selection 1 and Selection 1A.</para>
- <para>These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a = x and attribute b = y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a = x, and
- <emphasis role="italic">then</emphasis> taking those agents and choosing those agents with b=y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
- </para>
+ <para>This is how it looks in an actual model:</para>
<para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/ActionsSelBoundaryComplex.png"/>
+ <imagedata fileref="images/ActionsExampleNew.png"/>
</imageobject>
</mediaobject>
</para>
- <para>In the first case, we execute a search for all agents that meet the two criteria. This means that if there are
- <emphasis role="italic">any</emphasis> neighboring cells which are available, we're guaranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all. This then becomes an important aspect of model design. For example, if one were defining a model where neighbors played a game with each other, one might want to instruct agents to play the game only with neighbors that have a certain wealth threshold. In the real-world situation that we are modeling, we might simply search for neighbors who are over a given wealth threshold and then play the game with them. This would imply that information about other agent's wealth is open knowledge. Or, we might simply select a random neighbor, and ask that neighbor to play a game with us. Upon discovering that our neighbor does not meet our wealth criteria, we would then choose not to play with them. Here we are modeling a cost in time to obtain information about another agent's wealth, because we might miss an opportunity to play the game with another agent on that round.
- </para>
+ <para>And here is how this works in detail:</para>
+ <orderedlist>
+ <listitem>
+ <para>Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (Space isn't relevant in this case.</para>
+ </listitem>
+ <listitem>
+ <para>Create a child Select Action that will find our partner. Two important things to note here:</para>
+ <orderedlist>
+ <listitem>
+ <para>The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.</para>
+ </listitem>
+ <listitem>
+ <para>We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>Create two child Query Actions:</para>
+ <orderedlist>
+ <listitem>
+ <para>We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by the rule agent's partner for the first input and by the rule agent for the second. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.</para>
+ </listitem>
+ <listitem>
+ <para>We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.</para>
+ </listitem>
+ <listitem>
+ <para>Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.</para>
+ </listitem>
+ <listitem>
+ <para>As above, define some queries. This time we want only those agents that are:</para>
+ <orderedlist>
+ <listitem>
+ <para>available, and</para>
+ </listitem>
+ <listitem>
+ <para>neighbors of our partner.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>And another intersection..</para>
+ </listitem>
+ <listitem>
+ <para>Finally, we move to the location we've found. All that's required at this point is to specify:</para>
+ <orderedlist>
+ <listitem>
+ <para>The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and</para>
+ </listitem>
+ <listitem>
+ <para>The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
</section>
- <section id="Weaving">
- <title>Weaving</title>
- <para>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.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsWeavingSetAnother.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>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.)</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsWeavingEvaluate.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>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.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsWeaving1A.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>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. Now, consider the following example:</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsWeaving2.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>Before going into further details we need to introduce one more important concept. 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.</para>
- </section>
- </section>
- <section id="Details_3">
- <title>Details</title>
- <para>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.
- Let's look at the overall view again amd then dig into the details.</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsBlocks.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <section id="Selections_2">
- <title>Selections</title>
- <para>A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.</para>
- <section id="Select">
- <title>Select</title>
- <para>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):</para>
- <section id="Selection">
- <title>Selection</title>
- <para>The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.</para>
+ <section id="Reference_2">
+ <title>Reference</title>
+ <section id="Diagrams_2">
+ <title>Diagrams</title>
+ <para>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</para>
+ <section id="Meta-Classes_2">
+ <title>Meta-Classes</title>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsDiagram.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
</section>
- <section id="Agent">
- <title>Agent</title>
- <para>Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.</para>
+ <section id="Details_4">
+ <title>Details</title>
+ <para>In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.</para>
+ <orderedlist>
+ <listitem>
+ <para>An Act is anything that might happen during the execution of an Agent-Based Model.</para>
+ </listitem>
+ <listitem>
+ <para>All Actions have as their root-most source action a Root. These are added first to any agent behavior and act as triggers for all target behavior. For example, a Watch will execute any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that Accessor includes a reference to some Attribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)#Actions are targets and sources of one another, but an Act can never have itself as a source. (That is, Actions are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)</para>
+ </listitem>
+ <listitem>
+ <para>All Actions (except for root Actions) reference a Select, referred to as the "selected" relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) "world" that is currently being selected.</para>
+ </listitem>
+ <listitem>
+ <para>Commands trigger some model state change (Set) or spatial transformation (Transform).</para>
+ </listitem>
+ <listitem>
+ <para>Controls determine whether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.</para>
+ </listitem>
+ <listitem>
+ <para>Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).</para>
+ </listitem>
+ <listitem>
+ <para>Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.</para>
+ </listitem>
+ </orderedlist>
</section>
- <section id="Space">
- <title>Space</title>
- <para>The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.</para>
- <para>Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.</para>
- </section>
- <section id="For">
- <title>For</title>
- <para>This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.</para>
- </section>
- </section>
- <section id="Query">
- <title>Query</title>
- <para>A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions. </para>
- <section id="Function">
- <title>Function</title>
- <para>A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age = Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.</para>
- </section>
- </section>
- <section id="Logic">
- <title>Logic</title>
- <para>These Actions provide us with the ability to combine queries with one another, and follow the basic rules of set logic. But as we've seen above, it is important to understand that there are important differences between Logic Actions and typical programming logic. Most importantly, they apply not to individual agents per se, but to the set of agents that move through them. Also, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together because of the action flow design.</para>
- </section>
- <section id="Intersection">
- <title>Intersection</title>
- <para>An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. An agent must be able to flow through all incoming actions in order to flow out of an Intersection Action.</para>
- </section>
- <section id="Union">
- <title>Union</title>
- <para>A union contains all agents that match any of its source actions. This shares similiarities to a logical OR statement and the || operator in a java "if" statement. It does mroe than that however, as it acts to join multiple flows of action. That is, as set logic implies, an agent will never appear in the result of a union more than once.</para>
- </section>
- <section id="Difference">
- <title>Difference</title>
- <para>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.</para>
- </section>
- <section id="Roots">
- <title>Roots</title>
- <para>Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.</para>
- </section>
- <section id="Build">
- <title>Build</title>
- <para>The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined whether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.</para>
- </section>
- <section id="Initialize">
- <title>Initialize</title>
- <para>An Initialize action is executed once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guaranteed to execute before any other non-builder action occurs.</para>
- </section>
- <section id="Rule">
- <title>Rule</title>
- <para>A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.</para>
- </section>
- <section id="Schedule">
- <title>Schedule</title>
- <para>A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time = t.</para>
- <section id="Start">
- <title>Start</title>
- <para>The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..</para>
- </section>
- <section id="Interval">
- <title>Interval</title>
- <para>How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..</para>
- </section>
- <section id="Priority">
- <title>Priority</title>
- <para>Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.</para>
- </section>
- <section id="Pick">
- <title>Pick</title>
- <para>Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be replaced by another approach.</para>
- </section>
- </section>
- <section id="Watch">
- <title>Watch</title>
- <para>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.</para>
- <section id="Attribute">
- <title>Attribute</title>
- <para>The attribute that will be monitored for change.</para>
- </section>
- </section>
- </section>
- <section id="Commands">
- <title>Commands</title>
- <section id="Evaluate">
- <title>Evaluate</title>
- <para>Evaluate Actions define some calculation on a function based on the model state and a set of input(s). The inputs that an Evaluate Action can take is determined by its functions and can be either agent attributes, prior evaluations or literals. The result is then determined based on those inputs. In some cases Evaluate functions can be used to determine some action indirectly, such as with a graphics fill, but they can never be used to directly change model state.</para>
- <section id="Selection_2">
- <title>Selection</title>
- <para>As with all other actions, evaluations specify a selection, and just as with the other actions, this determines the set of agents that the evaluation occurs for, but the input selections determine what agent is used for the calculation itself.</para>
- </section>
- <section id="Function_2">
- <title>Function</title>
- <para>A with queries, a function is evaluated against its input set. Functions can represent simple operators as well as complex functions. See the functions section for more information on specific functions.</para>
- </section>
- <section id="Inputs">
- <title>Inputs</title>
- <para>The set of values that will be used to determine the result, in the order of the function prototype. Inputs can specify any source evaluation and any agent state or agent parent context state. The selection determines which agent's will be used to determine the value, and different inputs can specify different selections.</para>
- </section>
- </section>
- <section id="Move">
- <title>Move</title>
- <para>The Move Action causes an agent to change its location in some space or network. The agent will leave whatever location it was in before within the selection space, and move to its new destination.</para>
- <section id="Selection_3">
- <title>Selection</title>
- <para>As with any </para>
- </section>
- </section>
- <section id="Set">
- <title>Set</title>
- <para>The Set Action assigns some value to another value.</para>
</section>
</section>
</section>
- <section id="Example">
- <title>Example</title>
- <para>In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:</para>
- <literallayout>"Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-</literallayout>
- <para>Here, we create a sequence of actions like so:</para>
- <orderedlist>
- <listitem>
- <para>Select every agent for every period of the model. ("Find Partner" Rule)</para>
- </listitem>
- <listitem>
- <para>For every member of that selection, search for other agents of the same age within vision distance. ("Partner" selection.)</para>
- </listitem>
- <listitem>
- <para>From "Partners" find a random member and search for a neighboring locations. ("Partner Neighbor" selection.)</para>
- </listitem>
- <listitem>
- <para>Finally, move the agent in "Find Partner" to the "Partner Neighbor" location.</para>
- </listitem>
- </orderedlist>
- <para>Now, notice that although it's convenient to speak as if there is only one "Find Partner" and one "Partner Neighbor" in step 4 above, in fact selections are flowing through for each of the results of each of the previous action sequences, and we can refer to each of the directly. We could represent these behaviors in many different ways. For example, we might want to specify the model in a (hand-drawn) graphical language or in a (made-up) textual language:</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsExample.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>This is how it looks in an actual model:</para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsExampleNew.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>And here is how this works in detail:</para>
- <orderedlist>
- <listitem>
- <para>Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (Space isn't relevant in this case.</para>
- </listitem>
- <listitem>
- <para>Create a child Select Action that will find our partner. Two important things to note here:</para>
- <orderedlist>
- <listitem>
- <para>The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.</para>
- </listitem>
- <listitem>
- <para>We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.</para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Create two child Query Actions:</para>
- <orderedlist>
- <listitem>
- <para>We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.</para>
- </listitem>
- <listitem>
- <para>We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner.</para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.</para>
- </listitem>
- <listitem>
- <para>Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.</para>
- </listitem>
- <listitem>
- <para>As above, define some queries. This time we want only those agents that are:</para>
- <orderedlist>
- <listitem>
- <para>available, and</para>
- </listitem>
- <listitem>
- <para>neighbors of our partner.</para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>And another intersection..</para>
- </listitem>
- <listitem>
- <para>Finally, we move to the location we've found. All that's required at this point is to specify:</para>
- <orderedlist>
- <listitem>
- <para>The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and</para>
- </listitem>
- <listitem>
- <para>The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.</para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
- </section>
- <section id="Reference_2">
- <title>Reference</title>
- <section id="Diagrams_2">
- <title>Diagrams</title>
- <para>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</para>
- <section id="Meta-Classes_2">
- <title>Meta-Classes</title>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ActionsDiagram.png"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
- <section id="Details_4">
- <title>Details</title>
- <para>In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.</para>
- <orderedlist>
- <listitem>
- <para>An Act is anything that might happen during the execution of an Agent-Based Model.</para>
- </listitem>
- <listitem>
- <para>All Actions have as their root-most source action a Root. These are added first to any agent behavior and act as triggers for all target behavior. For example, a Watch will execute any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that Accessor includes a reference to some Attribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)#Actions are targets and sources of one another, but an Act can never have itself as a source. (That is, Actions are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)</para>
- </listitem>
- <listitem>
- <para>All Actions (except for root Actions) reference a Select, referred to as the "selected" relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) "world" that is currently being selected.</para>
- </listitem>
- <listitem>
- <para>Commands trigger some model state change (Set) or spatial transformation (Transform).</para>
- </listitem>
- <listitem>
- <para>Controls determine whether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.</para>
- </listitem>
- <listitem>
- <para>Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).</para>
- </listitem>
- <listitem>
- <para>Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.</para>
- </listitem>
- </orderedlist>
- </section>
+ <section id="Functions">
+ <title>Functions</title>
+ <section id="Overview_4">
+ <title>Overview</title>
+ <para>Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:</para>
+ <orderedlist>
+ <listitem>
+ <para>Operators are simple calculations sharing the same type.</para>
+ </listitem>
+ <listitem>
+ <para>Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s).</para>
+ </listitem>
+ </orderedlist>
+ <para>And by usage:</para>
+ <orderedlist>
+ <listitem>
+ <para>Generics can return any value and are used in Evaluate actions.</para>
+ </listitem>
+ <listitem>
+ <para>Logicals return some boolean result and are used by Query actions to decide whether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.</para>
+ </listitem>
+ </orderedlist>
+ <para>These overlap, so we have operators, logical operators, functions and logical functions. Functions are also divided into categories. We'll go through each of these in depth below.</para>
+ <para>The most important thing to point out about functions is that - as we've seen with other Acore concepts -- they provide richer sets of functionality than traditional approaches. Many functions are designed to collaborate with one another as we'll see when looking at Spatial and Graphical functions. Functions can also trigger the creation of related model artifacts as we'll see with the Distribution functions.</para>
+ <para>A technical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.</para>
</section>
- </section>
- </chapter>
- <chapter id="Functions">
- <title>Functions</title>
- <para>Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:</para>
- <orderedlist>
- <listitem>
- <para>Operators are simple calculations sharing the same type.</para>
- </listitem>
- <listitem>
- <para>Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s).</para>
- </listitem>
- </orderedlist>
- <para>And by usage:</para>
- <orderedlist>
- <listitem>
- <para>Generics can return any value and are used in Evaluate actions.</para>
- </listitem>
- <listitem>
- <para>Logicals return some boolean result and are used by Query actions to decide whether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.</para>
- </listitem>
- </orderedlist>
- <para>These overlap, so we have operators, logical operators, functions and logical functions.</para>
- <para>Functions are also divided into categories, as we'll see.</para>
- <para>A technical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.</para>
- <section id="Reference_3">
- <title>Reference</title>
- <section id="Function_Library">
- <title>Function Library</title>
- <section id="Operators">
- <title>Operators</title>
- </section>
- <section id="Logical_Operators">
- <title>Logical Operators</title>
- <section id="Not">
- <title>Not</title>
- <para>The result of the expression !X.</para>
+ <section id="Details_5">
+ <title>Details</title>
+ <section id="General_Functions">
+ <title>General Functions</title>
+ <para>Naturally, the Modeling tools provide general functions for performing calculations, comparisons and more complex mathematical expressions. The function library can be easily extended, and we'll be adding additional capabilities over time. As always, we welcome feedback and we'd like to hear what functions you need that aren't covered here.</para>
+ <section id="Logical_Operators">
+ <title>Logical Operators</title>
+ <section id="Not">
+ <title>Not</title>
+ <para>The result of the expression !X.</para>
+ </section>
+ <section id="Equal">
+ <title>Equal</title>
+ <para>The result of the expression X==Y.</para>
+ </section>
+ <section id="Identical">
+ <title>Identical</title>
+ <para>The result of the expression X==Y.</para>
+ </section>
+ <section id="Greater">
+ <title>Greater</title>
+ <para>The result of the expression X>Y.</para>
+ </section>
+ <section id="Lesser">
+ <title>Lesser</title>
+ <para>The result of the expression X<Y.</para>
+ </section>
+ <section id="Greater_or_Equal">
+ <title>Greater or Equal</title>
+ <para>The result of the expression X>=Y.</para>
+ </section>
+ <section id="Lesser_or_Equal">
+ <title>Lesser or Equal</title>
+ <para>The result of the expression X<=Y.</para>
+ </section>
+ <section id="True">
+ <title>True</title>
+ <para>The result of the expression true.</para>
+ </section>
+ <section id="False">
+ <title>False</title>
+ <para>The result of the expression false.</para>
+ </section>
+ <section id="Identity">
+ <title>Identity</title>
+ <para>The result of the expression X.</para>
+ </section>
+ <section id="Different">
+ <title>Different</title>
+ <para>The result of the expression X!=Y.</para>
+ </section>
</section>
- <section id="Equal">
- <title>Equal</title>
- <para>The result of the expression X==Y.</para>
+ <section id="Numeric_Operators">
+ <title>Numeric Operators</title>
+ <section id="Negative_Value">
+ <title>Negative Value</title>
+ <para>The result of the expression -X.</para>
+ </section>
+ <section id="Add">
+ <title>Add</title>
+ <para>The result of the expression X+Y.</para>
+ </section>
+ <section id="Subtract">
+ <title>Subtract</title>
+ <para>The result of the expression X-Y.</para>
+ </section>
+ <section id="Multiply">
+ <title>Multiply</title>
+ <para>The result of the expression X*Y.</para>
+ </section>
+ <section id="Divide">
+ <title>Divide</title>
+ <para>The result of the expression X/Y.</para>
+ </section>
+ <section id="Power">
+ <title>Power</title>
+ <para>The result of the expression X^Y.</para>
+ </section>
+ <section id="Modulo">
+ <title>Modulo</title>
+ <para>The result of the expression X%Y.</para>
+ </section>
+ <section id="Increment">
+ <title>Increment</title>
+ <para>The result of the expression ++X.</para>
+ </section>
+ <section id="Decrement">
+ <title>Decrement</title>
+ <para>The result of the expression --X.</para>
+ </section>
+ <section id="Unit_Value">
+ <title>Unit Value</title>
+ <para>The result of the expression 1.</para>
+ </section>
+ <section id="Zero_Value">
+ <title>Zero Value</title>
+ <para>The result of the expression 0.</para>
+ </section>
+ <section id="Original_Value">
+ <title>Original Value</title>
+ <para>The result of the expression o.</para>
+ </section>
</section>
- <section id="Identical">
- <title>Identical</title>
- <para>The result of the expression X==Y.</para>
- </section>
- <section id="Greater">
- <title>Greater</title>
- <para>The result of the expression X>Y.</para>
- </section>
- <section id="Lesser">
- <title>Lesser</title>
- <para>The result of the expression X<Y.</para>
- </section>
- <section id="Greater_or_Equal">
- <title>Greater or Equal</title>
- <para>The result of the expression X>=Y.</para>
- </section>
- <section id="Lesser_or_Equal">
- <title>Lesser or Equal</title>
- <para>The result of the expression X<=Y.</para>
- </section>
- <section id="True">
- <title>True</title>
- <para>The result of the expression true.</para>
- </section>
- <section id="False">
- <title>False</title>
- <para>The result of the expression false.</para>
- </section>
- <section id="Identity">
- <title>Identity</title>
- <para>The result of the expression X.</para>
- </section>
- <section id="Different">
- <title>Different</title>
- <para>The result of the expression X!=Y.</para>
- </section>
- </section>
- <section id="Numeric_Operators">
- <title>Numeric Operators</title>
- <section id="Negative_Value">
- <title>Negative Value</title>
- <para>The result of the expression -X.</para>
- </section>
- <section id="Add">
- <title>Add</title>
- <para>The result of the expression X+Y.</para>
- </section>
- <section id="Subtract">
- <title>Subtract</title>
- <para>The result of the expression X-Y.</para>
- </section>
- <section id="Multiply">
- <title>Multiply</title>
- <para>The result of the expression X*Y.</para>
- </section>
- <section id="Divide">
- <title>Divide</title>
- <para>The result of the expression X/Y.</para>
- </section>
- <section id="Power">
- <title>Power</title>
- <para>The result of the expression X^Y.</para>
- </section>
- <section id="Modulo">
- <title>Modulo</title>
- <para>The result of the expression X%Y.</para>
- </section>
- <section id="Increment">
- <title>Increment</title>
- <para>The result of the expression ++X.</para>
- </section>
- <section id="Decrement">
- <title>Decrement</title>
- <para>The result of the expression --X.</para>
- </section>
- <section id="Unit_Value">
- <title>Unit Value</title>
- <para>The result of the expression 1.</para>
- </section>
- <section id="Zero_Value">
- <title>Zero Value</title>
- <para>The result of the expression 0.</para>
- </section>
- <section id="Original_Value">
- <title>Original Value</title>
- <para>The result of the expression o.</para>
- </section>
- </section>
- <section id="Spatial">
- <title>Spatial</title>
- <section id="Nearest">
- <title>Nearest</title>
- <para>Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.</para>
- </section>
- <section id="Toward">
- <title>Toward</title>
- <para>Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.</para>
- </section>
- <section id="Within">
- <title>Within</title>
- <para>Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.</para>
- <literallayout>Inputs:
-[Numeral]
-</literallayout>
- </section>
- <section id="Neighbor">
- <title>Neighbor</title>
- <para>Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.</para>
- </section>
- <section id="Include_Self">
- <title>Include Self</title>
- <para>Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.</para>
- </section>
- <section id="Within_2D_Boundary">
- <title>Within 2D Boundary</title>
- <para>Represents agents or locations that exist within the boundary specified by the inputs.</para>
- <literallayout>Inputs:
-[Numeral]
-</literallayout>
- </section>
- <section id="Here">
- <title>Here</title>
- <para>Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used. </para>
- </section>
- <section id="Available">
- <title>Available</title>
- <para>Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.</para>
- </section>
- <section id="Distance">
- <title>Distance</title>
- <para>The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.</para>
- <literallayout>Outputs:
-[Real]
-</literallayout>
- </section>
- <section id="Away">
- <title>Away</title>
- <para>Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.</para>
- </section>
- <section id="Minimize">
- <title>Minimize</title>
- <para>This function is not currently supported.</para>
- </section>
- <section id="Maximize">
- <title>Maximize</title>
- <para>This function is not currently supported.</para>
- </section>
- <section id="Location_2D">
- <title>Location 2D</title>
- <para>Represents the location of the current agent for use in subsequent selections.</para>
- <literallayout>Inputs:
-[Real]
-[Real]
-</literallayout>
- </section>
- <section id="Boundary_2D">
- <title>Boundary 2D</title>
- <para>Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)</para>
- <literallayout>Outputs:
-[Real]
-[Real]
-</literallayout>
+ <section id="Math">
+ <title>Math</title>
+ <para>The math functions use the extremely well specified and tested routines form the Java Math library. (Because of copyright restrictions, we aren't able to include the exact definitions here. Click on the links to get more details on each function.)</para>
+ <section id="Sine">
+ <title>Sine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)</ulink>
+ </para>
+ </section>
+ <section id="Cosine">
+ <title>Cosine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)</ulink>
+ </para>
+ </section>
+ <section id="Tangent">
+ <title>Tangent</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)</ulink>
+ </para>
+ </section>
+ <section id="Arc_Sine">
+ <title>Arc Sine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)</ulink>
+ </para>
+ </section>
+ <section id="Arc_Cosine">
+ <title>Arc Cosine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)</ulink>
+ </para>
+ </section>
+ <section id="Arc_Tangent">
+ <title>Arc Tangent</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)</ulink>
+ </para>
+ </section>
+ <section id="Convert_Degree_to_Radians">
+ <title>Convert Degree to Radians</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)</ulink>
+ </para>
+ </section>
+ <section id="Convert_Radians_to_Degrees">
+ <title>Convert Radians to Degrees</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)</ulink>
+ </para>
+ </section>
+ <section id="Exp">
+ <title>Exp</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)</ulink>
+ </para>
+ </section>
+ <section id="Log">
+ <title>Log</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)</ulink>
+ </para>
+ </section>
+ <section id="Log_b10">
+ <title>Log b10</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)</ulink>
+ </para>
+ </section>
+ <section id="Square_Root">
+ <title>Square Root</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)</ulink>
+ </para>
+ </section>
+ <section id="Cube_Root">
+ <title>Cube Root</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)</ulink>
+ </para>
+ </section>
+ <section id="Remainder">
+ <title>Remainder</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="Ceiling">
+ <title>Ceiling</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)</ulink>
+ </para>
+ </section>
+ <section id="Floor">
+ <title>Floor</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)</ulink>
+ </para>
+ </section>
+ <section id="Rount">
+ <title>Rount</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)</ulink>
+ </para>
+ </section>
+ <section id="Arc_Tangent_Rectangular">
+ <title>Arc Tangent Rectangular</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="Power_2">
+ <title>Power</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="Absolute_Value">
+ <title>Absolute Value</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)</ulink>
+ </para>
+ </section>
+ <section id="Maximum">
+ <title>Maximum</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="Minimum">
+ <title>Minimum</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="ULP">
+ <title>ULP</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)</ulink>
+ </para>
+ </section>
+ <section id="Sign">
+ <title>Sign</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)</ulink>
+ </para>
+ </section>
+ <section id="Hyperbolic_Sine">
+ <title>Hyperbolic Sine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)</ulink>
+ </para>
+ </section>
+ <section id="Hyperbolic_Cosine">
+ <title>Hyperbolic Cosine</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)</ulink>
+ </para>
+ </section>
+ <section id="Hyperbolic_Tan">
+ <title>Hyperbolic Tan</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)</ulink>
+ </para>
+ </section>
+ <section id="Hypotuneuse">
+ <title>Hypotuneuse</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)</ulink>
+ </para>
+ </section>
+ <section id="Expm1">
+ <title>Expm1</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)</ulink>
+ </para>
+ </section>
+ <section id="Log1p">
+ <title>Log1p</title>
+ <para>See JavaDoc:
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)</ulink>
+ </para>
+ </section>
</section>
</section>
<section id="Random">
<title>Random</title>
- <section id="Random_In_Range">
- <title>Random In Range</title>
- <para>A pseudo-random value within that numeric range specified as drawn from a uniform distribution. The minimum values are inclusive. The maximum values are inclusive for integer inputs and exclusive for Real inputs.</para>
- <literallayout>Inputs:
+ <section id="Design_2">
+ <title>Design</title>
+ <para>Random functions are especially significant for agent models. Of particular interest are the weighted membership and random state and boolean value functions. You should be familiar with these functions so that you don't have to create more complex Action flows to accomplish the same thing.</para>
+ <para>Note that we only have support for uniform distributions as of this release. We're working on a collaborative design for evaluations that allow easy mixing and matching of random functions and distributions.</para>
+ </section>
+ <section id="Details_6">
+ <title>Details</title>
+ <section id="Random_In_Range">
+ <title>Random In Range</title>
+ <para>A pseudo-random value within that numeric range specified as drawn from a uniform distribution. The minimum values are inclusive. The maximum values are inclusive for integer inputs and exclusive for Real inputs.</para>
+ <literallayout>Inputs:
[Numeral] The minimum value (inclusive).
[Numeral] The maximum value (inclusive).
Outputs:
[Numeral] The random number.
</literallayout>
- </section>
- <section id="Random_To_Limit">
- <title>Random To Limit</title>
- <para>A pseudo-random value between zero and the value specified by the (non-zero) input and drawn from a uniform range. That value is inclusive for Integers and exclusive for Reals. (Note that as with the random in range function in the context of real numbers the distinction between an exclusive and inclusive limit is essentially meaningless.)</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Random_To_Limit">
+ <title>Random To Limit</title>
+ <para>A pseudo-random value between zero and the value specified by the (non-zero) input and drawn from a uniform range. That value is inclusive for Integers and exclusive for Reals. (Note that as with the random in range function in the context of real numbers the distinction between an exclusive and inclusive limit is essentially meaningless.)</para>
+ <literallayout>Inputs:
[Numeral] The maximum value (inclusive).
Outputs:
[Numeral] The result.
</literallayout>
- </section>
- <section id="Random_Unit">
- <title>Random Unit</title>
- <para>A pseudo-random Real value between 0 and 1 drawn from a uniform distribution. (The distinction between inclusive and exclusive range is essentially meaningless in this context and we can assume that the result will never be greater or equal to 1.)</para>
- <literallayout>Outputs:
+ </section>
+ <section id="Random_Unit">
+ <title>Random Unit</title>
+ <para>A pseudo-random Real value between 0 and 1 drawn from a uniform distribution. (The distinction between inclusive and exclusive range is essentially meaningless in this context and we can assume that the result will never be greater or equal to 1.)</para>
+ <literallayout>Outputs:
[Real]
</literallayout>
- </section>
- <section id="Random_Boolean">
- <title>Random Boolean</title>
- <para>A value that is randomly true or false, i.e. a fair coin toss.</para>
- </section>
- <section id="Random_Weighted">
- <title>Random Weighted</title>
- <para>An indexed value weighted against a probability distribution. The total probability must sum to 1.0. For example, an input of {.1,.2,.7} under a uniform distribution would would have 10% probability of producing "0" , 20% for "1" and 70% for "2". This function can then be used with Item to return a biased result from another list.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Random_Boolean">
+ <title>Random Boolean</title>
+ <para>A value that is randomly true or false, i.e. a fair coin toss.</para>
+ </section>
+ <section id="Random_Weighted">
+ <title>Random Weighted</title>
+ <para>An indexed value weighted against a probability distribution. The total probability must sum to 1.0. For example, an input of {.1,.2,.7} under a uniform distribution would would have 10% probability of producing "0" , 20% for "1" and 70% for "2". This function can then be used with Item to return a biased result from another list.</para>
+ <literallayout>Inputs:
[Real] A list of values that will determine the resulting weighted index.
Outputs:
[Integer] A resulting indexed value bounded by 0 and the length of the input list - 1.
</literallayout>
- </section>
- <section id="Random_Member">
- <title>Random Member</title>
- <para>Represents a random value drawn from the set of Real values specified.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Random_Member">
+ <title>Random Member</title>
+ <para>Represents a random value drawn from the set of Real values specified.</para>
+ <literallayout>Inputs:
[Real] Returns a random member of the supplied list of numbers.
Outputs:
[Generic] The value of the item at a random index.
</literallayout>
- </section>
- <section id="Random_State">
- <title>Random State</title>
- <para>A random specified value (option) from the specified state.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Random_State">
+ <title>Random State</title>
+ <para>A random specified value (option) from the specified state.</para>
+ <literallayout>Inputs:
[Generic] The state to select items from. All items are included.
Outputs:
[Boolean] The resulting option.
</literallayout>
+ </section>
</section>
</section>
- <section id="Graphic">
- <title>Graphic</title>
- <section id="Shape_Oval">
- <title>Shape Oval</title>
- <para>Draw a generic oval.</para>
+ <section id="Space_2">
+ <title>Space</title>
+ <section id="Design_3">
+ <title>Design</title>
+ <para>Spatial functions provide the core functionality for Agent Models. Spatial functions are polymorphic, which basically means that they don't care what space they are operating on as long as that space is suitable for them. Spatial functions are designed to collaborate with one another. For example, by intersecting the "Neighbor", "Available" and "Toward" functions, we can design a rule that causes the agent to move to the next neighboring cell that get's it closer to some target agent. See the function details for more information.</para>
</section>
- <section id="Shape_Rectangle">
- <title>Shape Rectangle</title>
- <para>Draws a rectangular shape.</para>
- </section>
- <section id="Shape_Inset">
- <title>Shape Inset</title>
- <para>Shrinks the current shape by the input amount. (The overall scale is currently unspecified, but in most implementations should be 20.)</para>
- <literallayout>Inputs:
-[Integer] Number of nominal pixels to inset.
+ <section id="Details_7">
+ <title>Details</title>
+ <section id="Nearest">
+ <title>Nearest</title>
+ <para>Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.</para>
+ </section>
+ <section id="Toward">
+ <title>Toward</title>
+ <para>Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.</para>
+ </section>
+ <section id="Within">
+ <title>Within</title>
+ <para>Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.</para>
+ <literallayout>Inputs:
+[Numeral]
</literallayout>
- </section>
- <section id="Shape_Marker">
- <title>Shape Marker</title>
- <para>Draw a marker, that is a graphical indicator that can be used to add an additional que about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape. </para>
- </section>
- <section id="Shape_Marker_2">
- <title>Shape Marker 2</title>
- <para>Represents a marker placed in a different location from the other shape markers.</para>
- </section>
- <section id="Shape_Marker_3">
- <title>Shape Marker 3</title>
- <para>Represents a marker placed in a different location from the other shape markers.</para>
- </section>
- <section id="Color_RGB">
- <title>Color RGB</title>
- <para>A color specified by the three inputs for Red, Green and Blue color components. Those inputs are expected to be in the range 0..1.</para>
- <literallayout>Inputs:
-[Real] A value from 0.0 to 1.0.
-[Real] A value from 0.0 to 1.0.
-[Real] A value from 0.0 to 1.0.
+ </section>
+ <section id="Neighbor">
+ <title>Neighbor</title>
+ <para>Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.</para>
+ </section>
+ <section id="Include_Self">
+ <title>Include Self</title>
+ <para>Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.</para>
+ </section>
+ <section id="Within_2D_Boundary">
+ <title>Within 2D Boundary</title>
+ <para>Represents agents or locations that exist within the boundary specified by the inputs.</para>
+ <literallayout>Inputs:
+[Numeral]
</literallayout>
+ </section>
+ <section id="Here">
+ <title>Here</title>
+ <para>Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used. </para>
+ </section>
+ <section id="Available">
+ <title>Available</title>
+ <para>Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.</para>
+ </section>
+ <section id="Distance">
+ <title>Distance</title>
+ <para>The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.</para>
+ <literallayout>Outputs:
+[Real]
+</literallayout>
+ </section>
+ <section id="Away">
+ <title>Away</title>
+ <para>Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.</para>
+ </section>
+ <section id="Minimize">
+ <title>Minimize</title>
+ <para>This function is not currently supported.</para>
+ </section>
+ <section id="Maximize">
+ <title>Maximize</title>
+ <para>This function is not currently supported.</para>
+ </section>
+ <section id="Location_2D">
+ <title>Location 2D</title>
+ <para>Represents the location of the current agent for use in subsequent selections.</para>
+ <literallayout>Inputs:
+[Real]
+[Real]
+</literallayout>
+ </section>
+ <section id="Boundary_2D">
+ <title>Boundary 2D</title>
+ <para>Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)</para>
+ <literallayout>Outputs:
+[Real]
+[Real]
+</literallayout>
+ </section>
</section>
- <section id="Color_Red">
- <title>Color Red</title>
- <para>The color red.</para>
- </section>
- <section id="Color_Yellow">
- <title>Color Yellow</title>
- <para>The color yellow.</para>
- </section>
- <section id="Color_Blue">
- <title>Color Blue</title>
- <para>The color blue.</para>
- </section>
- <section id="Color_Orange">
- <title>Color Orange</title>
- <para>The color orange.</para>
- </section>
- <section id="Color_Green">
- <title>Color Green</title>
- <para>The color green.</para>
- </section>
- <section id="Color_Purple">
- <title>Color Purple</title>
- <para>The color purple.</para>
- </section>
- <section id="Color_Black">
- <title>Color Black</title>
- <para>The color black.</para>
- </section>
- <section id="Color_White">
- <title>Color White</title>
- <para>The color white.</para>
- </section>
- <section id="Color_Gray">
- <title>Color Gray</title>
- <para>The color gray.</para>
- </section>
- <section id="Graphic_Outline">
- <title>Graphic Outline</title>
- <para>Draws an outline of the last evaluated shape, using the last specified color or the default color (usually black) if none has been specified.</para>
- </section>
- <section id="Graphic_Fill">
- <title>Graphic Fill</title>
- <para>Fills the last evaluated shape with the last specified color or the default color (usually black) if none has been specified.</para>
+ <section id="Example_2">
+ <title>Example</title>
+ <para>For examples of how spatial functions can be used within action flows to provide agents with complex movement behaviors, see the Modelers Guide actions examples. In the following example from that section, we define an action that causes a partner agent to move to an available neighboring space.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ActionsExampleNew.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
</section>
</section>
<section id="Time">
<title>Time</title>
- <section id="Now">
- <title>Now</title>
- <para>The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.</para>
- <literallayout>Outputs:
+ <section id="Details_8">
+ <title>Details</title>
+ <section id="Now">
+ <title>Now</title>
+ <para>The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.</para>
+ <literallayout>Outputs:
[Integer] The current period.
</literallayout>
+ </section>
</section>
</section>
- <section id="Math">
- <title>Math</title>
- <section id="Sine">
- <title>Sine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)</ulink>
- </para>
+ <section id="Graphics">
+ <title>Graphics</title>
+ <section id="Design_4">
+ <title>Design</title>
+ <para>Graphic functions are combined within Style Evaluate Actions to determine how to draw an agent within a visualization. One nice aspect of this approach is that the same style definition can be used in multiple places without changing any code. For example, the same style could be used to draw an agent on a two-dimensional grid within Escape, a three-dimensional shape within Escape, a Java Swing based visualization in Ascape, and an XML configured visualizaiton in Repast Simphony.</para>
+ <para>To define a graphic style for an agent, design a flow in which you create Evaluate Actions for color and shape, and then create an Evaluate Action with the graphic fill or outline function as a target of these.</para>
</section>
- <section id="Cosine">
- <title>Cosine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)</ulink>
- </para>
+ <section id="Details_9">
+ <title>Details</title>
+ <section id="Shape_Oval">
+ <title>Shape Oval</title>
+ <para>Draw a generic oval.</para>
+ </section>
+ <section id="Shape_Rectangle">
+ <title>Shape Rectangle</title>
+ <para>Draws a rectangular shape.</para>
+ </section>
+ <section id="Shape_Inset">
+ <title>Shape Inset</title>
+ <para>Shrinks the current shape by the input amount. (The overall scale is currently unspecified, but in most implementations should be 20.)</para>
+ <literallayout>Inputs:
+[Integer] Number of nominal pixels to inset.
+</literallayout>
+ </section>
+ <section id="Shape_Marker">
+ <title>Shape Marker</title>
+ <para>Draw a marker, that is a graphical indicator that can be used to add an additional cue about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape. </para>
+ </section>
+ <section id="Shape_Marker_2">
+ <title>Shape Marker 2</title>
+ <para>Represents a marker placed in a different location from the other shape markers.</para>
+ </section>
+ <section id="Shape_Marker_3">
+ <title>Shape Marker 3</title>
+ <para>Represents a marker placed in a different location from the other shape markers.</para>
+ </section>
+ <section id="Color_RGB">
+ <title>Color RGB</title>
+ <para>A color specified by the three inputs for Red, Green and Blue color components. Those inputs are expected to be in the range 0..1.</para>
+ <literallayout>Inputs:
+[Real] A value from 0.0 to 1.0.
+[Real] A value from 0.0 to 1.0.
+[Real] A value from 0.0 to 1.0.
+</literallayout>
+ </section>
+ <section id="Color_Red">
+ <title>Color Red</title>
+ <para>The color red.</para>
+ </section>
+ <section id="Color_Yellow">
+ <title>Color Yellow</title>
+ <para>The color yellow.</para>
+ </section>
+ <section id="Color_Blue">
+ <title>Color Blue</title>
+ <para>The color blue.</para>
+ </section>
+ <section id="Color_Orange">
+ <title>Color Orange</title>
+ <para>The color orange.</para>
+ </section>
+ <section id="Color_Green">
+ <title>Color Green</title>
+ <para>The color green.</para>
+ </section>
+ <section id="Color_Purple">
+ <title>Color Purple</title>
+ <para>The color purple.</para>
+ </section>
+ <section id="Color_Black">
+ <title>Color Black</title>
+ <para>The color black.</para>
+ </section>
+ <section id="Color_White">
+ <title>Color White</title>
+ <para>The color white.</para>
+ </section>
+ <section id="Color_Gray">
+ <title>Color Gray</title>
+ <para>The color gray.</para>
+ </section>
+ <section id="Graphic_Outline">
+ <title>Graphic Outline</title>
+ <para>Draws an outline of the last evaluated shape, using the last specified color or the default color (usually black) if none has been specified.</para>
+ </section>
+ <section id="Graphic_Fill">
+ <title>Graphic Fill</title>
+ <para>Fills the last evaluated shape with the last specified color or the default color (usually black) if none has been specified.</para>
+ </section>
</section>
- <section id="Tangent">
- <title>Tangent</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)</ulink>
+ <section id="Example_3">
+ <title>Example</title>
+ <para>In the following action flow for the epidemic style, we've create Query Actions to determine each agent's current state, picked a color based on that, and then used a shared target to select a shape for the agent style and fill it:</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/GraphicsFunctionExampleDesign.png"/>
+ </imageobject>
+ </mediaobject>
</para>
- </section>
- <section id="Arc_Sine">
- <title>Arc Sine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)</ulink>
- </para>
- </section>
- <section id="Arc_Cosine">
- <title>Arc Cosine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)</ulink>
- </para>
- </section>
- <section id="Arc_Tangent">
- <title>Arc Tangent</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)</ulink>
- </para>
- </section>
- <section id="Convert_Degree_to_Radians">
- <title>Convert Degree to Radians</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)</ulink>
- </para>
- </section>
- <section id="Convert_Radians_to_Degrees">
- <title>Convert Radians to Degrees</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)</ulink>
- </para>
- </section>
- <section id="Exp">
- <title>Exp</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)</ulink>
- </para>
- </section>
- <section id="Log">
- <title>Log</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)</ulink>
- </para>
- </section>
- <section id="Log_b10">
- <title>Log b10</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)</ulink>
- </para>
- </section>
- <section id="Square_Root">
- <title>Square Root</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)</ulink>
- </para>
- </section>
- <section id="Cube_Root">
- <title>Cube Root</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)</ulink>
- </para>
- </section>
- <section id="Remainder">
- <title>Remainder</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)</ulink>
- </para>
- </section>
- <section id="Ceiling">
- <title>Ceiling</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)</ulink>
- </para>
- </section>
- <section id="Floor">
- <title>Floor</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)</ulink>
- </para>
- </section>
- <section id="Rount">
- <title>Rount</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)</ulink>
- </para>
- </section>
- <section id="Arc_Tangent_Rectangular">
- <title>Arc Tangent Rectangular</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)</ulink>
- </para>
- </section>
- <section id="Power_2">
- <title>Power</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)</ulink>
- </para>
- </section>
- <section id="Absolute_Value">
- <title>Absolute Value</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)</ulink>
- </para>
- </section>
- <section id="Maximum">
- <title>Maximum</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)</ulink>
- </para>
- </section>
- <section id="Minimum">
- <title>Minimum</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)</ulink>
- </para>
- </section>
- <section id="ULP">
- <title>ULP</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)</ulink>
- </para>
- </section>
- <section id="Sign">
- <title>Sign</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)</ulink>
- </para>
- </section>
- <section id="Hyperbolic_Sine">
- <title>Hyperbolic Sine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)</ulink>
- </para>
- </section>
- <section id="Hyperbolic_Cosine">
- <title>Hyperbolic Cosine</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)</ulink>
- </para>
- </section>
- <section id="Hyperbolic_Tan">
- <title>Hyperbolic Tan</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)</ulink>
- </para>
- </section>
- <section id="Hypotuneuse">
- <title>Hypotuneuse</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)</ulink>
- </para>
- </section>
- <section id="Expm1">
- <title>Expm1</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)</ulink>
- </para>
- </section>
- <section id="Log1p">
- <title>Log1p</title>
- <para>See JavaDoc:
- <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)">http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)</ulink>
+ <para>After saving the model we can execute the two and three dimensional visualizations. Note something really nice -- even the charts have used the colors we've defined!</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/GraphicsFunctionExampleRun.png"/>
+ </imageobject>
+ </mediaobject>
</para>
</section>
</section>
- <section id="List">
- <title>List</title>
- <section id="Item">
- <title>Item</title>
- <para>Returns the item at the specified index from the list of items provided. Those items will typically be input primitives such as Integer or Real values.</para>
- <literallayout>Inputs:
+ <section id="Lists">
+ <title>Lists</title>
+ <section id="Details_10">
+ <title>Details</title>
+ <section id="Item">
+ <title>Item</title>
+ <para>Returns the item at the specified index from the list of items provided. Those items will typically be input primitives such as Integer or Real values.</para>
+ <literallayout>Inputs:
[Generic]
[Integer]
Outputs:
[Generic]
</literallayout>
- </section>
- <section id="Length">
- <title>Length</title>
- <para>The number of items in the provided list of items.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Length">
+ <title>Length</title>
+ <para>The number of items in the provided list of items.</para>
+ <literallayout>Inputs:
[Generic]
Outputs:
[Integer]
</literallayout>
+ </section>
</section>
</section>
- <section id="Distribution">
- <title>Distribution</title>
- <section id="Uniform_Cross_Distribution">
- <title>Uniform Cross Distribution</title>
- <para>A random number taken from a distribution of values as defined by a cross of all values. (See Cross Distribution.) This funciton then returns a value drawn from the minimum and maximum values as determined by the current agent state. In the cross distribution, each of the values is treated independently so that an input attribute is created for every potential combination of states.</para>
- <literallayout>Inputs:
+ <section id="Attribute_Distributions">
+ <title>Attribute Distributions</title>
+ <para>One of the most common tasks in the Agent Modeling process is the creation of agents with particular states drawn from a distribution. For example, you might want to create a number of agents with wealth randomly distributed between some minimum and maximum values. The distribution functions greatly ease the process of setting up those initializations and their associated parameters.</para>
+ <section id="Distribution">
+ <title>Distribution</title>
+ <section id="Uniform_Cross_Distribution">
+ <title>Uniform Cross Distribution</title>
+ <para>A random number taken from a distribution of values as defined by a cross of all values. (See Cross Distribution.) This funciton then returns a value drawn from the minimum and maximum values as determined by the current agent state. In the cross distribution, each of the values is treated independently so that an input attribute is created for every potential combination of states.</para>
+ <literallayout>Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
[Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
[Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting random number based on the current agent state and the input parameters.
</literallayout>
- </section>
- <section id="Uniform_Additive_Distribution">
- <title>Uniform Additive Distribution</title>
- <para>A random number taken from a distribution of values in which each of the minimum and maximum values are added to determine a total minimum and maximum value. (See Additive Distribution.) In the additive distribution, each of the values is treated as dependent on the others so that an input attribute is only created for each seperate state.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Uniform_Additive_Distribution">
+ <title>Uniform Additive Distribution</title>
+ <para>A random number taken from a distribution of values in which each of the minimum and maximum values are added to determine a total minimum and maximum value. (See Additive Distribution.) In the additive distribution, each of the values is treated as dependent on the others so that an input attribute is only created for each seperate state.</para>
+ <literallayout>Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
[Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
[Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting random number based on the current agent state and the input parameters.
</literallayout>
- </section>
- <section id="Cross_Distribution">
- <title>Cross Distribution</title>
- <para>A value taken from a set of (auto-generated) attributes based on the value of each state included. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create separate input attributes for AI, AII, BI and BII. Then for an agent with States A and II this function would return the value specified by the AII input attribute.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Cross_Distribution">
+ <title>Cross Distribution</title>
+ <para>A value taken from a set of (auto-generated) attributes based on the value of each state included. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create separate input attributes for AI, AII, BI and BII. Then for an agent with States A and II this function would return the value specified by the AII input attribute.</para>
+ <literallayout>Inputs:
[Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
[Real] The set of attributes that when multiplied against each other will determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting value based on the current agent state and the input parameters.
</literallayout>
- </section>
- <section id="Additive_Distribution">
- <title>Additive Distribution</title>
- <para>A value taken from a set of (auto-generated) attributes based on the combined values of the states provided. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create input attributes for A, B, I and II. Those values would then be added together, so that for an Agent with state A and II this function would return A + II.</para>
- <literallayout>Inputs:
+ </section>
+ <section id="Additive_Distribution">
+ <title>Additive Distribution</title>
+ <para>A value taken from a set of (auto-generated) attributes based on the combined values of the states provided. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create input attributes for A, B, I and II. Those values would then be added together, so that for an Agent with state A and II this function would return A + II.</para>
+ <literallayout>Inputs:
[Generic] The states to include in the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
[Real] The set of attributes that when combined with each other determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
Outputs:
[Real] The resulting value based on the current agent state and the input parameters.
</literallayout>
+ </section>
+ </section>
+ <section id="Example_4">
+ <title>Example</title>
+ <para>In the following example, we walk through the process of using a distribution functions, demonstrating how we can easily modify the Epidemic model so that instead of simply setting an initial exposed population, we can define factors that take together will determine an individuals initial exposure state. We simply:</para>
+ <orderedlist>
+ <listitem>
+ <para>Create an Evaluate Action called "Initial Status". </para>
+ </listitem>
+ <listitem>
+ <para>Set the function to "Cross Distribution"</para>
+ </listitem>
+ <listitem>
+ <para>Opened the "Multiple Value" node in the editor, and clicked the "Multiple Values" item within it.</para>
+ </listitem>
+ <listitem>
+ <para>Selected the "Status" attribute.</para>
+ </listitem>
+ </orderedlist>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DistributionDesignChoice.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>The appropriate attributes are automatically added to the model, as you can see below.</para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DistributionDesign.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>In order to assign these values to the agent, we'd simply need to assign the results of this Evaluate Action to the agent.</para>
+ </section>
+ </section>
+ <section id="Diagrams_3">
+ <title>Diagrams</title>
+ <para>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</para>
+ <section id="Meta-Classes_3">
+ <title>Meta-Classes</title>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/FunctionsDiagram.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
</section>
</section>
</section>
- <section id="Diagrams_3">
- <title>Diagrams</title>
- <para>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</para>
- <section id="Meta-Classes_3">
- <title>Meta-Classes</title>
+ </section>
+ </chapter>
+ <chapter id="Creating_Agent_Models">
+ <title>Creating Agent Models</title>
+ <section id="Getting_Started_2">
+ <title>Getting Started</title>
+ </section>
+ </chapter>
+ <chapter id="Exploring_Agent_Models">
+ <title>Exploring Agent Models</title>
+ </chapter>
+ <chapter id="Programer.27s_Guide">
+ <title>Programer's Guide</title>
+ <section id="Overview_5">
+ <title>Overview</title>
+ <para>Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based API and end user modeling tools. It's based on Ascape, which has been in use for more than 10 years. The core API is very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then execute those models within the same development environment.</para>
+ <para>
+ <ulink url="/wiki/image:EscapeExecutionScreenshot.png">image:EscapeExecutionScreenshot.png</ulink>
+ </para>
+ <para>A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM toolkit -- is to provide an exemplar to demonstrate how any arbitrary agent modeling framework can be integrated within the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than ten years ago and that has not been modified at all in order for it to work within the AMP environment.</para>
+ <para>(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and AGF components.)</para>
+ </section>
+ <section id="Getting_Started_3">
+ <title>Getting Started</title>
+ <section id="Documentation_and_other_Resources">
+ <title>Documentation and other Resources</title>
+ <para>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation. There is complete Javadoc as well as a manual and other web resources. See the
+ <ulink url="http://ascape.sourceforge.net">Ascape Website</ulink> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape so ignore all of the bits about project setup, and a lot of the UI is different, but the basics apply to Escape just as well. The
+ <ulink url="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</ulink> written by Damon Centola should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual work under Ascape. (Converting these models is a great opportunity for a community contribution!)
+ </para>
+ </section>
+ </section>
+ <section id="Installation">
+ <title>Installation</title>
+ <para>Escape is
+ <ulink url="http://eclipse.org/amp/installing/">installed</ulink> by default with the other model components. If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from source but in that case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site if you're not actually doing AMP development.
+ </para>
+ </section>
+ <section id="Exploring_Example_ABM_Models">
+ <title>Exploring Example ABM Models</title>
+ <para>The first thing most people will want to do in AMP is to play with the example models. You don't need to do any programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is
+ <ulink url="http://eclipse.org/amp/installing">Install AMP</ulink>. (You don't need any of the optional components unless you want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really interesting classic ABM models.
+ </para>
+ <section id="AMF_Models">
+ <title>AMF Models</title>
+ <para>There are a number of models developed with AMF that can automatically generate example models to run in Escape. There are two ways to run the example models:</para>
+ <section id="Setup_Escape_Projects">
+ <title>Setup Escape Projects</title>
+ <section id="Creating_a_New_Escape_Project">
+ <title>Creating a New Escape Project</title>
+ <para>The best option is to simply create a new Escape project and drag the models into it! We're working on a simple cheat sheet for this, but until then, just follow these simple steps:</para>
+ <orderedlist>
+ <listitem>
+ <para>If you're not already there, open the Agent Modeling Perspective. Select Window > Open Perspective > Other.. and then Agent Modeling. (Or you can choose Window > Reset Perspective and the Agent Modeling perspective should appear in the Open Perspective list itself.)</para>
+ </listitem>
+ <listitem>
+ <para>Next, let's create the project where we'll place our model. Select File > New > Escape AMF Project. Give it a name like "escape.tutorial", then click Finish.</para>
+ </listitem>
+ <listitem>
+ <para>Finally grab the Epidemic.metaabm model at
+ <ulink url="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</ulink> and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in which case just right-click on the link and save it to a file.)
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="Using_an_Pre-Built_Example_Project">
+ <title>Using an Pre-Built Example Project</title>
+ <para>If you get really stuck somewhere, you can also get ready made projects from CVS. See
+ <ulink url="http://eclipse.org/amp/developers/repositoryDetails.php">this page</ulink> for information on CVS setup. The project for Escape example models are located at:
+ </para>
+ <literallayout>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
+</literallayout>
+ </section>
+ </section>
+ <section id="Run_the_Model">
+ <title>Run the Model</title>
+ <para>Right-click on the model, and select "Execute"! You should see something like this:</para>
<para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/FunctionsDiagram.png"/>
- </imageobject>
- </mediaobject>
+ <ulink url="/wiki/image:EpidemicModelRunning.png">image:EpidemicModelRunning.png</ulink>
</para>
+ <para>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory. The toolbar buttons allow you to control model execution.</para>
+ <para>
+ <ulink url="/wiki/image:EpidemicModelControls.png">image:EpidemicModelControls.png</ulink>
+ </para>
+ <para>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.</para>
+ <para>
+ <ulink url="/wiki/image:EpidemicModelComparison.png">image:EpidemicModelComparison.png</ulink>
+ </para>
+ <para>If you want to find out more about an agent, show the properties view, and click on agent.</para>
+ <para>
+ <ulink url="/wiki/image:EpidemicModelAgentProperties.png">image:EpidemicModelAgentProperties.png</ulink>
+ </para>
+ <para>You can experiment with different parameters (settings) for models by then clicking in the gray area away within the view.</para>
+ <para>
+ <ulink url="/wiki/image:EpidemicModelProperties.png">image:EpidemicModelProperties.png</ulink>
+ </para>
+ <para>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.</para>
+ </section>
+ <section id="Next_Steps">
+ <title>Next Steps</title>
+ <para>Other models are located at: (to do)</para>
+ <para>To understand the capabilities of AMF, you might also want to try out running the same models automatically generated for Ascape or Repast.</para>
+ <literallayout>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
+org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
+</literallayout>
+ </section>
+ </section>
+ <section id="Classic_Java_ABM_Models">
+ <title>Classic Java ABM Models</title>
+ <para>Many models have been created using Ascape over the years, including all of the classic models created at Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've all been converted to run in Escape. They're in Java but you can execute and explore them in exactly the same way as the Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You can get the projects in two ways:</para>
+ <section id="From_Project_Archive">
+ <title>From Project Archive</title>
+ <itemizedlist>
+ <listitem>
+ <para>Download the Escape examples zip from the Ascape sourceforge site:
+ <ulink url="http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download">http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Unzip the file.</para>
+ </listitem>
+ <listitem>
+ <para>Import them into your workspace. For help, see
+ <ulink url="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this page</ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="From_SVN">
+ <title>From SVN</title>
+ <itemizedlist>
+ <listitem>
+ <para>Import the SVN projects from the sourceforge SVN. For help, see
+ <ulink url="/wiki/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page">http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php this page</ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <literallayout>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
+http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
+</literallayout>
+ <para>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models. For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select "Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</para>
+ </section>
+ </section>
+ </section>
+ <section id="Developing_Models">
+ <title>Developing Models</title>
+ <para>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write programs using it.To develop new models, you can:</para>
+ <orderedlist>
+ <listitem>
+ <para>Create a new Escape project. The Escape projects are actually configured for AMF code generation so there are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.</para>
+ </listitem>
+ <listitem>
+ <para> But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have a look at the example escape project to see what you need. Note that you will likely need more dependencies then you need to simply build -- this is because the class loader uses the classes from the project path and so runtime classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these dependencies up a bit.</para>
+ </listitem>
+ </orderedlist>
+ <para>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</para>
+ </section>
+ </chapter>
+ <chapter id="Reference_3">
+ <title>Reference</title>
+ <section id="Converting_Existing_Ascape_models">
+ <title>Converting Existing Ascape models</title>
+ <para>There are only a few changes should have to make to existing Ascape models or to use existing Ascape documentation to develop Escape models.</para>
+ <section id="Model">
+ <section>
+ <title>Model</title>
+ <para>The core model is completely API compatible. No changes!</para>
+ </section>
+ <section id="View">
+ <title>View</title>
+ <para>Because Escape uses SWT and Ascape uses Swing, there are a few unavoidable incompatibilities. Most of these we avoid by using higher level APIs but here are the key changes that you're likely to have to make:</para>
+ <section id="Convert_the_low-level_imports_from_AWT_and_Swing_to_SWT">
+ <title>Convert the low-level imports from AWT and Swing to SWT</title>
+ <para>The simplest way to accomplish this is to remove all of the imports and then organize imports. For example:</para>
+ <literallayout>java.awt.Color => org.eclipse.swt.graphics.Color
+java.awt.Graphics => org.eclipse.draw2d.Graphics
+</literallayout>
+ <para>Then just do a global find for all of the imports and replace them with nothing. This is a great place for a regexp. Try:</para>
+ <literallayout>find: import java\.awt\.(.*);
+replace: [nothing]
+</literallayout>
+ <para>You don't have to replace these with the SWT equivalents, just click on the project, right-click and choose "Source:Organize Imports.."
+ By the way, a great way to avoid having to select the right entries in optimize imports and to alert you when you have missed anything is to prevent the awt and swing classes from being used at all. Right-click on project, choose "Build Path:Configure Build Path", go to Libraries tab, open JRE System Library, choose "Access Rules", edit, and then add entries for java/awt/** and javax/swing/**. The code will regenerate and you'll have error markers for all of the stuff that won't work with Escape and Eclipse.</para>
+ </section>
+ <section id="Convert_color_features">
+ <title>Convert color features</title>
+ <para>You can't use AWT colors either so you'll need to replace any colors. AMP provides a convenience classes for Colors called ColorFeature and ColorFeatureConcrete. You can use these or any of the other ways to define SWT colors. For example:</para>
+ <literallayout>Color.lightGray => ColorFeature.LIGHT_GRAY
+new Color(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy) =>
+ ColorFeatureConcrete.create(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy)
+</literallayout>
+ </section>
+ <section id="Change_agent_color_getters">
+ <title>Change agent color getters</title>
+ <para>If you've defined colors through overriding Agents as in most models, you'll need to change the method signature. You could just do a global replace for this one.</para>
+ <literallayout>public Color getColor( => public Object getPlatformColor(
+</literallayout>
+ </section>
+ <section id="Get_rid_of_image_features">
+ <title>Get rid of image features</title>
+ <para>Escape doesn't support them. In practice they haven't been used a lot. At some point perhaps we'll have nice sprite support instead. :)</para>
+ <literallayout>public Image getImage() {**} => ""
+</literallayout>
+ </section>
+ <section id="Modify_usages_of_DrawFeatures">
+ <title>Modify usages of DrawFeatures</title>
+ <para>If you've created any of your own draw features, you'll need to change them slightly to accommodate the differences between the AWT and SWT / Draw2D APIs. This should be pretty straightforwrd. For example:</para>
+ <literallayout>g.setColor(...
+g.fillOval(..
+becomes:
+g.setBackgroundColor(
+g.fillOval(..
+</literallayout>
+ <para>That's about it, though it's probable that we've missed something. Please post a message on the amp newsgroup if you run into any other conversion issues.</para>
+ </section>
+ </section>
+ <section id="Configuration">
+ <title>Configuration</title>
+ <para>Instead of using Ant, Escape has really nice support for parameterizing and testing models. See
+ <ulink url="/wiki/Experimenting_and_Testing">Experimenting and Testing</ulink> (todo). If you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape so it's not even clear it will work.
+ </para>
+ </section>
+ </section>
+ </section>
+ </chapter>
+ <chapter id="More_Information">
+ <title>More Information</title>
+ <section id="Obtaining_Example_Models">
+ <title>Obtaining Example Models</title>
+ <para>There is a cheat-sheet available for obtaining the example models. If you would rather obtain them yourself, here is the CVS information:</para>
+ <section id="Import_from_CVS">
+ <section>
+ <title>Import from CVS</title>
+ <itemizedlist>
+ <listitem>
+ <para>Import the CVS projects from the AMP project repository. For help, see
+ <ulink url="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm">this page</ulink>. For repository details, see
+ <ulink url="http://eclipse.org/amp/developers/repositoryDetails.php">http://eclipse.org/amp/developers/repositoryDetails.php</ulink>. These are the example projects:
+ </para>
+ </listitem>
+ </itemizedlist>
+ <literallayout>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
+org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
+org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
+</literallayout>
+ <itemizedlist>
+ <listitem>
+ <para>Right-click on the models to execute them.</para>
+ </listitem>
+ <listitem>
+ <para>Play around with the model attribute settings and behavior (Acts).</para>
+ </listitem>
+ </itemizedlist>
</section>
</section>
</section>
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/customBuild.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/customBuild.xml
index 9f676de..5775ee7 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/customBuild.xml
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/customBuild.xml
@@ -4,7 +4,7 @@
(c) Lawrence Mandel <lmandel@ca.ibm.com>
(c) Peter Friese <peter.friese@itemis.com>
-->
-<project name="org.eclipse.amp.doc" default="build-doc" basedir=".">
+<project name="org.eclipse.amp.doc" default="build-and-deploy-doc" basedir=".">
<!--
Global vars
@@ -119,7 +119,7 @@
<mkdir dir="${build.dir}"/>
</target>
- <target name="promote-doc">
+ <target name="deploy-doc">
<copy todir="${website.dir}/documentation" overwrite="true">
<fileset dir="html/">
<include name="**" />
@@ -143,6 +143,9 @@
<antcall target="docbook2eclipsehelp"/>
</target>
+ <target name="build-and-deploy-doc" depends="build-doc, deploy-doc">
+ </target>
+
<target name="check-docbook">
<condition property="hasDocbook">
<and>
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/000-Guide_Overview.mediawiki
similarity index 81%
rename from org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.mediawiki
rename to org.eclipse.amp/doc/org.eclipse.amp.doc/doc/000-Guide_Overview.mediawiki
index ad09531..62e1003 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.mediawiki
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/000-Guide_Overview.mediawiki
@@ -1,7 +1,10 @@
=Overview=
-The AMP project provides extensible frameworks and exemplary tools for representing, editing, generating,
+The Eclipse Agent Modeling Project (AMP) provides extensible frameworks and exemplary tools for representing, editing, generating,
executing and visualizing agent-based models (ABMs) and any other domain requiring spatial, behavioral and functional features.
+
+==Architecture==
+
AMP has two main themes that complement but don't depend on one another:
The overall AMP architecture and Eclipse project dependencies are summarized below:
@@ -12,9 +15,9 @@
AMP has many potential facets and use cases. Here are a few ways to get started with it.
-First, you'll need to [http://eclipse.org/amp/installing/ install it]. Then...
+First, if you aren't using a full download version of AMP, you'll need to [http://eclipse.org/amp/installing/ install it]. Then...
-==ABM Explorers==
+==ABM Modelers==
Experiment with example Java and AMF based models without writing code.
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/100-ModelersGuide_Intro.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/100-ModelersGuide_Intro.mediawiki
new file mode 100644
index 0000000..ee4afb1
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/100-ModelersGuide_Intro.mediawiki
@@ -0,0 +1,52 @@
+=Modeler's Guide=
+
+==Introduction==
+
+In this Modeler's Guide we provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design one. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Attributes, Spaces, and Actions. The first three refer to structural components, whereas Actions define behavior. Agent models also have styles, which are a special kind of Action used to determine how to portray an agent in a visualization. Finally Actions make use of Functions. We'll describe of these components in a separate section.
+
+But first, we'll give a quick overview at what agent-based modeling is is and how the Agent Modeling Framework can help you to develop models for ABM or other problem domains.
+
+===Agent-Based Modeling===
+
+The primary focus of the Agent Modeling Platform tools is "Agent-Based Modeling" (ABM). ABM is an innovative technique used to explore complex phenomenon in many domains, including economics, social sciences, biomedicine, ecology and business operations. ABMs share characteristics with object models, but are:
+
+;Spatial
+: Models have explicit environment(s) in which agents interact. (An environment need not be a physical landscape; other examples of spatial relationships include social networks or positions within a logic system.)
+;Temporal
+: Models change over discrete units of time.
+;Autonomous
+: Agent behaviors are activated independently from other object requests.
+;Heterogeneous
+: Agents may share behavior definitions but have apparent and distinct states and behaviors.
+;Collective
+: Models contain large communities of agents which exhibit collaborative and competitive behaviors.
+;Emergent
+: Agents have collective macro-behaviors that are non-obvious from agent micro-specifications.
+
+Existing scientific models are very good at representing relatively simple systems, but generally speaking aren't very good at representing complex systems. The world is full of complex systems, and our misunderstanding of these systems has prevented us from addressing many of the key challenges facing the world, including the global financial crisis and climate change -- in fact once could argue that our misunderstanding of these systems has strongly contributed to these crises.
+
+Agent-Based Models (ABMs) seek to represent important real-world dynamics by designing communities of software agents that mimic real entities. Rather than make simplifying assumptions about such systems and then representing them in equation form or as off the shelf algorithmic constructs, the ABM researcher aims to identify key agent state, interaction spaces, and behaviors. Agents are then "let loose" on our computers and we explore what happens next. The computational horsepower exists today to simulate large numbers (e.g. >>10) of interacting, adaptive and autonomous agents but often desktop computers are all we need to explore significant domains. ABMs have been designed to represent all kinds of important natural systems, at scales reaching from cellular mechanics to international trade and are being used to solve truly hard problems in government, business, and academia. ABMs are not a solution to every problem, but they can help us to appreciate and gain unique insight into many systems, and often they can help us to come up with better practical decisions than we might using classic approaches.
+
+===Agent Modeling Framework===
+
+The Eclipse Platform provides many unique features that make it ideal for an ABM platform. AMF provides easy to use and powerful tools and techniques for designing Agent-Based Models, including a common representation, editors, generators and development environment.
+
+The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level.
+
+The foundation of the Agent Modeling Framework is "Acore". The current version uses an interim version of Acore called "MetaABM". We refer to the AMF models as "meta-models" because they are used to define ''how'' Agent-Based Models are themselves modeled. For those familiar with Eclipse Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. Acore and MetaABM are defined in Ecore but provide a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms. AMF is fully integrated with the Eclipse IDE platform, but Acore models themselves need have no dependencies on any particular technology beyond XML/XSD.
+
+Models designed in AMF are transparently converted to Java code for leading Agent-Based Modeling tools, such as the Escape tools which are included in AMP and allow direct execution of models within the AMP environment, and Repast Simphony, another popular Java based ABM tool. These tools create Java code that can then be compiled, executed and event modified in these environments just as with any other Java program. AMF's generative capability is designed to be pluggable and modular so that other developers can create AMF generators for their own tools. In fact, targets can be designed that have no inherent dependencies on Eclipse or even on a traditional platform.
+
+The Acore / MetaABM meta-model is made up of three main packages. This is all based on MetaABM, and while names and important details will change for Acore, the core design should be quite similar.
+
+===Other Uses===
+
+Many kinds of objects share characteristics of ABM agents -- after all, software agents are used in many other contexts. The Agent Modeling Framework meta-modeling support is potentially suitable (or extendible) for a number of approaches outside of ABM; for example business rules, object interactions, systems dynamics models and traditional discrete event models. Similarly, AMP execution and graphic support can be used for modeling natural systems but could also be used to manage other software agents -- for example independent reasoning tasks or dynamic visualization support.
+
+We hope you enjoy using the tool, and we look forward to your comments and feedback and most of all participation!
+
+===Credits===
+
+The AMF meta-model started life as [[http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf|"score"]], a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continues development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009.
+
+Miles Parker is a consultant and software developer with over ten years of experience in the agent-based modeling field and twenty years developing object-oriented tools and frameworks. Metascape, LLC provides Agent-Based Modeling tools, including sophisticated tools based on the AMF platform, and comprehensive consulting services. For more information on Metascape products and services visit http://metascapeabm.com.
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/110-ModelersGuide_Structure.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/110-ModelersGuide_Structure.mediawiki
new file mode 100644
index 0000000..0692e9c
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/110-ModelersGuide_Structure.mediawiki
@@ -0,0 +1,213 @@
+==Structure==
+
+===Overview===
+
+The basic structure of an agent-based model can be quite simple. While there are many subtle complexities -- beyond the scope of this manual -- we can construct most models following some straightforward and elegant design principles. And in fact, one of the main goals of the Agent Modeling Framework is to provide a consistent framework that can support using those principles to support the creation of models that can be easily understood, shared, and that can be used interchangeably as components in other models.
+
+Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents.
+
+===Details===
+
+====General====
+
+Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore -- including Actions and Functions which we describe in the next two sections -- have a number of shared values.
+
+=====Named Entities=====
+
+======Label======
+A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Exchange Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.
+======ID======
+An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)
+
+And most entities also define:
+
+======Description======
+A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.
+======Plural Label======
+The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".
+
+====Agents====
+
+=====Simple Agents=====
+
+An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.
+
+======Attributes======
+
+As described in the attribute sections above.
+
+======Actions======
+
+Described in the "Actions" section.
+
+======Styles======
+
+Special actions that are used to define how to draw an agent graphically as also described in the "Actions" section and detailed in the "Functions" section.
+
+=====Context Agents (Contexts)=====
+
+As detailed above, agents also form the basic structural component of an agent-based model. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".
+
+======Agents======
+
+The agents that are contained within this context. For example, a context representing a city might contain an Individual Agent for defining all individuals in the model, and a Vehicle agent defining all vehicles. Note that when we refer to an agent in this context, we mean a general type or class of agent, not the agent itself.
+
+======Spaces======
+
+The set of all spaces contained or subsumed by the agent. For example, a context representing a city might contain a geographical space and a transportation network space.
+
+====Attributes====
+
+Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.
+
+Here are the basic types of attributes available in Acore models:
+
+=====Basic Attributes=====
+
+Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. In this section we go over the values you can set for the attributes. For those with a tecnical bent, note that we are technically describing the meta-attributes for the meta-class "SAttribute". But it is far too confusing to refer to the attributes of attributes! So we'll just refer to the attributes that any of our model components as "values".
+
+======Type======
+
+These can be anyone of the following:
+
+{| cellpadding=="10" cellspacing=="0" border=="1"
+|Boolean
+|A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.
+|-
+|Integer
+|A discrete whole number value, such as "100", "-1", "10029920". It's generally a good idea to represent any value that can never have a decimal value as an integer.
+|-
+|Real
+|A continuous number value. While these are typically represented in software as floating point numbers, they can conceivably represent numbers at any arbitrary precision and in any scheme. Note that while technically speaking we should be representing irrational numbers, this is not currently supported for default values and users should simply use the closest decimal approximation.
+|-
+|Symbol
+|A string representing some state. More precisely, a computationally arbitrary value with contextual meaning. This could be any kind of identifier. For example, you might use it to store some kind of input coding from data that is then converted into an object state. Or it could simply be an agent's name. But theoretically (though this is not currently supported) one could imagine a symbol using an idiogram, an icon or even a sound that identifies or represents the agent in question.
+|}
+
+(Undefined and Numeric types should not be used within a well-defined model.)
+
+
+======Default Value======
+
+The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.
+
+======Gather Data======
+
+Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.
+
+======Immutable======
+
+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.
+
+======Units======
+
+Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.
+
+
+=====Arrays=====
+
+Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to what is defined above, arrays specify:
+
+======Size======
+
+The number of values that the array attribute will contain.
+
+=====States=====
+
+States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".
+
+======State Options======
+
+Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have
+
+======Default Option======
+
+unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.
+
+
+====Spaces====
+
+All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:
+
+=====Space (Continuous)=====
+
+In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.
+
+======Border Rule======
+
+A value representing what happens to an agent when that agent is asked to move beyond its extent.
+
+;Periodic
+: When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location {1,2} (0-based) within a Moore space (see grid discussion below) of size {10,10} is asked to find some other agent within distance 3, the agent look in the square defined between {8,9} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.
+;APeriodic
+: When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location {1,2} is asked to find some other agent within distance 3, the agent look between {0,0} and {4,5}. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.
+
+The "Strict" and "Bouncy" values are obsolete and should not be used.
+
+ ======Dimensionality======
+
+The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attribute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.
+
+=====Grid=====
+
+A grid is technically a regular lattice structure. Currently, only rectilinear structures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platforms support n-d spaces yet.)
+
+Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:
+
+======Multi-Occupant======
+
+Does the grid allow more than one agent to occupy it at a time? This value may be replaced with another mechanism in future releases.
+
+======Neighborhood======
+
+This value determines what constitutes a region within a particular distance from the agent. The value for this is often critical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:
+
+;Euclidean
+: The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.
+;Moore
+:Here, the distance between any two cells is defined by the number of edge ''or'' corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.
+;Von-Neumann
+: Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.
+
+=====Network=====
+
+A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.
+
+A network has only one value to specify:
+
+======Directed======
+
+This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)
+
+=====Geography=====
+
+A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.
+
+===Reference===
+
+====Diagrams====
+
+For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.
+
+=====Meta-Classes=====
+
+Our first diagram depicts the core structural design of the model.
+
+[[Image:images/StructureComplexDiagram.png|800px]]
+
+ There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
+
+=====Key Collaborations=====
+
+[[Image:images/StructureSimpleDiagram.png]]
+
+ Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
+
+=====Details=====
+
+#Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally).
+#(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.
+#Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.
+#Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidean) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.
+#Agents are Actable and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.
+#Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actable. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/120-ModelersGuide_Actions.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/120-ModelersGuide_Actions.mediawiki
new file mode 100644
index 0000000..d6db00e
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/120-ModelersGuide_Actions.mediawiki
@@ -0,0 +1,315 @@
+==Actions==
+
+Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.
+
+===Overview===
+
+Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.
+
+An action provides simple, well-defined details that a model can use to determine what steps to take in model execution. That definition seems general enough to be almost useless, but its important to understand that an action is not equivalent to an instruction, a method or a query. In fact, actions can have aspects of all of these. But an action is not in itself an instruction specifying exactly ''how'' the modeling engine should do something -- instead an action represents ''what'' the modeler intends for the agents to do. (Technically, we might say that Actions takes a "declarative" approach instead of an 'imperative' approach, but that's not quite true, because actions do allow us to define behavior in a richer way than most declarative approaches, and many action constructs map directly to imperative approaches.)
+
+Actions are connected together in a series of sources and targets. (Technically, an acyclic directed graph.) In an abstract sense that is similar to the way any programming language is defined although that structure isn't usually obvious because of the constraints of textual representations. But unlike a typical programming language, in Actions it is not the execution thread (the processor) that moves from one instruction to the next, but the result of the previous action. In this way, action results "flow" from the output of one action into the next action.
+
+Why are these distinctions between traditional Object-Oriented and the Action approaches important? They give us the advantages of simplicity, clarity and flexibility that [[http://en.wikipedia.org/wiki/Dataflow_programming|data-flow approaches]] like spreadsheets and some query languages have, but with less restrictions. At the same time, they can bring us much of the power and expressiveness of [[http://en.wikipedia.org/wiki/Functional_programming|functional languages]] like Lisp or [[http://en.wikipedia.org/wiki/Logical_programming|logical languages]] like Prolog, but without the level of complexity and obscurity that such languages can have.
+
+We can get a better idea for how Actions work by thinking about how a spreadsheet works. In a spreadsheet, we might define a cell A that adds up a row of data, say "Income". We might define another cell C ("Profit") that takes A and adds it to another cell B that adds up another row of data ("Expenses"). Now, if we change a value in any of the rows, all of the other rows are added up and we get the results in A and B updated automatically. We never had to write code that said something like "for each cell in row X, where...". In fact, we don't really care ''how'' our Spreadsheet program adds up the numbers -- it could have added them all up at once but in backward order, or stored a running total somewhere and updated just the difference in value for the cell we changed -- what we care about is ''what'' the result is, and whether it is correct.
+
+But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.
+
+
+===Design===
+
+In this section, we'll describe how modelers can assemble actions into sets of behavior that accomplish complex tasks on interrelated agents and spaces over time.
+
+====Kinds of Actions====
+
+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. All of these are discussed in detail in the section that follows this one.
+
+These are all summarized in the diagram below:
+
+[[Image:images/ActionsBlocks.png]]
+
+====Flow====
+
+First, let's look at how actions define the basic path that agents take during a model run. As with any programming language, the path we take through the program specification is what determines our state when we get there. In a pure object oriented program, the path just defines the control flow -- what we are doing. The actual state of our model is defined within the object itself. If we call a method B from another method A, we'll be relying on method A to set the values that we need into the object state itself. In a purely functional program the path defines how we are going to deal with whatever has been explicitly passed in to a function that has been called, that is the function parameters. In fact, most languages such as Java combine aspects of both approaches.
+
+In Actions, the path itself implicitly carries all of the context of prior execution with it. This means that we don't have to worry about storing context in the object -- as we would in an object-oriented language -- or passing the correct values from one method call to the next as we would in a functional language. Instead, Actions can use the implicit context of the path of flow to determine what the current state of execution is.
+
+Again, behaviors in Actions are always defined by a set of ''selections'' and ''queries''. In the following diagram, we can see the pattern.
+
+[[Image:images/ActionsSequence.png]]
+
+First, we define a Root Selection for a Rule, Schedule or other triggering event. Then, we might add a series of Query and Logic Actions to define the specific agents that we are interested in. These are all part of the Selection. Next, we might define a series of Commands to determine what to do with those agents. Or, we could use the result of that selection to immediately define another selection, for example if we are searching for an agent that is near another agent. The next diagram depicts a simple example.
+
+[[Image:images/ActionsSimpleSequence.png]]
+
+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. In the 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.
+
+[[Image:images/ActionsSimpleSequence2.png]]
+
+In the following example, we've defined a set of actions and their relationships. We have a selection, a few queries and a couple of logic operators leading to a Set Action. We'll describe in detail below how Logic Actions are used in conjunction with other actions to assemble any kind of query structure needed. But for now, we'll focus on the control flow itself.
+
+[[Image:images/ActionsFlowSimple.png]]
+
+As you have probably already guessed, the agents that have the Set Action applied to them could take one of two paths through the Action flow. Readers with experience with programming or formal logic will note that this looks just like a parse tree, and while that's basically what it is, there are important differences. For example, if we looked at the following structure as a definition of control flow for a single agent we'd take them to be equivalent. Both would evaluate the statement (Query 1 AND Query 2) OR Query 3 for each agent.
+
+[[Image:images/ActionsFlowUnion.png]]
+
+Within Actions in many cases these two approaches will also act equivalently. If we are simply setting a value, it doesn't matter how an agent gets to that Set Action, as long as it gets there. All sources that flow into a given target Action act like a logical union since any of the paths might reach that target. But note that we have two flows moving in parallel in the flow on the right. What happens when the conditions for ''both'' branches are true? As the set of agents flow through each branch the Set Action on the left will be evaluated once, while the one on the right will be evaluated twice. Again, this often ends up with the same behavior, but not always. If for example, the evaluate Action uses the value of the attribute that we are setting as input, we can get different results. Of course, you can write code in any language that accomplishes the same thing, but the code will look quite different. For example, if we wrote the same basic logic in Java, in the first case we'd have something like:
+
+ if ((query1.evaluate() && query2.evaluate()) || query3.evaluate()) {
+ doSomething();
+ }
+
+In the second we'd have:
+
+ if (query1.evaluate() && query2.evaluate()) {
+ doSomething();
+ }
+ if (query3.evaluate()) {
+ doSomething();
+ }
+
+This is a simple example, but with multiple branches such code design issues can quickly grow complex. The flow approach allows us to express things in a way that is often more natural and expressive. The important thing to keep in mind when desiging action flows is to see the flow as representing a selection of agents moving through streams independently. In the Actions example we expressed both approaches in nearly the same way, except in the case on the left we used a Union Action to bring the two branches of flow back together.
+
+====Selections====
+
+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.
+
+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.
+
+[[Image:images/ActionsSelBoundarySimple.png]]
+
+Each time we create a new selection, we define a new set of boundaries.
+
+[[Image:images/ActionsSelBoundary2Parts.png]]
+
+A very important aspect of boundaries is that they apply to a group of actions that begin with a Query Action, and not just such a group that begins with a Select Action. This is because Query Actions can be directly part of a selection definition, but they can also refine selections, as we'll see. So where does one selection boundary end and the next one begin? The simple rule is that the end of the boundary is defined for a given Action by the place where:
+
+#A Query Action is not followed by a Logic Action, or
+#A Logic Action is not followed by another Logic Action
+
+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 we can see in the following example.
+
+[[Image:images/ActionsSelBoundary11A.png]]
+
+Note that we refer to "Selection 1" and Selection 1A". This is because Selection 1A is a refinement of Selection 1 along its particular path of flow. When a query appears for the same selection but past a particular boundary, you can think of it as a sort of filter on the selection contents. We don't have a "Selection 2" here because any Actions that refer to "Selection 1" along the current path of flow will be acting on the selection defined by Selection 1 and Selection 1A.
+
+These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a == x and attribute b == y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a == x, and ''then'' taking those agents and choosing those agents with b==y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
+
+[[Image:images/ActionsSelBoundaryComplex.png]]
+
+In the first case, we execute a search for all agents that meet the two criteria. This means that if there are ''any'' neighboring cells which are available, we're guaranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all. This then becomes an important aspect of model design. For example, if one were defining a model where neighbors played a game with each other, one might want to instruct agents to play the game only with neighbors that have a certain wealth threshold. In the real-world situation that we are modeling, we might simply search for neighbors who are over a given wealth threshold and then play the game with them. This would imply that information about other agent's wealth is open knowledge. Or, we might simply select a random neighbor, and ask that neighbor to play a game with us. Upon discovering that our neighbor does not meet our wealth criteria, we would then choose not to play with them. Here we are modeling a cost in time to obtain information about another agent's wealth, because we might miss an opportunity to play the game with another agent on that round.
+
+====Weaving====
+
+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.
+
+[[Image:images/ActionsWeavingSetAnother.png]]
+
+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.)
+
+[[Image:images/ActionsWeavingEvaluate.png]]
+
+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.
+
+[[Image:images/ActionsWeaving1A.png]]
+
+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. Now, consider the following example:
+
+[[Image:images/ActionsWeaving2.png]]
+
+Before going into further details we need to introduce one more important concept. 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.
+
+===Details===
+
+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.
+Let's look at the overall view again amd then dig into the details.
+
+[[Image:images/ActionsBlocks.png]]
+
+
+====Selections====
+
+A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.
+
+=====Select=====
+
+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):
+
+======Selection======
+
+The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.
+
+======Agent======
+
+Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.
+
+======Space======
+
+The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.
+
+Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.
+
+======For======
+
+This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.
+
+=====Query=====
+
+A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions.
+
+======Function======
+
+A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age == Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.
+
+=====Logic=====
+
+These Actions provide us with the ability to combine queries with one another, and follow the basic rules of set logic. But as we've seen above, it is important to understand that there are important differences between Logic Actions and typical programming logic. Most importantly, they apply not to individual agents per se, but to the set of agents that move through them. Also, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together because of the action flow design.
+
+=====Intersection=====
+
+An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. An agent must be able to flow through all incoming actions in order to flow out of an Intersection Action.
+
+=====Union=====
+
+A union contains all agents that match any of its source actions. This shares similiarities to a logical OR statement and the || operator in a java "if" statement. It does mroe than that however, as it acts to join multiple flows of action. That is, as set logic implies, an agent will never appear in the result of a union more than once.
+
+=====Difference=====
+
+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.
+
+=====Roots=====
+
+Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.
+
+=====Build=====
+
+The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined whether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.
+
+=====Initialize=====
+
+An Initialize action is executed once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guaranteed to execute before any other non-builder action occurs.
+
+=====Rule=====
+
+A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.
+
+=====Schedule=====
+
+A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time == t.
+
+======Start======
+
+The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..
+
+======Interval======
+
+How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..
+
+======Priority======
+
+Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.
+
+======Pick======
+
+Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be replaced by another approach.
+
+=====Watch=====
+
+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.
+
+======Attribute======
+
+The attribute that will be monitored for change.
+
+====Commands====
+
+=====Evaluate=====
+
+Evaluate Actions define some calculation on a function based on the model state and a set of input(s). The inputs that an Evaluate Action can take is determined by its functions and can be either agent attributes, prior evaluations or literals. The result is then determined based on those inputs. In some cases Evaluate functions can be used to determine some action indirectly, such as with a graphics fill, but they can never be used to directly change model state.
+
+======Selection======
+
+As with all other actions, evaluations specify a selection, and just as with the other actions, this determines the set of agents that the evaluation occurs for, but the input selections determine what agent is used for the calculation itself.
+
+======Function======
+
+A with queries, a function is evaluated against its input set. Functions can represent simple operators as well as complex functions. See the functions section for more information on specific functions.
+
+======Inputs======
+
+The set of values that will be used to determine the result, in the order of the function prototype. Inputs can specify any source evaluation and any agent state or agent parent context state. The selection determines which agent's will be used to determine the value, and different inputs can specify different selections.
+
+=====Move=====
+
+The Move Action causes an agent to change its location in some space or network. The agent will leave whatever location it was in before within the selection space, and move to its new destination.
+
+======Selection======
+
+As with any
+
+=====Set=====
+
+The Set Action assigns some value to another value.
+
+===Example===
+
+In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:
+
+ "Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
+
+Here, we create a sequence of actions like so:
+
+#Select every agent for every period of the model. ("Find Partner" Rule)
+#For every member of that selection, search for other agents of the same age within vision distance. ("Partner" selection.)
+#From "Partners" find a random member and search for a neighboring locations. ("Partner Neighbor" selection.)
+#Finally, move the agent in "Find Partner" to the "Partner Neighbor" location.
+
+Now, notice that although it's convenient to speak as if there is only one "Find Partner" and one "Partner Neighbor" in step 4 above, in fact selections are flowing through for each of the results of each of the previous action sequences, and we can refer to each of the directly. We could represent these behaviors in many different ways. For example, we might want to specify the model in a (hand-drawn) graphical language or in a (made-up) textual language:
+
+[[Image:images/ActionsExample.png|800px]]
+
+This is how it looks in an actual model:
+
+[[Image:images/ActionsExampleNew.png|800px]]
+
+And here is how this works in detail:
+
+#Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (Space isn't relevant in this case.
+#Create a child Select Action that will find our partner. Two important things to note here:
+##The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.
+##We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.
+#Create two child Query Actions:
+##We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by the rule agent's partner for the first input and by the rule agent for the second. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.
+##We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner.
+#Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.
+#Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.
+#As above, define some queries. This time we want only those agents that are:
+##available, and
+##neighbors of our partner.
+#And another intersection..
+#Finally, we move to the location we've found. All that's required at this point is to specify:
+##The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and
+##The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.
+
+===Reference===
+
+====Diagrams====
+
+The following diagram may be helpful to readers familiar with UML and Meta-modeling:
+
+=====Meta-Classes=====
+
+[[Image:images/ActionsDiagram.png|800px]]
+
+=====Details=====
+
+In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.
+#An Act is anything that might happen during the execution of an Agent-Based Model.
+#All Actions have as their root-most source action a Root. These are added first to any agent behavior and act as triggers for all target behavior. For example, a Watch will execute any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that Accessor includes a reference to some Attribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)#Actions are targets and sources of one another, but an Act can never have itself as a source. (That is, Actions are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)
+#All Actions (except for root Actions) reference a Select, referred to as the "selected" relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) "world" that is currently being selected.
+#Commands trigger some model state change (Set) or spatial transformation (Transform).
+#Controls determine whether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.
+#Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).
+#Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/130-ModelersGuide_Functions.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/130-ModelersGuide_Functions.mediawiki
new file mode 100644
index 0000000..5b570e2
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/130-ModelersGuide_Functions.mediawiki
@@ -0,0 +1,392 @@
+==Functions==
+
+===Overview===
+
+Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:
+
+#Operators are simple calculations sharing the same type.
+#Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s).
+
+And by usage:
+
+#Generics can return any value and are used in Evaluate actions.
+#Logicals return some boolean result and are used by Query actions to decide whether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.
+
+These overlap, so we have operators, logical operators, functions and logical functions. Functions are also divided into categories. We'll go through each of these in depth below.
+
+The most important thing to point out about functions is that - as we've seen with other Acore concepts -- they provide richer sets of functionality than traditional approaches. Many functions are designed to collaborate with one another as we'll see when looking at Spatial and Graphical functions. Functions can also trigger the creation of related model artifacts as we'll see with the Distribution functions.
+
+A technical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.
+
+===Details===
+
+====General Functions====
+
+Naturally, the Modeling tools provide general functions for performing calculations, comparisons and more complex mathematical expressions. The function library can be easily extended, and we'll be adding additional capabilities over time. As always, we welcome feedback and we'd like to hear what functions you need that aren't covered here.
+
+=====Logical Operators=====
+======Not======
+The result of the expression !X.
+======Equal======
+The result of the expression X==Y.
+======Identical======
+The result of the expression X==Y.
+======Greater======
+The result of the expression X>Y.
+======Lesser======
+The result of the expression X<Y.
+======Greater or Equal======
+The result of the expression X>=Y.
+======Lesser or Equal======
+The result of the expression X<=Y.
+======True======
+The result of the expression true.
+======False======
+The result of the expression false.
+======Identity======
+The result of the expression X.
+======Different======
+The result of the expression X!=Y.
+=====Numeric Operators=====
+======Negative Value======
+The result of the expression -X.
+======Add======
+The result of the expression X+Y.
+======Subtract======
+The result of the expression X-Y.
+======Multiply======
+The result of the expression X*Y.
+======Divide======
+The result of the expression X/Y.
+======Power======
+The result of the expression X^Y.
+======Modulo======
+The result of the expression X%Y.
+======Increment======
+The result of the expression ++X.
+======Decrement======
+The result of the expression --X.
+======Unit Value======
+The result of the expression 1.
+======Zero Value======
+The result of the expression 0.
+======Original Value======
+The result of the expression o.
+
+=====Math=====
+
+The math functions use the extremely well specified and tested routines form the Java Math library. (Because of copyright restrictions, we aren't able to include the exact definitions here. Click on the links to get more details on each function.)
+
+======Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)]
+======Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)]
+======Tangent======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)]
+======Arc Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)]
+======Arc Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)]
+======Arc Tangent======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)]
+======Convert Degree to Radians======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)]
+======Convert Radians to Degrees======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)]
+======Exp======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)]
+======Log======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)]
+======Log b10======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)]
+======Square Root======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)]
+======Cube Root======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)]
+======Remainder======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)]
+======Ceiling======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)]
+======Floor======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)]
+======Rount======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)]
+======Arc Tangent Rectangular======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)]
+======Power======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)]
+======Absolute Value======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)]
+======Maximum======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)]
+======Minimum======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)]
+======ULP======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)]
+======Sign======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)]
+======Hyperbolic Sine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)]
+======Hyperbolic Cosine======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)]
+======Hyperbolic Tan======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)]
+======Hypotuneuse======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)]
+======Expm1======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)]
+======Log1p======
+See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)]
+
+====Random====
+
+=====Design=====
+
+Random functions are especially significant for agent models. Of particular interest are the weighted membership and random state and boolean value functions. You should be familiar with these functions so that you don't have to create more complex Action flows to accomplish the same thing.
+
+Note that we only have support for uniform distributions as of this release. We're working on a collaborative design for evaluations that allow easy mixing and matching of random functions and distributions.
+
+=====Details=====
+
+======Random In Range======
+A pseudo-random value within that numeric range specified as drawn from a uniform distribution. The minimum values are inclusive. The maximum values are inclusive for integer inputs and exclusive for Real inputs.
+ Inputs:
+ [Numeral] The minimum value (inclusive).
+ [Numeral] The maximum value (inclusive).
+ Outputs:
+ [Numeral] The random number.
+======Random To Limit======
+A pseudo-random value between zero and the value specified by the (non-zero) input and drawn from a uniform range. That value is inclusive for Integers and exclusive for Reals. (Note that as with the random in range function in the context of real numbers the distinction between an exclusive and inclusive limit is essentially meaningless.)
+ Inputs:
+ [Numeral] The maximum value (inclusive).
+ Outputs:
+ [Numeral] The result.
+======Random Unit======
+A pseudo-random Real value between 0 and 1 drawn from a uniform distribution. (The distinction between inclusive and exclusive range is essentially meaningless in this context and we can assume that the result will never be greater or equal to 1.)
+ Outputs:
+ [Real]
+======Random Boolean======
+A value that is randomly true or false, i.e. a fair coin toss.
+======Random Weighted======
+An indexed value weighted against a probability distribution. The total probability must sum to 1.0. For example, an input of {.1,.2,.7} under a uniform distribution would would have 10% probability of producing "0" , 20% for "1" and 70% for "2". This function can then be used with Item to return a biased result from another list.
+ Inputs:
+ [Real] A list of values that will determine the resulting weighted index.
+ Outputs:
+ [Integer] A resulting indexed value bounded by 0 and the length of the input list - 1.
+======Random Member======
+Represents a random value drawn from the set of Real values specified.
+ Inputs:
+ [Real] Returns a random member of the supplied list of numbers.
+ Outputs:
+ [Generic] The value of the item at a random index.
+======Random State======
+A random specified value (option) from the specified state.
+ Inputs:
+ [Generic] The state to select items from. All items are included.
+ Outputs:
+ [Boolean] The resulting option.
+
+====Space====
+
+=====Design=====
+
+Spatial functions provide the core functionality for Agent Models. Spatial functions are polymorphic, which basically means that they don't care what space they are operating on as long as that space is suitable for them. Spatial functions are designed to collaborate with one another. For example, by intersecting the "Neighbor", "Available" and "Toward" functions, we can design a rule that causes the agent to move to the next neighboring cell that get's it closer to some target agent. See the function details for more information.
+
+=====Details=====
+
+======Nearest ======
+Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.
+======Toward======
+Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.
+======Within======
+Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.
+ Inputs:
+ [Numeral]
+======Neighbor======
+Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.
+======Include Self======
+Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.
+======Within 2D Boundary======
+Represents agents or locations that exist within the boundary specified by the inputs.
+ Inputs:
+ [Numeral]
+======Here======
+Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used.
+======Available======
+Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.
+======Distance======
+The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.
+ Outputs:
+ [Real]
+======Away======
+Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.
+======Minimize======
+This function is not currently supported.
+======Maximize======
+This function is not currently supported.
+======Location 2D======
+Represents the location of the current agent for use in subsequent selections.
+ Inputs:
+ [Real]
+ [Real]
+======Boundary 2D======
+Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)
+ Outputs:
+ [Real]
+ [Real]
+
+=====Example=====
+
+For examples of how spatial functions can be used within action flows to provide agents with complex movement behaviors, see the Modelers Guide actions examples. In the following example from that section, we define an action that causes a partner agent to move to an available neighboring space.
+
+[[Image:images/ActionsExampleNew.png|800px]]
+
+====Time====
+=====Details=====
+
+======Now======
+The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.
+ Outputs:
+ [Integer] The current period.
+
+====Graphics====
+
+=====Design=====
+
+Graphic functions are combined within Style Evaluate Actions to determine how to draw an agent within a visualization. One nice aspect of this approach is that the same style definition can be used in multiple places without changing any code. For example, the same style could be used to draw an agent on a two-dimensional grid within Escape, a three-dimensional shape within Escape, a Java Swing based visualization in Ascape, and an XML configured visualizaiton in Repast Simphony.
+
+To define a graphic style for an agent, design a flow in which you create Evaluate Actions for color and shape, and then create an Evaluate Action with the graphic fill or outline function as a target of these.
+
+=====Details=====
+
+======Shape Oval======
+Draw a generic oval.
+======Shape Rectangle======
+Draws a rectangular shape.
+======Shape Inset======
+Shrinks the current shape by the input amount. (The overall scale is currently unspecified, but in most implementations should be 20.)
+ Inputs:
+ [Integer] Number of nominal pixels to inset.
+======Shape Marker======
+Draw a marker, that is a graphical indicator that can be used to add an additional cue about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape.
+======Shape Marker 2======
+Represents a marker placed in a different location from the other shape markers.
+======Shape Marker 3======
+Represents a marker placed in a different location from the other shape markers.
+======Color RGB======
+A color specified by the three inputs for Red, Green and Blue color components. Those inputs are expected to be in the range 0..1.
+ Inputs:
+ [Real] A value from 0.0 to 1.0.
+ [Real] A value from 0.0 to 1.0.
+ [Real] A value from 0.0 to 1.0.
+======Color Red======
+The color red.
+======Color Yellow======
+The color yellow.
+======Color Blue======
+The color blue.
+======Color Orange======
+The color orange.
+======Color Green======
+The color green.
+======Color Purple======
+The color purple.
+======Color Black======
+The color black.
+======Color White======
+The color white.
+======Color Gray======
+The color gray.
+======Graphic Outline======
+Draws an outline of the last evaluated shape, using the last specified color or the default color (usually black) if none has been specified.
+======Graphic Fill======
+Fills the last evaluated shape with the last specified color or the default color (usually black) if none has been specified.
+
+=====Example=====
+
+In the following action flow for the epidemic style, we've create Query Actions to determine each agent's current state, picked a color based on that, and then used a shared target to select a shape for the agent style and fill it:
+
+[[Image:images/GraphicsFunctionExampleDesign.png]]
+
+After saving the model we can execute the two and three dimensional visualizations. Note something really nice -- even the charts have used the colors we've defined!
+
+[[Image:images/GraphicsFunctionExampleRun.png]]
+
+====Lists====
+
+=====Details=====
+
+======Item======
+Returns the item at the specified index from the list of items provided. Those items will typically be input primitives such as Integer or Real values.
+ Inputs:
+ [Generic]
+ [Integer]
+ Outputs:
+ [Generic]
+======Length======
+The number of items in the provided list of items.
+ Inputs:
+ [Generic]
+ Outputs:
+ [Integer]
+
+====Attribute Distributions====
+
+One of the most common tasks in the Agent Modeling process is the creation of agents with particular states drawn from a distribution. For example, you might want to create a number of agents with wealth randomly distributed between some minimum and maximum values. The distribution functions greatly ease the process of setting up those initializations and their associated parameters.
+
+=====Distribution=====
+======Uniform Cross Distribution======
+A random number taken from a distribution of values as defined by a cross of all values. (See Cross Distribution.) This funciton then returns a value drawn from the minimum and maximum values as determined by the current agent state. In the cross distribution, each of the values is treated independently so that an input attribute is created for every potential combination of states.
+ Inputs:
+ [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
+ [Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ [Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ Outputs:
+ [Real] The resulting random number based on the current agent state and the input parameters.
+======Uniform Additive Distribution======
+A random number taken from a distribution of values in which each of the minimum and maximum values are added to determine a total minimum and maximum value. (See Additive Distribution.) In the additive distribution, each of the values is treated as dependent on the others so that an input attribute is only created for each seperate state.
+ Inputs:
+ [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
+ [Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ [Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ Outputs:
+ [Real] The resulting random number based on the current agent state and the input parameters.
+======Cross Distribution======
+A value taken from a set of (auto-generated) attributes based on the value of each state included. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create separate input attributes for AI, AII, BI and BII. Then for an agent with States A and II this function would return the value specified by the AII input attribute.
+ Inputs:
+ [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
+ [Real] The set of attributes that when multiplied against each other will determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ Outputs:
+ [Real] The resulting value based on the current agent state and the input parameters.
+======Additive Distribution======
+A value taken from a set of (auto-generated) attributes based on the combined values of the states provided. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create input attributes for A, B, I and II. Those values would then be added together, so that for an Agent with state A and II this function would return A + II.
+ Inputs:
+ [Generic] The states to include in the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
+ [Real] The set of attributes that when combined with each other determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
+ Outputs:
+ [Real] The resulting value based on the current agent state and the input parameters.
+
+=====Example=====
+
+In the following example, we walk through the process of using a distribution functions, demonstrating how we can easily modify the Epidemic model so that instead of simply setting an initial exposed population, we can define factors that take together will determine an individuals initial exposure state. We simply:
+
+# Create an Evaluate Action called "Initial Status".
+# Set the function to "Cross Distribution"
+# Opened the "Multiple Value" node in the editor, and clicked the "Multiple Values" item within it.
+# Selected the "Status" attribute.
+
+[[Image:images/DistributionDesignChoice.png]]
+
+The appropriate attributes are automatically added to the model, as you can see below.
+
+[[Image:images/DistributionDesign.png]]
+
+In order to assign these values to the agent, we'd simply need to assign the results of this Evaluate Action to the agent.
+
+====Diagrams====
+
+The following diagram may be helpful to readers familiar with UML and Meta-modeling:
+
+=====Meta-Classes=====
+
+[[Image:images/FunctionsDiagram.png]]
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/200-ModelersGuide_Creating.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/200-ModelersGuide_Creating.mediawiki
new file mode 100644
index 0000000..31dfaa4
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/200-ModelersGuide_Creating.mediawiki
@@ -0,0 +1,4 @@
+=Creating Agent Models=
+
+==Getting Started==
+
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/300-ModelersGuide_Exploring.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/300-ModelersGuide_Exploring.mediawiki
new file mode 100644
index 0000000..6db32a7
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/300-ModelersGuide_Exploring.mediawiki
@@ -0,0 +1 @@
+=Exploring Agent Models=
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/400-ProgrammersGuide_Escape.mediawiki
similarity index 94%
rename from org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.mediawiki
rename to org.eclipse.amp/doc/org.eclipse.amp.doc/doc/400-ProgrammersGuide_Escape.mediawiki
index d43ada3..567f399 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.mediawiki
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/400-ProgrammersGuide_Escape.mediawiki
@@ -1,14 +1,16 @@
-=Overview=
+=Programer's Guide=
+
+==Overview==
Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based API and end user modeling tools. It's based on Ascape, which has been in use for more than 10 years. The core API is very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then execute those models within the same development environment.
-[[image:AMPScreenshot.png]]
+[[image:EscapeExecutionScreenshot.png]]
A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM toolkit -- is to provide an exemplar to demonstrate how any arbitrary agent modeling framework can be integrated within the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than ten years ago and that has not been modified at all in order for it to work within the AMP environment.
(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and AGF components.)
-=Getting Started=
+==Getting Started==
===Documentation and other Resources===
@@ -146,10 +148,3 @@
====Configuration====
Instead of using Ant, Escape has really nice support for parameterizing and testing models. See [[Experimenting and Testing]] (todo). If you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape so it's not even clear it will work.
-
-==Current Limitations==
-
-#Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as stable for a while as Ascape which has been around for a long time.
-#Escape graphics performance is generally slower especially for charts. But on the other hand you can run multiple models at once and the headless models should perform just as well as console launched Ascape programs. In practice this shouldn't affect your normal model exploration work.
-#We don't have the speed slider working yet. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=291299]
-#Charts only support time series, not histograms and pie. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=282953]
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/900-Resources.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/900-Resources.mediawiki
new file mode 100644
index 0000000..07e0d7b
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/900-Resources.mediawiki
@@ -0,0 +1,13 @@
+=More Information=
+
+==Obtaining Example Models==
+
+There is a cheat-sheet available for obtaining the example models. If you would rather obtain them yourself, here is the CVS information:
+
+====Import from CVS====
+*Import the CVS projects from the AMP project repository. For help, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm this page]. For repository details, see [http://eclipse.org/amp/developers/repositoryDetails.php http://eclipse.org/amp/developers/repositoryDetails.php]. These are the example projects:
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
+ org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
+*Right-click on the models to execute them.
+*Play around with the model attribute settings and behavior (Acts).
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF-toc.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF-toc.xml
deleted file mode 100644
index b7e12d4..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF-toc.xml
+++ /dev/null
@@ -1,15 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<toc topic="wiki/AMF.html" label="AMF">
- <topic href="wiki/AMF.html" label="Overview"></topic>
- <topic href="wiki/AMF.html#Getting_Started" label="Getting Started">
- <topic href="wiki/AMF.html#Understanding_AMF" label="Understanding AMF"></topic>
- <topic href="wiki/AMF.html#Tutorials" label="Tutorials">
- <topic href="wiki/AMF.html#Run_an_Exiting_Model" label="Run an Exiting Model"></topic>
- <topic href="wiki/AMF.html#Older_Tutorial" label="Older Tutorial"></topic>
- </topic>
- <topic href="wiki/AMF.html#Explore_Other_Models" label="Explore Other Models">
- <topic href="wiki/AMF.html#Import_from_CVS" label="Import from CVS"></topic>
- <topic href="wiki/AMF.html#Design_a_Model" label="Design a Model"></topic>
- </topic>
- </topic>
-</toc>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.html
deleted file mode 100644
index e558aaf..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.html
+++ /dev/null
@@ -1,57 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <title>AMF</title>
- </head>
- <body>
- <h1 id="Overview">Overview</h1>
- <p>AMF provides an ABM meta-model representation, editor, generator and development environment. The AMF
- Acore meta-model is similar to EMF Ecore and defined in Ecore, but provides high-level support for complex agents.</p>
- <p>AMF generates complete executable models for Escape, Ascape and Repast Simphony, as well as Java Skeletons and Interfaces,
- JUnit test cases and documentation and is easily extensible to support additional targets.</p>
- <p>
- <img src="image/AMFScreenshot.png"/>
- </p>
- <h1 id="Getting_Started">Getting Started</h1>
- <h2 id="Understanding_AMF">Understanding AMF</h2>
- <p>You should have a sense for how the overall AMF approach works. Take a look through
- <a href="Acore.html" title="Acore">the Meta-Model</a>. Don't worry about too much about the details.
- </p>
- <h2 id="Tutorials">Tutorials</h2>
- <h4 id="Run_an_Exiting_Model">Run an Exiting Model</h4>
- <p>You can create an Escape project following
- <a href="Escape.html#Creating_a_New_Escape_Project" title="Creating_a_New_Escape_Project">these steps</a>.
- </p>
- <h4 id="Older_Tutorial">Model Design Screencast</h4>
- <p>
- This <a href="http://www.youtube.com/watch?v=lYp7Pq44CNM">screencast</a> goes through the design of an existing metaabm model.
- </p>
- <h4 id="Older_Tutorial">Older Tutorial</h4>
- <p>You can also look
- <a href="http://metaabm.org/docs/building_running.html">here</a> for a tutorial that set's up an Ascape and Simphony project. (Same caveats as below.)
- </p>
- <h2 id="Explore_Other_Models">Explore Other Models</h2>
- <p>There are three example projects that have already been setup for each of the current target platforms. If you try out the Ascape or Simphony projects, you'll need to install the relevant targets.</p>
- <h4 id="Import_from_CVS">Import from CVS</h4>
- <ul>
- <li>Import the CVS projects from the AMP project repository. For help, see
- <a href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm">this page</a>. For repository details, see
- <a href="http://eclipse.org/amp/developers/repositoryDetails.php">http://eclipse.org/amp/developers/repositoryDetails.php</a>. These are the example projects:
- </li>
- </ul>
- <pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
-org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
-org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
-</pre>
- <ul>
- <li>Right-click on the models to execute them.</li>
- <li>Play around with the model attribute settings and behavior (Acts).</li>
- </ul>
- <h3 id="Design_a_Model">Design a Model</h3>
- <p>We don't have a tutorial for AMF yet, sorry. (You could write one though!) But for now, the following tutorial is pretty close to current AMF functionality. (The icons and minor features have changed.)</p>
- <p>
- <a href="http://metaabm.org/docs/designing_model.html">MetaABM Tutorial</a> (Not-Eclipse hosted.)
- </p>
- </body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.mediawiki
deleted file mode 100644
index 4252360..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMF.mediawiki
+++ /dev/null
@@ -1,43 +0,0 @@
-=Overview=
-
-AMF provides an ABM meta-model representation, editor, generator and development environment. The AMF
-Acore meta-model is similar to EMF Ecore and defined in Ecore, but provides high-level support for complex agents.
-
-AMF generates complete executable models for Escape, Ascape and Repast Simphony, as well as Java Skeletons and Interfaces,
-JUnit test cases and documentation and is easily extensible to support additional targets.
-
-[[image:AMFScreenshot.png]]
-
-=Getting Started=
-
-==Understanding AMF==
-
-You should have a sense for how the overall AMF approach works. Take a look through [[AMP/UserGuide/AMF/MetaModel|the Meta-Model]]. Don't worry about too much about the details.
-
-==Tutorials==
-
-====Run an Exiting Model====
-
-You can create an Escape project following [[AMP/Running_Examples#Creating%20a%20New%20Escape%20Project|these steps]].
-
-====Older Tutorial====
-
-You can also look [http://metaabm.org/docs/building_running.html here] for a tutorial that set's up an Ascape and Simphony project. (Same caveats as below.)
-
-==Explore Other Models==
-
-There are three example projects that have already been setup for each of the current target platforms. If you try out the Ascape or Simphony projects, you'll need to install the relevant targets.
-
-====Import from CVS====
-*Import the CVS projects from the AMP project repository. For help, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm this page]. For repository details, see [http://eclipse.org/amp/developers/repositoryDetails.php http://eclipse.org/amp/developers/repositoryDetails.php]. These are the example projects:
- org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
- org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
- org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
-*Right-click on the models to execute them.
-*Play around with the model attribute settings and behavior (Acts).
-
-===Design a Model===
-
-We don't have a tutorial for AMF yet, sorry. (You could write one though!) But for now, the following tutorial is pretty close to current AMF functionality. (The icons and minor features have changed.)
-
-[http://metaabm.org/docs/designing_model.html MetaABM Tutorial] (Not-Eclipse hosted.)
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP-toc.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP-toc.xml
deleted file mode 100644
index 3462a59..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP-toc.xml
+++ /dev/null
@@ -1,96 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<toc topic="wiki/AMP.html" label="Agent Modeling Guide">
- <topic href="wiki/AMP.html" label="Overview"></topic>
-<topic href="help/Introduction" label="Modeler's Guide">
- <link toc="toc.xml"/>
-</topic>
- <topic href="wiki/AMP.html#Getting_Started" label="Getting Started">
- <topic href="wiki/AMP.html#ABM_Explorers" label="ABM Explorers"></topic>
- <topic href="wiki/AMP.html#ABM_Researchers" label="ABM Researchers"></topic>
- <topic href="wiki/AMP.html#ABM_Java_Developers" label="ABM Java Developers"></topic>
- <topic href="wiki/AMP.html#Eclipse_Plugin_Developers" label="Eclipse Plugin Developers"></topic>
- </topic>
- <topic href="wiki/AMF.html" label="Agent Modeling Framework (AMF)">
- <topic href="wiki/AMF.html#Understanding_AMF" label="Understanding AMF"></topic>
- <topic href="wiki/AMF.html#Tutorials" label="Tutorials">
- <topic href="wiki/AMF.html#Run_an_Exiting_Model" label="Run an Exiting Model"></topic>
- <topic href="wiki/AMF.html#Older_Tutorial" label="Older Tutorial"></topic>
- </topic>
- <topic href="wiki/AMF.html#Explore_Other_Models" label="Explore Other Models">
- <topic href="wiki/AMF.html#Import_from_CVS" label="Import from CVS"></topic>
- <topic href="wiki/AMF.html#Design_a_Model" label="Design a Model"></topic>
- </topic>
-<topic href="wiki/Acore.html" label="Acore">
- <topic href="wiki/Acore.html" label="Background"></topic>
- <topic href="wiki/Acore.html#Structure" label="Structure">
- <topic href="wiki/Acore.html#Diagrams" label="Diagrams">
- <topic href="wiki/Acore.html#Meta-Classes" label="Meta-Classes"></topic>
- <topic href="wiki/Acore.html#Key_Collaborations" label="Key Collaborations"></topic>
- <topic href="wiki/Acore.html#What_it_Means" label="What it Means"></topic>
- </topic>
- <topic href="wiki/Acore.html#AMF_Hierarchical_Editor_Example" label="AMF Hierarchical Editor Example"></topic>
- </topic>
- <topic href="wiki/Acore.html#Actions_.28Behavior.29" label="Actions (Behavior)">
- <topic href="wiki/Acore.html#Basic_Design" label="Basic Design"></topic>
- <topic href="wiki/Acore.html#Examples" label="Examples">
- <topic href="wiki/Acore.html#Simple_Example" label="Simple Example"></topic>
- <topic href="wiki/Acore.html#AMF_Hierarchical_Editor" label="AMF Hierarchical Editor"></topic>
- <topic href="wiki/Acore.html#Code" label="Code"></topic>
- </topic>
- <topic href="wiki/Acore.html#Design_in_Depth" label="Design in Depth">
- <topic href="wiki/Acore.html#.3Cfont_color.3Dred.3EAbstract_Actions.3C.2Ffont.3E" label="<font color=red>Abstract Actions</font>"></topic>
- <topic href="wiki/Acore.html#.3Cfont_color.3Dblue.3EConcrete_Actions.3C.2Ffont.3E" label="<font color=blue>Concrete Actions</font>"></topic>
- <topic href="wiki/Acore.html#Details" label="Details"></topic>
- </topic>
- </topic>
- <topic href="wiki/Acore.html#Functions" label="Functions">
- <topic href="wiki/Acore.html#Design" label="Design"></topic>
- <topic href="wiki/Acore.html#Built-in_Functions" label="Built-in Functions"></topic>
- </topic>
- <topic href="wiki/Acore.html#Acknowledgements" label="Acknowledgements"></topic>
- <topic href="wiki/Acore.html#References" label="References"></topic>
-</topic> </topic>
-
-<topic href="wiki/Escape.html" label="Escape">
- <topic href="wiki/Escape.html" label="Overview"></topic>
- <topic href="wiki/Escape.html#Getting_Started" label="Getting Started">
- <topic href="wiki/Escape.html#Documentation_and_other_Resources" label="Documentation and other Resources"></topic>
- <topic href="wiki/Escape.html#Installation" label="Installation"></topic>
- <topic href="wiki/Escape.html#Exploring_Example_ABM_Models" label="Exploring Example ABM Models">
- <topic href="wiki/Escape.html#AMF_Models" label="AMF Models">
- <topic href="wiki/Escape.html#Setup_Escape_Projects" label="Setup Escape Projects">
- <topic href="wiki/Escape.html#Creating_a_New_Escape_Project" label="Creating a New Escape Project"></topic>
- <topic href="wiki/Escape.html#Using_an_Pre-Built_Example_Project" label="Using an Pre-Built Example Project"></topic>
- </topic>
- <topic href="wiki/Escape.html#Run_the_Model" label="Run the Model"></topic>
- <topic href="wiki/Escape.html#Next_Steps" label="Next Steps"></topic>
- </topic>
- <topic href="wiki/Escape.html#Classic_Java_ABM_Models" label="Classic Java ABM Models">
- <topic href="wiki/Escape.html#From_Project_Archive" label="From Project Archive"></topic>
- <topic href="wiki/Escape.html#From_SVN" label="From SVN"></topic>
- </topic>
- </topic>
- <topic href="wiki/Escape.html#Developing_Models" label="Developing Models"></topic>
- </topic>
- <topic href="wiki/Escape.html#Reference" label="Reference">
- <topic href="wiki/EscapeConverting.html" label="Converting Existing Ascape models">
- <topic href="wiki/EscapeConverting.html#Model" label="Model"></topic>
- <topic href="wiki/EscapeConverting.html#View" label="View">
- <topic href="wiki/EscapeConverting.html#Convert_the_low-level_imports_from_AWT_and_Swing_to_SWT" label="Convert the low-level imports from AWT and Swing to SWT"></topic>
- <topic href="wiki/EscapeConverting.html#Convert_color_features" label="Convert color features"></topic>
- <topic href="wiki/EscapeConverting.html#Change_agent_color_getters" label="Change agent color getters"></topic>
- <topic href="wiki/EscapeConverting.html#Get_rid_of_image_features" label="Get rid of image features"></topic>
- <topic href="wiki/EscapeConverting.html#Modify_usages_of_DrawFeatures" label="Modify usages of DrawFeatures"></topic>
- </topic>
- <topic href="wiki/EscapeConverting.html#Configuration" label="Configuration"></topic>
- </topic>
- <topic href="wiki/Escape.html#Current_Limitations" label="Current Limitations"></topic>
- </topic>
- <topic href="http://ascape.sourceforge.net/api/index.html" label="Escape API (external)">
- </topic>
-</topic>
-<topic label="Reference">
-<topic href="docs/javadoc/index.html" label="API">
-</topic>
-</topic>
-</toc>
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.html
deleted file mode 100644
index a516b44..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/AMP.html
+++ /dev/null
@@ -1,42 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <title>AMP</title>
- </head>
- <body>
- <h1 id="Overview">Overview</h1>
- <p>The AMP project provides extensible frameworks and exemplary tools for representing, editing, generating,
- executing and visualizing agent-based models (ABMs) and any other domain requiring spatial, behavioral and functional features.
- AMP has two main themes that complement but don't depend on one another: </p>
- <p>The overall AMP architecture and Eclipse project dependencies are summarized below:</p>
- <p>
- <img src="image/AMPArchitectureDiagram.jpg" title="image/AMPArchitectureDiagram.jpg"/>
- </p>
- <h1 id="Getting_Started">Getting Started</h1>
- <p>AMP has many potential facets and use cases. Here are a few ways to get started with it.</p>
- <p>First, you'll need to
- <a href="http://eclipse.org/amp/installing/">install it</a>. Then...
- </p>
- <h2 id="ABM_Explorers">ABM Explorers</h2>
- <p>Experiment with example Java and AMF based models without writing code.</p>
- <p>
- <a href="Escape.html#Exploring_Example_ABM_Models" title="AMP/Running_Examples">Run Example Models</a>
- </p>
- <h2 id="ABM_Researchers">ABM Researchers</h2>
- <p>Create Agent-Based models using simple visual tools and deploy them to a number of popular ABM platforms, including Escape.</p>
- <p>
- <a href="AMF.html#Getting_Started" title="AMP/UserGuide/AMF#Getting Started">Modeling with AMF</a>
- </p>
- <h2 id="ABM_Java_Developers">ABM Java Developers</h2>
- <p>Write POJO Java models within a full-featured agent-based modeling framework.</p>
- <p>
- <a href="Escape.html#Getting_Started" title="AMP/UserGuide/Escape#Getting_Started">Programming with Escape</a>
- </p>
- <h2 id="Eclipse_Plugin_Developers">Eclipse Plugin Developers</h2>
- <p>AXF and AGF provide a number of features based around Eclipse technologies such as GEF, GEF3D, BIRT Charts and Zest. For example, AGF supports dynamic visualization of objects in space, and AXF supports managed UI and headless execution for models of any kind.</p>
- <p>
- <a href="/AMP/AGF_AXF_API" title="AMP/AGF_AXF_API">Programming with AXF and AGF</a> (todo)
- </p>
- </body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acknowledgements.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acknowledgements.html
deleted file mode 100644
index 8d89458..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acknowledgements.html
+++ /dev/null
@@ -1 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><title>Acore - Acknowledgements</title><link type="text/css" rel="stylesheet" href="styles/help.css"/><link type="text/css" rel="stylesheet" href="styles/main.css"/></head><body><table class="navigation" style="width: 100%;" border="0" summary="navigation"><tr><th style="width: 100%" align="center" colspan="3">Acknowledgements</th></tr><tr><td style="width: 20%" align="left"><a href="Functions.html" title="Functions"><img alt="Previous" border="0" src="images/prev.gif"/></a></td><td style="width: 60%" align="center"></td><td style="width: 20%" align="right"><a href="References.html" title="References"><img alt="Next" border="0" src="images/next.gif"/></a></td></tr><tr><td style="width: 20%" align="left" valign="top">Functions</td><td style="width: 60%" align="center"></td><td style="width: 20%" align="right" valign="top">References</td></tr></table><hr/><h1 id="Acknowledgements">Acknowledgements</h1><p>The AMF meta-model started life as "score" <a href="http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References">1</a>, a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continued development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009. The previous meta-models serveed as a Òstraw-agentsÓ that have allowed the community to refine and explore key representational issues. Some of the following discussion is drawn from previous Metascape documentation and is released by the author (Miles Parker) under ECL.</p><hr/><table class="navigation" style="width: 100%;" border="0" summary="navigation"><tr><td style="width: 20%" align="left"><a href="Functions.html" title="Functions"><img alt="Previous" border="0" src="images/prev.gif"/></a></td><td style="width: 60%" align="center"><a href="Acore.html" title="Acore"><img alt="Acore" border="0" src="images/home.gif"/></a></td><td style="width: 20%" align="right"><a href="References.html" title="References"><img alt="Next" border="0" src="images/next.gif"/></a></td></tr><tr><td style="width: 20%" align="left" valign="top">Functions</td><td style="width: 60%" align="center"></td><td style="width: 20%" align="right" valign="top">References</td></tr></table></body></html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore-toc.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore-toc.xml
deleted file mode 100644
index 84745cd..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore-toc.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<toc topic="wiki/Acore.html" label="Acore">
- <topic href="wiki/Acore.html" label="Background"></topic>
- <topic href="wiki/Acore.html#Structure" label="Structure">
- <topic href="wiki/Acore.html#Diagrams" label="Diagrams">
- <topic href="wiki/Acore.html#Meta-Classes" label="Meta-Classes"></topic>
- <topic href="wiki/Acore.html#Key_Collaborations" label="Key Collaborations"></topic>
- <topic href="wiki/Acore.html#What_it_Means" label="What it Means"></topic>
- </topic>
- <topic href="wiki/Acore.html#AMF_Hierarchical_Editor_Example" label="AMF Hierarchical Editor Example"></topic>
- </topic>
- <topic href="wiki/Acore.html#Actions_.28Behavior.29" label="Actions (Behavior)">
- <topic href="wiki/Acore.html#Basic_Design" label="Basic Design"></topic>
- <topic href="wiki/Acore.html#Examples" label="Examples">
- <topic href="wiki/Acore.html#Simple_Example" label="Simple Example"></topic>
- <topic href="wiki/Acore.html#AMF_Hierarchical_Editor" label="AMF Hierarchical Editor"></topic>
- <topic href="wiki/Acore.html#Code" label="Code"></topic>
- </topic>
- <topic href="wiki/Acore.html#Design_in_Depth" label="Design in Depth">
- <topic href="wiki/Acore.html#.3Cfont_color.3Dred.3EAbstract_Actions.3C.2Ffont.3E" label="<font color=red>Abstract Actions</font>"></topic>
- <topic href="wiki/Acore.html#.3Cfont_color.3Dblue.3EConcrete_Actions.3C.2Ffont.3E" label="<font color=blue>Concrete Actions</font>"></topic>
- <topic href="wiki/Acore.html#Details" label="Details"></topic>
- </topic>
- </topic>
- <topic href="wiki/Acore.html#Functions" label="Functions">
- <topic href="wiki/Acore.html#Design" label="Design"></topic>
- <topic href="wiki/Acore.html#Built-in_Functions" label="Built-in Functions"></topic>
- </topic>
- <topic href="wiki/Acore.html#Acknowledgements" label="Acknowledgements"></topic>
- <topic href="wiki/Acore.html#References" label="References"></topic>
-</toc>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.html
deleted file mode 100644
index d1b6af0..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.html
+++ /dev/null
@@ -1,147 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <title>Acore</title>
- </head>
- <body>
- <p>
- <i>'The Agent Modeling Framework MetaABM / Acore Meta-Model</i>
- </p>
- <p>
- <i>Important Note</i>
- The MetaABM "MetaABM" meta-model will be transitioning to a significantly changed "Acore" meta-model as part of the overall AMP project plan. At the moment, MetaABM is serving as the AMF meta-model. We'll be providing automated migration tools, so developers can use it without worry about future compatibility. To avoid having to re-edit all of this documentation, we'll be referring to "Acore" below, unless we anticipate a change in which case we'll tag that with (metaabm).
- </p>
- <h1 id="Background">Background</h1>
- <p>The foundation of the Agent Modeling Framework is "Acore" (metaabm). It's is designed to be a general representation or Òmeta-modelÓ for Agent-Based Models. As the name implies, the "Acore" model (will be) analogous to the EMF "ecore" meta-model but provides representations that are suited to agent-based and other modeling (in the "modeling and simulation" sense of the word) oriented domains. Models can be fully defined within the Acore lingua franca and model implementations can then be generated from those models with no further coding or configuration. The system as whole currently provides a hierarchical visual editor and reference implementations targeting the Escape, Ascape and Repast Simphony platforms. MetaABM is built upon the Eclipse Modeling Framework and a number of other Modeling project technologies, including Xpand. AMF is fully integrated with the Eclipse IDE platform, but Acore models themselves need have no dependencies on any particular technology beyond XML/XSD. We do not imagine that the meta-model covers every possible model instance, or that we have not overlooked important issues.</p>
- <p>The Acore / MetaABM meta-model is made up of three main packages. This is all based on MetaABM, and while names and important details will change for Acore, the core design should be quite similar.</p>
- <h1 id="Structure">Structure</h1>
- <h2 id="Diagrams">Diagrams</h2>
- <h3 id="Meta-Classes">Meta-Classes</h3>
- <p>Our first diagram depicts the core structural design of the MetaABM system -- again, much of this will carry through to Acore. </p>
- <p>
- <img src="image/MetaABM.png" title="image/MetaABM.png"/>
- </p>
- <p>There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.</p>
- <h3 id="Key_Collaborations">Key Collaborations</h3>
- <p>
- <img src="image/MetaABMStructure.png" title="image/MetaABMStructure.png"/>
- </p>
- <pre>Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-</pre>
- <h3 id="What_it_Means">What it Means</h3>
- <ol>
- <li>Every model has at its root a Context (Scape).
- <a href="http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References">2</a> Contexts are Agents that are capable of containing other Agents (including other contexts, naturally).
- </li>
- <li>(Meta-level) Contexts (Scapes) contain (meta-level) Agents at the model (Design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of ÒWiki ExampleÓ. Within that Context, we create an Agent and give it a label of "IndividualÓ and another Agent with the label ÒBlockÓ. At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.</li>
- <li>Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.</li>
- <li>Contexts (Scapes) can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidian) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.</li>
- <li>Agents are Actables and thus can contain any number of behaviors called ÒActionsÓ, described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.</li>
- <li>Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actables. For example, an Agent might have an Action that says effectively Òdraw a red circle shaded red for the wealth of the agentÓ.</li>
- </ol>
- <h2 id="AMF_Hierarchical_Editor_Example">AMF Hierarchical Editor Example</h2>
- <h1 id="Actions_.28Behavior.29">Actions (Behavior)</h1>
- <p>Actions are a fundamental aspect of the metaABM representational scheme, as they allow the definition of arbitrary but high level behavior for agents. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representation -- or as far as we have been able to tell, Model-Driven Software Development --approaches. While the Acore Actions meta-model doesn't look like a programming language, it is useful to see it as a programming language without a concrete syntax. Because it doesn't define an actual concrete language implementation, it can be suitable for any number of potential text and visual languages. The default editor provided with AMF is hierarchical which isn't ideal for representing Acore Actions, but other text and visual editors are being developed and refined. Conceptually, Acore Actions is a kind of
- <a href="http://en.wikipedia.org/wiki/Dataflow_programming">data-flow language</a>, though the Actions design also carries aspects of
- <a href="http://en.wikipedia.org/wiki/Functional_programming">functional</a> and
- <a href="http://en.wikipedia.org/wiki/Logical_programming">logical languages</a>.
- </p>
- <h2 id="Basic_Design">Basic Design</h2>
- <p>
- <img src="image/ActionsSimple.png" title="image/ActionsSimple.png"/>
- </p>
- <p>Actions represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other Actions are connected in a series of sources and targets, in which each child target carries the execution and data context for it's particular path.</p>
- <ol>
- <li>We define a Select Action, which determines what agent we are looking for, what space we are looking for that agent within, and what time (speaking very broadly, e.g. at startup, every period, at a scheduled time, on change in a specific state) we would like the behavior to occur. All Actions begin with a Root Action such as a Rule; these Actions trigger all resultant behavior.</li>
- <li>Then query terms and set operations are applied to that selection.</li>
- <li>Finally, commands are executed against the results of those queries.</li>
- </ol>
- <h2 id="Examples">Examples</h2>
- <h3 id="Simple_Example">Simple Example</h3>
- <p>In the following example, we want to create a set of actions that accomplish this task for the agent. It's always easier to express these things in natural languages! Our aim is to get as close as we can to that ease of expression without losing necessary detail and context.</p>
- <pre>"Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-</pre>
- <p>
- <img src="image/ActionsExample.png" title="image/ActionsExample.png"/>
- </p>
- <p>We define this model above in (conceptual) graphical and textual languages. No matter what tool we use to define the model in, the basic logic is the same..</p>
- <ol>
- <li>Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (We can define the space as well, but that's not relevant yet.</li>
- <li>Create a child Select Action that will find our partner. Two important things to note here:
- <ol>
- <li>The selection occurs "upon" the "find partner" select. On other words, for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.</li>
- <li>We also need to define what type of agent we want and in this case the space does matter. We want to be sure that the agent is nearby in the City space not any other space we might have defined.</li>
- </ol>
- </li>
- <li>Create two child Query Actions:
- <ol>
- <li>We want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner. (Design discussion note: re-examine this issue WRT possibility of allowing users to search in multiple spaces within the same query.)</li>
- <li>We also want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The seleciton carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional Imperative language such as Java.</li>
- </ol>
- </li>
- <li>Intersect (All in metaabm) these two queries. This delineates the end of the selection definition for any target Actions.</li>
- <li>Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.</li>
- <li>As above, define some queries. This time we want only those agents that are available and neighbors of our partner.</li>
- <li>And another intersection..</li>
- <li>Finally, we move to the location we've found. All that's required at this point is to specify:
- <ol>
- <li>The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and</li>
- <li>The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.</li>
- </ol>
- </li>
- </ol>
- <h3 id="AMF_Hierarchical_Editor">AMF Hierarchical Editor</h3>
- <p>Here's how the model looks in the default Acore editor. Note that we've collapsed the somewhat awkward multiple paths.</p>
- <p>
- <img src="image/WikiExample.png"/>
- </p>
- <h3 id="Code">Code</h3>
- <p>Why would we want to define our behaviors at such a high-level? There are a lot of reasons, including ease-of-use, transparency, parallelization and optimization, and all of the other MDSD goodies. You might want to take a look at what the code generated by AMF from this specification looks like in two POJO ABM APIs.</p>
- <p>
- <a href="/AMP/UserGuide/AMF/ExampleAscapeCode" title="AMP/UserGuide/AMF/ExampleAscapeCode">Ascape</a>
- </p>
- <p>
- <a href="/AMP/UserGuide/AMF/ExampleRepastCode" title="AMP/UserGuide/AMF/ExampleRepastCode">Repast Simphony</a>
- </p>
- <h2 id="Design_in_Depth">Design in Depth</h2>
- <p>
- <img src="image/MetaABMActions.png" title="image/MetaABMActions.png"/>
- </p>
- <h4 id="Details">Details</h4>
- <p>In the diagram above, all meta-objects are ActionsAInput, ALiteral, and the enumerators (lists of options) are Acts. Blue Acts are concrete (you can create and use them directly). Red indicates a key meta-object collaboration.</p>
- <ol>
- <li>An Act is anything that might happen during the execution of an Agent-Based Model.</li>
- <li>Acts are targets and sources of one another, but an Act can never have itself as a source. (That is, Acts are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)</li>
- <li>Acts reference a ASelect, referred to as the ÒselectedÓ relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) ÒworldÓ that is currently being selected.</li>
- <li>ATransforms also specify a ÒdestinationÓ ASelect. This represents aspects that the selected agent(s) will transform to. For example, an AMove may use an ARule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).</li>
- <li>All Acts have as their root-most source Act an ARoot. These are added first to any agent behavior and act as triggers for all target behavior. For example, an AWatch will ÒfireÓ any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that AAccessor includes a reference to some SAttribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)</li>
- <li>ASinks are Acts which use some FFunction (see next section) to interpret state in the form of AInputs. Inputs can come from selected agent attributes, other Acts, or literal values.</li>
- <li>AControls determine wether target acts are executed and against what agents. They are in some sense query terms.</li>
- <li>ACommands trigger some model state change (ASet) or spatial transformation (ATransform).</li>
- </ol>
- <h1 id="Functions">Functions</h1>
- <h2 id="Design">Design</h2>
- <p>
- <img src="image/MetaABMFunctions.png" title="image/MetaABMFunctions.png"/>
- </p>
- <p>The Function representation is relatively simple. As indicated above, Functions are used by Sinks to interpret some model state. Functions are broken into two broad types; Operators, which are simple calculations sharing the same type, and Generic Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s). Conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java. Logicals return some binary result and that is used by Queries to decide wether target Actions apply to a particular selection. Input types should be defined as generally as possible.</p>
- <h2 id="Built-in_Functions">Built-in Functions</h2>
- <p>Acore comes with a built-in library of core functions. See the
- <a href="/AMP/UserGuide/AMF/Core_Library" title="AMP/UserGuide/AMF/Core_Library">table of core functions</a>.
- </p>
- <h1 id="Acknowledgements">Acknowledgements</h1>
- <p>The AMF meta-model started life as "score"
- <a href="http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References">1</a>, a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continued development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009. The previous meta-models serveed as a Òstraw-agentsÓ that have allowed the community to refine and explore key representational issues. Some of the following discussion is drawn from previous Metascape documentation and is released by the author (Miles Parker) under ECL.
- </p>
- <h1 id="References">References</h1>
- <ol>
- <li>AGENT-BASED META-MODELS, Parker, et.al.
- <a href="http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf">http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf</a>
- </li>
- <li>Howe, et. al. CONTAINING AGENTS: CONTEXTS, PROJECTIONS, AND AGENTS
- <a href="http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf">http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf</a>
- </li>
- </ol>
- </body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.mediawiki
deleted file mode 100644
index 3bcaeee..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Acore.mediawiki
+++ /dev/null
@@ -1,131 +0,0 @@
-'''The Agent Modeling Framework MetaABM / Acore Meta-Model''
-
-''Important Note''
-The MetaABM "MetaABM" meta-model will be transitioning to a significantly changed "Acore" meta-model as part of the overall AMP project plan. At the moment, MetaABM is serving as the AMF meta-model. We'll be providing automated migration tools, so developers can use it without worry about future compatibility. To avoid having to re-edit all of this documentation, we'll be referring to "Acore" below, unless we anticipate a change in which case we'll tag that with (metaabm).
-
-=Background=
-
-The foundation of the Agent Modeling Framework is "Acore" (metaabm). It's is designed to be a general representation or Òmeta-modelÓ for Agent-Based Models. As the name implies, the "Acore" model (will be) analogous to the EMF "ecore" meta-model but provides representations that are suited to agent-based and other modeling (in the "modeling and simulation" sense of the word) oriented domains. Models can be fully defined within the Acore lingua franca and model implementations can then be generated from those models with no further coding or configuration. The system as whole currently provides a hierarchical visual editor and reference implementations targeting the Escape, Ascape and Repast Simphony platforms. MetaABM is built upon the Eclipse Modeling Framework and a number of other Modeling project technologies, including Xpand. AMF is fully integrated with the Eclipse IDE platform, but Acore models themselves need have no dependencies on any particular technology beyond XML/XSD. We do not imagine that the meta-model covers every possible model instance, or that we have not overlooked important issues.
-
-The Acore / MetaABM meta-model is made up of three main packages. This is all based on MetaABM, and while names and important details will change for Acore, the core design should be quite similar.
-
-=Structure=
-
-==Diagrams==
-
-===Meta-Classes===
-
-Our first diagram depicts the core structural design of the MetaABM system -- again, much of this will carry through to Acore.
-
-[[image:MetaABM.png|400px|Scary UML Diagram]]
-
-There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
-
-===Key Collaborations===
-
-[[image:MetaABMStructure.png|600px|Structure Diagram]]
-
- Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-
-===What it Means===
-
-#Every model has at its root a Context (Scape). [http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References 2] Contexts are Agents that are capable of containing other Agents (including other contexts, naturally).
-#(Meta-level) Contexts (Scapes) contain (meta-level) Agents at the model (Design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of ÒWiki ExampleÓ. Within that Context, we create an Agent and give it a label of "IndividualÓ and another Agent with the label ÒBlockÓ. At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.
-#Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.
-#Contexts (Scapes) can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidian) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.
-#Agents are Actables and thus can contain any number of behaviors called ÒActionsÓ, described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.
-#Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actables. For example, an Agent might have an Action that says effectively Òdraw a red circle shaded red for the wealth of the agentÓ.
-
-==AMF Hierarchical Editor Example==
-
-=Actions (Behavior)=
-
-Actions are a fundamental aspect of the metaABM representational scheme, as they allow the definition of arbitrary but high level behavior for agents. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representation -- or as far as we have been able to tell, Model-Driven Software Development --approaches. While the Acore Actions meta-model doesn't look like a programming language, it is useful to see it as a programming language without a concrete syntax. Because it doesn't define an actual concrete language implementation, it can be suitable for any number of potential text and visual languages. The default editor provided with AMF is hierarchical which isn't ideal for representing Acore Actions, but other text and visual editors are being developed and refined. Conceptually, Acore Actions is a kind of [http://en.wikipedia.org/wiki/Dataflow_programming data-flow language], though the Actions design also carries aspects of [http://en.wikipedia.org/wiki/Functional_programming functional] and [http://en.wikipedia.org/wiki/Logical_programming logical languages].
-
-==Basic Design==
-[[image:ActionsSimple.png|400px|Action Commands and Queries]]
-
-Actions represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other Actions are connected in a series of sources and targets, in which each child target carries the execution and data context for it's particular path.
-#We define a Select Action, which determines what agent we are looking for, what space we are looking for that agent within, and what time (speaking very broadly, e.g. at startup, every period, at a scheduled time, on change in a specific state) we would like the behavior to occur. All Actions begin with a Root Action such as a Rule; these Actions trigger all resultant behavior.
-#Then query terms and set operations are applied to that selection.
-#Finally, commands are executed against the results of those queries.
-
-==Examples==
-
-===Simple Example===
-
-In the following example, we want to create a set of actions that accomplish this task for the agent. It's always easier to express these things in natural languages! Our aim is to get as close as we can to that ease of expression without losing necessary detail and context.
-
- "Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-
-[[image:ActionsExample.png|800px|Actions Example]]
-
-We define this model above in (conceptual) graphical and textual languages. No matter what tool we use to define the model in, the basic logic is the same..
-#Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (We can define the space as well, but that's not relevant yet.
-#Create a child Select Action that will find our partner. Two important things to note here:
-##The selection occurs "upon" the "find partner" select. On other words, for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.
-##We also need to define what type of agent we want and in this case the space does matter. We want to be sure that the agent is nearby in the City space not any other space we might have defined.
-#Create two child Query Actions:
-##We want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner. (Design discussion note: re-examine this issue WRT possibility of allowing users to search in multiple spaces within the same query.)
-##We also want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The seleciton carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional Imperative language such as Java.
-#Intersect (All in metaabm) these two queries. This delineates the end of the selection definition for any target Actions.
-#Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.
-#As above, define some queries. This time we want only those agents that are available and neighbors of our partner.
-#And another intersection..
-#Finally, we move to the location we've found. All that's required at this point is to specify:
-##The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and
-##The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.
-
-===AMF Hierarchical Editor===
-
-Here's how the model looks in the default Acore editor. Note that we've collapsed the somewhat awkward multiple paths.
-
-[[image:WikiExample.png]]
-
-===Code===
-
-Why would we want to define our behaviors at such a high-level? There are a lot of reasons, including ease-of-use, transparency, parallelization and optimization, and all of the other MDSD goodies. You might want to take a look at what the code generated by AMF from this specification looks like in two POJO ABM APIs.
-
-[[AMP/UserGuide/AMF/ExampleAscapeCode|Ascape]]
-
-[[AMP/UserGuide/AMF/ExampleRepastCode|Repast Simphony]]
-
-==Design in Depth==
-
-[[image:MetaABMActions.png|Actions Diagram]]
-
-====<font color=red>Abstract Actions</font>====
-
-====<font color=blue>Concrete Actions</font>====
-
-====Details====
-In the diagram above, all meta-objects are ActionsAInput, ALiteral, and the enumerators (lists of options) are Acts. Blue Acts are concrete (you can create and use them directly). Red indicates a key meta-object collaboration.
-#An Act is anything that might happen during the execution of an Agent-Based Model.
-#Acts are targets and sources of one another, but an Act can never have itself as a source. (That is, Acts are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)
-#Acts reference a ASelect, referred to as the ÒselectedÓ relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) ÒworldÓ that is currently being selected.
-#ATransforms also specify a ÒdestinationÓ ASelect. This represents aspects that the selected agent(s) will transform to. For example, an AMove may use an ARule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).
-#All Acts have as their root-most source Act an ARoot. These are added first to any agent behavior and act as triggers for all target behavior. For example, an AWatch will ÒfireÓ any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that AAccessor includes a reference to some SAttribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)
-#ASinks are Acts which use some FFunction (see next section) to interpret state in the form of AInputs. Inputs can come from selected agent attributes, other Acts, or literal values.
-#AControls determine wether target acts are executed and against what agents. They are in some sense query terms.
-#ACommands trigger some model state change (ASet) or spatial transformation (ATransform).
-
-=Functions=
-
-==Design==
-
-[[image:MetaABMFunctions.png|600px|Structure Diagram]]
-
-The Function representation is relatively simple. As indicated above, Functions are used by Sinks to interpret some model state. Functions are broken into two broad types; Operators, which are simple calculations sharing the same type, and Generic Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s). Conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java. Logicals return some binary result and that is used by Queries to decide wether target Actions apply to a particular selection. Input types should be defined as generally as possible.
-
-==Built-in Functions==
-
-Acore comes with a built-in library of core functions. See the [[AMP/UserGuide/AMF/Core_Library|table of core functions]].
-
-=Acknowledgements=
-
-The AMF meta-model started life as "score" [http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References 1], a component of the Repast Simphony environment. It wasn't fully utilized within Simphony, and migrated from there to the MetaABM project. The MetaABM project defined a complete editor, code-generation and model execution suite that formed the initial AMP AMF contribution. Argonne National Labs supported the initial development of score and Metascape, LLC continued development of MetaABM and both agreed to contribute the relevant IP to the Eclipse project in 2009. The previous meta-models serveed as a Òstraw-agentsÓ that have allowed the community to refine and explore key representational issues. Some of the following discussion is drawn from previous Metascape documentation and is released by the author (Miles Parker) under ECL.
-
-=References=
-
-#AGENT-BASED META-MODELS, Parker, et.al. http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf
-#Howe, et. al. CONTAINING AGENTS: CONTEXTS, PROJECTIONS, AND AGENTS http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Actions-Behavior-.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Actions-Behavior-.html
deleted file mode 100644
index 493a857..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Actions-Behavior-.html
+++ /dev/null
@@ -1,161 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Acore - Actions (Behavior)</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">Actions (Behavior)</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Structure.html" title="Structure"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"><a href="Functions.html" title="Functions"><img alt="Next"
- border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Structure</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Functions</td>
- </tr>
-</table>
-<hr />
-<h1 id="Actions_.28Behavior.29">Actions (Behavior)</h1>
-<p>Actions are a fundamental aspect of the metaABM representational scheme, as they allow the definition of
-arbitrary but high level behavior for agents. They are also conceptually more challenging as unlike with structure they
-have no direct analogies to past agent representation -- or as far as we have been able to tell, Model-Driven Software
-Development --approaches. While the Acore Actions meta-model doesn't look like a programming language, it is useful to
-see it as a programming language without a concrete syntax. Because it doesn't define an actual concrete language
-implementation, it can be suitable for any number of potential text and visual languages. The default editor provided
-with AMF is hierarchical which isn't ideal for representing Acore Actions, but other text and visual editors are being
-developed and refined. Conceptually, Acore Actions is a kind of <a
- href="http://en.wikipedia.org/wiki/Dataflow_programming">data-flow language</a>, though the Actions design also
-carries aspects of <a href="http://en.wikipedia.org/wiki/Functional_programming">functional</a> and <a
- href="http://en.wikipedia.org/wiki/Logical_programming">logical languages</a>.</p>
-<h2 id="Basic_Design">Basic Design</h2>
-<p><img src="image/ActionsSimple.png" title="image/ActionsSimple.png"/></p>
-<p>Actions represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries.
-Queries, Transformations and other Actions are connected in a series of sources and targets, in which each child target
-carries the execution and data context for it's particular path.</p>
-<ol>
- <li>We define a Select Action, which determines what agent we are looking for, what space we are looking for
- that agent within, and what time (speaking very broadly, e.g. at startup, every period, at a scheduled time, on
- change in a specific state) we would like the behavior to occur. All Actions begin with a Root Action such as a
- Rule; these Actions trigger all resultant behavior.</li>
- <li>Then query terms and set operations are applied to that selection.</li>
- <li>Finally, commands are executed against the results of those queries.</li>
-</ol>
-<h2 id="Examples">Examples</h2>
-<h3 id="Simple_Example">Simple Example</h3>
-<p>In the following example, we want to create a set of actions that accomplish this task for the agent. It's always
-easier to express these things in natural languages! Our aim is to get as close as we can to that ease of expression
-without losing necessary detail and context.</p>
-<pre>"Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-</pre>
-<p><img src="image/ActionsExample.png" title="image/ActionsExample.png"/></p>
-<p>We define this model above in (conceptual) graphical and textual languages. No matter what tool we use to define
-the model in, the basic logic is the same..</p>
-<ol>
- <li>Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual"
- agents within the model. (We can define the space as well, but that's not relevant yet.</li>
- <li>Create a child Select Action that will find our partner. Two important things to note here:
- <ol>
- <li>The selection occurs "upon" the "find partner" select. On other words, for each Individual in the
- model, we'll be searching from the point of view of that agent to some other selection of agents.</li>
- <li>We also need to define what type of agent we want and in this case the space does matter. We want to be
- sure that the agent is nearby in the City space not any other space we might have defined.</li>
- </ol>
- </li>
- <li>Create two child Query Actions:
- <ol>
- <li>We want to search using a function for nearness, "within", which takes a parameter of vision. Note that
- the spatial functions are all polymorphic -- if we decided later on that we would rather search within say
- "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space
- we've defined in Select Partner. (Design discussion note: re-examine this issue WRT possibility of allowing
- users to search in multiple spaces within the same query.)</li>
- <li>We also want to search for someone who is the same age as us. This highlights the importance of the
- idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and
- <font color="red">ourselves</font>. The seleciton carries throughout the flow of execution and this context is
- an explicit part of the entire structure. Note that this is very different from the way control flow works in a
- traditional Imperative language such as Java.</li>
- </ol>
- </li>
- <li>Intersect (All in metaabm) these two queries. This delineates the end of the selection definition for any
- target Actions.</li>
- <li>Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of
- view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our
- target agent is a "Block", that is, a location within the city.</li>
- <li>As above, define some queries. This time we want only those agents that are available and neighbors of our
- partner.</li>
- <li>And another intersection..</li>
- <li>Finally, we move to the location we've found. All that's required at this point is to specify:
- <ol>
- <li>The movement selection, or those agents that are moving, which in this case is the original agent we're
- executing the rule for, and</li>
- <li>The destination, which is the cell that we've found. Note that the framework infers from the space
- definition that the Block agent is capable of hosting the Individual.</li>
- </ol>
- </li>
-</ol>
-<h3 id="AMF_Hierarchical_Editor">AMF Hierarchical Editor</h3>
-<p>Here's how the model looks in the default Acore editor. Note that we've collapsed the somewhat awkward multiple
-paths.</p>
-<p><img src="WikiExample.png"/></p>
-<h3 id="Code">Code</h3>
-<p>Why would we want to define our behaviors at such a high-level? There are a lot of reasons, including
-ease-of-use, transparency, parallelization and optimization, and all of the other MDSD goodies. You might want to take a
-look at what the code generated by AMF from this specification looks like in two POJO ABM APIs.</p>
-<p><a href="/AMP/UserGuide/AMF/ExampleAscapeCode" title="AMP/UserGuide/AMF/ExampleAscapeCode">Ascape</a></p>
-<p><a href="/AMP/UserGuide/AMF/ExampleRepastCode" title="AMP/UserGuide/AMF/ExampleRepastCode">Repast Simphony</a></p>
-<h2 id="Design_in_Depth">Design in Depth</h2>
-<p><img src="image/MetaABMActions.png" title="image/MetaABMActions.png"/></p>
-<h4 id="Details">Details</h4>
-<p>In the diagram above, all meta-objects are ActionsAInput, ALiteral, and the enumerators (lists of options) are
-Acts. Blue Acts are concrete (you can create and use them directly). Red indicates a key meta-object collaboration.</p>
-<ol>
- <li>An Act is anything that might happen during the execution of an Agent-Based Model.</li>
- <li>Acts are targets and sources of one another, but an Act can never have itself as a source. (That is, Acts
- are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include
- all ancestors or descendants, not just the immediately connected Act.)</li>
- <li>Acts reference a ASelect, referred to as the ÒselectedÓ relation. An ASelect represents the model aspects
- that the Act is working within; that is, the spatial, temporal and type (agent) ÒworldÓ that is currently being
- selected.</li>
- <li>ATransforms also specify a ÒdestinationÓ ASelect. This represents aspects that the selected agent(s) will
- transform to. For example, an AMove may use an ARule to select all SugarAgents (type) in the SugarGrid (space) every
- period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time
- implicit).</li>
- <li>All Acts have as their root-most source Act an ARoot. These are added first to any agent behavior and act
- as triggers for all target behavior. For example, an AWatch will ÒfireÓ any time the watched attribute is modified.
- (As the diagrams do not refer to elements outside of the current package, we cannot see here that AAccessor includes
- a reference to some SAttribute, but it does. To see these kinds of relationships you will want to refer to the
- metaabm.ecore file itself.)</li>
- <li>ASinks are Acts which use some FFunction (see next section) to interpret state in the form of AInputs.
- Inputs can come from selected agent attributes, other Acts, or literal values.</li>
- <li>AControls determine wether target acts are executed and against what agents. They are in some sense query
- terms.</li>
- <li>ACommands trigger some model state change (ASet) or spatial transformation (ATransform).</li>
-</ol>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Structure.html" title="Structure"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Acore.html" title="Acore"><img alt="Acore" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"><a href="Functions.html" title="Functions"><img alt="Next"
- border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Structure</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Functions</td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape-toc.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape-toc.xml
deleted file mode 100644
index ba43896..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape-toc.xml
+++ /dev/null
@@ -1,37 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<toc topic="wiki/Escape.html" label="Escape">
- <topic href="wiki/Escape.html" label="Overview"></topic>
- <topic href="wiki/Escape.html#Getting_Started" label="Getting Started">
- <topic href="wiki/Escape.html#Documentation_and_other_Resources" label="Documentation and other Resources"></topic>
- <topic href="wiki/Escape.html#Installation" label="Installation"></topic>
- <topic href="wiki/Escape.html#Exploring_Example_ABM_Models" label="Exploring Example ABM Models">
- <topic href="wiki/Escape.html#AMF_Models" label="AMF Models">
- <topic href="wiki/Escape.html#Setup_Escape_Projects" label="Setup Escape Projects">
- <topic href="wiki/Escape.html#Creating_a_New_Escape_Project" label="Creating a New Escape Project"></topic>
- <topic href="wiki/Escape.html#Using_an_Pre-Built_Example_Project" label="Using an Pre-Built Example Project"></topic>
- </topic>
- <topic href="wiki/Escape.html#Run_the_Model" label="Run the Model"></topic>
- <topic href="wiki/Escape.html#Next_Steps" label="Next Steps"></topic>
- </topic>
- <topic href="wiki/Escape.html#Classic_Java_ABM_Models" label="Classic Java ABM Models">
- <topic href="wiki/Escape.html#From_Project_Archive" label="From Project Archive"></topic>
- <topic href="wiki/Escape.html#From_SVN" label="From SVN"></topic>
- </topic>
- </topic>
- <topic href="wiki/Escape.html#Developing_Models" label="Developing Models"></topic>
- </topic>
- <topic href="wiki/Escape.html#Reference" label="Reference">
- <topic href="wiki/EscapeConverting.html" label="Converting Existing Ascape models">
- <topic href="wiki/EscapeConverting.html#Model" label="Model"></topic>
- <topic href="wiki/EscapeConverting.html#View" label="View">
- <topic href="wiki/EscapeConverting.html#Convert_the_low-level_imports_from_AWT_and_Swing_to_SWT" label="Convert the low-level imports from AWT and Swing to SWT"></topic>
- <topic href="wiki/EscapeConverting.html#Convert_color_features" label="Convert color features"></topic>
- <topic href="wiki/EscapeConverting.html#Change_agent_color_getters" label="Change agent color getters"></topic>
- <topic href="wiki/EscapeConverting.html#Get_rid_of_image_features" label="Get rid of image features"></topic>
- <topic href="wiki/EscapeConverting.html#Modify_usages_of_DrawFeatures" label="Modify usages of DrawFeatures"></topic>
- </topic>
- <topic href="wiki/EscapeConverting.html#Configuration" label="Configuration"></topic>
- </topic>
- <topic href="wiki/Escape.html#Current_Limitations" label="Current Limitations"></topic>
- </topic>
-</toc>
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.html
deleted file mode 100644
index f167f36..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Escape.html
+++ /dev/null
@@ -1,154 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
-<title>Escape</title>
-</head>
-<body>
-<h1 id="Overview">Overview</h1>
-<p>Escape is a full-featured Agent-Based Modeling (ABM) integrated development environment (IDE) with a Java based
-API and end user modeling tools. It's based on Ascape, which has been in use for more than 10 years. The core API is
-very stable, and that should give users a way to explore the features of AMP without concerns about keeping in synch
-with the rapidly evolving AXF /AGF API. It allows modelers to code in Java and/or generate models with AMF and then
-execute those models within the same development environment.</p>
-<p><img src="image/AMPScreenshot.png" /></p>
-<p>A primary purpose of the Escape project -- apart from the obvious goal of providing a nice Eclipse hosted ABM
-toolkit -- is to provide an exemplar to demonstrate how any arbitrary agent modeling framework can be integrated within
-the AMP environment. A cool aspect of this is that AMP has no dependencies on Escape, but also that the underlying ABM
-modeling framework for Escape has no dependencies on AMP -- instead Escape simply provides the runtime glue between AMP
-and the ABM framework. The underlying ABM framework uses the Ascape API, an API that first began development more than
-ten years ago and that has not been modified at all in order for it to work within the AMP environment.</p>
-<p>(Well, not quite.. Ascape was refactored into separate non-UI core and a Swing UI projects. This involved a bit
-of repackaging, but was really straightforward as Ascape follows a strict MVC architecture. Note that currently Escape
-is bulkier than it will eventually be -- over time we will be generalizing more aspects of Escape into the AMP AXF and
-AGF components.)</p>
-<h1 id="Getting_Started">Getting Started</h1>
-<h3 id="Documentation_and_other_Resources">Documentation and other Resources</h3>
-<p>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation.
-There is complete Javadoc as well as a manual and other web resources. See the <a href="http://ascape.sourceforge.net">Ascape
-Website</a> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape
-so ignore all of the bits about project setup, and a lot of the UI is different, but the basics apply to Escape just as
-well. The <a href="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</a> written by Damon Centola
-should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual
-work under Ascape. (Converting these models is a great opportunity for a community contribution!)</p>
-<h2 id="Installation">Installation</h2>
-<p>Escape is <a href="http://eclipse.org/amp/installing/">installed</a> by default with the other model components.
-If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from
-source but in that case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site
-if you're not actually doing AMP development.</p>
-<h2 id="Exploring_Example_ABM_Models">Exploring Example ABM Models</h2>
-<p>The first thing most people will want to do in AMP is to play with the example models. You don't need to do any
-programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is <a
- href="http://eclipse.org/amp/installing">Install AMP</a>. (You don't need any of the optional components unless you
-want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really
-interesting classic ABM models.</p>
-<h3 id="AMF_Models">AMF Models</h3>
-<p>There are a number of models developed with AMF that can automatically generate example models to run in Escape.
-There are two ways to run the example models:</p>
-<h4 id="Setup_Escape_Projects">Setup Escape Projects</h4>
-<h5 id="Creating_a_New_Escape_Project">Creating a New Escape Project</h5>
-<p>The best option is to simply create a new Escape project and drag the models into it! Just follow this <a href='javascript:liveAction(
-"org.eclipse.ui.cheatsheets",
-"org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction",
-"org.eclipse.amp.escape.intro")'>cheatsheet</a>.</p>
-<ol>
- <li>If you're not already there, open the Agent Modeling Perspective. Select Window : Open Perspective :
- Other.. and then Agent Modeling. (Or you can choose Window : Reset Perspective and the Agent Modeling perspective
- should appear in the Open Perspective list itself.)</li>
- <li>Next, let's create the project where we'll place our model. Select File : New : Escape AMF Project. Give it
- a name like "escape.tutorial", then click Finish.</li>
- <li>Finally grab the Epidemic.metaabm model at <a
- href="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</a>
- and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in
- which case just right-click on the link and save it to a file.)</li>
-</ol>
-<h5 id="Using_an_Pre-Built_Example_Project">Using a Pre-Built Example Project</h5>
-<p>If you get really stuck somewhere, you can also get ready made projects from CVS. See <a
- href="http://eclipse.org/amp/developers/repositoryDetails.php">this page</a> for information on CVS setup. The
-project for Escape example models are located at:</p>
-<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
-</pre>
-<h4 id="Run_the_Model">Run the Model</h4>
-<p>Right-click on the model, and select "Execute"! You should see something like this:</p>
-<p><img src="image/EpidemicModelRunning.png" /></p>
-<p>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory.
-The toolbar buttons allow you to control model execution.</p>
-<p><img src="image/EpidemicModelControls.png" /></p>
-<p>From right to left, you can start, restart, pause, step, stop and close a model. You can even run multiple models
-and control them independently. You can also move views around, close them and so on as with any other Eclipse views.
-Here we're running two separate models for comparison.</p>
-<p><img src="image/EpidemicModelComparison.png" /></p>
-<p>If you want to find out more about an agent, show the properties view, and click on agent.</p>
-<p><img src="image/EpidemicModelAgentProperties.png" /></p>
-<p>You can experiment with different parameters (settings) for models by then clicking in the gray area away within
-the view.</p>
-<p><img src="image/EpidemicModelProperties.png" /></p>
-<p>There are a number of other things to play around with, such as zooming the agent view or selecting other chart
-series to display using the Chart Customizer, so just explore. You can always close an active model by clicking on the
-close toolbar button. Or if you can't access the models controls for some reason, you can open the progress view and
-close projects form there.</p>
-<h4 id="Next_Steps">Next Steps</h4>
-<p>Other models are located at: (to do)</p>
-<p>To understand the capabilities of AMF, you might also want to try out running the same models automatically
-generated for Ascape or Repast.</p>
-<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
-org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
-</pre>
-<h3 id="Classic_Java_ABM_Models">Classic Java ABM Models</h3>
-<p>Many models have been created using Ascape over the years, including all of the classic models created at
-Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've
-all been converted to run in Escape. They're in Java but you can execute and explore them in exactly the same way as the
-Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial
-Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You
-can get the projects in two ways:</p>
-<h4 id="From_Project_Archive">From Project Archive</h4>
-<ul>
- <li>Download the Escape examples zip from the Ascape sourceforge site: <a
- href="http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download">http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download</a>
- </li>
- <li>Unzip the file.</li>
- <li>Import them into your workspace. For help, see <a
- href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this
- page</a>.</li>
-</ul>
-<h4 id="From_SVN">From SVN</h4>
-<ul>
- <li>Import the SVN projects from the sourceforge SVN. For help, see <a
- href="/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page"
- title="http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php this page">http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php
- this page</a>.</li>
-</ul>
-<pre>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
-http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
-</pre>
-<p>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models.
-For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select
-"Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have
-to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</p>
-<h2 id="Developing_Models">Developing Models</h2>
-<p>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write
-programs using it.To develop new models, you can:</p>
-<ol>
- <li>Create a new Escape project. The Escape projects are actually configured for AMF code generation so there
- are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the
- kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.</li>
- <li>But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have
- a look at the example escape project to see what you need. Note that you will likely need more dependencies then you
- need to simply build -- this is because the class loader uses the classes from the project path and so runtime
- classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these
- dependencies up a bit.</li>
-</ol>
-<p>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</p>
-<h1 id="Reference">Reference</h1>
-<h2 id="Current_Limitations">Current Limitations</h2>
-<ol>
- <li>Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as
- stable for a while as Ascape which has been around for a long time. But we haven't run into any issues recently.</li>
- <li>Escape graphics performance is generally a little bit slower. But on the other hand you can run
- multiple models at once and the headless models should perform just as well as console launched Ascape programs. In
- practice this shouldn't affect your normal model exploration work. Ad you can always speed ahead by using the speed slider!</li>
-</ol>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/EscapeConverting.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/EscapeConverting.html
deleted file mode 100644
index 873c841..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/EscapeConverting.html
+++ /dev/null
@@ -1,73 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
-<title>Escape</title>
-</head>
-<body>
-<h2 id="Converting_Existing_Ascape_models">Converting Existing Ascape models</h2>
-<p>There are only a few changes should have to make to existing Ascape models or to use existing Ascape
-documentation to develop Escape models.</p>
-<h4 id="Model">Model</h4>
-<p>The core model is completely API compatible. No changes!</p>
-<h4 id="View">View</h4>
-<p>Because Escape uses SWT and Ascape uses Swing, there are a few unavoidable incompatibilities. Most of these we
-avoid by using higher level APIs but here are the key changes that you're likely to have to make:</p>
-<h5 id="Convert_the_low-level_imports_from_AWT_and_Swing_to_SWT">Convert the low-level imports from AWT and Swing
-to SWT</h5>
-<p>The simplest way to accomplish this is to remove all of the imports and then organize imports. For example:</p>
-<pre>java.awt.Color <b>to</b> org.eclipse.swt.graphics.Color
-java.awt.Graphics <b>to</b> org.eclipse.draw2d.Graphics
-</pre>
-<p>Then just do a global find for all of the imports and replace them with nothing. This is a great place for a
-regexp. Try:</p>
-<pre>find: import java\.awt\.(.*);
-replace: [nothing]
-</pre>
-<p>You don't have to replace these with the SWT equivalents, just click on the project, right-click and choose
-"Source:Organize Imports.." By the way, a great way to avoid having to select the right entries in optimize imports and
-to alert you when you have missed anything is to prevent the awt and swing classes from being used at all. Right-click
-on project, choose "Build Path:Configure Build Path", go to Libraries tab, open JRE System Library, choose "Access
-Rules", edit, and then add entries for java/awt/** and javax/swing/**. The code will regenerate and you'll have error
-markers for all of the stuff that won't work with Escape and Eclipse.</p>
-<h5 id="Convert_color_features">Convert color features</h5>
-<p>You can't use AWT colors either so you'll need to replace any colors. AMP provides a convenience classes for
-Colors called ColorFeature and ColorFeatureConcrete. You can use these or any of the other ways to define SWT colors.
-For example:</p>
-<pre>Color.lightGray <b>to</b> ColorFeature.LIGHT_GRAY
-new Color(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy) <b>to</b>
- ColorFeatureConcrete.create(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy)
-</pre>
-<h5 id="Change_agent_color_getters">Change agent color getters</h5>
-<p>If you've defined colors through overriding Agents as in most models, you'll need to change the method signature.
-You could just do a global replace for this one.</p>
-<pre>public Color getColor( <b>to</b> public Object getPlatformColor(
-</pre>
-<h5 id="Get_rid_of_image_features">Get rid of image features</h5>
-<p>Escape doesn't support them. In practice they haven't been used a lot. At some point perhaps we'll have nice
-sprite support instead. :)</p>
-<pre>public Image getImage() {**} <b>to</b> ""
-</pre>
-<h5 id="Modify_usages_of_DrawFeatures">Modify usages of DrawFeatures</h5>
-<p>If you've created any of your own draw features, you'll need to change them slightly to accommodate the
-differences between the AWT and SWT / Draw2D APIs. This should be pretty straightforwrd. For example:</p>
-<pre>g.setColor(...
-g.fillOval(..
-becomes:
-g.setBackgroundColor(
-g.fillOval(..
-</pre>
-
-<h4 id="Configuration">Configuration</h4>
-<p>Instead of using Ant, Escape has really nice support for parameterizing and testing models. See <a
- href="/wiki/Experimenting_and_Testing" title="Experimenting and Testing">Experimenting and Testing</a> (todo). If
-you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have
-dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you
-think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape
-so it's not even clear it will work.</p>
-<p>That's about it, though we may have missed something. Please post a message on the amp newsgroup if
-you run into any other conversion issues.</p>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Functions.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Functions.html
deleted file mode 100644
index 05812d5..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Functions.html
+++ /dev/null
@@ -1,59 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Acore - Functions</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">Functions</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Actions-Behavior-.html" title="Actions (Behavior)"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"><a href="Acknowledgements.html" title="Acknowledgements"><img
- alt="Next" border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Actions (Behavior)</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Acknowledgements</td>
- </tr>
-</table>
-<hr />
-<h1 id="Functions">Functions</h1>
-<h2 id="Design">Design</h2>
-<p><img src="image/MetaABMFunctions.png" title="image/MetaABMFunctions.png"/></p>
-<p>The Function representation is relatively simple. As indicated above, Functions are used by Sinks to interpret
-some model state. Functions are broken into two broad types; Operators, which are simple calculations sharing the same
-type, and Generic Functions that can represent any general function that takes some well-defined input(s) and returns
-some well-defined output(s). Conceptually, functions can return multi-values, but that is not currently implemented in
-the reference targets because of limitations of the target language Java. Logicals return some binary result and that is
-used by Queries to decide wether target Actions apply to a particular selection. Input types should be defined as
-generally as possible.</p>
-<h2 id="Built-in_Functions">Built-in Functions</h2>
-<p>Acore comes with a built-in library of core functions. See the <a href="/AMP/UserGuide/AMF/Core_Library"
- title="AMP/UserGuide/AMF/Core_Library">table of core functions</a>.</p>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Actions-Behavior-.html" title="Actions (Behavior)"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Acore.html" title="Acore"><img alt="Acore" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"><a href="Acknowledgements.html" title="Acknowledgements"><img
- alt="Next" border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Actions (Behavior)</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Acknowledgements</td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Getting-Started.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Getting-Started.html
deleted file mode 100644
index e2f11f0..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Getting-Started.html
+++ /dev/null
@@ -1,160 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Escape - Getting Started</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">Getting Started</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Escape.html" title="Overview"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"><a href="Reference.html" title="Reference"><img alt="Next"
- border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Overview</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Reference</td>
- </tr>
-</table>
-<hr />
-<h1 id="Getting_Started">Getting Started</h1>
-<h3 id="Documentation_and_other_Resources">Documentation and other Resources</h3>
-<p>Because it's API is based on Ascape, Escape is one component of AMP that already has extensive documentation.
-There is complete Javadoc as well as a manual and other web resources. See the <a href="http://ascape.sourceforge.net">Ascape
-Website</a> to locate these resources. The documentation on the main page is a good place to start. It's written for Ascape
-so ignore all of the bits about project setup, and a lot of the UI is different, but the basics apply to Escape just as
-well. The <a href="http://ascape.sourceforge.net/docs/TheAscapeManual5.pdf">Ascape Manual</a> written by Damon Centola
-should be very helpful. Take a look at the conversion link below for ideas on how to make the models form the manual
-work under Ascape. (Converting these models is a great opportunity for a community contribution!)</p>
-<h2 id="Installation">Installation</h2>
-<p>Escape is <a href="http://eclipse.org/amp/installing/">installed</a> by default with the other model components.
-If you want to do 3D (really 2 1/2) visualizations, you will want AGF3D and the LWJGL dependency. You can build from
-source but in that case you'l need to launch a self-hosted runtime, so it's best to simply install from the update site
-if you're not actually doing AMP development.</p>
-<h2 id="Exploring_Example_ABM_Models">Exploring Example ABM Models</h2>
-<p>The first thing most people will want to do in AMP is to play with the example models. You don't need to do any
-programming for this, and the setup is really straightforward. Of course, the first think you'll need to do is <a
- href="http://eclipse.org/amp/installing">Install AMP</a>. (You don't need any of the optional components unless you
-want to play with the 3D visualizations, Ascape, or Repast.) You can explore AMF models as well as some really
-interesting classic ABM models.</p>
-<h3 id="AMF_Models">AMF Models</h3>
-<p>There are a number of models developed with AMF that can automatically generate example models to run in Escape.
-There are two ways to run the example models:</p>
-<h4 id="Setup_Escape_Projects">Setup Escape Projects</h4>
-<h5 id="Creating_a_New_Escape_Project">Creating a New Escape Project</h5>
-<p>The best option is to simply create a new Escape project and drag the models into it! We're working on a simple
-cheat sheet for this, but until then, just follow these simple steps:</p>
-<ol>
- <li>If you're not already there, open the Agent Modeling Perspective. Select Window : Open Perspective :
- Other.. and then Agent Modeling. (Or you can choose Window : Reset Perspective and the Agent Modeling perspective
- should appear in the Open Perspective list itself.)</li>
- <li>Next, let's create the project where we'll place our model. Select File : New : Escape AMF Project. Give it
- a name like "escape.tutorial", then click Finish.</li>
- <li>Finally grab the Epidemic.metaabm model at <a
- href="http://download.eclipse.org/amp/models/Epidemic.metaabm">http://download.eclipse.org/amp/models/Epidemic.metaabm</a>
- and drag it into the project. (Depending on your browser the file may load as text directly into your browser, in
- which case just right-click on the link and save it to a file.)</li>
-</ol>
-<h5 id="Using_an_Pre-Built_Example_Project">Using an Pre-Built Example Project</h5>
-<p>If you get really stuck somewhere, you can also get ready made projects from CVS. See <a
- href="http://eclipse.org/amp/developers/repositoryDetails.php">this page</a> for information on CVS setup. The
-project for Escape example models are located at:</p>
-<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.escape
-</pre>
-<h4 id="Run_the_Model">Run the Model</h4>
-<p>Right-click on the model, and select "Execute"! You should see something like this:</p>
-<p><img src="image/EpidemicModelRunning.png"/></p>
-<p>We're working on more end-user documentaiton, but hopefully you'll find model control pretty self-explanatory.
-The toolbar buttons allow you to control model execution.</p>
-<p><img src="image/EpidemicModelControls.png"/></p>
-<p>From right to left, you can start, restart, pause, step, stop and close a model. You can even run multiple models
-and control them independently. You can also move views around, close them and so on as with any other Eclipse views.
-Here we're running two separate models for comparison.</p>
-<p><img src="image/EpidemicModelComparison.png"/></p>
-<p>If you want to find out more about an agent, show the properties view, and click on agent.</p>
-<p><img src="image/EpidemicModelAgentProperties.png"/></p>
-<p>You can experiment with different parameters (settings) for models by then clicking in the gray area away within
-the view.</p>
-<p><img src="image/EpidemicModelProperties.png"/></p>
-<p>There are a number of other things to play around with, such as zooming the agent view or selecting other chart
-series to display using the Chart Customizer, so just explore. You can always close an active model by clicking on the
-close toolbar button. Or if you can't access the models controls for some reason, you can open the progress view and
-close projects form there.</p>
-<h4 id="Next_Steps">Next Steps</h4>
-<p>Other models are located at: (to do)</p>
-<p>To understand the capabilities of AMF, you might also want to try out running the same models automatically
-generated for Ascape or Repast.</p>
-<pre>org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.ascape
-org.eclipse.amp/org.eclipse.amp.amf/examples/org.eclipse.amp.amf.examples.repast
-</pre>
-<h3 id="Classic_Java_ABM_Models">Classic Java ABM Models</h3>
-<p>Many models have been created using Ascape over the years, including all of the classic models created at
-Brookings and some other cool models such as Craig Reynold's Boids and a pretty cool little traffic model, and they've
-all been converted to run in Escape. They're in Java but you can execute and explore them in exactly the same way as the
-Epidemic model above. All of the Ascape example models have been converted (a straightforward process) from their intial
-Ascape incarnations. For licensing reasons (they're BSD, not EPL) we can't host them directly on the Eclipse site. You
-can get the projects in two ways:</p>
-<h4 id="From_Project_Archive">From Project Archive</h4>
-<ul>
- <li>Download the Escape examples zip from the Ascape sourceforge site: <a
- href="http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download">http://sourceforge.net/projects/ascape/files/Escape/5.2.0/EscapeExamples.zip/download</a></li>
- <li>Unzip the file.</li>
- <li>Import them into your workspace. For help, see <a
- href="http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jst.j2ee.doc.user/topics/ph-projects.html">this
- page</a>.</li>
-</ul>
-<h4 id="From_SVN">From SVN</h4>
-<ul>
- <li>Import the SVN projects from the sourceforge SVN. For help, see <a
- href="/http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php_this_page"
- title="http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php this page">http://www.eclipse.org/subversive/documentation/teamSupport/find_check_wiz.php
- this page</a>.</li>
-</ul>
-<pre>http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.brook
-http://ascape.svn.sourceforge.net/svnroot/ascape/org.ascape.escape.models.examples
-</pre>
-<p>Once you've downloaded the projects, open up the src folder and navigate to the Java files for the actual models.
-For example, to run Conway's Life, you'll want src/edu.brook.life.ConwayLife. Right-click on the Java file and select
-"Execute". There are many models to explore! (It's not always obvious which Java files are for models, so you may have
-to poke around a bit. We need to put together a catalog here. Another nice opportunity for user contributions.)</p>
-<h2 id="Developing_Models">Developing Models</h2>
-<p>The easiest way for Java developers to get started doing agent-based modeling in Eclipse is to begin to write
-programs using it.To develop new models, you can:</p>
-<ol>
- <li>Create a new Escape project. The Escape projects are actually configured for AMF code generation so there
- are dependencies and builders in there that you don't need; you can remove all of the escape builders and any of the
- kitchen sink items. We'll try to get a POJO Escape project wizard out there at some point.</li>
- <li>But it might be simpler to just create a new Plugin Project and add the necessary dependencies there. Have
- a look at the example escape project to see what you need. Note that you will likely need more dependencies then you
- need to simply build -- this is because the class loader uses the classes from the project path and so runtime
- classes have to be there as well. We may simply package an Eclipse runtime convenience plugin to gather these
- dependencies up a bit.</li>
-</ol>
-<p>Then just create new Java classes for your root model scape and agents just as you would for an Ascape project.</p>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Escape.html" title="Overview"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Escape.html" title="Escape"><img alt="Escape" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"><a href="Reference.html" title="Reference"><img alt="Next"
- border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Overview</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Reference</td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide-toc.xml b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide-toc.xml
deleted file mode 100644
index 47f9b93..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide-toc.xml
+++ /dev/null
@@ -1,105 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<toc topic="wiki/ModelersGuide.html" label="ModelersGuide">
- <topic href="wiki/ModelersGuide.html" label="Introduction"></topic>
- <topic href="wiki/ModelersGuide.html#General" label="General">
- <topic href="wiki/ModelersGuide.html#Descriptions" label="Descriptions">
- <topic href="wiki/ModelersGuide.html#Label" label="Label"></topic>
- <topic href="wiki/ModelersGuide.html#ID" label="ID"></topic>
- <topic href="wiki/ModelersGuide.html#Description" label="Description"></topic>
- <topic href="wiki/ModelersGuide.html#Plural_Label" label="Plural Label"></topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Structure" label="Structure">
- <topic href="wiki/ModelersGuide.html#Agents" label="Agents">
- <topic href="wiki/ModelersGuide.html#Context_Agents_.28Contexts.29" label="Context Agents (Contexts)"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Attributes" label="Attributes">
- <topic href="wiki/ModelersGuide.html#Basic_Attributes" label="Basic Attributes">
- <topic href="wiki/ModelersGuide.html#Type" label="Type"></topic>
- <topic href="wiki/ModelersGuide.html#Default_Value" label="Default Value"></topic>
- <topic href="wiki/ModelersGuide.html#Gather_Data" label="Gather Data"></topic>
- <topic href="wiki/ModelersGuide.html#Immutable" label="Immutable"></topic>
- <topic href="wiki/ModelersGuide.html#Units" label="Units"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Arrays" label="Arrays">
- <topic href="wiki/ModelersGuide.html#Size" label="Size"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#States" label="States">
- <topic href="wiki/ModelersGuide.html#State_Options" label="State Options">
- <topic href="wiki/ModelersGuide.html#Default_Option" label="Default Option"></topic>
- </topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Spaces" label="Spaces">
- <topic href="wiki/ModelersGuide.html#Space_.28Continuous.29" label="Space (Continuous)">
- <topic href="wiki/ModelersGuide.html#Border_Rule" label="Border Rule"></topic>
- <topic href="wiki/ModelersGuide.html#Dimensionality" label="Dimensionality"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Grid" label="Grid">
- <topic href="wiki/ModelersGuide.html#Multi-Occupant" label="Multi-Occupant"></topic>
- <topic href="wiki/ModelersGuide.html#Neighborhood" label="Neighborhood"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Network" label="Network">
- <topic href="wiki/ModelersGuide.html#Directed" label="Directed"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Geography" label="Geography"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Reference" label="Reference">
- <topic href="wiki/ModelersGuide.html#Diagrams" label="Diagrams">
- <topic href="wiki/ModelersGuide.html#Meta-Classes" label="Meta-Classes"></topic>
- <topic href="wiki/ModelersGuide.html#Key_Collaborations" label="Key Collaborations"></topic>
- <topic href="wiki/ModelersGuide.html#Details" label="Details"></topic>
- </topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Actions" label="Actions">
- <topic href="wiki/ModelersGuide.html#Background" label="Background"></topic>
- <topic href="wiki/ModelersGuide.html#Types_of_Actions" label="Types of Actions"></topic>
- <topic href="wiki/ModelersGuide.html#Selections" label="Selections">
- <topic href="wiki/ModelersGuide.html#Sequences" label="Sequences"></topic>
- <topic href="wiki/ModelersGuide.html#Boundaries" label="Boundaries"></topic>
- <topic href="wiki/ModelersGuide.html#Root_Actions" label="Root Actions">
- <topic href="wiki/ModelersGuide.html#Build" label="Build"></topic>
- <topic href="wiki/ModelersGuide.html#Initialize" label="Initialize"></topic>
- <topic href="wiki/ModelersGuide.html#Rule" label="Rule"></topic>
- <topic href="wiki/ModelersGuide.html#Schedule" label="Schedule">
- <topic href="wiki/ModelersGuide.html#Start" label="Start"></topic>
- <topic href="wiki/ModelersGuide.html#Interval" label="Interval"></topic>
- <topic href="wiki/ModelersGuide.html#Priority" label="Priority"></topic>
- <topic href="wiki/ModelersGuide.html#Pick" label="Pick"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Watch" label="Watch">
- <topic href="wiki/ModelersGuide.html#Attribute" label="Attribute"></topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Selection" label="Selection">
- <topic href="wiki/ModelersGuide.html#Selection_2" label="Selection"></topic>
- <topic href="wiki/ModelersGuide.html#Agent" label="Agent"></topic>
- <topic href="wiki/ModelersGuide.html#Space" label="Space"></topic>
- <topic href="wiki/ModelersGuide.html#For" label="For"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Query" label="Query">
- <topic href="wiki/ModelersGuide.html#Function" label="Function"></topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Logic" label="Logic">
- <topic href="wiki/ModelersGuide.html#Intersection" label="Intersection"></topic>
- <topic href="wiki/ModelersGuide.html#Union" label="Union"></topic>
- <topic href="wiki/ModelersGuide.html#Difference" label="Difference"></topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Example" label="Example"></topic>
- <topic href="wiki/ModelersGuide.html#Reference_2" label="Reference">
- <topic href="wiki/ModelersGuide.html#Diagrams_2" label="Diagrams">
- <topic href="wiki/ModelersGuide.html#Meta-Classes_2" label="Meta-Classes"></topic>
- <topic href="wiki/ModelersGuide.html#Details_2" label="Details"></topic>
- </topic>
- </topic>
- </topic>
- <topic href="wiki/ModelersGuide.html#Functions" label="Functions">
- <topic href="wiki/ModelersGuide.html#Reference_3" label="Reference">
- <topic href="wiki/ModelersGuide.html#Diagrams_3" label="Diagrams">
- <topic href="wiki/ModelersGuide.html#Meta-Classes_3" label="Meta-Classes"></topic>
- </topic>
- </topic>
- </topic>
-</toc>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.html
deleted file mode 100644
index 4bff9dc..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.html
+++ /dev/null
@@ -1,4 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h1 id="Introduction">Introduction</h1><p>In this section of the documentation we'll provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design them. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Actions, Attributes, Spaces and Styles. We'll describe each component in depth. But first a generic concept:</p><h1 id="General">General</h1><h2 id="Descriptions">Descriptions</h2><p>Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore define:</p><h5 id="Label">Label</h5><p>A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Forex Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.</p><h5 id="ID">ID</h5><p>An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)</p><p>And most entities also define:</p><h5 id="Description">Description</h5><p>A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.</p><h5 id="Plural_Label">Plural Label</h5><p>The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".</p><h1 id="Structure">Structure</h1><h2 id="Agents">Agents</h2><p>An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.</p><h3 id="Context_Agents_.28Contexts.29">Context Agents (Contexts)</h3><p>Agents also form the basic structural component of an agent-based model. Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".</p><h2 id="Attributes">Attributes</h2><p>Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.</p><p>Here are the basic types of attributes available in Acore models:</p><h3 id="Basic_Attributes">Basic Attributes</h3><p>Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. Attributes have descriptions of course, and they also have:</p><h5 id="Type">Type</h5><p>These can be anyone of the following: </p><table border="1" cellpadding="10" cellspacing="0"><tr><td>Boolean</td><td>A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.</td></tr><tr><td>Integer</td><td>A discrete whole number value, such as "100", "-1", "10029920". It's generally a good idea to represent any value that can never have a decimal value as an integer.</td></tr><tr><td>Real</td><td>A continuous number value. While these are typically represented in software as floating point numbers, they can conceivably represent numbers at any arbitrary precision and in any scheme. Note that while technically speaking we should be representing irrational numbers, this is not currently supported for default values and users should simply use the closest decimal approximation.</td></tr><tr><td>Symbol</td><td>A string representing some state. More precisely, a computationally arbitrary value with contextual meaning. This could be any kind of identifier. For example, you might use it to store some kind of input coding from data that is then converted into an object state. Or it could simply be an agent's name. But theoretically (though this is not currently supported) one could imagine a symbol using an idiogram, an icon or even a sound that identifies or represents the agent in question.</td></tr></table><p>(Undefined and Numeric types should not be used within a well-defined model.)</p><h5 id="Default_Value">Default Value</h5><p>The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.</p><h5 id="Gather_Data">Gather Data</h5><p>Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.</p><h5 id="Immutable">Immutable</h5><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><h5 id="Units">Units</h5><p>Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.</p><h3 id="Arrays">Arrays</h3><p>Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to whatis defined above, arrays specify:</p><h5 id="Size">Size</h5><p>The number of values that the array attribute will contain.</p><h3 id="States">States</h3><p>States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".</p><h4 id="State_Options">State Options</h4><p>Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have</p><h5 id="Default_Option">Default Option</h5><p>unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.</p><h2 id="Spaces">Spaces</h2><p>All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:</p><h3 id="Space_.28Continuous.29">Space (Continuous)</h3><p>In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.</p><h5 id="Border_Rule">Border Rule</h5><p>A value representing what happens to an agent when that agent is asked to move beyond its extent.</p><table border="1" cellpadding="10" cellspacing="0"><tr><td>Periodic</td><td>When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location <a href="1,2">1,2</a> (0-based) within a Moore space (see grid discussion below) of size <a href="10,10">10,10</a> is asked to find some other agent within distance 3, the agent look in the square defined between <a href="8,9">8,9</a> and <a href="4,5">4,5</a>. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.</td></tr><tr><td>APeriodic</td><td>When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location <a href="1,2">1,2</a> is asked to find some other agent within distance 3, the agent look between <a href="0,0">0,0</a> and <a href="4,5">4,5</a>. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.</td></tr></table><p>The "Strict" and "Bouncy" values are obsolete and should not be used.</p><h5 id="Dimensionality">Dimensionality</h5><p>The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attrbiute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.</p><h3 id="Grid">Grid</h3><p>A grid is technically a regular lattice structure. Currently, only rectilinear strcutures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platfroms support n-d spaces yet.) </p><p>Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:</p><h5 id="Multi-Occupant">Multi-Occupant</h5><p>Does the grid allow more than one agent to occupy it at a time? This value can usually be ignored and will likely be deprecated in future releases.</p><h5 id="Neighborhood">Neighborhood</h5><p>This value determines what constitutes a region within a particular distance from the agent. The value for this is often ciritical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:</p><table border="1" cellpadding="10" cellspacing="0"><tr><td>Euclidian</td><td>The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidian space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidian space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notionally real spaces.</td></tr><tr><td>Moore</td><td>Here, the distance between any two cells is defined by the number of edge <i>or</i> corner adjacent cells crossed to get between them. To continue the chess board analaogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.</td></tr><tr><td>Von-Neumann</td><td>Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time.</td></tr></table><h3 id="Network">Network</h3><p>A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.</p><p>A network has only one value to specify:</p><h5 id="Directed">Directed</h5><p>This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)</p><h3 id="Geography">Geography</h3><p>A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.</p><h2 id="Reference">Reference</h2><h3 id="Diagrams">Diagrams</h3><p>For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.</p><h4 id="Meta-Classes">Meta-Classes</h4><p>Our first diagram depicts the core structural design of the model. </p><p><img border="0" src="image/StructureComplexDiagram.png"/> </p><pre>There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
-</pre><h4 id="Key_Collaborations">Key Collaborations</h4><p><img border="0" src="image/StructureSimpleDiagram.png"/></p><pre>Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-</pre><h4 id="Details">Details</h4><ol><li>Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally). </li><li>(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.</li><li>Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.</li><li>Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidian) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.</li><li>Agents are Actables and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.</li><li>Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actables. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".</li></ol><h1 id="Actions">Actions</h1><p>Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.</p><h2 id="Background">Background</h2><p>Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.</p><p>An action provides simple, well-defined details that a model can use to determine what steps to take in model execution. That definition seems general enough to be almost useless, but its important to understand that an action is not equivalent to an instruction, a method or a query. In fact, actions can have aspects of all of these. But an action is not in itself an instruction specifying exactly <i>how</i> the modeling engine should do something -- instead an action represents <i>what</i> the modeler intends for the agents to do. (Technically, we might say that Actions takes a "declarative" approach instead of an 'imperative' approach, but that's not quite true, because actions do allow us to define behavior in a richer way than most declarative approaches, and many action constructs map directly to imperative approaches.)</p><p>Actions are connected together in a series of sources and targets. (Technically, an acyclic directed graph.) In an abstract sense that is similar to the way any programming language is defined although that structure isn't usually obvious because of the constraints of textual representations. But unlike a typical programming language, in Actions it is not the execution thread (the processor) that moves from one instruction to the next, but the result of the previous action. In this way, action results "flow" from the output of one action into the next action.</p><p>Why are these distinctions between traditional Object-Oriented and the Action approaches important? They give us the advantages of simplicity, clarity and flexibility that <a href="/wiki/http://en.wikipedia.org/wiki/Dataflow_programming" title="http://en.wikipedia.org/wiki/Dataflow_programming">data-flow approaches</a> like spreadsheets and some query languages have, but with less restrictions. At the same time, they can bring us much of the power and expressivity of <a href="/wiki/http://en.wikipedia.org/wiki/Functional_programming" title="http://en.wikipedia.org/wiki/Functional_programming">functional languages</a> like Lisp or <a href="/wiki/http://en.wikipedia.org/wiki/Logical_programming" title="http://en.wikipedia.org/wiki/Logical_programming">logical languages</a> like Prolog, but without the level of complexity and obscurity that such languages can have.</p><p>We can get a better idea for how Actions work by thinking about how a spreadsheet works. In a spreadsheet, we might define a cell A that adds up a row of data, say "Income". We might define another cell C ("Profit") that takes A and adds it to another cell B that adds up another row of data ("Expenses"). Now, if we change a value in any of the rows, all of the other rows are added up and we get the results in A and B updated automatically. We never had to write code that said something like "for each cell in row X, where...". In fact, we don't really care <i>how</i> our Spreadsheet program adds up the numbers -- it could have added them all up at once but in backward order, or stored a running total somewhere and updated just the difference in value for the cell we changed -- what we care about is <i>what</i> the result is, and whether it is correct.</p><p>But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.</p><h2 id="Types_of_Actions">Types of Actions</h2><p>Before getting into the details of how each Action works, we need to understand how they all fit together. As discussed above, actions are strung together in a sequence. 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. There are two special kinds of selections. First, 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. 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.</p><p>There are two other special categories of actions. One we use to crate the spaces that agents exist upon. We call these Builders. The other category contains just one member, "Method".</p><p>These are all summarized in the diagram below.</p><p><img border="0" src="image/ActionsBlocks.png"/> </p><h2 id="Selections">Selections</h2><p>A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.</p><h3 id="Sequences">Sequences</h3><p>Again, a set of Behaviors in Actions is always defined by a set of selections and queries. In the following diagram, we can see the pattern.</p><p><img border="0" src="image/ActionsSequence.png"/></p><p>First, we define a Root Selection for a Rule, Schedule or other triggering event. Then, we might add a series of Query and Logic Actions to define the specific agents that we are intrested in. These are all part of the Selection. Next, we might define a series of Commands to determine what to do with those agents. Or, we could use the result of that selection to immediatly define another selection, for example if we are searching for an agent that is near another agent. The next diagram depicts a simple example.</p><p><img border="0" src="image/ActionsSimpleSequence.png"/></p><p>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. In the 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.</p><p><img border="0" src="image/ActionsSimpleSequence2.png"/></p><p>Logic Actions are used to assemble any kind of query structure needed. In the following example, we've defined a selection where the Set action occurs for any agent whoe meets the criteria defined by (Query 1 AND Query 2) OR Query 3. (Readers with experience with programming or formal logic will note that this looks just like a parse tree, and while that's basically what it is, there are important differences from how such trees are generally treated as we'll see later.)</p><p><img border="0" src="image/ActionsComplexLogic.png"/></p><p>Note that Unions are often superfulous, though they can be useful for organizing queries. This is because all sources that flow into a given target Action act just like a union since any of the paths might reach that target. The following Action design is fully equivalant to the one above.</p><p><img border="0" src="image/ActionsComplexLogicNoOr.png"/></p><h3 id="Boundaries">Boundaries</h3><p>An important concept in Actions is the idea of selection boundaries. A selection boundary is defined as the limit of a query directly upon a given Select Action. For example, in the following diagram, we can see the extent of the boundary for a straightforward selection.</p><p><img border="0" src="image/ActionsSelBoundary1.png"/></p><p>When does one selection boundary end and the next one begin? The simple rule is that the end of the boundary is defined for a given Action by the place where:</p><ol><li>A Query Action is not followed by a Logic Action, or</li><li>A Logic Action is not followed by another Logic Action</li></ol><p>In other words, as soon as a Logic Action occurs in a path leading to an Action, and other Query will define a new Selection, as we can see in the following example.</p><p><img border="0" src="image/ActionsSelBoundary2.png"/></p><p>These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behvavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinciton might not matter. For example, if we are using a Query 1 to test wether an agent's attribute a = x and attribute b = y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a = x, and <i>then</i> taking those agents and choosing those agents with b=y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.</p><p><img border="0" src="image/ActionsSelBoundaryComplex.png"/></p><p>In the first case, we execute a search for all agents that meet the two criteria. This means that if there are <i>any</i> neighboring cells whcih are available, we're guranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all.</p><h3 id="Root_Actions">Root Actions</h3><p>Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.</p><h4 id="Build">Build</h4><p>The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined wether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.</p><h4 id="Initialize">Initialize</h4><p>An Initialize action is excuted once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guranteed to execute before any other non-builder action occurs.</p><h4 id="Rule">Rule</h4><p>A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.</p><h4 id="Schedule">Schedule</h4><p>A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time = t.</p><h5 id="Start">Start</h5><p>The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..</p><h5 id="Interval">Interval</h5><p>How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..</p><h5 id="Priority">Priority</h5><p>Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.</p><h5 id="Pick">Pick</h5><p>Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be repalced by another approach.</p><h4 id="Watch">Watch</h4><p>A Watch action is executed anytime 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><h5 id="Attribute">Attribute</h5><p>The attribute that will be monitored for change.</p><h3 id="Selection">Selection</h3><p>A selection defines what we are searching for (Agent), where we are searching for it (Space), and from whose perspective we are doing it (Selection):</p><h5 id="Selection_2">Selection</h5><p>The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.</p><h5 id="Agent">Agent</h5><p>Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.</p><h5 id="Space">Space</h5><p>The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.</p><p>Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.</p><h5 id="For">For</h5><p>This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.</p><h3 id="Query">Query</h3><p>A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes, and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions. </p><h5 id="Function">Function</h5><p>A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age = Your Age", but they can also representSee the functions section for more information on specific functions.</p><h3 id="Logic">Logic</h3><h4 id="Intersection">Intersection</h4><p>An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. But it carries important differences too. For example, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together.</p><h4 id="Union">Union</h4><p>A union contains all agents that match any of its source actions. This essentially equivalent to a logical OR statement and shares similarities with the || operator in a java "if" statement.</p><h4 id="Difference">Difference</h4><p>A difference contains all agents that do not match any of its source actions. This essentailly equivalent to a logical NOT statement, and has similarities to (and important differences from) the Java else statement.</p><h2 id="Example">Example</h2><p>In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:</p><pre>"Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-</pre><p>Here, we create a sequence of actions like so:</p><ol><li>Select every agent for every period of the model. ("Find Partner" Rule)</li><li>For every member of that selection, search for other agents of the same age within vision distance. ("Partner" selection.)</li><li>From "Partners" find a random member and search for a neighboring locations. ("Partner Neighbor" selection.)</li><li>Finally, move the agent in "Find Partner" to the "Partner Neighbor" location.</li></ol><p>Now, notice that although it's convenient to speak as if there is only one "Find Partner" and one "Partner Neighbor" in step 4 above, in fact selections are flowing through for each of the results of each of the previous action sequences, and we can refer to each of the directly. We could represent these behaviors in many different ways. For example, we might want to specify the model in a (hand-drawn) graphical language or in a (made-up) textual language:</p><p><img border="0" src="image/ActionsExample.png"/></p><p>This is how it looks in an actual model:</p><p><img border="0" src="image/ActionsExampleNew.png"/></p><p>And here is how this works in detail:</p><ol><li>Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (Space isn't relevant in this case.</li><li>Create a child Select Action that will find our partner. Two important things to note here:<ol><li>The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.</li><li>We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.</li></ol></li><li>Create two child Query Actions:<ol><li>We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.</li><li>We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner. (Design discussion note: re-examine this issue WRT possibility of allowing users to search in multiple spaces within the same query.)</li></ol></li><li>Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.</li><li>Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.</li><li>As above, define some queries. This time we want only those agents that are:<ol><li>available, and</li><li>neighbors of our partner.</li></ol></li><li>And another intersection..</li><li>Finally, we move to the location we've found. All that's required at this point is to specify:<ol><li>The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and</li><li>The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.</li></ol></li></ol><h2 id="Reference_2">Reference</h2><h3 id="Diagrams_2">Diagrams</h3><p>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</p><h4 id="Meta-Classes_2">Meta-Classes</h4><p><img border="0" src="image/ActionsDiagram.png"/></p><h4 id="Details_2">Details</h4><p>In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.</p><ol><li>An Act is anything that might happen during the execution of an Agent-Based Model.</li><li>All Actions have as their root-most source action a Root. These are added first to any agent behavior and act as triggers for all target behavior. For example, a Watch will execute anytime the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that Accessor includes a reference to some Attribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)#Actions are targets and sources of one another, but an Act can never have itself as a source. (That is, Actions are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)</li><li>All Actions (except for root Actions) reference a Select, referred to as the "selected" relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) "world" that is currently being selected.</li><li>Commands trigger some model state change (Set) or spatial transformation (Transform).</li><li>Controls determine wether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.</li><li>Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).</li><li>Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.</li></ol><h1 id="Functions">Functions</h1><p>Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:</p><ol><li>Operators are simple calculations sharing the same type.</li><li>Generics that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s).</li></ol><p>And by usage:</p><ol><li>Functions proper can return any value and are used in Evaluate actions.</li><li>Logicals return some boolean result and are used by Query actions to decide wether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.</li></ol><p>A tehcnical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.</p><p>These overlap, so we have </p><h2 id="Reference_3">Reference</h2><h3 id="Diagrams_3">Diagrams</h3><p>The following diagram may be helpful to readers familiar with UML and Meta-modeling:</p><h4 id="Meta-Classes_3">Meta-Classes</h4><p><img border="0" src="image/FunctionsDiagram.png"/></p></body></html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.mediawiki b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.mediawiki
deleted file mode 100644
index 1a47a33..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/ModelersGuide.mediawiki
+++ /dev/null
@@ -1,892 +0,0 @@
-=Introduction=
-
-In this Modeler's Guide we provide an in-depth understanding of what goes into an Agent Model and how you can use the Agent Modeling Framework tools to design one. Fundamentally, an agent-based model, or "ABM", is composed of five pieces: Agents and Context Agents, Attributes, Spaces, and Actions. The first three refer to structural components, whereas Actions define behavior. Agent models also have styles, which are a special kind of Action used to determine how to portray an agent in a visualization. Finally Actions make use of Functions. We'll describe of these components in a separate section.
-
-But first, we'll give a quick overview at what agent-based modeling is is and how the Agent Modeling Framework can help you to develop models for ABM or other problem domains.
-
-==Agent-Based Modeling==
-
-The primary focus of the Agent Modeling Platform tools is "Agent-Based Modeling" (ABM). ABM is an innovative technique used to explore complex phenomenon in many domains, including economics, social sciences, biomedicine, ecology and business operations. ABMs share characteristics with object models, but are:
-
-;Spatial
-: Models have explicit environment(s) in which agents interact. (An environment need not be a physical landscape; other examples of spatial relationships include social networks or positions within a logic system.)
-;Temporal
-: Models change over discrete units of time.
-;Autonomous
-: Agent behaviors are activated independently from other object requests.
-;Heterogeneous
-: Agents may share behavior definitions but have apparent and distinct states and behaviors.
-;Collective
-: Models contain large communities of agents which exhibit collaborative and competitive behaviors.
-;Emergent
-: Agents have collective macro-behaviors that are non-obvious from agent micro-specifications.
-
-Existing scientific models are very good at representing relatively simple systems, but generally speaking aren't very good at representing complex systems. The world is full of complex systems, and our misunderstanding of these systems has prevented us from addressing many of the key challenges facing the world, including the global financial crisis and climate change -- in fact once could argue that our misunderstanding of these systems has strongly contributed to these crises.
-
-Agent-Based Models (ABMs) seek to represent important real-world dynamics by designing communities of software agents that mimic real entities. Rather than make simplifying assumptions about such systems and then representing them in equation form or as off the shelf algorithmic constructs, the ABM researcher aims to identify key agent state, interaction spaces, and behaviors. Agents are then "let loose" on our computers and we explore what happens next. The computational horsepower exists today to simulate large numbers (e.g. >>10) of interacting, adaptive and autonomous agents but often desktop computers are all we need to explore significant domains. ABMs have been designed to represent all kinds of important natural systems, at scales reaching from cellular mechanics to international trade and are being used to solve truly hard problems in government, business, and academia. ABMs are not a solution to every problem, but they can help us to appreciate and gain unique insight into many systems, and often they can help us to come up with better practical decisions than we might using classic approaches.
-
-==Agent Modeling Framework==
-
-The Eclipse Platform provides many unique features that make it ideal for an ABM platform. AMF provides easy to use and powerful tools and techniques for designing Agent-Based Models, including a common representation, editors, generators and development environment.
-
-The Agent Modeling Framework (AMF) provides high level representations for common ABM constructs, and introduces novel ways of representing agents and their behaviors. As detailed in other documentation sections, the Agent Modeling Framework and related tools have been designed to allow researchers to explore complex models in an intuitive way. One of our major design goals has been to create tools that non-programmers can use to create sophisticated models. It has been our experience that using Model-Driven Software Development (MDSD) techniques increase productivity for all developers regardless of skill level. For those familiar with Model-Driven Development tools, AMF is analogous to EMF but is targeted toward the design and execution of models composed of agents. The AMF meta-model (currently "MetaABM", but in the process of evolving to a new compatible "Acore" specification) is defined in Ecore but provides a more direct and high-level ABM representation of agents, including spatial, behavioral and functional features sufficient to generate complete executable models for the target platforms.
-
-Models designed in AMF are transparently converted to Java code for leading Agent-Based Modeling tools, such as the Escape tools which are included in AMP and allow direct execution of models within the AMP environment, and Repast Simphony, another popular Java based ABM tool. These tools create Java code that can then be compiled, executed and event modified in these environments just as with any other Java program. AMF's generative capability is designed to be pluggable and modular so that other developers can create AMF generators for their own tools. In fact, targets can be designed that have no inherent dependencies on Eclipse or even on a traditional platform.
-
-==Other Uses==
-
-Many kinds of objects share characteristics of ABM agents -- after all, software agents are used in many other contexts. The Agent Modeling Framework meta-modeling support is potentially suitable (or extendible) for a number of approaches outside of ABM; for example business rules, object interactions, systems dynamics models and traditional discrete event models. Similarly, AMP execution and graphic support can be used for modeling natural systems but could also be used to manage other software agents -- for example independent reasoning tasks or dynamic visualization support.
-
-We hope you enjoy using the tool, and we look forward to your comments and feedback and most of all participation!
-
-=Structure=
-
-==Design==
-
-The basic structure of an agent-based model can be quite simple. While there are many subtle complexities -- beyond the scope of this manual -- we can construct most models following some straightforward and elegant design principles. And in fact, one of the main goals of the Agent Modeling Framework is to provide a consistent framework that can support using those principles to support the creation of models that can be easily understood, shared, and that can be used interchangeably as components in other models.
-
-Unlike the approach of a traditional Object Oriented environment, the dominant organizing principal for agents within AMF follows a compositional hierarchical model, not an inheritance model. (Inheritance-like behavior will be supported in forthcoming versions of Acore, but in a more sophisticated, flexible and dynamic way than is supported by traditional programming languages such as Java.) Contexts -- also referred to as "Swarms" or "Scapes", are simply Agents that are capable of containing other agents. With this basic construct -- known as a Composition in design pattern language -- agents are able to contain other agents.
-
-==Details==
-
-===General===
-
-Everything represented in an Acore model needs to be referred to in some way. Just as software classes have names, Acore provides a way to label and describe every entity, but in a richer and more maintainable way. All entities in Acore -- including Actions and Functions which we describe in the next two sections -- have a number of shared values.
-
-====Named Entities====
-
-=====Label=====
-A reasonably short, human readable name for the agent. For example, "Timber Wolf", "Exchange Trader" or "Movement Probability". These should be defined so that they fit in well with auto-generated documentation.
-=====ID=====
-An ID is an identifier that can be used to represent the object in a software program. This means that it must follow certain rules such as no-spaces or non alpha-numeric characters. The editing tools will help make sure that this value is legal. Note that when you enter a label, a legal ID is automatically created for you! Usually you won't need to change this, but you might if for example you want the value to match up with some database or other external representation. So reasonable values here might be "timberWolf" or perhaps "MVMNT_PRB" if say you're trying to match up to some old statistics records you have. (Note that currently IDs by default use "camel case", i.e. "thisIsAnExampleOfCamelCase" to match with Java variable naming conventions, but this is likely to change.)
-
-And most entities also define:
-
-=====Description=====
-A complete textual description of the object. Don't overlook this -- it is the most important part of your model. The description will show up in your auto-generated html documentation, software documentation and even in your running model. You should include enough information that model users will understand what the entity is for and what it does without referring elsewhere. This is also where any attributions and references should go. You can put html tags in here -- such as href's to external papers, but keep those to a minimum as they won't be rendered as html in all contexts.
-=====Plural Label=====
-The plural representation of an entity. This can be a surprisingly useful thing to have in generated documentation and software code, so it's worth maintaining. The editor will automatically add an "s" at the end of the label you've entered above, but you change it to whatever is appropriate. For example "Person", or "Timber Wolves".
-
-===Agents===
-
-====Simple Agents====
-
-An Agent is simply a software object that has autonomous behavior and (generally speaking) exists within some set of spaces. By autonomous, we mean that agents make the choice about when and how to execute a behavior, as opposed to have that controlled from "above", so to speak. Like any software objects, agents have attributes (fields) and actions (methods) associated with them.
-
-=====Attributes=====
-
-As described in the attribute sections above.
-
-=====Actions======
-
-Described in the "Actions" section.
-
-=====Styles=====
-
-Special actions that are used to define how to draw an agent graphically as also described in the "Actions" section and detailed in the "Functions" section.
-
-====Context Agents (Contexts)====
-
-As detailed above, agents also form the basic structural component of an agent-based model. To get an idea for how this works, have a look at the "EpidemicRegional.metaabm" model. Note that in future releases, we will probably refer to Contexts as "Scapes".
-
-=====Agents=====
-
-The agents that are contained within this context. For example, a context representing a city might contain an Individual Agent for defining all individuals in the model, and a Vehicle agent defining all vehicles. Note that when we refer to an agent in this context, we mean a general type or class of agent, not the agent itself.
-
-=====Spaces=====
-
-The set of all spaces contained or subsumed by the agent. For example, a context representing a city might contain a geographical space and a transportation network space.
-
-===Attributes===
-
-Agents need some way to represent their internal state. For example, an agent in an economic model might have a wealth attribute, and an agent in an ecology model might have a quantity of food and a particular vision range. These states are represented as attributes just as all software objects do. In an agent model, we keep richer information about these attributes and generally represent them at a higher level. For example, rather than specify that a real value is a "double", a "float" or a "big number", we represent them as "Reals" so that they can be implemented and tested in different environments. This might allow us for instance to ensure that a model's behavior is not dependent on a particular machine implementation of floating point arithmetic. Also, note that attributes only represent so-called "primitive" values -- that is, actual measurable features of a particular agent but not an agent's relationship to other agents or objects. See the discussion about networks for more on this key topic.
-
-Here are the basic types of attributes available in Acore models:
-
-====Basic Attributes====
-
-Attributes are single values that a given agent contains. For example, an agent might have an "Age" attribute. In this section we go over the values you can set for the attributes. For those with a tecnical bent, note that we are technically describing the meta-attributes for the meta-class "SAttribute". But it is far too confusing to refer to the attributes of attributes! So we'll just refer to the attributes that any of our model components as "values".
-
-=====Type=====
-
-These can be anyone of the following:
-
-{| cellpadding="10" cellspacing="0" border="1"
-|Boolean
-|A value that is simply true or false. Note that unless this value really is a simple binary value, you should consider using state instead. (See details below.) For example, rather than representing gender as a 'Female' boolean value, define a 'Gender' state with values 'Male' and "Female'. Generated artifacts and documentation will be much clearer, and you'll be able to easily modify the model later if for example you discover that there are more than two potential gender categories that are relevant to your model.
-|-
-|Integer
-|A discrete whole number value, such as "100", "-1", "10029920". It's generally a good idea to represent any value that can never have a decimal value as an integer.
-|-
-|Real
-|A continuous number value. While these are typically represented in software as floating point numbers, they can conceivably represent numbers at any arbitrary precision and in any scheme. Note that while technically speaking we should be representing irrational numbers, this is not currently supported for default values and users should simply use the closest decimal approximation.
-|-
-|Symbol
-|A string representing some state. More precisely, a computationally arbitrary value with contextual meaning. This could be any kind of identifier. For example, you might use it to store some kind of input coding from data that is then converted into an object state. Or it could simply be an agent's name. But theoretically (though this is not currently supported) one could imagine a symbol using an idiogram, an icon or even a sound that identifies or represents the agent in question.
-|}
-
-(Undefined and Numeric types should not be used within a well-defined model.)
-
-
-=====Default Value=====
-
-The value that should be assigned to the attribute at the beginning of any model run. The attribute may of course be assigned a different value in an Initialize rule, but its a good idea to specify one here. It's OK to leave it blank, in which case a sensible 'empty' value will be assigned, i.e. false for Boolean, 0 for Integers and Reals, and an empty string for Symbol.
-
-=====Gather Data=====
-
-Here you can specify whether executing models should collect aggregate values for the data. For example, if you select this value as true for a 'Wealth' attribute, Escape will automatically keep track of minimum, maximum, average, sum and optionally standard deviation and variance across all agents for each model execution period. All of these statistics will then be selectable with a mouse click to appear in your model charts at runtime.
-
-=====Immutable=====
-
-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.
-
-=====Units=====
-
-Specifies what the attribute is actually measuring. For example, if you're defining an attribute for "Wealth" in the context of a model of the world economy, you might specify "USD". If you're defining "Age", you might specify "Years", for "Mass" "Kg". Like description, this value is often overlooked, but can be critically important to allowing yourself and others to understand and correctly calibrate a model. Note that this will also allow you to simplify variable names -- instead of using "Age in Years", you can simply specify "Age" and the appropriate unit. It may be obvious to you that your model is concerned with age in years, but a user who needs to specify a different granularity will be grateful for more clarity.
-
-
-====Arrays====
-
-Arrays are simply attributes with zero or more entries. For example, you might have an array of three Real numbers representing the Red Green and Blue color components for an object. Note that if you find yourself defining very complex sets of arrays, its likely that what you really want to define is a new agent with attributes for each array. In addition to what is defined above, arrays specify:
-
-=====Size=====
-
-The number of values that the array attribute will contain.
-
-====States====
-
-States represent any agent quality that may take on one of a number of well defined values. For example, an "Ice Cream Consumer" Agent might contain a state of "Ice Cream Preference" with options of "Chocolate", "Vanilla" and "Ginger".
-
-=====State Options=====
-
-Create new options for states by adding them to the state node. States are simple described items. Don't forget to provide a description! States also have
-
-=====Default Option=====
-
-unlike for regular attributes, this option is not optional! Simply pick a state option to be assigned that the agent will take if no other option has been assigned.
-
-
-===Spaces===
-
-All contexts can contain spaces. Spaces provide an environment in which agents can have a physical or notional location and upon which they can interact with one another and their environment. Agents can exist in more than one space at a time, and a given agent need not exist in every space. (Note that this is different from the Repast Simphony notion of projections, though the two representational approaches are generally compatible.) Agents need not represent explicit, "real" spatial structures such as a landscape, though this is of course the most common use. They can also represent relational and state information, such as a belief space or a social network. There are four kinds of space represented:
-
-====Space (Continuous)====
-
-In the modeling tools, we simply refer to this as a "Space" as it is represents the general concept of a space. A space is simply something that contains objects with certain locations and extents and has a certain number of dimensions. The space is continuous, in the sense that objects can be placed anywhere with arbitrary position. Spaces hold attributes, which simply define their dimensions-- see below.
-
-=====Border Rule=====
-
-A value representing what happens to an agent when that agent is asked to move beyond its extent.
-
-{| cellpadding="10" cellspacing="0" border="1"
-|Periodic
-|When encountering an edge, the agent will treat the space as wrapping around to the other side of the space. For example, if the agent at location [1,2] (0-based) within a Moore space (see grid discussion below) of size [10,10] is asked to find some other agent within distance 3, the agent look in the square defined between [8,9] and [4,5]. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge. You can imagine this as taking a piece of graph paper and connecting the opposite edges. You can't actually do that with paper, but if you could you would have a toroidal (donut) shape in three dimensions defining the shape in two.
-|-
-|APeriodic
-|When encountering an edge, the agent treats it as the edge of the space. For example, if the agent at location [1,2] is asked to find some other agent within distance 3, the agent look between [0,0] and [4,5]. An agent asked to move beyond the confines of the space will simply stop when it reaches the edge.
-|}
-
-The "Strict" and "Bouncy" values are obsolete and should not be used.
-
- =====Dimensionality=====
-
-The number of dimensions that the space has. After selecting a dimensionality, attributes will be added to represent each dimension. For example, if you enter 3 here, you will have an attribute for X, Y, and Z. Be sure to enter default values here, as they will be used to specify the actual size of the space.
-
-====Grid====
-
-A grid is technically a regular lattice structure. Currently, only rectilinear structures are supported, i.e. a One-dimensional vector, a two-dimensional grid, a three-dimensional cube and so on. (Though none of the current target platforms support n-d spaces yet.)
-
-Like continuous spaces, a grid has a border rule and dimensionality. A grid has a couple of other important values:
-
-=====Multi-Occupant=====
-
-Does the grid allow more than one agent to occupy it at a time? This value may be replaced with another mechanism in future releases.
-
-=====Neighborhood=====
-
-This value determines what constitutes a region within a particular distance from the agent. The value for this is often critical in obtaining particular behavior from a model, and shouldn't be overlooked. There are three possible values:
-
-{| cellpadding="10" cellspacing="0" border="1"
-|Euclidian
-|The distance between any two cells is taken to be the "real" distance. For example, if an agent was within a chess board, and we wanted to find all agents within distance three of it, we could determine that by taking a string of length 3, tacking it to the center of the source square, and including all cells whose centers we can reach with the other string end. Note that although Euclidean space may seem the most reasonable neighborhood configuration to choose, this really isn't the case. Euclidean space is continuous whereas grid space is discrete, and mapping the two to each other can create unexpected issues. Still, this is a good choice for models representing notional real spaces.
-|-
-|Moore
-|Here, the distance between any two cells is defined by the number of edge <i>or</i> corner adjacent cells crossed to get between them. To continue the chess board analogy, this is the set of moves that a king can make. Note that this does not map well to real space at all, as a cell at distance 1 in a moore space is at distance sqrt(2) in "real" space.
-|-
-|Von-Neumann
-|Here, the distance between any two cells is defined by the number of edge adjacent cells crossed to get between them. This is the set of moves that a rook might make on a chess board -- if a rook could only move one square at a time. It is also often referred to as a Manhattan distance for the self-evident reason.
-|}
-
-====Network====
-
-A network represents a set of relationships between agents, in a graph structure. The concept is pretty simple, but note that a network is actually a critical part of many AMF models. This is because we use networks to represent any kind of references between agents. You may have noticed in the discussion about attributes that there is no generic "object" type for an attribute. In fact, attributes only contain primitive values. So we will use networks to do the kinds of things that we would often use object references for in a traditional Object-Oriented model. For example, if an agent is a member of a family, rather than have that agent have a member attribute of "family" with a reference to the "Family" object, the modeler would create a "Family Members" network and connect agent's to their families as appropriate. This implies that network members can contain members of many different types.
-
-A network has only one value to specify:
-
-=====Directed=====
-
-This indicates whether connections between agents are one-way or two-way. If this value is false, then if a connection is made between an agent A and an agent B, and agent B searches within distance 1, agent B will find agent A. If this value is true, agent A can find agent B, but agent B can not find agent A. (Unless of course some other path leads B to A.)
-
-====Geography====
-
-A geography represents a physical landscape. Here we assume that that landscape is going to be defined by an external data source and representational scheme -- typically a Geographical Information System. We'll describe how to work with GIS in more detail when we discuss builder actions.
-
-==Reference==
-
-===Diagrams===
-
-For readers familiar with UML and meta-modeling, the following diagrams give more detail on the structural design.
-
-====Meta-Classes====
-
-Our first diagram depicts the core structural design of the model.
-
-[[Image:images/StructureComplexDiagram.png|800px]]
-
- There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the next diagram.
-
-====Key Collaborations====
-
-[[Image:images/StructureSimpleDiagram.png]]
-
- Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-
-====Details====
-
-#Every model has at its root a Context (Scape). Contexts are Agents that are capable of containing other Agents (including other contexts, naturally).
-#(Meta-level) Contexts contain (meta-level) Agents at the model (design-time) level. At runtime, (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we create a new Context, and give it a label of "Wiki Example". Within that Context, we create an Agent and give it a label of "Individual" and another Agent with the label "Block". At runtime when we are actually executing the model we will have one WikiExample model instance which contains a number of Individuals.
-#Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and Maximum Age.
-#Contexts can contain Projections (Spaces), which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidean) space, or a network (graph) or geographic space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move around within.
-#Agents are Actable and thus can contain any number of behaviors called "Actions", described in detail in the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member Agents and Projections are created.
-#Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actable. For example, an Agent might have an Action that says effectively "draw a red circle shaded red for the wealth of the agent".
-
-
-=Actions=
-
-Actions are the most important part of an agent model. While Agents, Attributes and Spaces define what we're modeling, it is Actions that give the models life.
-
-==Background==
-
-Actions allow the definition of behavior for agents at a very high level. You can think of actions as being analogous to methods in a traditional object-oriented model but that analogy only goes so far. In the same way that methods are defined as part of objects, actions belong to particular agents. (Though even more expressive ways of defining actions are contemplated in future releases.) In the next section we go into detail about what Actions are and how they can be used to define all agent behavior. They are also conceptually more challenging as unlike with structure they have no direct analogies to past agent representations.
-
-An action provides simple, well-defined details that a model can use to determine what steps to take in model execution. That definition seems general enough to be almost useless, but its important to understand that an action is not equivalent to an instruction, a method or a query. In fact, actions can have aspects of all of these. But an action is not in itself an instruction specifying exactly ''how'' the modeling engine should do something -- instead an action represents ''what'' the modeler intends for the agents to do. (Technically, we might say that Actions takes a "declarative" approach instead of an 'imperative' approach, but that's not quite true, because actions do allow us to define behavior in a richer way than most declarative approaches, and many action constructs map directly to imperative approaches.)
-
-Actions are connected together in a series of sources and targets. (Technically, an acyclic directed graph.) In an abstract sense that is similar to the way any programming language is defined although that structure isn't usually obvious because of the constraints of textual representations. But unlike a typical programming language, in Actions it is not the execution thread (the processor) that moves from one instruction to the next, but the result of the previous action. In this way, action results "flow" from the output of one action into the next action.
-
-Why are these distinctions between traditional Object-Oriented and the Action approaches important? They give us the advantages of simplicity, clarity and flexibility that [[http://en.wikipedia.org/wiki/Dataflow_programming|data-flow approaches]] like spreadsheets and some query languages have, but with less restrictions. At the same time, they can bring us much of the power and expressiveness of [[http://en.wikipedia.org/wiki/Functional_programming|functional languages]] like Lisp or [[http://en.wikipedia.org/wiki/Logical_programming|logical languages]] like Prolog, but without the level of complexity and obscurity that such languages can have.
-
-We can get a better idea for how Actions work by thinking about how a spreadsheet works. In a spreadsheet, we might define a cell A that adds up a row of data, say "Income". We might define another cell C ("Profit") that takes A and adds it to another cell B that adds up another row of data ("Expenses"). Now, if we change a value in any of the rows, all of the other rows are added up and we get the results in A and B updated automatically. We never had to write code that said something like "for each cell in row X, where...". In fact, we don't really care ''how'' our Spreadsheet program adds up the numbers -- it could have added them all up at once but in backward order, or stored a running total somewhere and updated just the difference in value for the cell we changed -- what we care about is ''what'' the result is, and whether it is correct.
-
-But Actions are much more powerful than a spreadsheet, because what is flowing from Action A to Action B is not just a number, but any model component such as a space or a set of agents that we need to use in target actions.
-
-
-==Design==
-
-In this section, we'll describe how modelers can assemble actions into sets of behavior that accomplish complex tasks on interrelated agents and spaces over time.
-
-===Kinds of Actions===
-
-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. All of these are discussed in detail in the section that follows this one.
-
-These are all summarized in the diagram below:
-
-[[Image:images/ActionsBlocks.png]]
-
-===Flow===
-
-First, let's look at how actions define the basic path that agents take during a model run. As with any programming language, the path we take through the program specification is what determines our state when we get there. In a pure object oriented program, the path just defines the control flow -- what we are doing. The actual state of our model is defined within the object itself. If we call a method B from another method A, we'll be relying on method A to set the values that we need into the object state itself. In a purely functional program the path defines how we are going to deal with whatever has been explicitly passed in to a function that has been called, that is the function parameters. In fact, most languages such as Java combine aspects of both approaches.
-
-In Actions, the path itself implicitly carries all of the context of prior execution with it. This means that we don't have to worry about storing context in the object -- as we would in an object-oriented language -- or passing the correct values from one method call to the next as we would in a functional language. Instead, Actions can use the implicit context of the path of flow to determine what the current state of execution is.
-
-Again, behaviors in Actions are always defined by a set of ''selections'' and ''queries''. In the following diagram, we can see the pattern.
-
-[[Image:images/ActionsSequence.png]]
-
-First, we define a Root Selection for a Rule, Schedule or other triggering event. Then, we might add a series of Query and Logic Actions to define the specific agents that we are interested in. These are all part of the Selection. Next, we might define a series of Commands to determine what to do with those agents. Or, we could use the result of that selection to immediately define another selection, for example if we are searching for an agent that is near another agent. The next diagram depicts a simple example.
-
-[[Image:images/ActionsSimpleSequence.png]]
-
-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. In the 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.
-
-[[Image:images/ActionsSimpleSequence2.png]]
-
-In the following example, we've defined a set of actions and their relationships. We have a selection, a few queries and a couple of logic operators leading to a Set Action. We'll describe in detail below how Logic Actions are used in conjunction with other actions to assemble any kind of query structure needed. But for now, we'll focus on the control flow itself.
-
-[[Image:images/ActionsFlowSimple.png]]
-
-As you have probably already guessed, the agents that have the Set Action applied to them could take one of two paths through the Action flow. Readers with experience with programming or formal logic will note that this looks just like a parse tree, and while that's basically what it is, there are important differences. For example, if we looked at the following structure as a definition of control flow for a single agent we'd take them to be equivalent. Both would evaluate the statement (Query 1 AND Query 2) OR Query 3 for each agent.
-
-[[Image:images/ActionsFlowUnion.png]]
-
-Within Actions in many cases these two approaches will also act equivalently. If we are simply setting a value, it doesn't matter how an agent gets to that Set Action, as long as it gets there. All sources that flow into a given target Action act like a logical union since any of the paths might reach that target. But note that we have two flows moving in parallel in the flow on the right. What happens when the conditions for ''both'' branches are true? As the set of agents flow through each branch the Set Action on the left will be evaluated once, while the one on the right will be evaluated twice. Again, this often ends up with the same behavior, but not always. If for example, the evaluate Action uses the value of the attribute that we are setting as input, we can get different results. Of course, you can write code in any language that accomplishes the same thing, but the code will look quite different. For example, if we wrote the same basic logic in Java, in the first case we'd have something like:
-
- if ((query1.evaluate() && query2.evaluate()) || query3.evaluate()) {
- doSomething();
- }
-
-In the second we'd have:
-
- if (query1.evaluate() && query2.evaluate()) {
- doSomething();
- }
- if (query3.evaluate()) {
- doSomething();
- }
-
-This is a simple example, but with multiple branches such code design issues can quickly grow complex. The flow approach allows us to express things in a way that is often more natural and expressive. The important thing to keep in mind when desiging action flows is to see the flow as representing a selection of agents moving through streams independently. In the Actions example we expressed both approaches in nearly the same way, except in the case on the left we used a Union Action to bring the two branches of flow back together.
-
-===Selections===
-
-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.
-
-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.
-
-[[Image:images/ActionsSelBoundarySimple.png]]
-
-Each time we create a new selection, we define a new set of boundaries.
-
-[[Image:images/ActionsSelBoundary2Parts.png]]
-
-A very important aspect of boundaries is that they apply to a group of actions that begin with a Query Action, and not just such a group that begins with a Select Action. This is because Query Actions can be directly part of a selection definition, but they can also refine selections, as we'll see. So where does one selection boundary end and the next one begin? The simple rule is that the end of the boundary is defined for a given Action by the place where:
-
-#A Query Action is not followed by a Logic Action, or
-#A Logic Action is not followed by another Logic Action
-
-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 we can see in the following example.
-
-[[Image:images/ActionsSelBoundary11A.png]]
-
-Note that we refer to "Selection 1" and Selection 1A". This is because Selection 1A is a refinement of Selection 1 along its particular path of flow. When a query appears for the same selection but past a particular boundary, you can think of it as a sort of filter on the selection contents. We don't have a "Selection 2" here because any Actions that refer to "Selection 1" along the current path of flow will be acting on the selection defined by Selection 1 and Selection 1A.
-
-These rules allow actions to be defined in the simplest possible way, but it is important to understand their implication as they result in behavior that can be different from what someone used to and imperative programming environment such as Java might expect. In a simple case the distinction might not matter. For example, if we are using a Query 1 to test whether an agent's attribute a = x and attribute b = y, we would get the same outcome if we placed intersected the queries as if we simply put them in sequence. Internally we would actually be searching for agents with a = x, and ''then'' taking those agents and choosing those agents with b=y, but the outcome would be the same. But consider a more sophisticated case, where we are searching for neighboring available cells.
-
-[[Image:images/ActionsSelBoundaryComplex.png]]
-
-In the first case, we execute a search for all agents that meet the two criteria. This means that if there are ''any'' neighboring cells which are available, we're guaranteed to find one (random) cell. In the second case, we first search for all cells that are neighbors. This will match any agents that include both available and non available agents. Now, at this point since our search returns one agent (in the current AMF design -- richer behavior will be supported in the future) the randomly selected agent could be either available or not. So in the second case, we might end up with no cell to move to, and thus make no move at all. This then becomes an important aspect of model design. For example, if one were defining a model where neighbors played a game with each other, one might want to instruct agents to play the game only with neighbors that have a certain wealth threshold. In the real-world situation that we are modeling, we might simply search for neighbors who are over a given wealth threshold and then play the game with them. This would imply that information about other agent's wealth is open knowledge. Or, we might simply select a random neighbor, and ask that neighbor to play a game with us. Upon discovering that our neighbor does not meet our wealth criteria, we would then choose not to play with them. Here we are modeling a cost in time to obtain information about another agent's wealth, because we might miss an opportunity to play the game with another agent on that round.
-
-===Weaving===
-
-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.
-
-[[Image:images/ActionsWeavingSetAnother.png]]
-
-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.)
-
-[[Image:images/ActionsWeavingEvaluate.png]]
-
-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.
-
-[[Image:images/ActionsWeaving1A.png]]
-
-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. Now, consider the following example:
-
-[[Image:images/ActionsWeaving2.png]]
-
-Before going into further details we need to introduce one more important concept. 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.
-
-==Details==
-
-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.
-Let's look at the overall view again amd then dig into the details.
-
-[[Image:images/ActionsBlocks.png]]
-
-
-===Selections===
-
-A selection defines a particular set of agents that we want to do something with. Selections are made up of the Select action itself, along with Query and Logic actions. When we refer to a selection in any target command, we are referring to the selection in the context of where we have defined the behavior.
-
-====Select====
-
-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):
-
-=====Selection=====
-
-The selection that we are searching "from". This seems to be the concept that new users have the most difficulty with, but it is key to understanding how Actions works. Just as with any other Action -- a Move command for example -- a selection needs to know what set of agents that it is working with. For example, if we want to define a selection B that finds the cells neighboring a rule B's agent, we would set selection B's selection to A.
-
-=====Agent=====
-
-Here we define what agent we will be looking for. In order for this to make sense, the agent has to be related in some meaningful way to the agent whose behavior we are defining. For example, it might be a partner agent or a location that we might want to move to. An agent must be specified unless we are searching within a continuous space, in which case this value should be empty, and the result of the selection will represent some location in that space. In the current version of the framework, we treat destination cell locations as agents, and require that location to be specified as a target agent, but in a future version we'll allow searches without defining an agent within grid spaces as well.
-
-=====Space=====
-
-The space that we want to search within. Of course, this must be specified if we use any spatial query terms (see below), but if we simply want to search across all agents it should not be specified.
-
-Represent Queries (Controls) on agents and Transformations, or Commands, on the result of those queries. Queries, Transformations and other in which each child target carries the execution and data context for it's particular path.
-
-=====For=====
-
-This value is obsolete and will be replaced with a different mechanism in the next version of the modeling environment.
-
-====Query====
-
-A Query represents a concrete criteria for our search. The name is a bit confusing because of potential for confusion with a generic query. Queries -- along with their cousin Evaluators -- define a function that is evaluated and that can take Agent attributes and the results of other Actions as input. Queries are combined with each other and with the logic actions to determine the results of a selection for their direct target actions.
-
-=====Function=====
-
-A query function is evaluated to determine the results of a particular selection. Functions can represent very simple search criteria such as "My Age = Your Age", but they can also represent complex and inter-related concepts such as spatial relationships. See the functions section for more information on specific functions.
-
-====Logic====
-
-These Actions provide us with the ability to combine queries with one another, and follow the basic rules of set logic. But as we've seen above, it is important to understand that there are important differences between Logic Actions and typical programming logic. Most importantly, they apply not to individual agents per se, but to the set of agents that move through them. Also, there is not neccesarily short circuit execution (it's not needed) and much richer criteria can be joined together because of the action flow design.
-
-====Intersection====
-
-An intersection contains only those agents that match all of its source actions. This is essentially equivalent to a logical AND statement and has similarities to an && operator in a java "if" statement. An agent must be able to flow through all incoming actions in order to flow out of an Intersection Action.
-
-====Union====
-
-A union contains all agents that match any of its source actions. This shares similiarities to a logical OR statement and the || operator in a java "if" statement. It does mroe than that however, as it acts to join multiple flows of action. That is, as set logic implies, an agent will never appear in the result of a union more than once.
-
-====Difference====
-
-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.
-
-====Roots====
-
-Root actions are a special case of a selection. These represent behaviors that are defined for all members of agents; these are the highest granularity of an agent's behavior, such as "Find Partners" or "Eat" or "Reproduce". When you want to create a new set of Actions, you have the following choices.
-
-====Build====
-
-The Build Action is a specialized action that allow the construction of member agents and spaces within a parent context. A Build Action executes once for each context before any initialization actions occur for any children agents of that context. Currently it is undefined whether a context's own Initialize Action is executed before the Build Action occurs, so implementors should not rely on any initialized values being available at build time.
-
-====Initialize====
-
-An Initialize action is executed once and only once for every agent when the model is first started -- at time 0. Initialize Actions are guaranteed to execute before any other non-builder action occurs.
-
-====Rule====
-
-A Rule executes once for every agent for every iteration of the model. An important note is that the actual sequence of rules is technically undefined. An implementor should not rely on the fact that a rule occurs before another rule in the list of agent actions though typically the order in which the rules were actually created is respected.
-
-====Schedule====
-
-A schedule is executed on a recurring basis, according to the values detailed below. Note that schedules are often overused. In most agent-based models it makes sense to have any behaviors occur at the same granularity using a Rule. Please note that Schedules are not currently supported in the Escap target, but that support should be available soon. In the following descriptions we refer to period as the current iteration of the model, that is where time = t.
-
-=====Start=====
-
-The period that the schedule will first be invoked. For example, if this value is 100, and interval is 1, the schedue will be executed at times 100,101,102..
-
-=====Interval=====
-
-How often the schedule is invoked. For example, if this value is 3 and start is 1, the schedule will be executed at times 1,4,7..
-
-=====Priority=====
-
-Where the rule will be placed in the execution queue for a given time period. For example, if Schedule A's priority is set to 3 and Schedule B's is set to 2, Schedule B will be executed for all agents before Schedule B is executed for any agents.
-
-=====Pick=====
-
-Controls how many agents to execute the schedule against. While this value will have an effect on the Repast target, it is not recommended to be used for general models and is likely to be replaced by another approach.
-
-====Watch====
-
-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.
-
-=====Attribute=====
-
-The attribute that will be monitored for change.
-
-===Commands===
-
-====Evaluate====
-
-Evaluate Actions define some calculation on a function based on the model state and a set of input(s). The inputs that an Evaluate Action can take is determined by its functions and can be either agent attributes, prior evaluations or literals. The result is then determined based on those inputs. In some cases Evaluate functions can be used to determine some action indirectly, such as with a graphics fill, but they can never be used to directly change model state.
-
-=====Selection=====
-
-As with all other actions, evaluations specify a selection, and just as with the other actions, this determines the set of agents that the evaluation occurs for, but the input selections determine what agent is used for the calculation itself.
-
-=====Function=====
-
-A with queries, a function is evaluated against its input set. Functions can represent simple operators as well as complex functions. See the functions section for more information on specific functions.
-
-=====Inputs=====
-
-The set of values that will be used to determine the result, in the order of the function prototype. Inputs can specify any source evaluation and any agent state or agent parent context state. The selection determines which agent's will be used to determine the value, and different inputs can specify different selections.
-
-====Move====
-
-The Move Action causes an agent to change its location in some space or network. The agent will leave whatever location it was in before within the selection space, and move to its new destination.
-
-=====Selection=====
-
-As with any
-
-====Set====
-
-The Set Action assigns some value to another value.
-
-==Example==
-
-In this section, we'll look at an example that should make clear how the basic Actions approach works in a model. Say we want to define a behavior like:
-
- "Search for a random agent within my vision that is the same age as I am. Find a location next to that agent that is not already occupied and move to it."
-
-Here, we create a sequence of actions like so:
-
-#Select every agent for every period of the model. ("Find Partner" Rule)
-#For every member of that selection, search for other agents of the same age within vision distance. ("Partner" selection.)
-#From "Partners" find a random member and search for a neighboring locations. ("Partner Neighbor" selection.)
-#Finally, move the agent in "Find Partner" to the "Partner Neighbor" location.
-
-Now, notice that although it's convenient to speak as if there is only one "Find Partner" and one "Partner Neighbor" in step 4 above, in fact selections are flowing through for each of the results of each of the previous action sequences, and we can refer to each of the directly. We could represent these behaviors in many different ways. For example, we might want to specify the model in a (hand-drawn) graphical language or in a (made-up) textual language:
-
-[[Image:images/ActionsExample.png|800px]]
-
-This is how it looks in an actual model:
-
-[[Image:images/ActionsExampleNew.png|800px]]
-
-And here is how this works in detail:
-
-#Create a Rule that will trigger the behavior. In this case, we want this rule to apply to all "Individual" agents within the model. (Space isn't relevant in this case.
-#Create a child Select Action that will find our partner. Two important things to note here:
-##The selection occurs based on the "Find Partner" selection. This means that for each Individual in the model, we'll be searching from the point of view of that agent to some other selection of agents.
-##We also need to define what type of agent we want and in this case the space does matter. We want to find an agent that is nearby within the City space. If instead we wanted to find a partner in a social network, we'd specify that instead.
-#Create two child Query Actions:
-##We want to search for someone who is the same age as us. This highlights the importance of the idea of the Selection in the Actions design. We're qualifying Age by our <font color="green">Partner</font> and <font color="red">ourselves</font>. The selection carries throughout the flow of execution and this context is an explicit part of the entire structure. Note that this is very different from the way control flow works in a traditional imperative language such as Java.
-##We also want to search using a function for nearness, "within", which takes a parameter of vision. Note that the spatial functions are all polymorphic -- if we decided later on that we would rather search within say "Kevin Bacon space", that is a graph structure representation of space, we would only need to change the space we've defined in Select Partner.
-#Intersect the results of these two query components. This delineates the end of the selection definition for any target Actions.
-#Select a neighbor. Again, we can see the importance of Selections. Here, we are selecting from the point of view of the partner, not the initial agent that the current Rule is being executed for. Note that this time our target agent is a "Block", that is, a location within the city.
-#As above, define some queries. This time we want only those agents that are:
-##available, and
-##neighbors of our partner.
-#And another intersection..
-#Finally, we move to the location we've found. All that's required at this point is to specify:
-##The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and
-##The destination, which is the cell that we've found. Note that the framework infers from the space definition that the Block agent is capable of hosting the Individual.
-
-==Reference==
-
-===Diagrams===
-
-The following diagram may be helpful to readers familiar with UML and Meta-modeling:
-
-====Meta-Classes====
-
-[[Image:images/ActionsDiagram.png|800px]]
-
-====Details====
-
-In the diagram above, all meta-objects except for Input, Literal, and the enumerators (lists of options) are Actions. Blue meta-classes are concrete (you can create and use them directly). Red meta-classes are key collaborations.
-#An Act is anything that might happen during the execution of an Agent-Based Model.
-#All Actions have as their root-most source action a Root. These are added first to any agent behavior and act as triggers for all target behavior. For example, a Watch will execute any time the watched attribute is modified. (As the diagrams do not refer to elements outside of the current package, we cannot see here that Accessor includes a reference to some Attribute, but it does. To see these kinds of relationships you will want to refer to the metaabm.ecore file itself.)#Actions are targets and sources of one another, but an Act can never have itself as a source. (That is, Actions are acyclic, but branches can re-converge. When we refer to an Act source or target, we typically mean to include all ancestors or descendants, not just the immediately connected Act.)
-#All Actions (except for root Actions) reference a Select, referred to as the "selected" relation. An ASelect represents the model aspects that the Act is working within; that is, the spatial, temporal and type (agent) "world" that is currently being selected.
-#Commands trigger some model state change (Set) or spatial transformation (Transform).
-#Controls determine whether target Actions are executed and against what agents. They are in some sense query terms and include Query actions and Logic Actions.
-#Transforms also specify a "destination" Select. This represents aspects that the selected agent(s) will transform to. For example, a Move may use a Rule to select all SugarAgents (type) in the SugarGrid (space) every period (time) and move them to a destination of a neighboring SugarCell (type) in the SugarGrid (space, with time implicit).
-#Sinks are Actions which use some Function (see next section) to interpret state in the form of Inputs. Inputs can come from selected agent attributes, other Actions, or literal values.
-
-
-=Functions=
-
-Functions are relatively simple in terms of model design, but we need to understand how particular functions work in order to develop models. Functions are divided in two ways. By type:
-
-#Operators are simple calculations sharing the same type.
-#Functions that can represent any general function that takes some well-defined input(s) and returns some well-defined output(s).
-
-And by usage:
-
-#Generics can return any value and are used in Evaluate actions.
-#Logicals return some boolean result and are used by Query actions to decide whether target Actions apply to a particular selection, and by Evaluate actions just as with any other functions. Input types should be defined as generally as possible.
-
-These overlap, so we have operators, logical operators, functions and logical functions.
-
-Functions are also divided into categories, as we'll see.
-
-A technical note: conceptually, functions can return multi-values, but that is not currently implemented in the reference targets because of limitations of the target language Java.
-
-
-==Reference==
-
-===Function Library===
-====Operators====
-====Logical Operators====
-=====Not=====
-The result of the expression !X.
-=====Equal=====
-The result of the expression X==Y.
-=====Identical=====
-The result of the expression X==Y.
-=====Greater=====
-The result of the expression X>Y.
-=====Lesser=====
-The result of the expression X<Y.
-=====Greater or Equal=====
-The result of the expression X>=Y.
-=====Lesser or Equal=====
-The result of the expression X<=Y.
-=====True=====
-The result of the expression true.
-=====False=====
-The result of the expression false.
-=====Identity=====
-The result of the expression X.
-=====Different=====
-The result of the expression X!=Y.
-====Numeric Operators====
-=====Negative Value=====
-The result of the expression -X.
-=====Add=====
-The result of the expression X+Y.
-=====Subtract=====
-The result of the expression X-Y.
-=====Multiply=====
-The result of the expression X*Y.
-=====Divide=====
-The result of the expression X/Y.
-=====Power=====
-The result of the expression X^Y.
-=====Modulo=====
-The result of the expression X%Y.
-=====Increment=====
-The result of the expression ++X.
-=====Decrement=====
-The result of the expression --X.
-=====Unit Value=====
-The result of the expression 1.
-=====Zero Value=====
-The result of the expression 0.
-=====Original Value=====
-The result of the expression o.
-====Spatial====
-=====Nearest =====
-Represents the nearest agents (including gird cells) or locations to this agent. If more than one agent or location is the same distance away they will all be considered. Note that while this function is defined for the selection of an agent, the result of this function is defined by the context within which it is used. If the selection specifies another agent within a space, this function will represent the nearest agent in that space. If the selection specifies a Cell within a grid space, this function will represent that cell.
-=====Toward=====
-Represents a location that is on the shortest path to a particular agent or location from the source agent (that is, the selection's selection's agent). This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction towards some objective.
-=====Within=====
-Represents a limit to the distance of a spatial search. When used in combination with other spatial functions such as "nearest" requires that all agents or locations must be within the distance specified by the input value.
- Inputs:
- [Numeral]
-=====Neighbor=====
-Represents any agents that are nearest neighbors to the agent, that is nominally of distance 1. This function is only relevant in discrete spaces -- grids and networks -- where there are immediate neighboring cells as defined by the geometry of the selection's space.
-=====Include Self=====
-Specifies whether the agent that we are searching from -- that is, the agent of the selection for this Query Action's selection -- is included in the results of the search.
-=====Within 2D Boundary=====
-Represents agents or locations that exist within the boundary specified by the inputs.
- Inputs:
- [Numeral]
-=====Here=====
-Represents the location of the searching agent. For example, if a selection is defined for an agent cell, and that selection's selection's agent is an occupant of a cell, the cell that the agent is occupying will be used.
-=====Available=====
-Represents cells which are not currently occupied. This function is only relevant for grids which are not multi-occupant.
-=====Distance=====
-The distance between the source agent and an agent represented by this selection. If more than one agent is represented by the other functions in the selection, this function will the distance to an arbitrary (randomly selected) agent as defined by those other functions.
- Outputs:
- [Real]
-=====Away=====
-Represents a location that is on the path that will take the source agent (that is, the selection's selection's agent) the farthest distance from the agent(s) represented by the search. This function collaborates with the within and neighbor functions to allow the agent to move in a particular direction away from some location or agent.
-=====Minimize=====
-This function is not currently supported.
-=====Maximize=====
-This function is not currently supported.
-=====Location 2D=====
-Represents the location of the current agent for use in subsequent selections.
- Inputs:
- [Real]
- [Real]
-=====Boundary 2D=====
-Represents a two-dimensional boundary within a space. (Not currently relevant for any general usages.)
- Outputs:
- [Real]
- [Real]
-====Random====
-=====Random In Range=====
-A pseudo-random value within that numeric range specified as drawn from a uniform distribution. The minimum values are inclusive. The maximum values are inclusive for integer inputs and exclusive for Real inputs.
- Inputs:
- [Numeral] The minimum value (inclusive).
- [Numeral] The maximum value (inclusive).
- Outputs:
- [Numeral] The random number.
-=====Random To Limit=====
-A pseudo-random value between zero and the value specified by the (non-zero) input and drawn from a uniform range. That value is inclusive for Integers and exclusive for Reals. (Note that as with the random in range function in the context of real numbers the distinction between an exclusive and inclusive limit is essentially meaningless.)
- Inputs:
- [Numeral] The maximum value (inclusive).
- Outputs:
- [Numeral] The result.
-=====Random Unit=====
-A pseudo-random Real value between 0 and 1 drawn from a uniform distribution. (The distinction between inclusive and exclusive range is essentially meaningless in this context and we can assume that the result will never be greater or equal to 1.)
- Outputs:
- [Real]
-=====Random Boolean=====
-A value that is randomly true or false, i.e. a fair coin toss.
-=====Random Weighted=====
-An indexed value weighted against a probability distribution. The total probability must sum to 1.0. For example, an input of {.1,.2,.7} under a uniform distribution would would have 10% probability of producing "0" , 20% for "1" and 70% for "2". This function can then be used with Item to return a biased result from another list.
- Inputs:
- [Real] A list of values that will determine the resulting weighted index.
- Outputs:
- [Integer] A resulting indexed value bounded by 0 and the length of the input list - 1.
-=====Random Member=====
-Represents a random value drawn from the set of Real values specified.
- Inputs:
- [Real] Returns a random member of the supplied list of numbers.
- Outputs:
- [Generic] The value of the item at a random index.
-=====Random State=====
-A random specified value (option) from the specified state.
- Inputs:
- [Generic] The state to select items from. All items are included.
- Outputs:
- [Boolean] The resulting option.
-====Graphic====
-=====Shape Oval=====
-Draw a generic oval.
-=====Shape Rectangle=====
-Draws a rectangular shape.
-=====Shape Inset=====
-Shrinks the current shape by the input amount. (The overall scale is currently unspecified, but in most implementations should be 20.)
- Inputs:
- [Integer] Number of nominal pixels to inset.
-=====Shape Marker=====
-Draw a marker, that is a graphical indicator that can be used to add an additional que about the object state. For example, in a two-dimensional graphics representation this might be a small shape drawn inset at the corner of the larger shape.
-=====Shape Marker 2=====
-Represents a marker placed in a different location from the other shape markers.
-=====Shape Marker 3=====
-Represents a marker placed in a different location from the other shape markers.
-=====Color RGB=====
-A color specified by the three inputs for Red, Green and Blue color components. Those inputs are expected to be in the range 0..1.
- Inputs:
- [Real] A value from 0.0 to 1.0.
- [Real] A value from 0.0 to 1.0.
- [Real] A value from 0.0 to 1.0.
-=====Color Red=====
-The color red.
-=====Color Yellow=====
-The color yellow.
-=====Color Blue=====
-The color blue.
-=====Color Orange=====
-The color orange.
-=====Color Green=====
-The color green.
-=====Color Purple=====
-The color purple.
-=====Color Black=====
-The color black.
-=====Color White=====
-The color white.
-=====Color Gray=====
-The color gray.
-=====Graphic Outline=====
-Draws an outline of the last evaluated shape, using the last specified color or the default color (usually black) if none has been specified.
-=====Graphic Fill=====
-Fills the last evaluated shape with the last specified color or the default color (usually black) if none has been specified.
-====Time====
-=====Now=====
-The current simulation period, that is the number of iterations that the model has gone through, or in the case of models with callibrarted time, the number of iterations added to the model's nominal start time.
- Outputs:
- [Integer] The current period.
-====Math====
-=====Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sin(double)]
-=====Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cos(double)]
-=====Tangent=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tan(double)]
-=====Arc Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#asin(double)]
-=====Arc Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#acos(double)]
-=====Arc Tangent=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan(double)]
-=====Convert Degree to Radians=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toRadians(double)]
-=====Convert Radians to Degrees=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#toDegrees(double)]
-=====Exp=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#exp(double)]
-=====Log=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log(double)]
-=====Log b10=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log10(double)]
-=====Square Root=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#squareRoot(double)]
-=====Cube Root=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cbrt(double)]
-=====Remainder=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#iEEEremainder(double,%20double)]
-=====Ceiling=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ceil(double)]
-=====Floor=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#floor(double)]
-=====Rount=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#rint(double)]
-=====Arc Tangent Rectangular=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#atan2(double,%20double)]
-=====Power=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#pow(double,%20double)]
-=====Absolute Value=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#abs(double)]
-=====Maximum=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#max(double,%20double)]
-=====Minimum=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#min(double,%20double)]
-=====ULP=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#ulp(double)]
-=====Sign=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#signum(double)]
-=====Hyperbolic Sine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#sinh(double)]
-=====Hyperbolic Cosine=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#cosh(double)]
-=====Hyperbolic Tan=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#tanh(double)]
-=====Hypotuneuse=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#hypotuneuse(double,%20double)]
-=====Expm1=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#expm1(double)]
-=====Log1p=====
-See JavaDoc: [http://java.sun.com/javase/6/docs/api/java/lang/Math.html#log1p(double)]
-====List====
-=====Item=====
-Returns the item at the specified index from the list of items provided. Those items will typically be input primitives such as Integer or Real values.
- Inputs:
- [Generic]
- [Integer]
- Outputs:
- [Generic]
-=====Length=====
-The number of items in the provided list of items.
- Inputs:
- [Generic]
- Outputs:
- [Integer]
-====Distribution====
-=====Uniform Cross Distribution=====
-A random number taken from a distribution of values as defined by a cross of all values. (See Cross Distribution.) This funciton then returns a value drawn from the minimum and maximum values as determined by the current agent state. In the cross distribution, each of the values is treated independently so that an input attribute is created for every potential combination of states.
- Inputs:
- [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
- [Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- [Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- Outputs:
- [Real] The resulting random number based on the current agent state and the input parameters.
-=====Uniform Additive Distribution=====
-A random number taken from a distribution of values in which each of the minimum and maximum values are added to determine a total minimum and maximum value. (See Additive Distribution.) In the additive distribution, each of the values is treated as dependent on the others so that an input attribute is only created for each seperate state.
- Inputs:
- [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
- [Real] The set of attributes that will determine the minimum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- [Real] The set of attributes that will determine the maximum value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- Outputs:
- [Real] The resulting random number based on the current agent state and the input parameters.
-=====Cross Distribution=====
-A value taken from a set of (auto-generated) attributes based on the value of each state included. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create separate input attributes for AI, AII, BI and BII. Then for an agent with States A and II this function would return the value specified by the AII input attribute.
- Inputs:
- [Generic] The list of states to factor into the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
- [Real] The set of attributes that when multiplied against each other will determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- Outputs:
- [Real] The resulting value based on the current agent state and the input parameters.
-=====Additive Distribution=====
-A value taken from a set of (auto-generated) attributes based on the combined values of the states provided. For example, if the multi-values included a state X with values A and B and a state Y with values I and II, this distribution would create input attributes for A, B, I and II. Those values would then be added together, so that for an Agent with state A and II this function would return A + II.
- Inputs:
- [Generic] The states to include in the distribution. This is a multi-argument, which means that you can specify any number of attributes as arguments.
- [Real] The set of attributes that when combined with each other determine the value of the function result based on the current state of the agent. Note that this list is automatically created and maintained. These values don't need to be and should not be manually edited.
- Outputs:
- [Real] The resulting value based on the current agent state and the input parameters.
-
-===Diagrams===
-
-The following diagram may be helpful to readers familiar with UML and Meta-modeling:
-
-====Meta-Classes====
-
-[[Image:images/FunctionsDiagram.png]]
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Reference.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Reference.html
deleted file mode 100644
index d651f38..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Reference.html
+++ /dev/null
@@ -1,118 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Escape - Reference</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">Reference</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Getting-Started.html" title="Getting Started"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Getting Started</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top"></td>
- </tr>
-</table>
-<hr />
-<h1 id="Reference">Reference</h1>
-<h2 id="Converting_Existing_Ascape_models">Converting Existing Ascape models</h2>
-<p>There are only a few changes should have to make to existing Ascape models or to use existing Ascape
-documentation to develop Escape models.</p>
-<h4 id="Model">Model</h4>
-<p>The core model is completely API compatible. No changes!</p>
-<h4 id="View">View</h4>
-<p>Because Escape uses SWT and Ascape uses Swing, there are a few unavoidable incompatibilities. Most of these we
-avoid by using higher level APIs but here are the key changes that you're likely to have to make:</p>
-<h5 id="Convert_the_low-level_imports_from_AWT_and_Swing_to_SWT">Convert the low-level imports from AWT and Swing
-to SWT</h5>
-<p>The simplest way to accomplish this is to remove all of the imports and then organize imports. For example:</p>
-<pre>java.awt.Color <b>to</b> org.eclipse.swt.graphics.Color
-java.awt.Graphics <b>to</b> org.eclipse.draw2d.Graphics
-</pre>
-<p>Then just do a global find for all of the imports and replace them with nothing. This is a great place for a
-regexp. Try:</p>
-<pre>find: import java\.awt\.(.*);
-replace: [nothing]
-</pre>
-<p>You don't have to replace these with the SWT equivalents, just click on the project, right-click and choose
-"Source:Organize Imports.." By the way, a great way to avoid having to select the right entries in optimize imports and
-to alert you when you have missed anything is to prevent the awt and swing classes from being used at all. Right-click
-on project, choose "Build Path:Configure Build Path", go to Libraries tab, open JRE System Library, choose "Access
-Rules", edit, and then add entries for java/awt/** and javax/swing/**. The code will regenerate and you'll have error
-markers for all of the stuff that won't work with Escape and Eclipse.</p>
-<h5 id="Convert_color_features">Convert color features</h5>
-<p>You can't use AWT colors either so you'll need to replace any colors. AMP provides a convenience classes for
-Colors called ColorFeature and ColorFeatureConcrete. You can use these or any of the other ways to define SWT colors.
-For example:</p>
-<pre>Color.lightGray <b>to</b> ColorFeature.LIGHT_GRAY
-new Color(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy) <b>to</b>
- ColorFeatureConcrete.create(Math.min(1.0f, (float) (redEnergy + orangeEnergy)), (float) orangeEnergy * .8f, (float) blueEnergy)
-</pre>
-<h5 id="Change_agent_color_getters">Change agent color getters</h5>
-<p>If you've defined colors through overriding Agents as in most models, you'll need to change the method signature.
-You could just do a global replace for this one.</p>
-<pre>public Color getColor( <b>to</b> public Object getPlatformColor(
-</pre>
-<h5 id="Get_rid_of_image_features">Get rid of image features</h5>
-<p>Escape doesn't support them. In practice they haven't been used a lot. At some point perhaps we'll have nice
-sprite support instead. :)</p>
-<pre>public Image getImage() {**} <b>to</b> ""
-</pre>
-<h5 id="Modify_usages_of_DrawFeatures">Modify usages of DrawFeatures</h5>
-<p>If you've created any of your own draw features, you'll need to change them slightly to accommodate the
-differences between the AWT and SWT / Draw2D APIs. This should be pretty straightforwrd. For example:</p>
-<pre>g.setColor(...
-g.fillOval(..
-becomes:
-g.setBackgroundColor(
-g.fillOval(..
-</pre>
-<p>That's about it, though it's probable that we've missed something. Please post a message on the amp newsgroup if
-you run into any other conversion issues.</p>
-<h4 id="Configuration">Configuration</h4>
-<p>Instead of using Ant, Escape has really nice support for parameterizing and testing models. See <a
- href="/wiki/Experimenting_and_Testing" title="Experimenting and Testing">Experimenting and Testing</a> (todo). If
-you do want to work with ant you will need to install the plugins from the Sourceforge download site. (These have
-dependencies that I didn't want to bother with going through the Eclipse IP process to get in. If for some reason you
-think these should be part of core Escape let Miles know and I'll take care of it.) Ant has not been tested for Escape
-so it's not even clear it will work.</p>
-<h2 id="Current_Limitations">Current Limitations</h2>
-<ol>
- <li>Escape is pretty robust, and the APIs are solid and well-tested but the runtime is not going to be as
- stable for a while as Ascape which has been around for a long time.</li>
- <li>Escape graphics performance is generally slower especially for charts. But on the other hand you can run
- multiple models at once and the headless models should perform just as well as console launched Ascape programs. In
- practice this shouldn't affect your normal model exploration work.</li>
- <li>We don't have the speed slider working yet. See <a
- href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=291299">https://bugs.eclipse.org/bugs/show_bug.cgi?id=291299</a></li>
- <li>Charts only support time series, not histograms and pie. See <a
- href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=282953">https://bugs.eclipse.org/bugs/show_bug.cgi?id=282953</a></li>
-</ol>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Getting-Started.html" title="Getting Started"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Escape.html" title="Escape"><img alt="Escape" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Getting Started</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top"></td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/References.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/References.html
deleted file mode 100644
index a22062a..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/References.html
+++ /dev/null
@@ -1,51 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Acore - References</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">References</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Acknowledgements.html" title="Acknowledgements"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Acknowledgements</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top"></td>
- </tr>
-</table>
-<hr />
-<h1 id="References">References</h1>
-<ol>
- <li>AGENT-BASED META-MODELS, Parker, et.al. <a
- href="http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf">http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf</a></li>
- <li>Howe, et. al. CONTAINING AGENTS: CONTEXTS, PROJECTIONS, AND AGENTS <a
- href="http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf">http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf</a></li>
-</ol>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Acknowledgements.html" title="Acknowledgements"><img
- alt="Previous" border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Acore.html" title="Acore"><img alt="Acore" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Acknowledgements</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top"></td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Structure.html b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Structure.html
deleted file mode 100644
index 7df4112..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/Structure.html
+++ /dev/null
@@ -1,85 +0,0 @@
-
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Acore - Structure</title>
-<link type="text/css" rel="stylesheet" href="styles/help.css" />
-<link type="text/css" rel="stylesheet" href="styles/main.css" />
-</head>
-<body>
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <th style="width: 100%" align="center" colspan="3">Structure</th>
- </tr>
- <tr>
- <td style="width: 20%" align="left"><a href="Acore.html" title="Background"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right"><a href="Actions-Behavior-.html" title="Actions (Behavior)"><img
- alt="Next" border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Background</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Actions (Behavior)</td>
- </tr>
-</table>
-<hr />
-<h1 id="Structure">Structure</h1>
-<h2 id="Diagrams">Diagrams</h2>
-<h3 id="Meta-Classes">Meta-Classes</h3>
-<p>Our first diagram depicts the core structural design of the MetaABM system -- again, much of this will carry
-through to Acore.</p>
-<p><img src="image/MetaABM.png" title="image/MetaABM.png"/></p>
-<p>There seems to be a lot going on here, but the basic components are pretty straightforward as we can see in the
-next diagram.</p>
-<h3 id="Key_Collaborations">Key Collaborations</h3>
-<p><img src="image/MetaABMStructure.png" title="image/MetaABMStructure.png"/></p>
-<pre>Core interactions are in Red. The meta-model structure is essentially a Composite pattern.
-</pre>
-<h3 id="What_it_Means">What it Means</h3>
-<ol>
- <li>Every model has at its root a Context (Scape). <a
- href="http://wiki.eclipse.org/AMP/UserGuide/AMF/MetaModel#References">2</a> Contexts are Agents that are capable
- of containing other Agents (including other contexts, naturally).</li>
- <li>(Meta-level) Contexts (Scapes) contain (meta-level) Agents at the model (Design-time) level. At runtime,
- (model-level) Context instances defined in a (meta-level) SContext will contain (model-level) agent instances of the
- defined (meta-level) SAgent. This sounds more complicated than it is, so let's look at a simple example. Suppose we
- create a new Context, and give it a label of ÒWiki ExampleÓ. Within that Context, we create an Agent and give it a
- label of "IndividualÓ and another Agent with the label ÒBlockÓ. At runtime when we are actually executing the model
- we will have one WikiExample model instance which contains a number of Individuals.</li>
- <li>Agents contain Attributes, such as Vision and Age. Context attributes often represent input parameters for
- contained agents. For example, our Wiki Agent Context might contain an Individual Count as well as a Minimum Age and
- Maximum Age.</li>
- <li>Contexts (Scapes) can contain Projections (Spaces), which represent some kind of spatial or structural
- interaction space for the agents; either a grid, a continuous (euclidian) space, or a network (graph) or geographic
- space of some kind. For example, we might want to have a City that contains Blocks and that an Individual can move
- around within.</li>
- <li>Agents are Actables and thus can contain any number of behaviors called ÒActionsÓ, described in detail in
- the next section. Actions can describe individual behavior, and at the Context (Scape) level can define how member
- Agents and Projections are created.</li>
- <li>Styles provide a mechanism for defining generic visualization behavior for Agents and so are also Actables.
- For example, an Agent might have an Action that says effectively Òdraw a red circle shaded red for the wealth of the
- agentÓ.</li>
-</ol>
-<h2 id="AMF_Hierarchical_Editor_Example">AMF Hierarchical Editor Example</h2>
-<hr />
-<table class="navigation" style="width: 100%;" border="0" summary="navigation">
- <tr>
- <td style="width: 20%" align="left"><a href="Acore.html" title="Background"><img alt="Previous"
- border="0" src="images/prev.gif" /></a></td>
- <td style="width: 60%" align="center"><a href="Acore.html" title="Acore"><img alt="Acore" border="0"
- src="images/home.gif" /></a></td>
- <td style="width: 20%" align="right"><a href="Actions-Behavior-.html" title="Actions (Behavior)"><img
- alt="Next" border="0" src="images/next.gif" /></a></td>
- </tr>
- <tr>
- <td style="width: 20%" align="left" valign="top">Background</td>
- <td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Actions (Behavior)</td>
- </tr>
-</table>
-</body>
-</html>
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/amp-index.txt b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/amp-index.txt
index b8b4e96..3b81a88 100644
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/amp-index.txt
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/amp-index.txt
@@ -1 +1,9 @@
-ModelersGuide.mediawiki
\ No newline at end of file
+000-Guide_Overview.mediawiki
+100-ModelersGuide_Intro.mediawiki
+110-ModelersGuide_Structure.mediawiki
+120-ModelersGuide_Actions.mediawiki
+130-ModelersGuide_Functions.mediawiki
+200-ModelersGuide_Creating.mediawiki
+300-ModelersGuide_Exploring.mediawiki
+400-ProgrammersGuide_Escape.mediawiki
+900-Resources.mediawiki
\ No newline at end of file
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/AMFScreenshot.png b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/AMFScreenshot.png
deleted file mode 100644
index 5a5b9c0..0000000
--- a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/AMFScreenshot.png
+++ /dev/null
Binary files differ
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesign.png b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesign.png
new file mode 100644
index 0000000..2398ec5
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesign.png
Binary files differ
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesignChoice.png b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesignChoice.png
new file mode 100644
index 0000000..68762ce
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionDesignChoice.png
Binary files differ
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionRun.png b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionRun.png
new file mode 100644
index 0000000..932a0d7
--- /dev/null
+++ b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/DistributionRun.png
Binary files differ
diff --git a/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/AMPScreenshot.png b/org.eclipse.amp/doc/org.eclipse.amp.doc/doc/images/EscapeExecutionScreenshot.png
similarity index
