Dynamic model configuration

Dynamic SELES models are the “central model type for creating landscape dynamics models. The static models are usually generated using the user interface, but dynamic models must be specified using the file syntax (and stored in files with a “.sel” suffix).

Model State-Space and Initial Conditions

The state of a SELES model consists of a set of spatial raster layers, a set of global variables and a set of global constants combined with a set of landscape events and agents. The dynamic model file is used to define (configure) the model state-space.

The state at the start of a simulation is called the initial condition. State components may be static or dynamic. Global constants by definition are static, and cannot be modified by a model. Static global variables and constant input tables usually represent input parameters. Dynamic global variables are used to communicate between events or to track aspatial model output SELES makes no explicit distinction between static and dynamic information (e.g. SELES does not prohibit a model from modifying a static layer, but such changes will persist until the source raster is reloaded).

Global Constants and Variables

Global constants are simply floating point values that may be used anywhere a numeric value can be used. Since they are specified by name, they improve model readability, and they allow changes to be made only in one place, improving model maintenance. They also facilitate loading in input values from files. An input table loaded from a file into a global constant can be used to create a one-dimensional array (also called a vector) or a two-dimensional array. See Section 2 for input format and Section 9 for usage in landscape events. Global variables are like constants, but are potentially dynamic, and so may be modified by one or more landscape events, providing dynamic aspatial model state. Global variables can act as model parameters to provide model control at the simulation interface level or within scenario scripts, as output statistics, or for communication between events. As parameters, global variables are generally static within the model (i.e. they are not modified by any event). Parameters allow some users (model drivers) to be unaware of all the details contained in a landscape model, but still have a means of controlling model behaviour. For example, parameters could be used to control fire frequency, amount of logging, management strategy, etc. Global variables can be referred to in any expression in a landscape event. Like global constants, global variables can also be loaded from files (but in this case, the file input defines the initial condition, which may be modified during a simulation).

Dynamic Model Specification

A SELES dynamic model configures the dynamic process sub-models and the state space, and specifies the initial conditions. It consists of a set of landscape events, mappings (linkages) from variables in landscape events/agents to rasters in views (windows), legends, constants and initial values for global variables. This section describes the syntax and semantics (meaning) of commands used to create dynamic model definitions. The same general rules from the static models apply (Section 3).

A dynamic model is defined in two sections. The first defines the model name, dimensions and time units. The second defines and configures the model components. The definition section should be specified before the component sections. Otherwise sections may be in any order or number (e.g. it is often convenient to have more than one set of global constants definitions). The following is the general format of a dynamic model:

SELES MODEL { Model Definitions } { External Script Variables } { Landscape Events and Agents }

{ Legends } Define legends, or loads legends from file. { Global Constants } Define global constants and their values. { Global Variables } Define global variables and initial values. { Macros } { Spatial Constants } Define spatial constants and input rasters { Spatial Variables } Define spatial (layer) variables and rasters for dynamic (output) and initial conditions.

{ Initial State Variable Mapping } These three blocks are the old (prior to { Dynamic State Variable Mapping } version 3.3) method for defining spatial { Dynamic State Output Bounds } constants and variables and bounds for the dynamic rasters.

{ Dynamic State Output } Specifies dynamic output of rasters to file during a simulation. { Refresh Rate commands }

Model Definitions

This section describes the general characteristics of the dynamic model, including the model name and dimensions. Dimensions are optional, and are often defined in the scenario file based on loaded rasters (see Scenario Reference). Time unit definitions only affect the user interface.

MODEL NAME : <Identifier> Default: blank or no name

MODEL SIZE : <#rows>,<#cols> Specifies the number of rows and columns. Default: 100x100

MODEL ROWS : <#rows> Alternate forms for specifying the number | MODEL HEIGHT : <#rows> of rows and columns in the model. MODEL COLS : <#cols> | MODEL WIDTH : <#cols>

TIME UNITS: <BaseUnit> <MetaUnit> <#Factor> <#DefaultHorizon> Defines the name of a single time unit, and metaunit (e.g. days and years), as well as the default simulation length. The factor is the number of units per metaunit.

External Script Variables

This block specifies the names of script variables (defined in scenario files) that can be imported into a .sel file, as well as default values to be used if they are not defined. Script variables are always surrounded by “$” symbols. They can be placed in the .sel file anywhere, and they will be replaced by their value when the command is processed. This is a literal replacement (i.e. as if the value was typed in the file), and so script variables can be used in places requiring text or numeric values (and can even be part of a label). If the scenario that loads the .sel file does not define one of these external script variables, then the value defined here will be used (and so is the same as if the default value was used instead of the script variable). However, if the scenario defines a script variable before loading the .sel file, then this will override the default value.

This feature has a few advanced applications. Often different files contain different parameters (e.g. different harvest schedules). In past versions of SELES, these had to be copied in the scenario first with a “system” command to a file loaded by the .sel file (e.g. AAC1.txt copied to AAC.txt, where AAC.txt would be loaded by the .sel file). This copy process was error-prone because the system command is unable to report errors. Also, if multiple copies of SELES are running (e.g. on a multi-CPU system), there could be undesired interactions. External script variables can be used to perform a “virtual file copy”, where (i) a script variable is used for an input file name and (ii) the value of the script variable is changed in scenario, thereby causing a different file to be loaded when the .sel file is loaded. Similarly, script variables can be used to change the folders in which input files are loaded. In the above example, an external script variable $AAC$ could be defined with a default value of “AAC.txt”, and a scenario could use the command “$AAC$ = AAC1.txt” prior to loading the .sel file to cause the file AAC1.txt to be loaded instead of AAC.txt.

EXTERNAL VARIABLES: { ExternalVariableSpec }+

A ExternalVariableSpec takes the following form:

$<ScriptVariable>$ = “Text”

Landscape Events and Agents

Landscape events and agents are specified individually in separate (.lse) files. The mode (.sel) file defines which event and agents to include, and the nature of that inclusion (i.e. enabled, enabled in debug mode, disabled).

LANDSCAPE EVENTS: Specifies the landscape events and agents to { LandscapeEventFile }+ include in the scenario.

A LandscapeEventFile takes one of the following forms:

“FileName” { UseType } A filename containing a landscape event or agent definition.

The optional “use type” flag indicates whether to enable (ON), disable (OFF) or enable in debug mode (DEBUG) the event in a simulation (Default: ON). As a general rule, unless a model is completely verified and a minor improvement in speed is needed, events and agents should be enabled in DEBUG mode, which will dynamically check access limits on arrays and rasters.

Legends

Legends define the set of constants in the legend as well as a lookup vector for label output in DISPLAY and OUTPUT expressions in landscape events.

LEGENDS: Specifies the legends to include. { LegendSpec }+

A LegendSpec can take one of the following forms:

<LegendName> = {#:<Label>, …, #:<Label>} Specifies a list of number-label pairs that define a legend. Numbers must be integers. <LegendName> = <Filename> Loads legend from a file that has one row for each value-label pair, where each pair is specified with the form “# : Label”

Global Constants

This block defines the names and values of global constants to include in the model state-space. Global constants are essentially named synonyms for values. The help improve model readability and adaptability.

GLOBAL CONSTANTS: { GlobalConstantSpec }+

A GlobalConstantSpec can take one of the following forms:

<ConstantName> = {Expr} Defines a simple constant and its value. <ConstantName> = {Expr}, …, {Expr} Defines a vector of constants and values. <ConstantName> = <Filename> Loads constant values from a file.

When loading from a file, the file must consist of tab-separated columns. By default the first column is the index. Hence a file with two columns defines a one-dimensional array. Files with more than two columns define a two-dimensional array.

Global Variables

This block defines the names and initial values of global variables to include in the model state-space. Single-value global variables specified here will show up in the user interface (unless followed by the “OFF” keyword). Global variables shared between landscape events must be specified here. Global variables in landscape events that are not specified here cannot be shared among events, will not show up in the user interface and have an undefined initial value (and should be defined instead as LOCAL variables). Global variables are used for parameters, output values, and inter-event communication.

GLOBAL VARIABLES: { GlobalVariableSpec }+

A GlobalVariableSpec can take one of the following forms:

<VariableName> = {Expr} Defines a simple global variable and its initial value. <VariableName> = {Expr}, …, {Expr} Specifies a global variable vector and values. <VariableName>[{Expr}] = <Value> Defines a global variable vector with a common initial value. <VariableName>[{Expr},{Expr}] = <Value> Defines a global variable 2-D array with a common initial value. <VariableName> = <Filename> Loads values for a global variable from a file (same format as for global constants).

Macros

This block specifies the names of macros and the files containing their definitions. The definition file has the format similar to a cell expression file. The macro can be declared in a landscape event, and evaluated similar to indexing a global variable (but the macro executes a function rather than simply looking up an array value). Macros are an advanced feature, and effectively allow a model to be parameterized with functions or a function to be used in multiple places in a model.

MACROS: { MacroSpec }+

A MacroSpec takes the following form:

<MacroName> = <Filename> Loads expressions in a macros from a file.

Spatial Constants

This block defines spatial constants (static layers) as part of the state space. Each definition specifies a mapping (or linkage) to the name of the raster view that the spatial constant refers to. Spatial constants must be defined before use in landscape events (as layers). This block has the following format:

SPATIAL CONSTANTS: { SpatialConstantSpec}+

A SpatialConstantSpec takes one of the following forms:

<VariableName> = <ViewName> Defines spatial constant VariableName and <VariableName> the mapping to a raster in the named view (window). In the second form, the view name is assumed be the same as the variable name. The raster view must exist. <VariableName> = [ViewName,…,ViewName] Defines a static raster vector.

Spatial Variables

This block defines spatial variables (dynamic layers) as part of the state space. Each definition specifies a mapping (or linkage) to the name of the raster view that the spatial variable refers to for output, and optionally a mapping to the raster view used for initial conditions. Spatial variables must be defined before use in landscape events (as layers). This block has the following format:

SPATIAL VARIABLES: { SpatialVariableSpec }+

A SpatialVariableSpec takes one of the following forms:

<VariableName> = <ViewName> <Bounds> Defines spatial variable VariableName with output mapped to the named raster view. Initial state is assumed to be 0. The bounds specify the min and max raster value. <VariableName> = <ViewName> <Bounds> <= <Number> Same as above, but value for the initial state is taken from the number (all cells set to same value) <VariableName> = <ViewName> <Bounds> <= <ViewName> Same as above, but initial state is taken from the second named view.

Raster Bounds takes one of the following forms: [<Number>] Maximum value (min. is assumed to be 0) [<Number>, <Number>] Minimum and maximum value

If an output view does not exist, it will be created automatically.

The keyword Accumulate can be placed to the right of a spatial variable definition to specify that the value is only initialized at the start of the first run in a multi-replicate simulation. That is, values accumulate between runs. As with spatial constants, the “= <ViewName>” can be omitted in all cases if the raster view is the same as the spatial variable name. Also the ViewName can be replaced by a list of view names “[ViewName, …, ViewName> to defines a dynamic raster vector. If input views are given, the number must be the same as the number of output views. However, in this case, no bounds can be given. To set bounds, use in conjunction with single value specifications.

Initial State Variable Mapping

Note: initial and dynamic state variable mappings are older methods (version 2.2. and before) of specifying spatial variables and constants. Many existing models use this format, and so it will continue to be supported (and is perhaps preferred by some users). The spatial variables and constants sections described above provide an alternate, and perhaps more clear, method of setting up spatial state. The Initial State Variable Mapping defines spatial variables as part of the state space and specifies a mapping (or linkage) to the names of raster views to use for initial values during simulation. Spatial variables must be defined before use in landscape events. One initial state mapping must be made for each spatial (layer) variable used in any landscape event, unless the desired initial state is all zeros. This block has the following format:

VARIABLE-INPUT VIEW MAPS: | VARIABLE-INPUT VIEW LINKS: | INPUT VIEW MAPS : { VarViewMapping }+

A VarViewMapping takes one of the following forms <VariableName> = <ViewName> Defines a single map (link) between a <VariableName> variable name and a raster in the named view (window). In the second form, the view name is assumed be the same as the variable name. The raster view must exist.

Dynamic State Variable Mapping

The Dynamic State Variable Mapping defines dynamic spatial variables as part of the state space and specifies a mapping to the names of raster views to use for dynamic output during simulation. Spatial variables must be defined in this block or the initial state variable mapping block before use in landscape events. One dynamic state mapping must be made for each dynamic spatial variable used in any landscape event. If an output raster doesn’t exist, it will be created. See previous section for the definition of a VarViewMapping. This block has the following format:

VARIABLE-OUTPUT VIEW MAPS: | VARIABLE-OUTPUT VIEW LINKS: | OUTPUT VIEW MAPS: { VarViewMapping }+

Dynamic Raster Bounds

Prior to running a simulation, SELES cannot foresee the range of values that are valid for a dynamic raster (i.e. a raster linked to the output of a dynamic spatial variable). This makes display and optimization of the raster difficult. Thus, the bounds for each dynamic raster need to be specified using the following format. The default bounds for a dynamic raster with an initial state raster are taken from the initial state, but it is good practice to explicitly state the bounds of all dynamic rasters

OUTPUT MODEL BOUNDS: { RasterBoundsSpec }+

A RasterBoundsSpec takes one of the following forms:

<VariableName> #Min, #Max Specifies that the raster will be in the range <VariableName> #Max* [Min,Max] or [Min, Min+Num-1]. In the last option, the min is assumed to be 0.

Dynamic Raster Output

During a simulation, a modeller may wish to periodically output the current state of a raster layer. The user can either specify a directory or a file name base for the raster. If a directory is specified, the file name base will be the name of the raster. If a file name base is specified, the directory will be the directory of this file name. The actual name of a file created will have the simulation run number and the sequence number of the output appended to the file name. For example, if the file name base is “Species”, then the 3rd output of the raster during the second simulation run will use the file named “Species_2_3”. Setting up raster output is done using the following format:

OUTPUT MODEL FREQUENCY: { RasterOutputSpec }+

A RasterOutputSpec takes one of the following forms:

<RasterName> FREQUENCY: {Expr} FILE: <“FileNameBase”> TYPE: {OutputType}* <RasterName> FREQUENCY: {Expr} DIRECTORY: <“Dir”> TYPE: {OutputType}*

These specify that the raster view named will be output at the specified frequency using the FileNameBase, where OutputType is one of: GRASS Uncompressed GRASS binary. GRASS COMPRESSED Compressed GRASS binary GRASS ASCII GRASS ASCII format ARC ASCII ARC ASCII format ERDAS8 8-bit ERDAS format (only use for rasters with bounds less than [0,255]) ERDAS16 16-bit ERDAS format. JPEG JPEG image format.

NOTE: The frequency expression is limited to numeric values, constants or simply global variable names.

Refresh Rate Commands

OUTPUT FREQUENCY : <#days> Specifies the default display refresh rate for dynamic raster views. This can be changed on the user interface.

Configuration Expressions

Configuration expressions are a restricted form of expression used to define values based on arithmetic combinations of numbers and previously defined constants or variables.

{Expr}= #Number {Expr}= <constant> {Expr}= <variable> {Expr} = ({Expr}) {Expr} = {Expr}+ {Expr} {Expr} = {Expr} – {Expr} {Expr} = {Expr} * {Expr} {Expr} = {Expr} / {Expr} {Expr}= {Expr} % {Expr} {Expr} = {Expr} % {Expr}

{Expr} = MIN(ViewName) Minimum bound for raster. {Expr} = MAX(ViewName) Maximum bound for raster. {Expr} = CELL SIZE(ViewName) length/width (usually in metres) of a cell. {Expr} = NUM > Number (ViewName) Number of values in raster greater than the number specified. {Expr} = ROWS(Global) Number of rows or columns, respectively, {Expr} = COLS(Global) (indexed from 0) of global variable, global constant or legend.

{Expr} = TOP(ViewName) Top georeferencing for raster (from header) {Expr} = BOTTOM(ViewName) Bottom georeferencing for raster {Expr} = LEFT(ViewName) Left georeferencing for raster {Expr} = RIGHT(ViewName) Right georeferencing for raster

Georeferencing information will depend on the raster projection.

Go to...  Prev Chapter  Next Chapter  Guide Index