Barnes D.J., Chu D. Introduction to Modeling for Biosciences

Подождите немного. Документ загружается.

3.2 An Outline of Repast Concepts 83

method does not alter the agent’s state, it just tells us something about part of its

state. Such methods are often called accessor methods. In contrast, the infect

method is known as a mutator method because it modiﬁes (i.e., mutates) the state

of an agent. In this case, a mosquito’s infection properties are altered.

The bite method illustrates interaction between a mosquito and another type

of agent, a human. If the bitten human is already infected then the mosquito be-

comes infected. Similarly, if the bitten human is not infected before the bite but the

mosquito is, then the infection is passed on to the human. Finally, the step method

represents the passage of simulation time, causing an infection within a mosquito

to progress and possibly die out. There will almost certainly be other interactions at

each step but we have omitted these from Code 3.1 for the sake of simplicity.

What our example class does not show is: (i) how the humans in the neighbor-

hood of a mosquito are identiﬁed and passed to its bite method, and; (ii) how

and when the step method is called. In order to illustrate these aspects we would

need to explore further classes and the simulation infrastructure as a whole, which

would be too complicated for this point in the chapter. Instead, we prefer to intro-

duce those elements when we take a detailed look at the Repast toolkit. In the next

section we will begin our look at Repast, then, in later sections, we give a more

detailed, step-by-step introduction to using the toolkit in practice.

3.2 An Outline of Repast Concepts

Repast stands for Recursive Porous Agent Simulation Toolkit. Repast Simphony—

often abbreviated as Repast S, or simply Repast—is part of a family of modeling

tools. Repast is a sophisticated modeling environment that supports not only the

programming of models, but also their visualization and data analysis. While vi-

sualizations are often unnecessary once a model or simulation has been fully de-

veloped, their value in ensuring that a model is working as it should in the early

stages of development cannot be overestimated, and Repast makes it particularly

easy to create visualizations and other forms of displays. For the purposes of this

chapter, we will assume that the reader has obtained the latest version of Repast S

and installed it according to the installation instructions. Repast’s developers main-

tain an active, support mailing list that caters for both novices and experienced

users.

Repast has been made available as a plug-in to the free open-source Eclipse In-

tegrated Development Environment (IDE) [16]. However, it is important to appre-

ciate that the Repast toolkit is essentially independent of Eclipse, and programs

developed with it can be run independently of Eclipse. This becomes particularly

important when we have moved beyond the development stage and want to start

generating results from multiple simulation runs. As a general-purpose program-

ming environment, Eclipse provides a convenient platform within which to create

Repast programs. The down-side of using Repast within a general-purpose IDE is

that Eclipse contains a lot of features that don’t necessarily have anything to do with

agent-based modeling, and could therefore be distracting. It can also be difﬁcult, at

84 3 ABMs Using Repast and Java

times, to appreciate which parts of the environment are Eclipse and which parts are

Repast. The major positive, however, is that Eclipse provides a lot of sophisticated

programming and debugging support that would probably be beyond the resources

of the Repast developers to provide in addition to the modeling functionality. As

modelers, therefore, we beneﬁt signiﬁcantly from the synergy between the two ap-

plications.

While we will primarily be looking to build ABMs using Java, it is worth noting

that Repast also supports agent modeling via ﬂowcharts and Groovy code [24]. In

this chapter we will make use of ﬂowcharts but we won’t be looking at Groovy.

However, the reader should be aware that all ﬂowcharts are automatically converted

into the corresponding Groovy source code, and it is possible to see the two forms

alongside each other during model development. Even if one is unfamiliar with

Groovy, this form can sometimes be useful when debugging a model and the error

is not clear from looking at the ﬂowchart.

Whichever language is used to program them, agents in Repast correspond to

Java objects at runtime in the way we have described above. In Repast terminology

agents

are deﬁned in terms of Properties and Behaviors. As we illustrated above,

in object-oriented terminology, properties are the instance variables and behaviors

are the methods of their class.

3.2.1 Contexts and Projections

Within an ABM there are likely to be hundreds or perhaps even hundreds of millions

of individual agent instances. It is inevitable that these must be organized in some

way. For instance, if our model uses a synchronous, time-driven algorithm, then we

need to be able to “visit” every agent at each time step and tell it to execute its rel-

evant behaviors. Programming language libraries will often contain list-like struc-

tures that are suitable for this purpose, for instance an ArrayList or Linked-

List from the Java standard API, or the vector class from the C++ standard

library. However, aside from the need to organize the agents for the sake of the gen-

eral simulation logic, it will usually also be necessary to organize them within the

“environment” that is an explicit part of the model. For instance, the geographical

area inhabited by mosquitoes, or the cellular structure occupied by proteins. The

characteristics of these environments will tend to have a signiﬁcant effect upon the

state of the agents and the interactions between them—the physical proximity of

humans and mosquitoes affects their ability to infect each other, for instance.

Repast provides two distinct structuring devices for organizing agents: Contexts

and Projections. These are always used in combination. Successful modeling within

Repast relies on an appreciation of the differences between them.

Strictly speaking, the sorts of agents we shall be concerning ourselves with are called proto-

agents in Repast S, where the term agent is reserved for proto-agents that exhibit learning behavior.

However, for the sake of consistency with the rest of this book we will not use the term proto-agent.

3.2 An Outline of Repast Concepts 85

• Contexts provide the way to group agents without regard to any spatial or struc-

tural arrangement between them. A context is used, therefore, to indicate that a

set of agents are related in some way. Neither agents nor projections have any

useful existence outside of contexts within Repast.

• Projections are subordinate to contexts. They impose a spatial or structural ar-

rangement on the agents within a given context.

Once an agent has been created, it must be added to a context. The projection ap-

plied to that context then describes the relationships of the agents to each other

within the context. For instance, at the start of a mosquito simulation we might

create all the mosquito and human agents we require and place them together in a

single context because we want them to be aware of each other and to be able to

interact. In order to impose a geographical structure on them we would create and

add a projection to the context. For instance, it could be a two-dimensional discrete

grid projection, or a two-dimensional continuous projection. The chosen projection

would determine aspects such as the physical area occupied by the agents. The scale

of the projection used for the mosquitoes and humans would be related to the sizes

of the agents’ movements. A wide range of projection types is available within the

Repast API: N-dimensional continuous (ﬂoating-point coordinate) spaces; single-

and multi-occupancy N-dimensional cellular grids; GIS Geospacial coordinate sys-

tems; and network/graph relationships.

There is always a root context, which is a top-level context to which all agents

belong by default. In many models, this single context will be sufﬁcient but contexts

also can be organized in a nested, hierarchical structure to ﬁt the needs of a model.

A second-level of multiple contexts might be nested within the root context, there-

fore. Such an arrangement would be an ideal way of partitioning bacteria between

different hosts in a model of ﬁmbriation (see Chap. 2), for instance. An individual

bacterium would be placed in a single sub-context but the model might permit it to

move to a different one over the course of the simulation. In other types of models,

a single agent might exist simultaneously in multiple contexts. In addition, contexts

may be nested to any level in order to provide different sub-groupings of agents

within an overall root context For instance, individual people are often members of

family groupings, work groupings, and other social groupings. Each such grouping

could be represented as a different context in Repast.

Note that grouping in a context tells us nothing about physical location or con-

nectedness of the agents, only that some form of relationship between the contained

agents exists. Each context will have its own projection to provide the structuring. It

follows that a single agent may be related in many ways to other agents through dif-

ferent projections simultaneously if they exist in multiple contexts. Think, for exam-

ple, of work relationships. While at their workplace an individual will be physically

located in a particular geographical location, with work connections to co-located

colleagues; yet they may also be in phone or email contact with other colleagues

who are geographically much more widely separated. This connectivity might be

represented by a network projection applied to that individual’s work context in

Repast. A network projection does not necessarily imply a bounded physical space.

86 3 ABMs Using Repast and Java

In summary, while a single context-projection pairing for all agents may be suf-

ﬁcient for many ABMs, it is still worth being aware of the sophistication that is

available within Repast with respect to agent organization, through the nesting of

contexts and application of projections.

An important consequence of the use of projections to indicate both spatial and

structural arrangements is that agents themselves are freed both from the respon-

sibility for maintaining their location and from keeping track of their neighbors.

This approach often considerably simpliﬁes the basic internal structure of an agent,

and allows sophisticated relational operations to be provided by specialized pro-

jection objects. We shall see how this works in practice when we look in detail at

an implementation of the Game of Life, where cells have no need to “know” their

own location. Access to neighbors’ state can be delegated to a library query opera-

tion.

3.2.2 Model Parameterization

Having a readily-available description of the overall structure and parameters of

a model can be both important and useful. In Repast, details of all the essen-

tial elements of a model that we have looked at so far—the agents, contexts

and projections—are captured in a special model deﬁnition ﬁle that Repast calls

model.score (“the score ﬁle”). We will look at the details of this in Sect. 3.3.1.

This ﬁle is separate from the code of the model and is usually the ﬁrst aspect to

be deﬁned when creating a new model; how to create this ﬁle and what precisely

it does will be discussed extensively in the context of the following case-studies.

One reason it is important in Repast is because the information it holds is used by

other tools, such as for those concerned with model visualization, data storage and

charting. For instance, the visualization tool takes the set of agent types deﬁned

in the score ﬁle and provides a default visual representation for each, making it

possible to obtain a visual display of the progress of the simulation for no coding

effort at all. If desired, the default display can be customized, for instance to use

different colors to signify different infection states in malaria agents. The visual-

ization also offers interactive inspection of agent state, which is very useful when

debugging a mis-behaving model—again, at no programming cost to the modeler.

Features such as these make Repast very attractive to use—practically all of the

programming effort is spent creatively on the model rather than on its external rep-

resentation.

When visualization of individual agents is at too ﬁne a level of detail, built-in

charting tools offer the ability to present aggregated data, such as the numbers of

agents of each type, at either every time step or user-deﬁned periodic intervals. We

will see examples of these in the models we explore in detail in this chapter.

Another role of the score ﬁle is to support external model initialization and

run variation. By deﬁning parameters—such as numbers of agents, projection

sizes, and so on—outside the code of the model, it becomes a lot easier to run

3.3 The Game of Life in Repast S 87

models with different parameter sets. Access to the external parameters is ob-

tained from within the model’s code via library classes that are part of the Repast

API.

There are further tools that facilitate different forms of loading and saving of data

from the runtime environment. For instance, data loader classes are provided that

can read model and agent data from an external text ﬁle or XML speciﬁcation. Simi-

larly, freezing and rehydration classes allow dynamic program states to be saved and

restored, while outputters provide a convenient way to output the results of a sim-

ulation without having to write one’s own code. Finally, every modeler’s essential

requirement—random number generation—is supported through the Repast library,

which provides many different distributions types, such as uniform, exponential,

Poisson, etc.

In a sophisticated toolkit like Repast, there are many well-developed features

that make the modeler’s life a lot simpler than if they were writing everything from

scratch. However, rather than catalog every feature in the form of text, it is proba-

bly better to illustrate those features we have described with a couple of practical

examples: the Game of Life, and the Malaria model, both of which were discussed

in Chap. 2.

3.3 The Game of Life in Repast S

In this section we are going to walk through the creation of a full model of Con-

way’s Game of Life, the rules for which are described in Sect. 2.3. Modeling this

will allow us to explore a wide range of the toolkit’s features, such as agents, con-

texts, projections, ﬂowcharts and displays. This section is best read at a computer

with Repast running, so that the reader can either follow the code we have already

created, or create a version for herself. The ﬁnished code of this example can also

be downloaded from this book’s web site.

We will start by describing the overall structure of the model, in terms of con-

texts, projections and parameters, in the form of the model.score ﬁle. We will then

develop the code for the agent in the form of a ﬂowchart. This will cover all the

issues associated with accessing neighbor state and the rules for updating an agent’s

state. We then describe how to create a model initializer, in order to set up the start-

ing point for the model. This is followed by an introduction to how to set up a

visualization of the progress of the model.

The Game of Life is conveniently simple to model: it consists of a collec-

tion of identical agents arranged in the form of a grid. In Repast terminology,

the agents can all be stored in a single Context (the root context), and a single,

two-dimensional Grid Projection will be applied to them. We need names for the

context, projection and agents, so we will call them Life, World, and Agent re-

spectively. These details will all be recorded in the score ﬁle before we write any

code.

88 3 ABMs Using Repast and Java

Fig. 3.1 Initial model.score

ﬁlefortheGameofLife

3.3.1 The model.score File

We start to build our model by creating a project within the Eclipse environment.

From the File menu at the top-left corner, select New → Other. . . and Repast Sim-

phony Project. Select the Next button and name the project Life. We don’t need

any further conﬁguration at this stage, so now select the Finish button. In the Pack-

age Explorer area to the left of the Eclipse window there should now be a new

folder named Life and the main area of the window should have opened a tab named

model.score with an icon named Life at its top-left corner (Fig. 3.1). If something

other than this happened, please refer to the Repast S installation procedures to en-

sure that the environment and everything it requires has been properly installed.

The model.score ﬁle is where the overall structure of the model is described, in

terms of the contexts, projections, agents and a model initializer. The Life icon al-

ready in place represents the root context. All of a model’s agents must be present in

the root context, regardless of whether we create nested sub-contexts or not. Agents

placed in a nested sub-context are automatically members of its parent context, and

hence the root context.

For the Game of Life we will need a projection that imposes a grid structure on

the agents. We indicate this by right-clicking on the root context icon and selecting

Create Member → Projection – Grid. By default, the projection will be named

Grid but we can change that value, as we will often wish to do so. Right click

over Grid and select Show Properties. The Properties panel should appear towards

the bottom of the Eclipse window. Select the property named Label and change

the current value of Grid to our chosen value of World. Towards the bottom of the

Properties panel, change the value of the Dimensionality property to 2. Nothing else

Eclipse should, of course, already have the Repast Simphony plug-ins installed. This version is

available from the Repast Simphony web site.

3.3 The Game of Life in Repast S 89

Fig. 3.2 Completed

model.score for the Game of

Life

should require changing in this panel, however notice that it is possible to conﬁgure

whether multiple agents may occupy a single cell of the grid via the Multi Occupant

property. The default value of false is appropriate for our model.

To the left of the World icon in the model.score view is a +symbol which reveals

that a Grid projection has some properties. A two-dimensional grid has a Width and

a Height property. The labels for these could be changed, if desired, as could the

default values of 20. We will leave them all unchanged.

The name in the tab of the model.score pane contains an asterisk character im-

mediately to its left. This is an indication that the ﬁle has been changed since it was

last saved. Save the ﬁle either by selecting File → Save, or by selecting the disk

icon, or by using the keyboard shortcut (Control S on some systems).

The next step is to add an agent type to the model. Right click on the Life context

and select Create Member → Agent. The default name will be LifeAgent so change

the value of the Label property to be Agent.

We have nearly ﬁnished outlining the structure of the model but there is one

further important element to add to the root context—a model initializer.Inthe

creation of most models there is a setup process that takes place just once, right at

the start. This is where the initial state of the model is created. In Repast, this is

indicated by adding a pseudo-agent to the root context called ModelInitializer.Add

this via Create Member → Agent, remembering to change the value of its Label

property, and to save the model. The model.score ﬁle should now look like that in

Fig. 3.2.

3.3.2 The Agent Class

TheﬁrststepincreatingtheAgent class is to expand the src folder of the Life

package in Eclipse’s package explorer area (Fig. 3.3). Now right click on the life

90 3 ABMs Using Repast and Java

Fig. 3.3 The Life package in the package explorer

folder below src, select New → Other ···→ Repast Simphony Agent, and click

on Next. Type Agent.agent in the File name ﬁeld and select Finish. Figure 3.4

shows how things should look now: a pair of ﬁles have been added to the life folder

in the package explorer. In addition, a blank frame called Agent.agent will have been

added to the main ﬁle area (Fig. 3.5). This frame is the visual editor for creating

ﬂowcharts. Notice that at the left side of this ﬁle window is a panel containing

ﬂowchart symbols. We will be using these to deﬁne the properties and behavior of

our agent. In addition, the Properties frame underneath contains a list of steps,most

of which are blank. Each ﬂowchart symbol, as well as the ﬂowchart as a whole,

has a distinctive set of steps to be ﬁlled out. The completion of these steps is what

leads to the corresponding Groovy code for an agent. The text in the value column

of step 1 can be changed to something like, “This is a Game of Life agent.”

3.3.2.1 Properties

A feature of agents is that they maintain some form of state, whose value varies

over the course of the model. In Repast, an agent’s state and other persistent vari-

3.3 The Game of Life in Repast S 91

Fig. 3.4 The Life package after addition of the Agent class

ables are provided via Properties.

In the panel of ﬂowchart symbols there is one

named Property. Click on this and place a Property symbol in the blank program-

ming area to the right via a mouse click. A property panel should appear below the

programming panel (right click the new property symbol just placed and select Show

Properties if it does not appear automatically). The panel contains six steps whose

values can be edited to specify details of the new property (Table 3.1). Although the

ﬁnal three are indicated as being optional, we will typically prefer to deﬁne them all

explicitly for the same of clarity.

Not to be confused with the Properties tab that is used to set values for things like the Label

property of contexts and projections.

92 3 ABMs Using Repast and Java

Fig. 3.5 Visual editor for creating ﬂowcharts

Table 3.1 The steps

of a property

Step 1: A comment that describes the property

Step 2: A human-readable diagram label

Step 3: A compilable name for the property

Step 4: The property’s accessibility (optional)

Step 5: A type for the property (optional)

Step 6: A default initial value for the property (optional)

A Game of Life agent maintains a simple state, indicating whether it is alive or

dead. Click in the Value cell for step one and enter a comment such as, “Whether

the agent is alive or dead”. A label for step 2 might be, “Current State”—this will

appear in the programming panel above the property icon. For step 3, an appropriate

name for the property would be currentState; the name chosen must match the

rules for variable names in Java, so it is not possible to include spaces, for instance.

Step 4 relates to the visibility or accessibility level of the property to other entities

in the simulation. There are eight options available from the drop-down menu in