Documentation for Evolver beta 1


A. OVERVIEW

Evolver is a a rapid application development environment for RePast
simulations. The intention is that the user can visually construct a
simulation out of component pieces and specifiy the behavoir of that
simulation using Not Quite Python, a subset of the Python
(http://www.python.org) computer language.

When Evolver is started, you'll see the main Evolver window. This
window is divided into five parts.

1. Menu Bar: at the very top you'll see the menu bar with File,
Project and Help entries. The File menu allows you to create a new
evolver project, open a previously saved project, save the current
project, and exit Evolver. From the Project menu, you can compile or
run the current project. In the Help menu, only the about entry is
currently enabled.

2. Tool Bar: beneath the menu bar, you'll see the tool bar. This
provides quick access to the the open, save, new, and help menu
entries from the file menu as well as the compile and run entries from
the project menu.

3. Component Palette: beneath the tool bar, you'll see the component
palette. The component palette contains the components you'll use to
create your simulation as well as the default selector (the button
labeled with the white arrow icon). The components themselves are
represented as buttons on a tabbed panel. Leaving the mouse cursor
over a particular component will pop up a tooltip with the name of the
component.

A component is added to a simulation by clicking on it (which changes
the shape of the mouse cursor) and then clicking on a parent component
in the project pane. For example, if I want to add a Default Evolver
Model component to the Default Project in the project pane, I click on
the Default Evolver Model component button and then on the Default
Project in the project pane. The Default Evolver Model component
should then appear as a child of the Default Project. The change in
shape of the mouse cursor means that the cursor is now "carrying" the
component. If you wish to "drop" the component with adding it to the
project pane, you can click on the default selector, the button
labeled with the white arrow icon that is next to the tabbed panel of
components.

4. Project Pane: the project pane is the left-hand side panel beneath
the component palette. Simulations are assembled in the project pane
in a tree structure. The root or top-most component of a simulation
will always a be project, represented by a box icon. Components are
placed in the project pane as described above. You can delete a
component from a project by clicking on it and pressing the delete or
backspace keys. Deleting a component will delete any children of that
component. The default project component cannot be deleted.

5. Property Pane: the property pane is to the right of the project
pane. The property pane displays the properties of the currently
selected (highlighted) component. The properties are displayed in a
table, one property per row with the property name in the left hand
column and the property value in the right hand column. Properties can
be edited by directly entering new values into the right hand column
in the case of simple properties or by clicking on a button in the
case of more compilicated properties. This button will be in the right
hand column and once clicked will bring up additional windows
appropriate for editing that property.

YOU MUST PRESS ENTER FOR THE PROPERTY CHANGE TO REGISTERED BY
THE COMPONENT.


B. COMMON PROPERTIES AND HOW TO EDIT THEM

a. Actions -- Actions are collections of NQPy (see the document
entitled Not_Quite_Python for more information on NQPy) code that can
be executed by your model. An Actions property is made up of zero or
more individual action items defined by NQPy code. Each item has a
name and a body composed of NQPy code. An action can be executed from
inside other actions. If this executed action is executed from within
another action defined in the same component, the action must be
prepended with "self". For example, suppose you define two individual
actions within your Default Evolver Node. The first is called run and
the next is called prepareToRun. If you want the run action to execute
prepareToRun, you execute it with:

self.prepareToRun()

Actions are edited by clicking on the "edit" button in the property
panel. This will pop up the Actions editor. You use the Actions editor
to add and edit an individual action. The Action editor has five
parts.

1. The Tool Bar: the toolbar is the set of buttons and combo box
located at the top of the window. The buttons are used to create a new
action and to save the current action.

To create a new action, click the new button (the button with a "new"
piece of paper on it). Type in the name of the action and press enter.
THE NAME OF THE ACTION MUST NOT INCLUDE ANY SPACES. You can now write
the NQPy code for the action. Note that clicking new will save the
current action, if any.

To save an action, click the save button (the button with the disk
icon). This will save the current code, and imports as part of the
action named in the combo box.

The combo box can be used to select a single action from the currently
defined actions. This action can then be edited and saved. When you've
clicked the new button, the combo box is replaced by a text box where
you can type the name of a new action . It resumes its normal
appearance once you click enter. Note that changing the currently
selected action with the combo box will save any changes you have made.

2. The Variables Pane: the variables pane lists variables available
for use by the action. At the very least this will include any
parameters you have defined for the current component. Clicking on a
variable name and then pressing enter will insert that variable name
at the current cursor position in the source pane. Similarly you can
also insert a variable name in your source, by clicking on a variable
name and dragging it to the source pane.

3. The Source Pane: the source pane is a simple text editor where you
write the nqpy code for the current action.

4. The Imports Pane: any java class can be reference and used in your
nqpy source. However, for effeciency, Evolver is not aware of every
java package. If you use a java class from a package that Evolver
doesn't know about, you can specify that package here. Import
statements include only the package and class name. For example,

java.awt.Color

5. The Button Bar: The Ok button will set the actions property to the new
set of actions you have defined. The Cancel button will ignore any
changes you have made and revert the actions property to the former set
of actions.

Usage - To create an action, you click the new button, type the name
of the action in the space provided and hit enter. At that point, the
cursor will move to the source pane, and you can start writing your
nqpy code. Alternatively, you can also add code to an action that
evolver has predefined or to an action that you have previously
defined. In this case, choose the action name from the combo box list,
and edit the code in the source pane. 

Components that allow you to add actions are based on java
classes. All the methods, that is, actions, in these java classes are
available in these components. See the document entitled
Not_Quite_Python for more information on how to call java methods from
nqpy code. See the Evolver_Component reference document for
descriptions of which java classes a component is based on and what
methods are then available to the component.

b. Parameters -- The parameters property is a collection of individual
parameters. A parameter is special type of variable that become part
of the component once you've compiled it.

Parameters are edited by clicking on the "edit" button in the property
panel. This will pop up the Parameters editor. You use the Parameters
editor to add and edit individual parameters. The Parameters editor
has three parts.

1. The Edit Parameter Pane: The edit parameter pane is used to add a
new parameter to the list of parameters. You must specify the
parameters name (e.g. numAgents), its type. The name CANNOT include
any spaces. The type can be one of the already listed primitive types
or any java class. If the type is a java class, you must use the fully
qualified class name (i.e. the package + class name,
i.e. java.awt.Color). Optionally you can specify a default value for
primitive types, and whether or not the parameter is probeable. If the
parameter is probeable it will show up as part of the parameter pane
when the model is run, assuming the parameter is part of a model type
component.

2. The Parameters Table: the parameters table lists any parameters
that you have defined and any that are pre-defined by evolver. 

3. Ok and Cancel: the Ok button will set the new the parameters property
to the new set of parameters in the parameter list. The Cancel button
will ignore any changes you have made to the parameters property and
revert the property to its original list of parameters.

Usage:

Adding parameters. You add parameters by filling in the appropriate
values in the edit parameter pane and then pressing the add
button. The parameter will then appear in the parameters table. 

Editing parameters. You can edit a parameter's properties directly in
the table. Click on the property (name, type, etc.) that you want to
edit and edit the property. YOU MUST PRESS ENTER AFTER EDITING IN
ORDER FOR THE CHANGES TO BE REGISTERED.

Deleting parameters. You can delete a parameter by clicking on that
parameter in the parameters table and clicking the delete button.

You can refer to the parameters of a component from within a
components action code (see Actions above) as "self.X" where X is the
parameter name. For example, if you define a parameter called
startWealth in component Y, you can refer to this startWealth
parameter from within Y's actions as self.startWealth. If you want to
get or set the value of a parameter from outside the component in
which it is defined, you can use the getX and setX methods, where X is
the name of the parameter. So, getStartWealth() and setStartWealth()
can be used to access component Y's startWealth parameter from within
another component's action code.


C. BUILDING A SIMULATION

Evolver works by compiling the components in the project pane into
java code compatible with the RePast simulation framework. Building a
simulation is then done by adding components from the component
palette to the property pane, customizing these components by editing
their properties, compiling the project and then running the resulting
RePast simulation. The remainder of this section gives a brief
overview of an Evolver simulation and then describes how to build a
simple simulation. See the document entitled "Evolver_Components" for
more detailed reference information on the components and their
properties.

An Evolver simulation minimally consists of a model component, such as
Default Evolver Model, and a child agent component, such as Default
Evolver Node. Once compiled the model is responsible for setting up
the various pieces of the simulation including the agents. The agent
component acts as a template for the creation of agents by the
model. The agent component defines the properties and behavoir of an
agent, and the model when compiled and run creates some number of
these agents. The current version of Evolver allows for the creation
of only one agent template, and thus only a single agent component
should be present in your simulation. 


Building a Simple Simulation. This section describes how to build a
simple simulation focusing how to use the various component
properties.

Our simple model will be developed in several iterations. The first
iteration of the simulation will create a random network of 10 nodes,
and assign each node a numerical label. When the simulation runs, each
node will print out its own label. The completed tutorial simulations
can be found in the evolver/docs/tutorial directory.

TUTORIAL 1

1. Start evolver or, if it is already running, choose new from the
file menu, or click the new button on the toolbar. This will create a
new project.

2. In the project name box in the property table, type Tutorial 1 and
press enter so Evolver can register the property change.

The project name has no bearing on the compilation and running of the
simulation, but serves to name your simulation.

3. Click on the Default Evolver Model component on the palette. It is
the button with the three colored boxes connected by lines. 

This selects the this component, and the mouse cursor is now
"carrying" it.

4. Click on the project component in the project pane (the box icon
labeled Tutorial 1).

This "drops" the Default Evolver Component onto the project
component. The Default Evolver Component is now a child of the project
component.

5. Change the display name to Tutorial 1, and the model name to
TutorialOneModel. Remember to hit enter after each change.

The display name will be displayed in title bars of the various
windows of your repast simulation once it is running. The model name
is the name of the java class that this component gets compiled
into. You needn't worry about this except that the model name CANNOT
contain spaces, and should, by convention, have its first letter
capitalized.

6. Click on the Default Evolver Node component (the blue circle) and
then click on the model component (now labeled TutorialOneModel) in
the project pane.

As before, this adds a Default Evolver Node component to our
simulation as a child of the model node.

7. Change the name property of the Default Evolver Node component to
TutorialOneAgent. Hit enter so that Evolver can register the change.

The name property is the name of the java class that this component
gets compiled to. As before, this is important only in that the name
cannot contain any spaces, and should by convention start with a
capital letter.

8. Choose save from the file menu, or click the save button on the
toolbar. You can save the simulation wherever you like, but the file
should, by convention, end with .xml.

You now have the core components of your simulation. A model component
(TutorialOneModel) that once compiled sets up the simulation, and an
agent component (TutorialOneAgent) whose behavoir drives the
simulation. We now need to customize these components by editing their
properties.

9. Click on TutorialOneModel in the project pane. This should display
TutorialOneModel's properties in the property pane.

This is how you navigate between components in the project pane. Click
on a component to bring up its properties.

10. Click on the combo box for the network source property in the
property table, and choose random density.

The network source property allows you to choose the structure and
number of nodes in your network. Your agent components will become the
nodes in this network. Random Density creates a network of a random
density, that is, it creates some number of nodes, and randomly create
links between them. 

11. Click on the edit button in the network source property. This pops
up an editor for a random density network. Change the size to 10, and
the density to 0.2. Click ok.

The edit button will pop-up an editor appropriate to whatever network
source you have selected. In this case, the random density network
will be created with 10 nodes, and a density of approximately 0.2.

12. Click on the edit button for the actions property in the
TutorialOneModel component. You should see the Action editor come up
with the "initAgents" action displayed. 

The initAgents action is a default action in the Default Evolver Model
component. The default code should never be deleted, but you can add
whatever code you like here. This is the place to add any agent
initialization code.

The default code should look like:

for agent as __AGENT_NAME__ in self.agentList:
  agent.setModel(self)
  agent.init()

what this code does is to iterate through all the agents in the list
of agents and give each one a reference to the model, and call the
init action on each agent. The list of agents is constructed by the
network source that we defined in the previous step. 

13. Add the following code to the source panel for initAgents. Before
the for loop, add 

i = 1

Between agent.setModel(self) and agent.init() add

agent.setLabel("id - " + i)

After agent.init(), add

i = i + 1

So the new complete code looks like:

i = 1

for agent as __AGENT_NAME__ in self.agentList:
  agent.setModel(self)
  agent.setLabel("id - " + i)
  agent.init()
  i = i + 1

Make sure the code lines up as it does above.

We want to give each agent a numerical label, and the agentInit action
in the model component is the place to do this kind of
initialization. What our new code does is create a variable i and set
it equal to 1. We then iterate through the list of agents and set the
label for each agent to "id - " and whatever the current value of i
is. Then we set the current value of i to equal its previous value
plus 1.

14. Click on the TutorialOneAgent component in the project pane to
display its properties in the property pane.

15. Click on the actions property's edit button to display the actions
editor and chose the step action from the combo box if it is not
already displayed.

16. In the source pane of the step action, type

print self.getLabel()

This will print this agent's label to the console everytime this agent's step
action is executed. 

This step action is a default action provided by the Default Evolver
Node component. It is here in the step action where you should define
your agent's behavoir. Each iteration of the model, this step action
is executed for every agent.  In the above, we defined the
TutorialOneModel component so that it would create 10
TutorialOneAgent-s and link them randomly. In addition we assigned
each of these ten a different numeric id. These agents are created
using the TutorialOneAgent component as a template. The 10 are
separate however, and thus although each one has the same step action
(i.e. print self.getLabel()), their actual labels will be
different.


17. Save your project as in step 8. You can overwrite your previous
save.

You have now defined the properties of your core components so that
when the simulation is run,

a. A random network of 10 nodes is created (done in steps 10 and 11).
b. A numeric id is assigned to each agent created in a. (steps 12 and
13).
c. Every iteration of the model, each agent will print out its id to
the console (steps 15 and 16).

It is now time to compile and run the simulation.

18. Choose compile from the project menu, or click the compile button
(the button with the two swirly arrows) on the toolbar.

This compiles the project into Java code in order that it can be run
like any other RePast simulation. If there are any errors in your
code, they should be displayed together with an error message.

19. Choose run from the project menu or click the run button (the
button with the large sideways triangle) on the toolbar.

This will run the simulation. 

You should now see the user interface for your RePast simulations. You
controll it via the toolbar (the bar with the buttons and tick count
on its right side). You'll also see a window with settings for your
simulation. 

20. Press the step button (the second button on the left) on the
RePast toolbar. 

This will step through one iteration of the simulation. You should see
the appropriate node ids printed out to the console.

When you start the RePast simulation the following happens:

a. a random network is created with 10 nodes. These are placed into a
variable called agentList contained by the model. (Recall that in the
model's initAgents action we iterated through this list.)

b. TutorialOneModel's initAgents action is executed.

c. The simulation loop begins. This loop executes the step action on
each node in the agentList created by the network source (a. above),
and then increments the tick count.

21. Exit the RePast simulation by clicking on exit button (the button
with the big red X).


TUTORIAL 2

We now want to add some additional features to our simulation. The
numeric node labels will now be some random number between a user
defined minimum and a user defined maximum. The intention here is to
demonstrate what parameters are and how to use them.

1. Start evolver if it is not already started.

2. Click on the open button (the open folder) on the toolbar or choose
open from the file menu, and open the file where you saved the
tutorial1 model (e.g. tutorial1.xml).

You use "open" to load previously saved simulations.

3. Rename the project Tutorial 2, by clicking on the project icon in
the project pane and changing the project name property.

4. Change the model display name to Tutorial 2, and the modelName to
TutorialTwoModel by clicking on the model (labeld TutorialOneModel) in
the project pane, and changing the display name and model name
properties appropriately.

5. Rename the agent to TutorialTwoAgent by clicking on the agent in
the project pane and changing the name property appropriately.

6. Save your project as tutorial2.xml

In order to set the node labels randomly between some user defined
minimum and maximum, we need some way for the user to input new
parameter values into the simulation once it is compiled and run. We
do this by defining parameters in our model component. These
parameters are then displayed in the parameters settings panel of the
resulting RePast simulation.

7. Click on TutorialTwoModel and click on the parameters property edit
button. 

This will bring up the Parameter Editor. You'll see several parameters
already defined. Do not edit these. Evolver will silently add
parameters to allow you to control your simulation once it is
compiled. In this case, the Evolver defined parameters that you see
are created as part of choosing a the random density network
source. Changing the values of these parameters will change the
structure of the initial network.

8. In the parameter editor fill in the following:

name - labelMin
type - int
DefaultValue - 10
Probeable - true (click it to check the box).

Then click add. You should see it added to the list of parameters in
the parameter table.

All this adds a parameter called labelMin to TutorialTwoModel. This
parameter is of type int meaning that it represents an integer and if
we try to assign anything else to it, we will get an error. It will
have a default value of 10, and is probeable. By making it probeable,
the parameter appears in the parameter settings pane of the resulting
RePast simulation.

In creating a parameter you create a variable of the same name that
can be used from within a components actions, as we shall see
below. However, you also create implicit accessor actions for that parameters,
in this case, a getLabelMin action and a setLabelMin action. This
allows other component's actions access to this parameter.

9. In the parameter editor fill in the following:

name - labelMax
type - int
DefaultValue - 100
Probeable - true (click it check the box).

Then click add. You should see it added to the list of parameters in
the parameter table.

This adds a parameter called labelMax with a default value of 100.

10. Click ok in the parameter editor to register your parameter
changes with evolver.

11. Click on the actions property of TutorialTwoModel and choose the
initAgents action if it is not already selected.

Notice that the variables list now contains our new self.labelMax, and
self.labelMin. The self here means that this variable is part of the
component you are currently editing. If you want to refer to variables
or actions that are part of the currently selected component, you need
to prefix them with self.

12. Delete the lines that read

i = 1
i = i + 1

and add

Random.createUniform()

at the top of the source pane, and add 

i = Random.uniform.nextIntFromTo(self.labelMin, self.labelMax)

after agent.setModel(self)

make sure that this new line is indented correctly. The new code
should look like:

Random.createUniform()

for agent as TutorialOneAgent in self.agentList:
  agent.setModel(self)
  i = Random.uniform.nextIntFromTo(self.labelMin, self.labelMax)
  agent.setLabel("id - " + i)
  agent.init()

Random is a java class that provides random number distributions for
RePast simulations. Here, you've created a uniform distribution and
then drawn integer values between labelMin and labelMax from it. More
info on Random can be found in the RePast javadoc documentation in
evolver/docs/repast/api/index.html

13. Click ok to register your changes to the action property with
Evolver.

14. Save the project. Its okay to overwrite your previous save file.

15. Compile the project by pressing the compile button.

At this point, the Actions Editor should pop-up and display an error
in its Errors pane at the bottom of the editor. The error should read:

Block: TutorialTwoModel.initAgents, line: 3
Compiler Error: Cast class 'TutorialOneAgent' not found
  for agent as TutorialOneAgent in self.agentList:

This means that there is an error in the specified line in the
specified block. In this case, the error is in line 3 of the
initAgents action of the TutorialTwoModel component. The Compiler
Error: line indicates the kind of error and the next line gives the
line where the error occured. The problem is that

Cast class 'TutorialOneAgent' not found 

in the line

for agent as TutorialOneAgent in self.agentList:

What this line does is iterate through all the agents in
TutorialTwoModel's agentList and treat each item in the list as a
TutorialOneAgent. By treating each one as a TutorialOneAgent, the
compiler can ensure that any code in the for loop that references
agent (which is being treated as a TutorialOneAgent) is correct. 

The error says that the cast class 'TutorialOneAgent' cannot be
found. This means that the compiler is having trouble treating each
item in the list as a TutorialOneAgent because it doesn't know what a
TutorialOneAgent is. Recall that the items in the agentList are
created from our agent component template. We renamed this template to
TutorialTwoAgent and so the compiler doesn't know what a
TutorialOneAgent is. So to fix the error we need to change
TutorialOneAgent to TutorialTwoAgent.

To do this, you can just edit the line as with any other text editor,
or if you double click the error or click on the error and press
enter, the problem line will be hightlighted in red and you can then
edit it. (Note that double clicking on the error does not work on some
version of Linux using IBM's java virtual machine.) After you've
edited the code, it should read:

Random.createUniform()

for agent as TutorialTwoAgent in self.agentList:
  agent.setModel(self)
  i = Random.uniform.nextIntFromTo(self.labelMin, self.labelMax)
  agent.setLabel("id - " + i)
  agent.init()


16. click on ok to register your changes with the TutorialTwoModel
component.


17. Save and compile.

You should not receive any errors this time.

19. Run the simulation by clicking the run button on the Evolver
toolbar.

The first thing to notice is the addition of the labelMax and labelMin
parameters in Model Parameters pane of the RePast simulation. As
mentioned above, the other parameters are "silently" created by the
random network source in Evolver and can be edited to change how the
random network is created.

20. Click the step button (second from left) to run one iteration of
the simulation.

You should see something like:

id - 47
id - 41
id - 30
...

printed to the console. Note that the id number is now some random
number between 10 and 100. 

21. Click the stop button (the blue square) on the RePast toolbar, and
then the setup button (the swirly arrows). 

Stop stops the simulation run, and setup prepares it for another run
by, among other things, setting the parameters back to their default
values.

22. Enter 1 in labelMin and 5 in labelMax. Press the step button.

You should now see something like:

id - 5
id - 1
id - 1
...

on the console. The point is that by defining parameters in Evolver
which compile to parameters in the resulting RePast simulation you can
alter the initial conditions of the simulation.

23. Play with the parameters and run some simulations, if you
like. Then exit the simulation by pressing the exit button (the big
red X).


TUTORIAL 3

The next iteration of our simple simulation will add more complicated
agent behavoir as well as a display. In this version of the
simulation, each agent will have some integer amount of wealth. Each
iteration each agent (the "self" agent) will attempt a "transaction"
with another agent that it is linked to. This other agent will be
chosen at random from all the other agents that this agent is linked
to. The "transaction" works as follows. If the other agent has more
wealth than self, and that agent's wealth is greater than two, then
two units of wealth will be taken from the other agent and given to
self. If the other agent has less wealth than self, then self removes
the link to the other agent, andcreates a new one with an an agent
chosen at random.

1. Open Evolver and load the Tutorial 2 model, if you don't already
have it open.

2. Rename the project, model display name, model name and agent
component name to Tutorial 3, Tutorial 3, TutorialThreeModel and
TutorialThreeAgent respectively. At this point you should know how to
do this. If not, follow the beginning steps for the second iteration
of our simple simulation, given above.

3. Save your project as tutorial3.xml.

4. Click on the Network Display component (the button with the big eye) in the
network component palette. Click on TutorialThreeModel. 

You should see a new component added to the project tree. This
component will be labeled EvNetworkDisplay. Most components are added
the model component, although some may be added to the agent. See the
Evolver Component reference for what can be added to what.

5. Click on EvNetworkDisplay if it is not already highlighted to
display its properties.

6. Choose circular from the layout property. 

The layout property defines how the network will be laid out on the
display. Circular will layout the nodes in a circle; Fruchman-Reingold
will layout the nodes according to the Fruchman-Reingold algorithm (a
"simulated annealing" type graph layout); Kamada-Kawai will layout the
nodes according to the Kamada-Kawai algorithm (this one is a bit
buggy); and Random will layout the nodes randomly. The Edit button can
be used to set properties specific to each type of graph layout.

That's it for adding a dispaly. We'll now add some more complicated
agent behavoir.

7. Save your project. Its okay to overwrite your current save file.

8. Click on TutorialThreeAgent.

9. Add a new parameter to TutorialThreeAgent called wealth. It should
be of int type with a default value of 0, and not probeable.

10. Click on the edit button of the actions property in
TutorialThreeAgent, and select the step method if it is not already
selected.

11. Delete all the source code from the step action.

12. Add the following to the step action.

if (self.getNumOutEdges()):
  otherAgent = (TutorialThreeAgent)self.getRandomNodeOut()
  otherWealth = otherAgent.getWealth()
  if (otherWealth > self.wealth and otherWealth > 2):
    self.wealth = self.wealth + 2
    otherAgent.setWealth(otherWealth - 2)
  else:
    self.removeEdgeTo(otherAgent)
    self.makeRandomOutEdge(self.model.getAgentList(),
				DefaultDrawableEdge(), false)

else:
  self.makeRandomOutEdge(self.model.getAgentList(), DefaultDrawableEdge(), 
						false)

self.setLabel(String.valueOf(self.wealth))


Make sure that the code is indented exactly as it is above. Here's the
same code with line numbers added for reference.

1.  if (self.getNumOutEdges()):
2.    otherAgent = (TutorialThreeAgent)self.getRandomNodeOut()
3.    otherWealth = otherAgent.getWealth()
4.    if (otherWealth > self.wealth and otherWealth > 2):
5.      self.wealth = self.wealth + 2
6.      otherAgent.setWealth(otherWealth - 2)
7.    else:
8.      self.removeEdgeTo(otherAgent)
9.      self.makeRandomOutEdge(self.model.getAgentList(),
				DefaultDrawableEdge(), false)
10.
11. else:
12.   self.makeRandomOutEdge(self.model.getAgentList(), DefaultDrawableEdge(), 
						false)
13.
14. self.setLabel(String.valueOf(self.wealth))

Line one here checks that the current agent (the "self" agent) has out
edges. If so, then the indented code under the if statement is
executed. Line 2 gets an other agent at the other end of one of self's
out edges, and stores that agent in a variable called otherAgent. The
"(TutorialThreeAgent)" is called a cast, and ensures that the node
returned from getRandomNodeOut will be treated by the compiler as a
TutorialThreeAgent. Line 3 gets the amount of wealth this other agent
has and stores that number in a variable called otherWealth. Line 4
tests that the other agent has more wealth than self and that this
amount of wealth is greater than 2. We test that the amount is greater
than two, so that wealth never falls below 0. If this test is true,
then line 5 and line 6 add two units of wealth to self, and remove 2
units from the other agent. Lines 8 and 9 are executed if the test on
line 4 fails. Line 8 removes the edge to the other agent, and line 9
makes an edge at random between self and an agent in the list of all
the agents. self.model contains this list and we get it by calling the
getAgentList method. The false argument ensures that we do not get any
self loops as the result. Line 12 gets executed if the test in line 1
fails. Line 12 is identical to line 9. The last line ensures that the
displayed label for self is updated to self's current wealth
amount. String.valueOf(...) returns the value of the self.wealth
parameter as a String (a list of text characters) suitable for a
label.

13. Click ok to save your changes

14. Rename the labelMin and labelMax parameters in TutorialThreeModel
to wealthMin and wealthMax and the their respective default values to
10 and 20.

Recall that you edit parameters by bringing up the parameter editor
and then clicking on the parameter property you want to edit in the
parameter table. For example, to edit the name of the labelMax
parameter, click on the labelMax in the parameter table, delete the
text and type in wealthMax. Do the same to edit the default
value. Press enter after each change.

We now have a range of wealth from a minimum of 10 to a maximum of
20. What we want to do now is assign some value from this range to
the wealth parameter of each agent. Recall that this kind of
assignment is done is the model's initAgent's method. So,

15. Bring up the actions editor to edit the initAgents action. (Click
on the edit button for TutorialThreeModel's action property, and
select the initAgents action if it is not already selected.)

16. Replace the references to labelMin, labelMax and the variable i
in the line

i = Random.uniform.nextIntFromTo(self.labelMin, self.labelMax)

with wealthMin, wealthMax and wealth respectively. The line should now
look like

wealth = Random.uniform.nextIntFromTo(self.wealthMin, self.wealthMax)

This will assign a random integer from the range defined by
self.wealthMin and self.wealthMax to the variable wealth. Replacing i
with wealth is not necessary here, but it does give a clearer idea of
what this random integer will be used for.

Beneath this newly edited line, add

agent.setWealth(wealth)

This will set the agent's wealth to the value of the wealth
variable. When you created the wealth parameter for
TutorialThreeAgent, Evolver silently created getWealth and setWealth
accessor methods for you. You use the setWeath method to set the
wealth value and the getWealth value to get the value.

Edit the line

agent.setLabel("id - " + i)

to read

agent.setLabel(String.valueOf(wealth))

This sets the label of the node to text value of the value of the
wealth variable.

Lastly replace the reference to TutorialTwoAgent in the for loop
header to TutorialThreeAgent, just as you did in the second iteration
of the simulation. The entire action source should now read:

Random.createUniform()

for agent as TutorialThreeAgent in self.agentList:
  agent.setModel(self)
  wealth = Random.uniform.nextIntFromTo(self.wealthMin, self.wealthMax)
  agent.setWealth(wealth)
  agent.setLabel(String.valueOf(wealth))
  agent.init()

Click ok to save your changes.

17. Save and compile.

18. Run the simulation.

When you click the run button on the RePast toolbar, you should see a
circular display of the network with the wealth displayed on each
node. However, the wealth label and the links do not change while the
simluation is running, although they should.

In this case, the simulation is running correctly, wealth is being
altered and links are being created a destroyed, but the display is
not updating to show the changes. We need to edit the
EvNetworkDisplayComponent for this to work.

19. Exit the RePast simulation and click on the EvNetworkDisplay
component. Then click on the schedule property's edit button. This
will bring up the schedule editor.

Evolver allows you to schedule components actions to execute at
certain times in the simulation. Recall that when you run a RePast
simulation the tick count on the toolbar increase by one for each
iteration of the simulation. You can schedule component actions
against these ticks with the schedule editor.

In our case, we'd like to update the display every iteration of the
simulation, that is, at every tick. So,

20. Select the update_display action from the combo box of actions in
the schedule editor.

The actions box lists the actions available for scheduling, some of
these may be user defined via the actions property and some may be
internally defined by the component. The two listed here are
internally defined by the EvNetworkDisplay component.

21. Select EVERY_TICK from the execution combo box and make sure that
the tick text area reads 1.

The execution combo box lists the types of execution you can use to
schedule your action. These types are 

1. EVERY_TICK -- the specified action executes every tick beginning at
the tick specificed in the tick box.

2. AT A SINGLE TICK -- the specified action executes once at the tick
specificed in the tick box.

3. AT INTERVAL -- the specified action executes at the interval
specified by the tick box (e.g. every three ticks).

4. AT END -- the specified action executes at the end of the RePast
simulation, that is, when the stop button is pressed. The tick box is
ignored in this case.

4. AT PAUSE -- the specified action executes at a pause in the RePast
simulation, that is, when the pause button is pressed, or when the
step button is pressed (step runs a single iteration and then
pauses). The tick box is ignored in this case.

The execute last check box is available for the AT INTERVAL and AT A
SINGLE TICK types. Checking execute last check box ensures that the
specified action will execute after any regularly scheduled
actions. So for example, if action x is scheduled to execute every
tick beginning at 1, and action y is scheduled to execute only at tick
3, and has execute last checked then y will execute after x at tick 3.

The master schedule property in the model component gives you a view
of all the scheduled actions in relation to each other. You can edit
their relative order there.

22. Click the add button to add the action execution to the table. 

To delete an action execution click on it in the table and click the
delete button. 

There is no way to edit actions other than deleting them and re-adding
them.

23. Click ok to register your changes with the component.

24. Save and compile.

25. Run the RePast simulation. 

The wealth of each node will change a bit a first and then settle
down as nodes begin to swap wealth back and forth.


The samples directory contains several more sample models. They are
good examples of how to create more complicated Evolver models.


