Model Builder's Guide Chapter 8

SELES Landscape Agents

Landscape agents (LSA) have a similar structure to landscape events, but differ in their properties. The properties for agents focus on key attributes for creating individual-based models. Table 7 describes the purpose and meaning of each agent property. The fundamental difference between agent-based and event-based perspectives is that events come and go, but agents are persistent. That is, an agent has a clear identity that is maintained as it moves around the landscape, whereas when an active cell event spreads to another cell (even to the same cell), it creates a new active cell event.

A LSA must define the number and location of agents, the rate at which populations are processed, and agent behaviours such as moving, survival and reproduction. Conceptually, individual-agents are clustered into “groups” which are then clustered into “populations”. A LSA is defined by properties that help to separate the agent behaviour from its effects on the landscape. Conceptually, the LSA definition is used to determine the time between instances of population creation (ImmigrationTime property), the spatial locations in which the agents should initiate (AgentLocation, NumPopulations, NumGroups, NumAgents and ProbInit properties), the time interval between population processing steps (PopulationTime property), and individual agent behaviour for movement, survival and reproduction (MoveLocation, MoveProb, NumOffsopring, and Transitions properties).

At the beginning of a simulation, the first populations are created based on NumPopulations. For each population, a number of groups are created based on NumGroups. Then for each group a number of agents are created based on NumAgents, each of which must be placed in a cell. The AgentLocation property is a region that defines the universe of possible locations for initiation. Probability of Initiation (ProbInit) specifies the relative probability of selecting a cell for placing an agent. More than one agent can be within a given cell, and the default for NumAgents is to select with replacement (i.e. each agent selects a cell independently from other agents).

During each time step, agents have the opportunity to move, survive and reproduce. The time interval between these steps is specified by PopulationTime. Unlike event spread, where SpreadTime is unique for each active cell, this time step is the same for all agents within a population. During each iteration, every agent is processed in turn. The first step is to test whether the agent survives to move and/or reproduce, which is specified by Transitions. If this evaluates to TRUE then the agent survives otherwise the agent is terminated.

During each step, agents select a cell to move to (which may include the current cell they are in). The potential set of locations is specified with MoveLocation and the relative probability of selecting any one of these is specified by MoveProb. Note that unlike events, since agents retain identity, they can only move to a single cell, whereas events can spread to multiple cells. After moving agents can create offspring using NumOffspring that start in the same population/group and cell as the parent.

As with landscape events, the properties describe the behaviour of agents as they start and move around in a landscape. Agents will continue moving until they die or the end of the simulation is reached. Note that agents may disappear from the system for two reasons: (i) they explicitly experience mortality according to the Transitions property; or (ii) there is nowhere to move, including staying in the same place. The latter will occur if the MoveLocation is empty or if MoveProb is zero for all cells in the MoveLocation. This effect is consistent with the model specification since in these cases, the model is stating that there is nowhere the agent can move (not even staying still). In general, care should be taken to avoid this situation, in particular if the model requires tracking the number of active agents. A simple way to do this is to ensure that the current cell is always part of the MoveLocation and that it has a non-zero probability (even if very small) of being selected.

Table 7 SELES landscape agent properties. Each property controls a specific aspect of an agent’s behaviour.

Landscape Agent Dynamic Variables and Contexts

The dynamic context variables specific to landscape agents are as follows: (a) Population variables define values that apply to each population. For example, an Elk agent model might declare a population variable called NumBulls that is used to store the number of mature males in the population. (b) Group variables define variables that apply to individual groups within a population. (c) Agent variables define variables associated with individual agents. For example, an agent model called Elk may declare an agent variable called CurrDirection to store the current direction the agent is moving.

The hierarchy for agents is analogous to that of events (Figure 4) with each population having a set of active groups, and each group having a set of active agents. Table 8 shows the default values, and operating and consequent contexts for agents.

Table 8 Value and default for main expression, and context of landscape agent properties.

Landscape Agent Property Details

This section gives a more detailed description of the duty or behaviour of each of the LSA properties. The same notation is used here as in section 6.3 for landscape events.

InitialState

Defines the number of immigration instances to create at simulation startup

Result: A set of immigration instances.

Default: One immigration instance

Context: Preliminary expressions: global

Main Expression: global

Consequent expressions: global (population)

The main expression is any valid global expression defining the number of immigration instances to create at the beginning of a simulation.

Description: This property is useful to set up initial conditions local to an event, and to create multiple immigration instances of an event at startup. The preliminary expressions are evaluated once, while the consequent expressions are evaluated for each instance created. Note that since there is no instance prior to this property, population variables are not available in the preliminary context.

ImmigrationTime

Defines the interval between instances of population creation, and schedules new immigration instances.

Result: Create a LSA instance and update the event queue Q.

Default: Schedule the agent model to immigrate exactly once at simulation startup.

Context: Preliminary expressions: global

Main Expression (rt): global

Consequent expressions: global

The main expression is any valid global expression, rt(S), defining the time elapsed (in time units) between successive immigration events.

Description: At simulation startup, preliminary expressions and main expression, rt(S), are evaluated. The instance is scheduled to occur at rt(S) number of time units in the future. When a LSA instance is taken off the queue, its consequent expressions are evaluated. Then NumPopulations is invoked to process population initiation. Once the instance completes all of its activities, a new immigration instance is created and the preliminary expressions and main expression, rt(S), are evaluated. The new instance is scheduled to occur at rt(S) number of time units in the future.

NumPopulations

Defines the number of populations to create for an immigration instance

Result: A set of new agent populations

Default: One population

Context: Preliminary expressions: global

Main Expression: global

Consequent expressions: population

The main expression is any valid global expression defining the number of populations to create for this immigration instance.

Description: Each immigration event, this property is evaluated and the specified number of populations is created. For each population, NumGroups is evaluated to specify the number of groups within the population to create. If NumPopulations is not defined, then a single population is created.

NumGroups

Defines the number of groups to create for a new population

Result: A set of new agent sub-population goups

Default: One group

Context: Preliminary expressions: population

Main Expression: population

Consequent expressions group

The main expression is any valid population expression defining the number of groups to create for this new population.

Description: After each new population created this property is evaluated and the specified number of groups within the population is created. For each group, NumAgents is evaluated to specify the number of agents within the group to

If NumGroups is not defined, then a single group within each new population is created.

AgentLocation

Defines the set of potential cells in which an agent can initiate.

Result: A set of spatial locations for potential initiation of an agent (InitRegion)

Default: Every cell in the landscape.

Context: Preliminary expressions: global

Main Expression: global

Consequent expressions: spatial

The main expression is any valid spatial region defining the cells in which agents may initiate. Although the consequent expressions are spatial, they can only refer to layer variables and not agent variables, since at this point, new agents have not yet been created.

Description: The set of cells returned by this function defines the landscape as seen during the initiation of the event via ProbInit and NumAgents. Initiation only applies to this set of cells. The preliminary expressions are evaluated once before the main expression, while the consequent expressions are evaluated in each of the cells in the event region.

ProbInit

Defines the relative probability that an agent will initiate in a particular cell.

Result: Transient “probability surface” for cells in the initiation region InitRegion with floating point values indicating the potential of selecting each cell for an agent to initiate (InitProb).

Default: Every cell in the initiation region has a value of 1.0.

Context: Preliminary expressions: spatial

Main Expression: spatial

Consequent expressions: agent

The main expression is any valid spatial expression defining the probability, normally between zero and one, of an agent initiating in a cell. Although the preliminary expressions and main expression are spatial, they can only refer to layer variables and not agent variables, since at this point, agents have not yet been created. The consequent expressions can refer to agent, group and population variables.

Informal Specification: After determining the initiation location, the preliminary expressions and the main expression are evaluated for each cell in the initiation region. The consequent expressions are only evaluated in those cells in which agents actually initiate – see NumAgents below.

NumAgents

Defines the number of agents to create for each new group

Result: A set of agents, each in a cell, the location of which is derived from the initiation region InitRegion and probability of initiation layer InitProb for the LSA.

Default: Every cell i,j in InitRegion has a relative probability of initiating equal to InitProbi,j. (Thus, the location of new agents is stochastic)

Context: Preliminary expressions: group

Main Expression: group

Consequent expressions: agent

The main expression is any valid group expression defining the number of agents to create in the initiation region.

Description: Once ProbInit has produced the “probability surface” InitProb of potential sites, each agent selects a cell for initiation. By default this selection is independent (i.e. with replacement, where more than one agent may be placed in the same cell). Selection without replacement is possible by adding the keywords WITHOUT REPLACEMENT following the NumAgents property name. The cells in which each agent is initiated are selected stochastically from the potential sites based on the probabilities in InitProb (the probabilities are relative). After agents are placed, the consequent expressions for both NumAgents and ProbInit are evaluated.

Transitions

Defines if an agent survives.

Result: A surviving agent (or a terminating agent).

Default: The agent survives.

Context: Preliminary expressions: agent

Main Expression (tr): agent

Consequent expressions: agent

The main expression is any valid spatial expression tr(S), defining a Boolean value.

Description: For each agent, ether after initiation or during the population update loop (after movement and reproduction), the preliminary expressions and the main expression, tr(S), are evaluated. If the result of tr(S) is TRUE (non-zero), then the agent survives. If the agent doesn’t survive, the agent is terminated. Otherwise the consequent expressions are evaluated, and the agent stays in the population pool until the next update step.

PopulationTime

Defines the time between population update steps. On each iteration, all agents are processed to test for movement, reproduction and survival.

Result: Updates the event queue Q

Default: One time unit.

Context: Preliminary expressions: population

Main Expression (pt): population

Consequent expressions: population

The main expression is any valid population expression pt(S), defining the time elapsed (in time units) between each update iteration for the population.

Description: After a population initiates, the preliminary expressions are evaluated. The main expression is then evaluated to determine the length of time between update steps. The next population update step is scheduled on the event queue to occur at pt(S) number of time units in the future. At the start of a population update step, the consequent expressions are evaluated and population is updated, starting with the movement step for each agent.

MoveLocation

Defines the set of potential cells to which an agent can move.

Result: A set of spatial locations for potential movement of an agent (MoveRegion)

Default: The four cardinal neighbours of the agent (north, south, east and west)

Context: Preliminary expressions: agent

Main Expression: agent

Consequent expressions: agent

The main expression is any valid spatial region defining the cells to which the agent may move.

Description: The set of cells returned by this function defines the landscape as seen during the movement of an agent. The preliminary expressions are evaluated once before the main expression, while the consequent expressions are evaluated in each of the cells in the region.

MoveProb

Defines the relative probability that an agent will move to a particular cell.

Result: Transient “probability surface” for cells in the move region MoveRegion with floating point values indicating the potential of each cell for selection by the agent (MoveProb).

Default: Every cell in the move region has a potential value of 1.0.

Context: Preliminary expressions: agent

Main Expression: agent

Consequent expressions: agent

The main expression is any valid agent expression defining the probability, normally between zero and one, of an agent moving to a cell from its current location.

Description: After determining the move region, the preliminary expressions and main expression are evaluated for each cell in the move region. The consequent expressions are only evaluated in the single cell to which the agent actually moves. Note that if the move region is empty, or if no cell in the move region has a positive probability, then the agent has no cells to choose from, and so disappears from the system.

NumOffspring

Defines the number of offspring created by an agent.

Result: A set of agents created within the same group and population, and at the same location, as the parent agent.

Default: None

Context: Preliminary expressions: agent

Main Expression: agent

Consequent expressions: agent & recipient

The main expression is any valid spatial expression defining the number of new agents to create by a given agents.

Description: After movement, each agent has the option to create offspring, which are new agents in the same group, and at the same location as the parent. The new offspring are placed in the population pool until the next population update. After reproduction, the parent agent is assessed for survival (via Transitions). The consequent expressions are evaluated for each new offspring.

Go to...  Prev Chapter  Next Chapter  Guide Index