Structure
Our first step is to create an agent. Right-click on the root Simple Model context. (A lot more right-clicking to come!)
Let's call it "Bug".
We'll do the same for a Habitat agent -- in metaABM representations, cells are simply represented in the same way as other agents.
Creating Agents and Spaces
We then create a grid for the Bugs to move around upon.
Now, if we look at the attributes for Simple Model, we can see that an attribute for number of bugs as been automatically created for us. Let's assign a default value, hmmm.. according to the specification, this should be "100".
Turning back to the Grid, we can see that there are a lot of aspects to play with. Here we need to say that the space's borders should be "Periodic" -- that's what one half of the ABM community thinks "Toroidal" really means -- and the neighborhood should be "Moore" -- that's how we are going to interpret the statement "in the X and Y directions".
When we set the dimensionality to "2" attributes for height and width are added to the grid. We'll set them to 100 by 100, a lot of cells!
We need to do one other thing to set up the structure. The editor has created behaviors (we call them "Act"s) for creating agents, but we need to create an Act to build the grid Habitat members and make it a hospitable (or at least known) space for our bugs. So right-click to create a new Build Grid Act within the Build Stupid Model node within Simple Agent's Acts. (You'll need to expand some nodes to get there.)
To define the rule, we simply need to specify that it includes Bug agents and is filled with Habitats, give it a nice name, and specify that the projection is our 'Grid 2D'.
Agent Initialization
As we've defined the behavior, now we can make these bugs do something. Let's create our first rule. In this case we're going to create a special Initialize rule that gets activated only when the model is first created. All Acts begin from the agent (or style) Acts list and there are only a few Acts that can serve as roots. Right-click on the Bug Acts node and select "Initialize".
Next, right click on the new Initialize node and create a Select target. Selects are the central building blocks of metaABM behavior definitions and define a particular query that can be modified and used in subsequent targets. Targets are acts that "follow from" other acts. With this Select we are going to be searching for places for the Bug to initially land. So we need to specify Habitiat as the kind of Agent we are looking for, Grid 2D as the space we want to look within, and the preceding Initialize root Act (all root Acts are also Selects) as the basis for the selection; that is, the perspective we are searching from.
Now, we create a Query. A query is really a query term; we're specifying some aspect of the search that we're interested in.
In this case we want a special kind of query, a query within space for any agents that are available; that is unoccupied by another agent. So we select "Spatial: Available" form the drop down list of query functions.
Now that we know our destination we can Move. Create a Move Rule. (At this point you should be getting familiar with the interface, so we will skip steps here and there.) For the Move we need to define a Select from which we want to Move; "Selected", and a Select that we want to move to; "Destination". MetaABM picks exactly what we want here for this common case.
Agent Styles
There is one other thing to do before we can see what we have accomplished. While most ABM platforms have some kind of default color scheme, let's make the Bugs red. Agent visualization is accomplished using the same mechanism as ordinary agent rules. So first, let's create a new Style. By default the style will be called BugStyle2D, and that will work fine for now.
Now we need to create a series of evaluations. An Evaluation is like a Query in that it performs some kind of function in the broadest sense, but unlike a Query, it does not affect whether target (downstream) Acts are performed. For Styles we have a set of Graphic functions that we will chain together to draw a figure. First we create the Evaluation.
We make the first Evaluation define a Color of "Red".
Next, create a "Draw Oval" fill. There are other graphic shapes, but at this writing we only have implementations for Ovals and Rectangles and Markers.
For the last part of our style, we need to actually draw the figure. To do this we create a last Evaluation of "Graphic: Fill Shape".
"Fill" or "Outline" will always come last in a chain of graphic evaluations, but otherwise the order shouldn't matter. See the Demographic Prisoner's Dilemma model for an example of how this can be used to selectively pick Colors and or Shapes.
We can also create a Style for the Habitat. This gives the cells a nice green Color, and will come in handy later when we want to draw state for the Habitat agents. (Also it is currently necessary to make our implementation of Repast graphics work correctly.)
It is time to run our model. Right-click on the StupidModel metaabm file, and select Run As..:Ascape metaABM Model.
Voila!
Agent Movement
To make our agents move randomly every iteration, we will create a Rule. (For those familiar with Repast or other scheduling oriented AM platforms, a rule is just a schedule that gets activated each and every period for all agents.)
The first part of the Bug Rule is exactly the same as the Initialize rule. Remember to make the Select statement Agent property "Habitat" instead of "Bug", as we want to move to a habitat cell. (We should really assign a better name then "Bug Rule" perhaps "Random Movement".) As before, we want to make sure the Cell is free before we try to move in, so we'll select a "Spatial: Available" Query function.(By the way, to make scrolling through the list easier, you can type the first letters of the selection, in this case "SP".)
Error Checking
But now, instead of moving anywhere we want to move nearby. So now, we create a parallel or "sibling" Query from the same Select root. Often, we would pick the "Spatial: Neighbor" function to take a random walk, but according to the specification, we actually want to move into some random Cell within distance four (4). So we will pick "Spatial: Within" from the list of functions. Instead of specifying the actual distance now, let's examine another feature of metaABM, error checking. Save the model by selecting File:Save or the appropriate keyboard command.
You should see an error message.
Over in the Package Explorer (file list) you can see that the .metaabm file has been marked with an error symbol.
Double-click on the problem marker and the offending item will be highlighted.
In addition to error markers, metaABM provides warnings designed to help you avoid common design mistakes. For example, a warning will be issued if you attempt to move an agent from its selection to the same selection; this is not strictly speaking an error, but it doesn't make much sense. Notice that the Demographic Prisonner's Dilemma model has a warning marker, this is because we are happy with the default values for the attributes and didn't provide any.
You might also notice a number of Java warnings. By default the Eclipse IDE is very conservative when it comes to warnings, and expects the usage of language constructs that we choose not to use. A full discussion of all of this is beyond the scope of the tutorial, but see the Eclipse documentation on problem views for more ideas about how to customize these views.Returning to our model, we need a cell that is both Available and Within 4. To accomplish this, metaABM supports Logical Acts which control how various Queries work together. So create an All Act as a target of the Spatial Available Query.
Now for an interesting issue. Option-Drag the All node to also be a target of the Spatial Within Act. (This is a copy and drag action -- the same one you would use to copy a file from one directory to another without removing it form the original location. Depending on your OS, you may need to use the ALT or SHIFT key to accomplish this.)
We can then create a Target movement just as we did for the Initialize method above. But now as we have defined parallel but Logically linked Acts the same Move node shows up in our hierarchical editor twice!
This is probably a bit confusing for new users, but it is one of the aspects of the metaABM design that provides efficient behavior representation. Supporting tools such as the Metascape IDE Visualizer provide other ways to explore more complex Act structures.
Now we just need to assign a value for search distance. We could simply create a literal for the Spatial: Within Query but that isn't really god practice. (In fact, originally metaABM didn't allow any literals, but that began to seem a little too hard-headed.) So we will create our first Attribute. In this case, we want the Attribute to belong to Simple Model as it will be the same value for all Agents for now. So right-click on Simple Agent: Attributes and create a new one.
Name the Attribute -- "Bug Vision" seems descriptive -- give it a type of Integer, and assign it a default value of 4. This will allow most ABM platforms to provide the ability to change vision at runtime or through batch definitions, something we couldn't do if we had used a literal value.
Finally, we assign the Vision attribute to the "Input" node in our Spatial: Within Query.
Run Final Model
And here is our final model! Not looking much different in a snapshot, but those agents should now be moving around.
We have built a complete Ascape model from our metaABM model. But that's not all -- we also have a complete Repast model! We will leave this as an exercise -- you can simply follow the directions in the example model section on Demographic Prisoner's Dilemma.
If you get completely stuck, SimpleModel1 is available in model downloads.That's all for Now
We hope these "Getting Started" has enabled you to get up and running and given you some familiarity with the basic metaABM approach. Upcoming articles will explore metaABM model design in more depth and provide a complete Stupid Model implementation. Technical Articles will provide more explanation of the theoretical and practical decisions that went into metaABM.