SELES Landscape Events and Landscape Agents

Landscape event and agent specifications consist of two parts: a set of definitions that describe the layers and variables that can be referred to and modified by the sub-model, and a number of properties that specify the behaviour of the process being modelled. Each property defines some aspect or characteristic of the process being modelled by the event, and is optional, with a well-defined default, so a model can be precisely and succinctly defined. A set of declared variables defines the spatial and aspatial state relevant to the sub-model. The modeller defines these variables and attributes meaning to them. All state changes caused by the sub-model are specified as explicit assignments made to one of these declared variables.

Variable Declarations

A landscape event or agent can predicate its behaviour on the global variables, constants and raster layers that define the landscape state. In addition, an event can define and operate on a set of dynamic context variables that are used to control the sub-model behaviour. Dynamic variables are assigned a scope based on the context in which they are available (e.g., within event instance, within a cluster, etc.) and are created and destroyed automatically by SELES. The dynamic variables available in landscape events and agents differ, and are described in Sections 7 and 8. The declaration section of a landscape event or agent consists of a series of pairs of the form:

variable type: variable name [, variable name]*.

The following types of variables can be defined in a landscape event or agent: (a) Spatial layers specify spatial variables in the state space that are to be used by the landscape event. These may be defined as static or dynamic in the dynamic model file (but they should be defined there). (b) Global variables and constants specify aspatial values in the state space that are to be used by the landscape event. These generally define some large-scale state information and may by accessed any time, by any event. For example, a global variable called WindDirection might store the prevailing wind direction. A Wind event might be employed to change the WindDirection during the simulation, whereas events called Fire and WindThrow might use the WindDirection to influence their behaviour. In addition, global variables can appear on the user interface to act as adjustable parameters for the scenario. These should be defined in the dynamic model file. (c) Local variables specify aspatial global variables that are internal (local) to the event (i.e. not defined in the dynamic model file). These are useful for tracking internal information within an event. Initial state should be consider as undefined, and such variables should be given values prior to use. If an array is defined, the bounds must be explicitly defined. (d) Output variables define variables that will be output to record files during a simulation. Their use in properties is restricted to expressions that create a record of a simulation. Output variable declarations also specify the filename to which output records are to be stored. These are a primary means of obtaining text output from a model. (e) Dynamic context variables: specific to landscape events or agents.

Spatial layers and global variables are external to all landscape events and agents in a scenario  they are part of the initial conditions of the scenario and have a global scope. The other variables are internal to a specific landscape event/agent and are created when appropriate for their scope. There are two other types of variables are do not appear in the definitions section. System variables are system-defined variables, including the current simulation time (Time), the end time of the simulation (EndTime), the current run number (Run) and current spatial location (Location). Any variable that is referred to, but is not defined is assumed to be a local variable. Local variables have a very limited scope that is generally limited to the immediately subsequent assignments or main expression (see next subsection).

Landscape Event and Agent Properties

A landscape event or agent is constructed from a number of properties (e.g. for landscape events, Table 2). Although each property has a unique purpose, they are all constructed using the same general structure. We first provide an overview of this general format, and defer details until sections 7-9. Note that the modeller need only specify those properties relevant to the current landscape event or agent, since properties have a well-defined default. Each SELES event/agent property consists of the following parts:

Preliminary expressions

Main expression

Consequent expressions

The main expression is the only part that is required, and it is a function that defines the value of the property. This value characterizes the property, as described in Table 2 for events and Table 7 for agents. The preliminary and consequent expressions allow state changes to be associated with a property. These may be assignments of the form: variable = expression, but some expressions may be procedural in nature (e.g. “while loops”). Section 9 describes expressions in detail.

Preliminary expressions are normally used to initialize part of the state-space for the main expression, whereas significant state changes are generally made with consequent expressions. Each property has an operating scope, or context, that defines the set of variables that can be referred to in the expressions, and the spatial locations at which the expressions are evaluated (Table 4). Preliminary expressions are evaluated immediately before the main expression in this context. One effect of evaluating the main expression is to modify the context. The consequent expressions are evaluated after the main expression in the consequent scope. For example, a FireSize cluster variable may be declared as part of a Fire event to control the number of cells to which a particular instance of Fire will spread. The consequent assignment FireSize = normal(=200,=50) in the Number of Clusters property will assign a random FireSize to a new cluster. In the Transitions propery, the main expression FireSize > 0 will only allow an instance of Fire to spread while FireSize is positive. The consequent assignment FireSize = FireSize – 1 in the Transitions property will record the fact that a cell has burned. Thus, Fires will spread until they burn FireSize cells and then extinguish. The scopes and default for each property are defined in Table 4 for events and Table 8 for agents, and further described later in this document.

Expressions in Events and Agents

Property expressions (main, preliminary, consequent) form the heart of the SELES modelling language. Expressions can range from simple constant values to complex functions, can be deterministic or stochastic, continuous or discrete, computed at a single cell or over a neighbourhood of cells, etc. Most expressions are functions, but some procedural expressions are provided. We refrain from delving into details on the syntax and focus on the general structure of the language. See section 9 for a description of the expressions supported by SELES as well as the precise syntax. The following describes some of the types expressions available: (a) Constants: simply return a constant value specified as numbers or named constants. (b) Distributions: draw values from probability distributions such as normal, Weibull, negative exponential, etc. For example, an expression that specifies a normal distribution with a mean of 20.0 and a standard deviation of 5.0 will return a value drawn from this distribution each time it is invoked. The value such expression return is not deterministic, and may be different each time it is evaluated. This is one way in which stochasticity can be introduced into landscape events. For example, one could specify a normally distributed return time for a fire event with a mean of 10 years and a standard deviation of 2 years, or a negative exponential distribution of fire size with a mean of 100ha. (c) Continuous functions: evaluate a function f(x) for some variable x, which may be any of the variables described above. Examples include linear functions, exponential and trigonometric functions. (d) Classified functions: define a mapping for categorical variables. Many rasters contain categorical data (e.g., soil type or species), and are thus not amenable to ordinary continuous functions. A classified function defines a separate resultant value or sub-function for each class (e) Conditional functions: are defined as: if (expression1) then (result1) else (result2), and represent braching depending on the outcome of expression1. (f) Composite functions: provide a means of combining multiple sub-functions into a more complex expression. Examples include summations, products and averages. A region function can be used to define a spatial region over which such a function is evaluated. For example, the maximum age of cells defined in the region can be computed. (g) Region functions: define spatial regions. These functions are unlike other functions in that they don't return a single value, but rather return a spatial area of the landscape. Their application is limited: (i) they are used to define the main expression of the Event Location and Spread Location properties, and (ii) they may be used in conjunction with a composite function as described above. (h) Matrix functions: define operations on one-dimensional and two-dimensional matrices (arrays). (i) Set, list, tree and graph functions: define operations on collection and linked structures.

Property and Expression Contexts

The spatial domain and the set of variables that can be referred to in an expression is called the context of an expression (see Table 4 for events and Table 8 for agents). Some properties (e.g. ReturnTime for events) have no spatial context (e.g., the spatial domain of ReturnTime is the landscape as a whole) and so cannot directly refer to cell or cluster variables, and layers are referred to in their entirety. Expressions with a spatial context that refers to a spatial variable reference the value of the variable in a given cell. Such expressions permit computation of a value for a specific location (i.e. at a cell) based on the current state of that location (i.e. the value of the spatial state variables for that cell or region). Put more formally, let S = {s1 ,s2,...sn} be an n element vector containing the values of all state variables defined in the context of an expression in a SELES model. Then a SELES expression specifies a function: y = f(S )

If the expression has a spatial context that ranges over a region of cells, then each cell in the region will potentially have a unique value. In this case, we can think of the result as a “transient” raster layer, with the value in cell i,j equal to yi,j = f(Si,j). Thus, when a spatial expression is evaluated at a particular cell in the model, the function parameters take on the values of the state variables at that cell, and the result of the function is given the spatial location of that cell. Readers familiar with GIS will recognize a similarity between such spatial expressions and raster overlays. One difference is that while a GIS overlay generally produces a complete and durable raster layer, the value of a SELES spatial expression may be transient -- it is only computed at the time which and for cells in which it is required, and is discarded when the operation is complete. There are other important differences. One is that the variables also include the global variables as well as dynamic variables defined for the landscape event/agent. Another is that SELES expressions may include random numbers drawn from a distribution each time the expression is evaluated, allowing stochastic operations rather than strictly deterministic functions.

Each property is evaluated in two contexts: the operating context and the consequent context. The former is the context in which the preliminary expressions and main expression are evaluated. It is essentially the “input context” for the property and is the result of previous interactions. As a result of evaluating the property, contexts are created, filtered or modified (e.g. as a consequence of specifying that 3 fires will ignite in a model called Fire, 3 active spatial contexts will be created to capture the point of ignition for the fire). These contexts are automatically managed by SELES, and differ for the various properties of events and agents.

Go to...  Prev Chapter  Next Chapter  Guide Index