Model Builder's Guide Chapter 7

=Landscape Events= Landscape events are designed as a general tool to capture processes acting on a landscape. A Landscape event (LSE) defines when and where a state change should occur along with the nature of that state change. A LSE is defined using properties that help to separate when and where the process being modelled affects the landscape, and what the nature of the effect is (Table 2). Each property, in turn, is defined by a set of assignments and expressions that are evaluated during the simulation to determine the action to be taken. Together, these properties form the LSE definition. Conceptually, the LSE definition is used to determine the time between instances of the event (ReturnTime property), the spatial locations in which the event should initiate (EventLocation, NumClusters, and ProbInit properties), and the rate and directions the event should spread out from the cell in which it initiated (Spread properties).

At the beginning of a simulation, the first instance of an event is scheduled based on ReturnTime. For continuous processes, this is simply the time step used to discretely model state changes. For example, succession is often modelled annually, corresponding to a ReturnTime of one year for an AnnualGrowth LSE. Alternatively, for processes that occur periodically, the ReturnTime is the interval between successive occurrences of the event. For example, a disturbance agent, such as a wind storm, may occur three times a year on average -- this would correspond to a ReturnTime defined by some distribution with a mean of 122 days for a WindStorm LSE. ReturnTime is also used to help order event sequencing.

When an event is processed, the EventLocation property defines a region of possible locations for the event to start, of which some subset will be selected based on the other initiation properties. This allows identification of the set of cells in which an event can potentially initiate (e.g. forested cells in the study area).

Probability of Initiation (ProbInit) and Number of Clusters (NumClusters) together specify the cells in which events will initiate (see Table 3). Many types of processes are sensitive to the underlying spatial structure of the landscape. In these cases, the probability that an event will occur at a specific spatial location is conditional on the properties, or state, of that location. ProbInit allows you to specify either an absolute or a relative probability of the event occurring in any model cell, as a function of the cell state. That is, given that the event is going to occur somewhere in the model, what is the probability that it will occur at a given spatial location in the EventLocation. If NumClusters is defined, then it specifies the number of cells in which to initiate the event. These locations may be drawn purely at random, or may be dependent on the relative probability for each location, as defined by ProbInit. If NumClusters is not defined, then each cell in EventLocation is tested independently for initiation using ProbInit as an absolute probability. Table 3 illustrates the possible combinations of ProbInit and NumClusters, along with the behaviour invoked when each of these combinations is used.

For each cell that initiates, a new active cell and cluster are created. The value of Transitions then determines whether or not a transition occurs. Usually, the main state transitions for the event are defined in this property. This property determines if an event should proceed (i.e. occur) in a cell and, if so, what should happen as a result of that event. This property is also used to determine if a spreading event will actually spread. If the event does occur, it will spread, whereas if the event does not occur, the active cell simply terminates without spreading. The SpreadTime property specifies if and when an event will spread from the current cell to neighbouring cells. This is analogous to the ReturnTime property above, except that SpreadTime is computed in the current location. If specified, this gives the number of time units in the future to schedule spreading from the current cell. If not specified, then the event will not spread. Another difference from ReturnTime is that the consequence of ReturnTime is processed before initiation (to allow a set-up context) while the consequence of SpreadTime is processed after spreading (to allow a context prior to an active cell terminating).

When a cell attempts to spread, SpreadLocation defines the set of potential cells to which spread may occur, analogously to EventLocation. Probability of Spread (SpreadProb) and Number of Spread Recipients (NumRecipients) select the set of cells to initiate via spreading, and operate analogous to ProbInit and NumClusters. The primary difference is that spreading has a source cell whereas event initiation does not. If NumRecipients is defined, then it specifies the number of cells to which a cell may spread. The relative probability of spreading to a cell is given by SpreadProb. If NumRecipients is not defined, then each cell in SpreadLocation is tested independently for initiation using SpreadProb as an absolute probability (see Table 3).

Eventually a spreading cluster (defined as the set of active cells that arrived from a common initiation cell) terminates. When this happens the EndCluster property is processed, allowing for a finalization context. Likewise, when all clusters that initiated in a given step terminate, the event instance terminates. When this happens, the EndEvent property is processed. In SELES v3.3, only the preliminary context of these properties is defined. Note that we have not described how the actual changes to the landscape are to be specified. The properties describe the behaviour of an event as it starts in a landscape, spreads across and is finally extinguished.

Landscape Event Dynamic context Variables and contexts
The types of dynamic context variables available in landscape events are as follows:

(a)	Event variables define values that apply to individual active instances of an event. For example, a Fire event might declare an event variable called FireSize that is used to store the size for each recurrence fire in the landscape. Thus, each instance of Fire can have a different size.

(b)	Cluster variables define variables that apply to individual active clusters of an event. For example, if FireSize is a cluster variable, then it applies to a single cluster, whereas if FireSize is an event variable, then it applies to all clusters created by one instance of a fire event.

(c)	Cell variables define variables associated with individual cells in which the event instance is currently active. For example, an event called Fire may declare a cell variable called Intensity to store the magnitude of the fire at each cell.

When an event creates a new cluster, any cluster variables declared for the event will be created. The value of an event variable will be the same for all clusters created by the event, but each cluster will have a unique set of cluster variables. Each cell to which a cluster spreads will refer to one set of cluster variables, and when the last cell of the cluster is extinguished, this set of variables will be removed from the system. Thus, the dynamic state is hierarchically organized as shown in Figure 4, where an active event has a set of active clusters, each of which in turn has a set of active cells.



Figure 4. The hierarchical structure of the dynamic state. Each active event has a single set of event variables, and one or more active clusters. Each active cluster has a single set of cluster variables, and one or more active cells. Each active cell has a set of cell variables.

The allocation and destruction of dynamic variables is managed by SELES and is transparent to the modeller. Modellers simply need to declare variables at the appropriate event, cluster or cell scope levels. This hierarchical structure is important because lower order entities of the simulation (e.g., cell level) may need to act semi-independently, but may also need to be coordinated by the higher order entities (e.g., cluster, event, and global levels).

Table 4 shows the default values, and operating and consequent contexts for landscape events.

Instantiation, Initiation and Spread of a SELES Landscape Event
It is important to clarify the difference between the definition and an instance of a LSE. A LSE definition is composed of the assignments and expressions defined for the properties described in Tables 1 and 3, and detailed more formally below. Instances of this definition are what get scheduled on the event queue during a simulation to occur at some time in the future. When a LSE instance is taken off the queue and executed, it initially has no spatial location. The first step taken when processing an event instance is initiation, in which a set of clusters or cells is selected according to the EventLocation, NumClusters and ProbInit properties. After initiation (but often before spreading), the LSE instance schedules a new instance to occur at some later time according to the ReturnTime property. A LSE instance remains active as long as one of its clusters is active. A cluster remains active as long as its initiating cell, or a cell that was spread to from this initiating cell, is active. A cell is active if it has scheduled spreading on the event queue or if it is currently being processed. A cell is terminated after it has finished spreading, but this may result in the activation of other cells.

Table 4 Value and default for main expression, and context of landscape event properties.



An event instance is basically a dynamic activation of the LSE definition. Through initiation of clusters and spread, it acquires specific spatial locations at which it affects the landscape. Although the definition has a ReturnTime, an instance does not. It initiates clusters at the current clock time. It has a duration while active cells spread across the landscape, but it terminates when the last active cell, and hence the last active cluster terminates. The ReturnTime is used to schedule a new instance of an event.

The distinction between and an LSE definition and its instances is important since more than one instance of a single LSE type (same definition) may be active at one time. Each instance has its own internal state of event variables, just as each active cluster has its own set of cluster variables and each active cell has its own set of cell variables. Note that the identity of active cells is determined by the source of their initiation. Thus, it is possible for the same spatial cell to be simultaneously active with more than one LSE instance. For example, this may occur if a fire event spreads to the same cell from two neighbouring cells. If such a possibility is undesirable, additional state should be included to facilitate communication between active cells within a single spatial location (e.g., using an event variable or a spatial layer that records the activity of an event).

For clarity and brevity in the rest of the document, an LSE definition or instance will simply be referred to as a Landscape Event, or LSE for short. An active cell within an event instance is an event that is associated with a particular cell. In general, a LSE is a recurring phenomenon on the landscape, with no specific spatial location, while an active cell is a phenomenon that occurs at a specific time and place, with the ability to propagate by spreading.

It is also important to understand when and how an active cell spreads. An active cell may spread only if it occurs in its own cell. The Transitions property is used to determine if an active cell actually occurs in each particular cell where the event was initiated. If the active cell did not occur, then it terminates. If it did occur, the active cell schedules spreading to occur at some future time as determined by the SpreadTime property. When spreading is processed, a number of new active cells are created and propagated to neighbouring cells. These new active cells are within the same active cluster and event instance as the original. Note that we draw a clear distinction between the initiation of an event and the occurrence of an event. An event is initiated when the event instance is "dropped" into the cell (via a new cluster, or via spread from some neighbouring cell). An event occurs when the Transitions property is evaluated as true after initiation. For example, a lightning strike may initiate a fire in the cell it hits, but whether or not a fire actually occurs in that cell might be determined as a function of current fuel and weather conditions.

Landscape Event Property Details
This section gives a more detailed descriptions of the duty or behaviour of each of the LSE properties listed above. In these descriptions, the following notation is defined for brevity:
 * Q represents the simulation engine priority event queue described above (see Figure 2).
 * S represents the set of n variables available in the current context. For spatial context s, this additionally includes a specific spatial location, where Si,j represents a vector of length n containing the values of the state variable at cell i,j.

Each LSE property is described by the following characteristics: Result : Specifies the object created or modified by this property. Default: Specifies the default behaviour if the property is not defined.

Context : Specifies the precise state context of the property. This determines the set of state variables, S, that can be referred to in an expression. The preliminary expressions and main expression share one context (the operating context) while the consequent expressions generally have a different context (the consequent context). A context can either be global, spatial, active, recipient or active & recipient. A global context includes global, “whole” layer and event variables as well as the Time and EndTime system variables. A reference to a layer in a global context applies to every cell in the layer, which we call a “whole” layer reference. A spatial context includes global, layer (at a specific location), and event variables, as well as the Time, EndTime and Location system variables. An active context is a spatial context with an active cell, and hence also includes cluster and cell variables. A recipient context is a spatial context for a potential recipient of spread, and so includes the source (spreading) cell, location, cell and layer variables (which are accessed using the prefix SOURCE). An active recipient context combines an active context with a recipient context.

Description : Specification of the property’s function.

InitialState
Defines the number of event instances to create at simulation startup Result : A set of event instances. Default: One instance

Context : Preliminary expressions: global Main Expression: global Consequent expressions: global (event instance) The main expression is any valid global expression defining the number of event 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 instances of an event at startup. The preliminary expressions are evaluated once, while the consequent expressions are evaluated for each event instance created. The initial values for event variables are set to zero. Since there is no instance prior to this property, event variables are not available in the preliminary context. After an event instance is created, ReturnTime is evaluated to schedule it for future processing



ReturnTime
Defines the interval between event instance initiations, and schedules new instances.

Result : Create a LSE instance and update the event queue Q. Default: Schedule the event to occur exactly once at simulation startup (ReturnTime = 0).

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 instances of the event being created.

Description : When an event instance is created and the preliminary expressions and the main expression, rt(S), for the event are evaluated. The event instance is scheduled to occur at rt(S) number of time units in the future. When the event instance is taken off the queue, the consequent expressions are evaluated. Then EventLocation is invoked to process event initiation. Once initiation is completed, a new event instance is created and the preliminary expressions and main expression, rt(S), are evaluated. The initial values of the new instance are set to the values of the previous instance. The new instance is scheduled to occur at rt(S) number of time units in the future. Note that an spreading event instance may not be completed prior to creating the next instance.



EndEvent
Expression within the preliminary context are processed when an event instance terminates. Main expression is presently undefined.

E.g., ENDEVENT OUTPUT RECORD(OutFile) Label: OutVar ENDFN ENDEVENT = TRUE ENDEE

Result :

Context :

Description :

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

Result : A set of spatial locations for potential initiation of an event (InitRegion) Default: Every cell in the landscape.

Context : Preliminary expressions: global Main Expression: global Consequent expressions: spatial The main expression is a region expression that defines the cells in which the event may initiate. Although the consequent expressions are spatial, they can only refer to layer variables and not cell variables, since at this point, active cells have not yet been created by the event instance.

Description : The set of cells returned by this function defines the landscape as seen during the initiation of the event via ProbInit and NumClusters. 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 cell in the event region.



ProbInit
Defines the probability (relative or absolute) that an event will initiate in a particular cell.

Result : Transient “probability surface” for cells in the initiation region InitRegion (created by EventLocation) with floating point values indicating the potential of each cell to initiate with the event (InitProb). Default: Every cell in the initiation region has a value of 1.0.

Context : Preliminary expressions: spatial Main Expression (pi): spatial Consequent expressions: active The main expression is any valid spatial expression, pi(S), defining the probability, normally between zero and one, of an event initiating in a cell. Although the preliminary expressions and main expression are spatial, they can only refer to layer variables and not cell variables, since at this point, active cells have not yet been created by the event instance. The consequent expressions can refer to cell and cluster variables. Informal Specification: The preliminary expressions and main expression, pi(S), are evaluated for each cell in the initiation region InitRegion. The consequent expressions are only evaluated in those cells in which the event actually initiates – see NumClusters below.



NumClusters
Defines the number of clusters for an event instance (i.e. number of cells to initiate)

Result : A set of active cells derived from the initiation region InitRegion and probability of initiation surface InitProb. Default: Every cell i,j in InitRegion has an absolute probability of initiating equal to InitProbi,j. (Thus, the actual number of clusters, or initiating cells, is emergent.)

Context : Preliminary expressions: global Main Expression (nc): global Consequent expressions: active The main expression is any valid global expression, nc(S), defining the number of cells in initiation region in which the event is to initiate.

Description : Once ProbInit has produced the “probability surface” InitProb of potential sites, and their relative probabilities, NumClusters is evaluated to determine the actual number of cells in which to initiate the event. The cells in which the event is initiated are selected stochastically from the potential sites based on the probabilities in InitProb (i.e. the probabilities are relative). For cells that initiate, the consequent expressions for both NumClusters and ProbInit are evaluated.



If NumClusters is not defined, then cells are selected for initiation independently based on InitProb (i.e. the probabilities are absolute). For cells that initiate, the consequent expressions for ProbInit are evaluated.



Transitions
Defines if the event occurs in an active cell.

Result : An active cell (or a terminating cell). Default: The event occurs.

Context : Preliminary expressions: active Main Expression (tr): active Consequent expressions: active The main expression is any valid spatial expression tr(S), defining a Boolean value.

Description : When an active cell has initiated in a cell, either through event initiation or spread, the preliminary expressions and main expression, tr(S), are evaluated. If the result of tr(S) is TRUE (> 0), then the event occurs in the cell. The consequent expressions are only evaluated, and spreading is only attempted, if the event occurs. For spreading events, SpreadTime is invoked to schedule spreading.



SpreadTime
Defines the time it takes between initiation of an event in a cell and spreading of the event to neighbouring cells, and schedules the active cell to spread at this time in the future.

Result : Updates the event queue Q Default: Event does not spread.

Context : Preliminary expressions: active Main Expression (st): active Consequent expressions: active The main expression is any valid spatial expression st(S), defining the time elapsed (in time units) between when an event occurs in a cell and when it spreads to neighbouring cells. If st(S) is negative, then spreading is “immediate” (spreading will occur without scheduling on the queue). Once immediate mode starts, all spreading with negative values will be processed before returning to normal processing. The magnitude of the negative value indicates the ordering within immediate active cells (e.g. a value of –1 will be processed ahead of –2, and the order for subsequent spreading will be incremental from the source). Note: this facility must be used with caution and only in cases that have well-defined termination. Poorly constructed models that permit immediate spreading repeatedly to the same cell can cause infinite loops.

Description : When an active cell occurs in a cell, the preliminary expressions are evaluated. The main expression is then evaluated to determine the length of time required for the event to spread to neighbouring cells. Spread from this active cell is scheduled on the event queue to occur at st(S) number of time units in the future. After the spreading is processed, the consequent expressions are evaluated and the active cell terminates.



SpreadLocation
Defines the set of potential cells in which an event can initiate through spread from an active cell.

Result : A set of spatial locations for potential spread of an event (SpreadRegion) Default: The four cardinal neighbours (north, south, east and west)

Context : Preliminary expressions: active Main Expression: active Consequent expressions: recipient The main expression is a spatial region that defines the cells to which the active cell may spread. Although the consequent expressions are spatial, they can only refer to layer variables and not cell variables, since at this point the new active cell has not yet been created by the spreading cell. However, the source cell variables (for the spreading active cell) can be referenced.

Description : The set of cells returned by the region defines the landscape as seen during the spread of the active cell via SpreadProb and NumRecipients. Spreading 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.



SpreadProb
Defines the probability (relative or absolute) that an active cell will spread to a particular cell.

Result : Transient “probability surface” for cells in the spread region SpreadRegion with floating point values indicating the potential of each cell to initiate the event (SpreadProb). Default: Every cell in the spread region has a potential value of 1.0.

Context : Preliminary expressions: recipient Main Expression (sp): recipient Consequent expressions: active & recipient The main expression is any valid spread expression, sp(S), defining the probability, normally between zero and one, of an event initiating in a cell via spread from active cell. Although the preliminary expressions and main expression are spatial, they can only refer to layer variables and not cell variables, since at this point the new active cell has not yet been created by the spreading cell. However, the source cell variables (for the spreading active cell) can be referenced. The consequent expressions can refer to cell variables.

Description : After determining the spread location, the preliminary expressions and the main expression, sp(S), are evaluated for each cell in the spread region. The consequent expressions are only evaluated in those cells to which the active cell actually spreads – see NumRecipients below.



NumRecipients
Defines the number of cells to spread to.

Result : A set of active cells, derived from the spread region SpreadRegion and probability of spread layer SpreadProb from the active cell.

Default : Every cell i,j in SpreadRegion has an absolute probability of spreading equal to SpreadProbi,j. (Thus, the actual number of cells spread to is emergent.)

Context : Preliminary expressions: active Main Expression (nr): active Consequent expressions: active & recipient The main expression is any valid spatial expression, nr(S), defining the number of cells to which to spread.

Description : Once SpreadProb has produced the “probability surface” SpreadProb, SpreadRecipients is evaluated to determine the actual number of cells to which the active cell should spread. The actual cells in which the event is initiated via spread are selected stochastically from the potential sites based on the probabilities in SpreadProb. For cells that initiate via spread, the consequent expressions for both SpreadRecipients and SpreadProb are evaluated. Once a cell has been spread to, initiation of the new active cell is handled by invoking Transitions, as for NumClusters, thereby cycling the event loop.




 * If NumRecipients is not defined, then cells are selected for spread independently based on SpreadProb (i.e. the probabilities are absolute). For cells that initiate, the consequent expressions for SpreadProb are evaluated.



Property options and initiation/spread algorithms
There are a number of optional flags that can be used to modify property behaviour by using some options placed to the right of the property names. These are advanced features, and are less commonly used than the base versions. The base behaviour of initiation (via ProbInit and NumClusters) and spread (via SpreadProb and NumRecipients) can be modified. The “random” flag for ProbInit causes cells to be processed in random order, while the “ordered” flag for ProbInit causes cells to be processed in order of decreasing values of ProbInit. In general these simply change the order in which cells are tested (the default is row by row from the bottom left to top right). However, in conjunction with other feedbacks, these can provide more control over the order in which cells are initiated. By default, during initiation, the cells selected are unique (i.e. selection is without replacement). Selection with replacement” is possible by adding the keywords WITH REPLACEMENT following the NumClusters or NumRecipients property names. In this case a given cell may be selected more than once for initiation. Table 5 summarizes the different initiation variations that can be set up with options set for ProbInit or SpreadProb. Number control refers to whether the number of cells is unbounded (NumClusters / NumRecipients not specified) or bounded (NumClusters / NumRecipients specified).

Table 5 Initiation/spread algorithms possible using options



NumClusters and NumRecipients can also be specified as a conditional. That is, rather than evaluating to a number (e.g. NUMCLUSTERS = 5), the keyword “WHILE” specifies that the expression is a condition rather than a number of cells to select, and that cells are to be chosen for initiation until that condition is false (or until all cells in EventLocation have been initiated). For example NUMCLUSTERS = WHILE numLeft > 0 will continue selecting cells for initation until numLess is <= 0 or every cell has been selected. Table 6 shows the additional initiation algorithms possible using a conditional number control.

Table 6 Initiation/spread algorithms possible using conditional “WHILE” option with NumClusters and NumRecipients and options.



Hence a fairly large number different initiation/spread algorithms can be invoked by modifying whether ProbInit/NumClusters are specified, and the options specified.

SpreadTime is assumed to be elapsed time during spread (even conceptually in immediate mode, although no time is actually consumed). That is the time step is “relative” to the time at which the source cell is processed. Setting the option “ABSOLUTE” for SpreadTime causes the time step to be in absolute time. In this case, time is no longer necessarily a forward progression, as events may be scheduled to occur in the “past”. This option is primarily intended for non-temporal models that use the event queue as a priority queue rather than a time series of events.

SpreadTime is specified using immediate mode using negative values. This causes a cluster to spread without consuming simulation time, and to be processed prior to any further initiations. That is, immediate mode can be used to process clusters sequentially. The default is interleaved, or parallel, spreading of all clusters initiated by an event instance. Sequential processing of clusters has many uses ranging from identifying patches to harvesting blocks one at a time until a target has been reached. However, care must also be taken. Since time is not consumed, the user interface must wait until immediate mode completes because the user interface must use the priority queue to interact with the simulation engine. Hence, if immediate mode has an infinite loop, the simulation cannot be stopped (unlike with normal parallel spreading). So immediate mode should be used with caution, only when necessary, and after appropriate testing ensures the model will operate as designed. The absolute value of SpreadTime in immediate mode has the same interpretation as in regular mode in terms of the ordering of cell processing within the cluster. That is, lower absolute values will be processed before higher values at the specified rate (e.g. if a portion of the cluster has a SpreadTime of –2 and another has a SpreadTime of –10 will the former will process 5 cells for every one of the latter).

Go to... Prev Chapter Next Chapter  Guide Index