A. Introduction

This document is a reference to the components that ship with
Evolver. If you are unfamiliar with Evolver and how it uses
components, please see the document entitled Evolver.

Some of the Evolver components are based on Java classes. Many of the
methods (roughly equivalent to 'actions' as described in the Evolver
document) in these base classes are available to their corresponding
Evolver components. For example, the Default Evolver Node is based on
the Java class DefaultNode. Among the methods DefaultNode defines is
getNumOutEdges() which returns the number of outgoing edges contained
by that node. Because Default Evolver Node is based on DefaultNode,
the method getNumOutEdges() is an action (a method) of the Default
Evolver Node component and can be used when you write source code for
that component.

The component referrence below will list the Java parent class (if
any) for Evolver components. You can get more information about these
parent classes in the javadoc documentation for RePast. The
information is in html format in
evolver/docs/repast/api/index.html. When you bring this document up in
your browser, you will see a list of Java classes in a frame in the
lower left hand side of the browser. Search this list for the Java
class you are interested in and click on it. The main frame in the
browser should then give a description of the class, its methods, and
so forth.


B. EVOLVER COMPONENTS

The general format of this reference is:

* Component Name

** Type

** Appropriate Parent Type(s)

** Java Parent Class (if any)

** Description

** Property

** Variable (if any)

** Usage (if necessary)

Note that in the final version Evolver will not allow you
to add a component to an illegal parent. This feature is not fully
implemented in the beta release.


1. EVOLVER PROJECT

* Component Name: Project

** Type: Project

** Appropriate Parent Type(s): N/A

** Description:

The project component is the root of all the components in the
component tree. It provides a "package" into which the child
components of a simulation can be put. You cannot manually add or
delete a project component. One is provided for you automatically in
the project pane.

** Property: Project Directory

The directory where the compiled code is saved. This defaults to a
classes directory within the evolver home directory

** Property: Project Name

The name of the project. This is not used internally by evolver, but
is useful for categorizing models.


2. DEFAULT EVOLVER MODEL

* Component Name: Default Evolver Model

** Type: Model

** Appropriate Parent Type(s): Project

** Java Parent Class: SimModelImpl

** Description:

This is a default evolver model. It contains properties for creating a
network of agents, and setting the starting conditions of a
simulation.

** Property: actions

See the section on Actions and editing them in the Evolver document if
you are unfamiliar with Actions.

Default Evolver Model includes a single default action:
initAgents. This action will be executed at the beginning of the
simulation as part of set up. You should NOT delete any of the code
for this action, although you can certainly add to it. The code for
initAgents is as follows:

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

This code iterates through the all the agents in agentList and gives
each one a reference to itself, and calls the init() action on each
agent. If you wish to set some parameter of each agent as part of
setup you would do it here, adding code between agent.setModel() and
agent.init().


** Property: displayName

This name will be displayed as the title of your model when it is
running.

** Property: master schedule

See the tutorial 3 in the Evolver document for more schedules and scheduling.

The master schedule property gives you an editable view of all the
scheduled actions in relation to each other. You can edit their
relative order here. By default, the step action of every agent is
scheduled to execute every iteration of the simulation beginning at
the first iteration.

** Property: model name

The name of the model used internally by Evolver during
compilation. This name should not have any spaces it in it. The java
class created by Evolver has this name.

** Property: Network source

Evolver network simulations are initialized with a network of nodes.
This property defines the structure of that network. Five types are
available, and the attributes (e.g. number of nodes, etc.) particular
to that type of network source can be edited by clicking on the edit
button.

1. Matrix File. The network is created from a file description in
UCINet dl format. The editable attributes are the file name, and its
type. Type refers to the edge strength as given in the dl adjacency
matrix where binary is 0, or 1, small is -128 to 128 and large every
thing else.

2. Random Density. The network is created from the specified number of
nodes, which are then linked at random according to the specified
density.

3. Square Lattice. The network is created as a square lattice.

4. Unlinked Nodes. The "network" is created with the specified number
of nodes that are not linked.

5. Watts-Strogatz Small World. The network is created as a ring
substrate of a Watts-Strogatz type small world.

Note that the attributes of these network source types will become
parameters in your model, showing up in the parameter pane of the
resulting RePast simulation.

** Property: Parameters

See the section on parameters and editing them in the Evolver
document.

Here you can define any parameters you want your model to have.

** Property: Schedule

See tutorial 3 in the Evolver document for more information on the
schedule property.

The schedule property defines the execution schedule of any actions
defined in your model.

** Variable: agentList

This is an ArrayList (a Java class) that contains the nodes of the
network created by the network source. It is possible to get a
reference to this list from outside of Default Evolver Model by using
the built-in method

getAgentList()

So, for example, every agent has a reference to the model, and from
within an agent you can get a reference to the agent list with

list = self.model.getAgentList()


3. DEFAULT EVOLVER NODE

* Component Name: Default Evolver Node

** Type: Agent

** Appropriate Parent Type(s): Model

** Java Parent Class (if any): DefaultNode

DefaultNode has many methods for working with edges, and nodes. See
the javadoc documentation (as mentioned above) for more information.

** Description:

Default Evolver Node is the default agent component in simulations
constructed by evolver. It acts as template from which all the agents
in the simulation are constructed. In this beta release only a single
agent component can be used in your simluation, although the number of
agents created from this template is limited only by your computer.

** Property: Actions

See the section on Actions and editing them in the Evolver document
for more information.

Default Evolver Node defines two actions by default.

1. init

init is called on every agent as part of setting up the model. So, any
custom initialization code would go here. For example, you may set
some custom agent parameters in your model's agentInit action, and
then here you would calculate a new parameter value based on those
passed in values.

Other types of components (e.g. Agent Compileables) may add their own
code to the init action of your agent component. In order to
differentiate your own code from that added by Evolver, you must add
your own code below the comment line reading

## user defined init code below


2. step

The step action is where you define the behavoir of your agents. Of
course, you can have your step action call other actions, but the step
action of every agent created from your agent component is by default
executed every iteration of your simluation.

** Property: Name

The name of the agent. This property is used internaly by Evolver and
must not contain any spaces.

** Property: Parameters

See the section on parameters and editing them in the Evolver
document.

Here you can define any parameters you want your agent to have.

** Property: Schedule

See tutorial 3 in the Evolver document for more information on the
schedule property.

The schedule property defines the execution schedule of any actions
defined in your agent. By default the step action will execute every
iteration beginning at the first.

** Variable: model

Every agent has a reference to the model with which it is
associated. You can use this in your own code as self.model.


4. NETWORK RECORDER

* Component Name: Network Recorder

** Type: ?? (type that adds to models but not agents)

** Appropriate Parent Type(s): Model

** Description:

The network recorder component is attached to a model component and is
used to record the simulated network as an adjacency matrix in one of
three formats to the specified file. The actual network matrix is
written out in the specified format, although relevant non-matrix
information is recorded as well: a file header containing the constant
parameters for the model and a timestamp, and a block header that
contains header information relevant to the network data recorded
beneath it. The block header will contain the value of any dynamic
model parameters at the time a network was recorded,.

The actual format of the file is thus:

 file header

 block_header_1
 network data in the specified format

 block_header_2
 network data in the specified format

 ...

Note that you MUST schedule some actions in order for the Network
Recorder to work. See the Schedule property below for details.

** Property: File Name

This is the name of the file to record the network to. The name itself
must be in the format expected by your operating system.

** Property: Format

The format to record to the data to. This can be one of three types.

1. DL. UCINet dl format.

2. Excel. UCINet excel spreadsheet format. This is very slow and only
available on Windows. Not Recommended.

3. ASCII. Records the matrix and the matrix labels in comma delimited
plain text suitable for import in to Excel or UCINet.

** Property: Matrix Type

The matrix type refers to a range of edge strenghs recorded as values
in the matrix cells, and can be one of three types.

1. Binary. The edge strengths of the recorded network is 1 or 0
(presence or absence).

2. Small. Strengths from -128 to 128.

3. Large. Everything else.

You should always choose the smallest possible type.

** Property: Name

The name of the recorder component. This name is used internally by
Evolver and should not contain any spaces. There is no real reason to
change the default value.

** Property: Schedule

See tutorial 3 in the Evolver document for more information on the
schedule property.

Although there are no user-definable actions associated with the
Network Recorder component, Evolver implicitly defines two actions
that you MUST schedule in order for recording to work. These two
actions are:

1. record - this records the current structure of the network at the
time this action is executed.

2. write - this writes whatever has been recorded by calls to the
record action up until this point.

A typical execution scheme for the Network Recorder might have the
record action schedule to execute at some small interval such as 5,
executing last, and write executing at some larger interval such as 10
or 20, and also executing last. Its important to also schedule write
and record to execute AT END in order to capture any new data created
between the recording intervals.

Note that you can edit the relative order of your action executions in
the master schedule property of your model component. Doing so, you
can ensure that record and write are executed when you want them to
relative to the rest of your simulation.


5. NETWORK DISPLAY

* Component Name: Network Display

** Type: ?? (type that adds to models but not agents)

** Appropriate Parent Type(s): Model

** Description:

The Network Display component is used to visualize the network as a
graph. A variety of graph layouts are available.

** Property: height

The height in pixels of the display window.

** Property: Layout

The layout property defines how the network will be laid out on the
display. There are four types of layouts and you can edit the
particular attributes of each layout by clicking the edit button.

1. Circular. Lays out the nodes in a circle

2. Fruchman-Reingold. Lays out the nodes according to a modified
Fruchman-Reingold algorithm. Nodes are positioned according to an
iterative algorithm that assumes that nodes repel each other when
close, but are attracted to connected nodes. Convergence is obtained
by using a "simulated annealing"-style technique with an arbitrary
cooling function.  See, Fruchterman, T.M.J and Reingold, E.M. (1991)
"Graph Drawing by Force-directed Placement" in Software-Practice and
Experience, Vol 21(11), 1129-1164.

3. Kamada-Kawai lays out the nodes according to a modified
Kamada-Kawai algorithm. The Kamada-Kawai graph layout attempts to
position nodes on the space so that the geometric (Euclidean) distance
between them is as close as possible to the graph-theoretic (path)
distance between them. See, Kamada, Tomihisa and Satoru Kawai (1989)
"An Algorithm for Drawing Undirected Graphs" Information Processing
Letters 31:7-15.

Note that the Kamada-Kawai is a bit buggy and may crash your
simulation.

4. Random. Lays out the nodes at random.


Fruchman-Reingold and Kamada-Kawai are considerably slower than
circular or random, particularly with large networks.

When the RePast simulation is running and the display is visible, you
can move the nodes with the mouse by clicking and dragging them.

** Property: Node Shape

For now only oval is available.

** Property: Schedule

See tutorial 3 in the Evolver document for more information on the
schedule property.

Although there are not user-definable actions associated with the
Network Display component, Network Display implicitly defines two
actions. These two actions are:

1. update_display. This will update the display showing any changes to
node color, label, and links since the last call to update_display.

2. update_layout. This will update the layout of the nodes, that is,
their x and y coordinates in the display window. Provided the nodes
have not moved their is no real reason to schedule the update_layout
action for execution if you are using the circular or random
layouts. However, if you are using Fruchman-Reingold or Kamada-Kawai
where the x and y coordinates are dependent on node links, then you
probably want to schedule update_layout for execution.

Typically, update_display is scheduled for execution every tick
(iteration) and the scheduling of update_layout depends on the size of
the network and how long you are willing to wait between
iterations. As mentioned above, Fruchman-Reingold and Kamada-Kawai are
comptuationaly expensive algorithms and can be slow.

** Property: width

The width in pixels of the display window.


6. NODE LINKER (for want of a better name)

* Component Name: Node Linker

** Type: ?? (the type that attaches to agents)

** Appropriate Parent Type(s): Agent

** Java Parent Class (if any): AbstractEvProbRule,
			       AbstractProbabilityRule

** Description:

Node Linker allows you to easily link one node ("i") with another node
("j") according to some user-defined probability. The idea here is
that i will create a link with some other agent chosen at random. The
choice of who to link with is determined by a vector of relative
weights assigned to other agents that i may possibly link with. The
probabilty of i linking with j is determined using these weights, and
that these weights are updated over the iterations of the simulation
in response to network evolution.

For example, the probability of i creating a link with j may be
calculated by dividing j's current weight by the sum of all the
weights in the weight vector. Assuming then that i does link with j,
j's weight may then be updated by some amount increasing the
probabilty that i will link with j again.

The actual usage of Node Linker is described below in the usage section.

** Property: Actions

See the section on Actions and editing them in the Evolver document
for more information.

Node Linker defines two actions by default.

1. getProbabilty. This action is used to calculate the probabilty of
one node linking to another.

2. update. This action is used update the vector of node weights by
the specified amount.

See the Usage section below for more information.

** Property: Name

This name is used internally by Evolver and should not contain any
spaces.

** Property: Parameters

See the section on parameters and editing them in the Evolver
document.

Here you can add any parameters, you'd like your NodeLinker to
have. See the Usage section for more info.


** Property: Start Weight

The starting weight for nodes in the weight vector.

** Variable: discount

A float value between 0 and 1. This can be set with the
setPastDiscount action / method. (There's no real reason why this
shouldn't be a user-defined parameter).

** Variable: sum

The current sum of the weight vector.

** Usage:

Adding a NodeLinker to an Agent component adds two parameters and some
code to that Agent component. The two parameters are:

1. _linker. _linker is of type Linker (see Linker in the RePast
javadoc), and is what an agent will use to create links between
itself and other nodes.

2. startWeight. This corresponds to the start weight property above,
and allows the you to change the start weight when the RePast
simulation is running.

NodeLinker also adds code to the Agent's init action. The code looks
like:

### uchicago.src.simbuilder.beans.NodeLinker Generated Code ###
rule = NodeLinker(self.model.getAgentList(), self.startWeight, self)
self._linker = Linker(rule)

The first line here is a comment and identifies the next two lines as
Evolver (not user) generated code. The next two lines create a
NodeLinker and then create _linker using that newly created
NodeLinker. The important point here is that the NodeLinker here is
created using the NodeLinker component as a template (much the same as
agents are created), and that this NodeLinker is now part of _linker.

Three three important actions / methods that _linker has are:

1. init. The init action initializes _linker for link creation by
recreating the probability map. The probability map is created by
calling the getProbability action of the NodeLinker, passing in each
node to which a link could be created. The map itself maps nodes to
probabilities, the larger the probability the more likely that node
will be chosen as a the end of a link. init should be called before
any calls to makeLink if the result of those calls is to reflect any
updates.

2. makeLink(from, edge, amtToUpdate). Using the current probabilty map
(see 1. above) this method creates an edge between a randomly chosen node and
the from node. It also calls NodeLinker's update action passing in the
randomly chosen node and the amtToUpdate.

3. makeLink(from, edge). This merely calls the above with amount to
update of 1.

The important points here are how _linker uses NodeLinker's
getProbability action to create the probability map, and how _linker
uses NodeLinker's update action to update the weight vector.

Implementing getProbabilty and update -- getProbability and update are
unlike user defined actions in that they have arguments passed in to
them. You can see these arguments in the variables pane of the Action
editor. They are specific to these two actions respectively and are
not prefixed by self.

1. getProbability. This action has a single passed in argument -
otherNode. This "otherNode" is the node for which we want to calculate
the probability. If, for example, we are calculating the probability
by getting the current weight of otherNode and dividing it by the sum
of the all the weights then the source code to getProbabilty would
look like:

return self.getWeight(otherNode) / self.sum

Notice the return keyword here. getProbability must return some
numeric value and the return keyword does this. If you do not include
the return statement, you'll either get an appropriate error message
or a cryptic one reporting Compiler Error: Compilation not supported
on expr_stmt. In either case, you need to return a value.

2. update. This action has two passed in arguments, otherNode and
amtToUpdate. The intention here is that you update the vector of
weights using these values. otherNode is the node whose weight we want
to update, and amtToUpdate is the amount we want to update the
weight. Of course, you can do whatever transformations of this
amtToUpdate value you like, or ignore it all together. The simplest
update to the weight vector looks like:

self.addToNodeWeight(otherNode, amtToUpdate)

which simply adds otherNode amtToUpdate to the current weight of the
otherNode.

The NodeLinker inherits several important methods / actions and
variables from its java ancestors. These are described below.

1. sum. This is the current sum of the weight vector. It is
recalculated each time _linker.init() is called.

2. getWeight(otherNode) - this returns the weight for otherNode.

3. addToNodeWeight(otherNode, amtToUpdate) - this adds the amtToUpdate
to the current weight of otherNode.

See the javadoc for AbstractProbabilityRule for more info.

Using a NodeLinker then is a matter of adding one to an agent
component in the Evolver project pane, and then defining the
getProbability and update methods to suit your own needs. The agent
then uses the _linker parameter provided by the NodeLinker component
to make links based on the probabilities update etc. defined in
NodeLinker. This is typically done in the step action. For example the
following step action code,

self.clearOutEdges()
self._linker.makeLink(self, DefaultDrawableEdge(), 1)

removes any previously created outgoing edges from the agent, and then
creates a new link between this agent ("self") and one chosen at
random. DefaultDrawableEdge is used as the edge, and the weight of the
randomly chosen otherNode is updated by 1.


The sample simulations distributed with Evolver contain some simulations
using the NodeLinker, so see those for more complicated examples.







