Metascape "Extraordinary Tools for Extraordinary Science"

Stupid World 1

We can now get to the heart of designing an agent-based model with metaABM. We need to know a bit about where we are going before we start. This is our target, from the Railsback, Lytien and Grimm paper:

The space is a two-dimensional grid of dimensions 100 x 100. The space is toroidal, meaning that if bugs move off one edge of the grid they appear on the opposite edge.
100 bug agents are created. They have one behavior: moving to a randomly chosen grid location within +/- 4 cells of their current location, in both the X and Y directions. If there already is a bug at the location (including the moving bug itself—bugs are not allowed to stay at their current location unless none of the neighborhood cells are vacant), then another new location is chosen. This action is executed once per time step.
The bugs are displayed on the space. Bugs are drawn as red circles. The display is updated at the end of each time step.
Instead of specifying which random number generation algorithm to use, the default generator for each platform is used.

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.
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 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, and give it a nice name.
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.

By the way, you've probably noticed that the platform creates names that often make sense, but you can always replace them with more descriptive names.
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.
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 wether 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. Please use only these two shapes for the time being.
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.
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 basically 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".)
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. We won't be specifying the actual distance just yet. Notice in fact that if you save the model now, you will see an error in the Java code. While the metaABM editor attempts to prevent user's from doing anything completely silly, such as creating Acts that have themselves as Targets, it doesn't currently mark issues that arise as part of the normal development process.
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 the interesting part. 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. Forthcoming tools may provide different representations of parallel structures, but we think that this method of visualization is still preferable in many ways to flowcharts and other "layout" style visual editors.
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.

Important, ensure that the "Selected" value within the Input node is for the "Rule", not for the Desitination Select. There is currently a known issue that will cause one or both targets to fail if you use the default select.
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 the setup of the model 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 the Model section of the Downloads page.

That's all for Now

[ Back ]