Model Builder's Guide Chapter 8: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
=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. | 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). | 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). | 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 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. | 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. | 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. | ||
| Line 11: | Line 16: | ||
'''TABLE MISSING''' | '''TABLE MISSING''' | ||
==Landscape Agent Dynamic Variables and Contexts== | |||
The dynamic context variables specific to landscape agents are as follows: | 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. | (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. | ||
| Line 23: | Line 28: | ||
'''TABLE MISSING''' | '''TABLE MISSING''' | ||
==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. | 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 | Defines the number of immigration instances to create at simulation startup | ||
Result: A set of immigration instances. | Result: A set of immigration instances. | ||
Default: One immigration instance | Default: One immigration instance | ||
Context: Preliminary expressions: global | Context: Preliminary expressions: global | ||
Main Expression: global | Main Expression: global | ||
Consequent expressions: global (population) | 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===ImmigrationTime=== | |||
Defines the interval between instances of population creation, and schedules new immigration instances. | Defines the interval between instances of population creation, and schedules new immigration instances. | ||
Result: Create a LSA instance and update the event queue Q. | Result: Create a LSA instance and update the event queue Q. | ||
Default: Schedule the agent model to immigrate exactly once at simulation startup. | Default: Schedule the agent model to immigrate exactly once at simulation startup. | ||
Context: Preliminary expressions: global | Context: Preliminary expressions: global | ||
Main Expression (rt): global | Main Expression (rt): global | ||
Consequent expressions: 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===NumPopulations=== | |||
Defines the number of populations to create for an immigration instance | Defines the number of populations to create for an immigration instance | ||
Result: A set of new agent populations | Result: A set of new agent populations | ||
Default: One population | Default: One population | ||
Context: Preliminary expressions: global | Context: Preliminary expressions: global | ||
Main Expression: global | Main Expression: global | ||
Consequent expressions: population | Consequent expressions: population | ||
The main expression is any valid global expression defining the number of populations to create for this immigration instance. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===NumGroups=== | |||
Defines the number of groups to create for a new population | Defines the number of groups to create for a new population | ||
Result: A set of new agent sub-population goups | Result: A set of new agent sub-population goups | ||
Default: One group | Default: One group | ||
Context: Preliminary expressions: population | Context: Preliminary expressions: population | ||
Main Expression: population | Main Expression: population | ||
Consequent expressions group | Consequent expressions group | ||
The main expression is any valid population expression defining the number of groups to create for this new population. | 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 | 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 | ||
| Line 75: | Line 109: | ||
If NumGroups is not defined, then a single group within each new population is created. | 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. | 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) | Result: A set of spatial locations for potential initiation of an agent (InitRegion) | ||
Default: Every cell in the landscape. | Default: Every cell in the landscape. | ||
Context: Preliminary expressions: global | Context: Preliminary expressions: global | ||
Main Expression: global | Main Expression: global | ||
Consequent expressions: spatial | 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===ProbInit=== | |||
Defines the relative probability that an agent will initiate in a particular cell. | 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). | 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. | Default: Every cell in the initiation region has a value of 1.0. | ||
Context: Preliminary expressions: spatial | Context: Preliminary expressions: spatial | ||
Main Expression: spatial | Main Expression: spatial | ||
Consequent expressions: agent | 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===NumAgents=== | |||
Defines the number of agents to create for each new group | 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. | 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) | 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 | Context: Preliminary expressions: group | ||
Main Expression: group | Main Expression: group | ||
Consequent expressions: agent | Consequent expressions: agent | ||
The main expression is any valid group expression defining the number of agents to create in the initiation region. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===Transitions=== | |||
Defines if an agent survives. | Defines if an agent survives. | ||
Result: A surviving agent (or a terminating agent). | Result: A surviving agent (or a terminating agent). | ||
Default: The agent survives. | Default: The agent survives. | ||
Context: Preliminary expressions: agent | Context: Preliminary expressions: agent | ||
Main Expression (tr): agent | Main Expression (tr): agent | ||
Consequent expressions: agent | Consequent expressions: agent | ||
The main expression is any valid spatial expression tr(S), defining a Boolean value. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===PopulationTime=== | |||
Defines the time between population update steps. On each iteration, all agents are processed to test for movement, reproduction and survival. | 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 | Result: Updates the event queue Q | ||
Default: One time unit. | Default: One time unit. | ||
Context: Preliminary expressions: population | Context: Preliminary expressions: population | ||
Main Expression (pt): population | Main Expression (pt): population | ||
Consequent expressions: 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===MoveLocation=== | |||
Defines the set of potential cells to which an agent can move. | 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) | 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) | Default: The four cardinal neighbours of the agent (north, south, east and west) | ||
Context: Preliminary expressions: agent | Context: Preliminary expressions: agent | ||
Main Expression: agent | Main Expression: agent | ||
Consequent expressions: agent | Consequent expressions: agent | ||
The main expression is any valid spatial region defining the cells to which the agent may move. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===MoveProb=== | |||
Defines the relative probability that an agent will move to a particular cell. | 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). | 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. | Default: Every cell in the move region has a potential value of 1.0. | ||
Context: Preliminary expressions: agent | Context: Preliminary expressions: agent | ||
Main Expression: agent | Main Expression: agent | ||
Consequent expressions: 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. | 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. | 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. | ||
'''FIGURE MISSING''' | '''FIGURE MISSING''' | ||
===NumOffspring=== | |||
Defines the number of offspring created by an agent. | 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. | Result: A set of agents created within the same group and population, and at the same location, as the parent agent. | ||
Default: None | Default: None | ||
Context: Preliminary expressions: agent | Context: Preliminary expressions: agent | ||
Main Expression: agent | Main Expression: agent | ||
Consequent expressions: agent & recipient | Consequent expressions: agent & recipient | ||
The main expression is any valid spatial expression defining the number of new agents to create by a given agents. | The main expression is any valid spatial expression defining the number of new agents to create by a given agents. | ||
Revision as of 18:25, 13 September 2006
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.
TABLE MISSING
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.
TABLE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
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.
FIGURE MISSING
Go to... Prev Chapter Next Chapter Guide Index