Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

AMP/UserGuide/FromScratch

Creating a new model from scratch: A naive, ground-up tutorial

This tutorial assumes no knowledge of AMP. It is a work in progress, and shows how one naive AMP user navigates through the model creation process. While it is under construction there may be parts that trail off; the AMP developer community will chime in for guidance, and these loose ends will be sewn up, leading to the next challenge.

I'm just going to throw comments in like this.. as you continue to work on this and integrate anything useful back into the text, just edit them back out. --Milesparker.gmail.com 14:00, 17 March 2010 (UTC)

The Model

The model to be created is a simple one. It is based on a forthcoming paper whose primary author is John W. Pepper (University of Arizona), who built on his previous work by taking a suggestion from Robert Axelrod.

The model is intended to demonstrate that positive and negative assortment can occur among populations comprised of two kinds of individuals both of which, regardless of their own type, show a preference for being near members of one type. The situation is analogous to a condition in which one kind of individual causes some form of environmental degradation that impacts itself and others around it.

The model specification is as follows:

N agents exist in space. Agents are of two kinds, traditionally called Cooperators and Defectors. Agents are able to perceive the agents immediately around them within a radius of r units; r is the same for all agents. Agents are able to discern whether these neighbors are C's or D's. If the number of D's around a given agent is greater than the number of C's, the agent will move to a new, randomly selected location (with uniform probability throughout the space).

Parameters in the model:

  • N - the number of agents, usually 100
  • DF - the 'Defector Fraction', or the proportion of the N agents that are defectors
  • r - the radius agents can 'see'

Additionally there are some other variations that will eventually be performed; I'm not sure how AMP will consider these, and whether they are parts of the same 'model' or would be different 'models'. For now the main issue is space; the original formulation, which we can take as a starting point here, is that space is a continuous 1-D ring with periodic boundaries. Agents are located at points along this ring, which is considered to have length 1 (so agent locations are all values between zero [inclusive] and one [exclusive]).

Hmm...you've started off with an edge case! I don't think this will work out of the box for Ascape / Escape targets..we've never actually done a 1D continuous periodic space. :) Is the idea to have real point sources; that is, all of the agents could end up at the same location on the ring? Or do we really want a discrete space here? Also the visualizations for Escape aren't going to be as nice; though Ascape handles 1D discrete very nicely. I'm not sure about Repast, frankly -- I don't think I've seen any 1D visualizations there.--Milesparker.gmail.com 13:55, 17 March 2010 (UTC)

An additional point: all agents assess their neighborhoods simultaneously; then all agents that choose to move on the basis of this assessment move simultaneously.

Again, an edge case as simultaneous movement is actually quite difficult to implement for situations of contention. If you're doing update of state manually, you'll also have to track a temporary value and then do a separate update step. Testing under situations of synchronous and asynchronous update is something that AMF could support quite well from a meta modeling perspective but the actual targets don't support that. -- Milesparker.gmail.com 13:55, 17 March 2010 (UTC)

Note that there will also be more to be said about what data are collected from this model, but for now the focus will be on getting the model to run.

Step 1: Creating a new project

Assuming you have correctly installed AMP and have Eclipse open, your first step is to create a new project.

Creating a new project is easy, but there's a trick: to do it the easy way you have to be in the right 'Perspective.' Eclipse manages what you see, and what options you have in menus, based on the 'perspective' that you have open. To change perspectives, go to the 'Window' menu and select 'Show Perspective...'. The one you want is 'Agent Modeling'. It may not be listed in the first menu you see; select 'other' and you'll find it in the list (again, if AMP is properly installed).

You could also select "Reset Perspective" which will apply the changes for the AMP software you've just installed. -- Milesparker.gmail.com 13:58, 17 March 2010 (UTC)

If you are in the "Agent Modeling" perspective, then when you select 'File: New...' one of the menu items is 'Basic MetaABM Project'. Choose that one; you will be asked for a name and a file location- supply whatever you like here. For our tutorial, the project name is 'EvCoOpTutorial'.

Some notes about this: A 'Basic MetaABM Project' allows you to create the model specification. AMP works by taking these specification and automatically generating code to run the model in a specific implementation; the three implementations available are Repast Simphony, AScape, and 'EScape', which runs within the Eclipse environment. Our initial project won't do any of this: for now we are just working on the model specification. Later we'll move it to a specific implementation.

And, since you can simply drag the model from a Basic Project to say an Escape project when you're ready that's a good way to go. Though there is something to be said for the instance gratification of being bale to just click the execute button as you go along. --Milesparker.gmail.com 13:58, 17 March 2010 (UTC)

Step 2: Creating a .metaabm file for the model's specification

The next step is to create a .metaabm file for the model's specification. Assuming you are still in the 'Agent Modeling' perspective, this is also easy: 'File: New...' allows you to create a new 'MetaABM Model'.

When you do this you are first asked to choose the 'folder' in which to place the new model; choose the folder associated with the project you just created. You are also asked for a name for the file, which we have called evcooptutorial.metaabm. After you enter these and click 'Next' you are confronted with a window that asks you to re-state the package (folder) and file name (I don't know why...?), and then for an 'Implementation Mode', a 'Base Directory', and the kind of XML encoding to be used. Accept the defaults (Implementation Mode is 'Generate' and XML encoding is UTF-8, while 'Base Directory' is blank), even if they are empty, and click 'Finish'.

The file will be created in the folder and opened in the editor. You may also notice that two other subfolders are added: src and doc. The 'doc' folder will already have some contents (html files that describe the components of the model). We will watch as components are added to these automatically.

Step 3: Attributes of the model

The next step is to specify some attributes for the model- these are equivalent to global parameters. For our example, we have three: N, r, and DF (see above).

This is our first look at how the AMP hierarchical editor works.

The editor should initially show the file as the root node in a hierarchical structure that is, at first, collapsed. Expand it by clicking on the little arrow to the left of the file name, and you will see that it contains three child nodes: Acts, Attributes, and Styles.

Right clicking on 'Attributes' gives a large context menu, but the important item is at the top: 'Create Member'. This menu, when selected, offers three options: Attribute, Attribute Array, and State.

This is our first sign of how MetaABM will work. Within the hierarchy each node can have child nodes; however, a node can only have child nodes of certain kinds; each kind of child node, in turn, can have child nodes itself, but, again, only as appropriate. The menus will guide you through what kinds of nodes are available at each point in the hierarchy.

It is also important that you have the 'Properties' window visible somewhere on your screen. If it is not, it can be summoned by 'Window: Show View', though you may, again, have to use the 'Other...' submenu to find it.

We want to add an 'Attribute' to our 'Attributes' node, so we select 'Attribute'. It is added and initially called 'Attribute'. In the Properties window we can see that its ID is 'attribute' (lower-case), its label is 'Attribute' and its plural label is 'Attributes'. These are all default values; whereas we are keeping the name 'Attributes' for the parent node, we will be assigning names to the individual attributes we create. The first one we will call 'PopulationSize'. This is done by typing an ID ('populationSize') to replace the word 'attribute' in the ID slot in the Properties window, and the word 'PopulationSize' to replace the word 'Attribute' in the label' slot in the Properties window. AMP assumes that the plural will be 'PopulationSizes'.

Further down in the Properties window is 'SType'. I don't know what the 'S' is for, but this refers to the type of attribute that will be specified. The default is 'Boolean', which is not what we need; choose, from the drop-down options available, 'Integer'.

Below this is a slot for 'Default Value'; enter 100.

For now we can ignore the other three options available in this node's properties. Optionally we can add a description ('The number of agents in the simulation.').

When this has been entered, save the file. Notice that AMP automatically builds some elements that depend on the structure we have entered; in the 'doc' folder, the html documents (you can click on these to open them) will now include the description of the 'PopulationSize' parameter.

The basic process we used for 'PopulationSize' can now be repeated for 'DefectorFraction'; right-click on the 'Attributes' node to add the member, choosing 'Attribute' and changing its ID, labels, and values as needed. In this case the value will not be of type 'Integer', but rather, 'Real', and the default value should be 0.5.

Similarly, an attribute of 'Radius' can be set, also as a 'Real' and with a default value of .05. (If you're a purist, you can overwrite the default plural label 'Radiuss' with the correct 'Radii'.)

Note that these attributes cannot have child nodes; right-clicking on them in the hierarchy doesn't present the user with an option to add a member.

Step 3: Define the Model's Space

The agents in our must exist within some space. Space is a child node of the root node of the hierarchy. Right-clicking on the root node allows us to 'Add a member', which includes the option to add a 'Space' node.

Taking no shortcuts, we will (again in the properties window) change the ID and label of our space to 'ring' and 'Ring' (pl. 'Rings', of course). A description can be added, but the real meat of the matter are the last two options. For 'Border Rule' we need 'Periodic' instead of the default, 'Sticky'. We will also need to change the dimensionality- BUT: before you change it, right-click on the space node (now visible as 'Ring' in the hierarchy'. Notice that you cannot add child nodes. Now return to the Properties window and change the dimensionality to '1'. Once this change is made, two child nodes appear under the 'Ring' node. These represent the dimensions (or, in this case, dimension) of that space.

(And here I'm confused... I can see that if I increase the Dimensionality of the 'Space' node, I get additional options: with 1 I only get Length, with 2 I get Width and Height, etc. But what is the difference between the 'Dimensions' node and the 'Length' node? The 'Dimensions' node seems superfluous, unless I'm missing something.)

Step 4: Define the Agents

Step 5: Initialize the Model

Back to the top