Revision as of 19:55, 14 October 2009

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.

Acknowledgements

The AMF meta-model started life as "score" 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.

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

Our first diagram depicts the core of the metaABM system. Core interactions are in Red. Every metaABM model has at its root an SContext. 2 SContexts instances represent types of agents that are capable of containing other SAgents (including other contexts, naturally). At runtime, instances of SContext instances (got that?) contain agent instances each corresponding to one of the contained SAgent instances.

This sounds more complicated than it is, so perhaps an example will help explain the flavor, after which we will simply discuss important aspects of the metaABM model which may not be apparant from the general model. Suppose we create a new SContext, and give it a label of “Sugarscape Model”.*2 Within that SContext, we create an SAgent and give it a label of “SugarAgent” and another SAgent with the label “SugarCell”. (For those unfamiliar with UML notation, we know that SContexts are sub-types of SAgent because there is an open arrow from SContext to SAgent, and we know that SAgents can have a label because they are sub-types of SImplementated, which are sub-types of IID -- almost every object in metaABM has identifiers -- and IID has an attribute of “label”.) At runtime (when we are actually executing the model, and ignoring setting up projections and initializers), we will have one Sugarscape model which contains a number of SugarAgents along with a set of SugarCells arranged in a grid structure. We can add an SAttribute to our “SugarAgent” SAgent, and give it a label of say “Wealth”, with a type of “Real”. (We know that SAgents can have SAttributes because they are a sub-type of SActables, which are a sub-type of SAttributed. SAttrributed has a line leading to SAttribute and that line has a a solid diamond at one end and a “0..*” label at the other, telling us that each SAgent can include any number of attributes. *3

SContexts may have SProjections, which represent some kind of spatial or structural interaction space for the agents; either a grid, a continuous (euclidian) space, or a network or GIS space of some kind. (GIS is currently only supported as a notional construct and has no target platform implementation.) In addition to SAttributes, agents are SActables can have any number of behaviors, called “Acts”, described in the next diagram. *4 SStyles provide a mechanism for defining generic visualization behavior for Agents and so are also SActables. For example, an SAgent might have an Act that says effectively “draw a red circle shaded red for the wealth of the agent”.

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 data-flow language, though the Actions design also carries aspects of functional and logical languages.

Basic Design

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.

1. 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.
2. Then query terms and set operations are applied to that selection.
3. Finally, commands are executed against the results of those queries.

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."

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..

1. 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.
2. Create a child Select Action that will find our partner. Two important things to note here:
   1. 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.
   2. 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.
3. Create two child Query Actions:
   1. 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.)
   2. 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 Partner and ourselves. 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.
4. Intersect (All in metaabm) these two queries. This delineates the end of the selection definition for any target Actions.
5. 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.
6. As above, define some queries. THis time we want only those agents that are available and neighbors of our partner.
7. And another intersection..
8. Finally, we move to the location we've found. All that's required at this point is to specify:
   1. The movement selection, or those agents that are moving, which in this case is the original agent we're executing the rule for, and
   2. 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.

Paths

Of course, much more complex rule designs are possible. For example we can use a Union (Any in MetaABM) action to allow any one of the possible source paths to trigger the target actions.

In the example above, we've defined a new Query Action. Our now snobbish agent is attracted to other individuals with the same wealth level, and will pick a random agent that fits either criteria; here the Agent has selected an agent that shares the same wealth.

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. So, let's see what the code generated by AMF from this specification looks like in two POJO ABM APIs.

Ascape

    public void findPartner() {
        org.ascape.util.Conditional partnerCondition = new org.ascape.util.Conditional() {
            private static final long serialVersionUID = 6846144446402098985L;
            public boolean meetsCondition(Object partnerCell) {
                partnerCell = ((org.ascape.model.HostCell) partnerCell)
                .getOccupant();
                if (partnerCell instanceof Individual) {
                    return true;
                } else {
                    return false;
                }
            }
        };
        Individual partner = null;
        org.ascape.model.space.Location partnerLocation = ((org.ascape.model.space.Discrete) getWikiExample()
                .getCity().getSpace()).findRandomAvailable(
                                                           ((org.ascape.model.CellOccupant) this).getHostCell(),
                                                           partnerCondition, false, partner.getVision());
        if (partnerLocation != null) {
            partner = (Individual) ((org.ascape.model.HostCell) partnerLocation)
            .getOccupant();
        }
        if (partner != null) {
            Block partnerNeighbor = (Block) ((org.ascape.model.space.Discrete) getWikiExample()
                    .getCity().getSpace())
                    .findRandomAvailableNeighbor(((org.ascape.model.CellOccupant) partner)
                                                 .getHostCell());
            if (partnerNeighbor != null) {
                moveTo(partnerNeighbor);
            }
        }
    }

Detail

Abstract Actions

Concrete Actions

Abstract Actions

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.

1. An Act is anything that might happen during the execution of an Agent-Based Model.
2. 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.)
3. Acts reference an 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.
4. 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).
5. 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.)
6. 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.
7. AControls determine wether target acts are executed and against what agents. They are in some sense query terms.
8. ACommands trigger some model state change (ASet) or spatial transformation (ATransform).

Functions

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.

References

1. AGENT-BASED META-MODELS, Parker, et.al. http://www.agent2005.anl.gov/2006procpdf/Parker_Agent_2006.pdf
2. Howe, et. al. CONTAINING AGENTS: CONTEXTS, PROJECTIONS, AND AGENTS http://www.agent2006.anl.gov/2006procpdf/Howe_Agent_2006.pdf