Scenario Reference

Note: this conversion between the Word .doc and the Wiki is incomplete: please help

Documentation Version SELES v3.1

This document describes SELES scenario files. A SELES scenario executes a sequence of commands to perform tasks such as loading spatial information, opening models and running simulations. Scenario files essentially provide a scripting language for setting up and running experiments in SELES. This document describes the syntax and meaning of the commands available for scenarios. See the SELES Model Builder’s Guide for other information. The scenario reference is presented in a separate document from the builder’s guide because some users (model drivers) may only need to understand the user interface and scenario language to make use of existing models.

Deciphering the Syntax Descriptions

• Every command must be placed on a separate line (i.e. separated by a carriage return).

• The last command must also have a carriage return (i.e. the last line is blank).

• All KEYWORD’s are shown in upper case and must be spelled exactly as shown although the scenario language is not case sensitive.

• Labels enclosed in “<>“ indicate that the modeller must substitute an appropriate value.

• Values preceded by a “#” must be integers, those preceded by “#.#” may be any numeric;

• Values preceded by a “%” are logical values (true or false);

• Values enclosed in double quotes (“”) indicate literal strings or filenames;

• All other values are identifiers.

Most of the commands have a meaning obvious from their keyword. In cases where the semantics, or meaning, of a command is not obvious, a description is included to the right of the syntax.

General Syntax Rules

• White space (spaces, tabs, carriage returns) is ignored. Be as liberal or sparse with it as you like. Comments are treated as white space by the parser.
• Comments can be placed anywhere in a model definition file. Comments are surrounded by “/*” and “*/” (e.g. /* This is a comment, and is ignored by the parser */ ). In addition, any text to the right of “//” is treated as a comment.
• Literal text string values must be enclosed in double quotes (e.g., “This is a literal string”).
• Filenames may be specified as literal strings or as regular text. If spaces or unusual characters are used then enclose the name in double quotes.
• Logical value may be any of the following: ‘0’, ‘OFF’, or ‘FALSE’ to indicate false; ‘1’, ‘ON’, or ‘TRUE’ to indicate true.

Scenario Specification

A scenario file must begin with the the line:

Scenario Information

or

Seles Scenario

It may then include the following types of commands, in any order and number:

• Open GIS rasters:

<filename>
<viewname> = <filename>

Each open command is specified using the name of the raster file. Raster file names can be optionally preceded by an identifier to rename the raster. Thus, the command:

Elev100.asc

opens the raster in file “Elev100.asc” and display it in a window (view) of the same name. The command:

Elevation = Elev100.asc

opens the same raster file, but displays it in a window with the name “Elevation”. Rasters can be in GRASS, ARC GRID ASCII or ERDAS formats.

Appending an asterisk and expression (e.g. “* 10”) as a suffix to one of the above commands will multiply each cell value read by the amount of the expression. This is useful to read real-value rasters.

• Save Views as GIS rasters:

SAVE <ViewName> <FileName> <Type>

Saves the raster in the specified view in the specified file. The file type must be one of GRASS, GRASS COMPRESSED, GRASS ASCII, ARC ASCII, ERDAS8, ERDAS16

• Save Views as JPEG images:

SAVE <ViewName> <FileName> JPG
SAVE <ViewName> <FileName> JPEG
SAVE <ViewName> <FileName> JPG [#Bottom, # Left, #Top, #Right]
SAVE <ViewName> <FileName> JPEG [#Bottom, # Left, #Top, #Right]

Saves the raster in JPEG format. The latter two versions allow users to specify a sub-region of the raster.

• Open sub-model files:

<filename>

Sub-model may be static models or a Seles model file (see the SELES Static and Dynamic Model References). Note that at most one dynamic model can be loaded at a time (but this may contain multiple landscape events). Each subsequent dynamic model supercedes any previously loaded dynamic model.

• Set spatial dimensions(which override sub-model dimensions):

Model Width: #NumColumns
Model Cols: #NumColumns
Model Height: #NumRows
Model Rows: #NumRows
Model Dimensions: #NumRows, #NumColumns
Model Dimensions: <ViewName>

The first five commands specify the dimensions of the scenario statically. The last command specifies that the scenario dimensions should be the same as the dimensions of a loaded raster, where the view name must be the name of a currently loaded raster layer. A dynamic model file should have its dimension specified prior to loading.

• Display commands:

Minimize All
Minimize <viewname>
Minimize Initial State
Minimize Static
Minimize
Tile

The first minimizes all views currently open, while the second minimizes a specified view. The third minimizes all windows that contain rasters that are part of the initial state of a dynamic model. The fourth command minimizes all windows that contain raster layers that are static in a dynamic model. This includes the initial state layers as well as other static layers. The next minimizes the entire SELES application. The Display Resolution command allows rasters to be displayed at a lower resolution than they are stored at, which may speed up display for extensive rasters. The value must be larger than 0 and at most 0.5 to take effect. The last command tiles the windows that are not minimized.

• Simulation control:

SimStart #RunLength #Runs
SimStart #RunLength #Runs PRIORITY SimPriority
SIMPRIORITY SimPriority
DryRun
<landscape event filename>  %UseEvent

The first command starts a simulation for #Runs number of runs, each of which will run for #RunLength number of time units. The second command is the same, but allows control of the simulation priority (HIGH PRIORITY, LOW PRIORITY, VLOW PRIORITY or NORMAL PRIORITY). The default is normal. Low and vlow (very low) priority are useful which modifying and verifying some models to improve system response to user input. High priority is useful for some mdoels to increase execution speed during batch simulations. Simulation priority can be set on its own, which may be useful when a scenario does not actually start a run. The next command performs all the setup for a simulation without actually starting the run. This is useful to test a model to ensure that it has a valid confguration. The last command allows specify landscape events (in the current dynamic model file) to be activated or deactivated.

• Scenario (also called string) variables:

$Label$ = Value

This command sets a local variable named “Label” to the value on the right-hand side. The dollar signs ($) must be surround the variable label to identify this as a scenario variable (and allow concatentation of multiple labels when using the variable). In general, scenario variables can be placed whereever a numeric or text value is required, and the label is replaced by the variable value. When used in place of a number, the text must denote a numeric value. When used in a position requiring text, the variable can be concatentated with other text or string variables. For example:

$x$ = “meso”
$y$ = 5
MesoView = $x$$y$.grd

This will attempt to open a raster file named

“meso5.grd” into a view named 
“MesoView”

If the scenario variable is assigned the name of a global variable, then by default the text name of the variable is used. If the value of the global variabl eis desired, surround the global variable by “#”. For example:

$x$ = ForestSize
$y$ = #ForestSize#

Suppose “ForestSize” is a global variable with values 200. Then $x$ will have value “ForestSize” while $y$ will have value “200”.

Note: If the value is “.”, then the scenario variable will be assigned the path of the current working directory. This is useful to be able to return to the working directory after doing complex directory movements.

• Setting model variables:

<variable> = Expression
<variable> = Expression, Expression, …, Expressions
<variable> = [Expression, Expression, …, Expressions]

This command changes the initial value for a global variable that must have been previously defined in a model file. The latter two forms are for one-dimensional array variables, where one expression can be specified for each entry. Expressions are defined as:

#Value
#GlobalVariable
#GlobalConstant
$StringVariable$
(Expression)
Expression + Expression
Expression - Expression
Expression * Expression
Expression / Expression
Expression ^ Expression
| Expression |
ROUND( Expression)
CEIL( Expression)
FLOOR( Expression)
Expression AND Expression
Expression OR Expression
NOT Expression
Expression EQ Expression
Expression == Expression
Expression NEQ Expression
Expression != Expression
Expression < Expression
Expression <= Expression
Expression > Expression
Expression >= Expression
Expression << Expression
Expression >> Expression 

Thus, complex arithmetic expressions can be created to define the value. Note that for using string variables, dollar signs ($) must surround the variable name and the text value must represent a number. The “^” sign denotes exponentiation, and the “|” symbols denote absolute value. “EQ” and “==” both test equality, while “NEQ” and “!=” both test inequality. The symbols “<<” and “>>” denote left and right bit-shifting.

• Spatial Variable Override:

RELINK <Layer variable> = <Raster view name>

This command can be used to override a variable-view mapping from a SELES model file. For example:

Relink Elevation = ElevationGrid2

Suppose the Elevation was linked to “ElevationGrid” in the SELES model file. This command would change that mapping to “ElevationGrid2”.

• Legend Override:

LEGEND <LegendConstant> ={Value:Name, …, Value:Name}

This command can be used to modify legend labels for a legend constant set up in a a SELES model file. For example:

Legend SppLegend = {1:DouglasFir, 2:Hemlock}

This would change the legend names “SppLegend” so that index 1 has value “DouglasFir” and index 2 has value “Hemlock”.

• Other control commands:

cwd <directory>   (or cd <directory>)
Close <viewname>
Close All

The first command changes the current directory (which by default is that of the scenario file). This is useful for controlling where output files are created for different experiments. The directory name on the right-hand side can be specified usign a string variable (e.g. cwd $gisDir$). If the directory specifies a multi-level path (which may include “..” to go to parent folders), then the directory must exists. If a single level path is specified (e.g.. cwd tmp), then the folder will be created if it doesn’t exist. Sometimes it is useful to use these commands to ensure that certain directories exist (e.g. the directories used for raster output that will be scheduled be a dynamic model).

The first close command closes a specified window while the second closes all windows. This is useful for freeing memory used by rasters after a simulation has run, especially when multiple simulations are processed in batch.

• System commands:

system "command"

Execute the system command specified as a literal string. For example, sometimes it is useful to copy files in an experiement. For example, the command:

system "copy harvestRate1.txt harvestRate.txt"

copies the file harvestRate1.txt to the file harvestRate.txt (which allows modifying the harvest rate input file in this model). Note that in this case, the dynamic model must be reloaded to cause this change to take effect (since input files are generally loaded when the dynamic model is read). Any system command can be performed. In Windows, this includes any command available in a command prompt.

• File looping/wildcard commands:

A wildcard is an asterisk (*) used to denote arbitraty text (e.g. “*.txt”). Sometimes it is useful to run a sequence of commands repetitively over a set of related files. The current syntax is:

for($label$ = “text”)
…
end

where the text should normally have at least one wildcard, and the “…” represents any sequence of commands. If there is precisely one wildcard, then the scenario variable will be assigned the “filler” for this wildcard. If there are more than one wildcards, then he scenario variable will be assigned the complete text for each match. Note that loops can be nested. The following is an example loop:

model.sel
cwd age1
for($x$ = “age*.grd”)
StandAge = age$x$.grd
cwd ..\age$x$
SimStart 100 1
Close StandAge
end"

This sequence opens a dynamic model file and runs a simulation on each file named “age*.grd”. It also creates and changed to different directories so that output files for each simulation do not get overwritten.

• Iterative Looping commands:

Sometimes it is useful to run a sequence of commands repetitively over a range of values. The syntax is:

for($label$ = n1:n2)
…
end
or 
for($label$ = n1:n2, step)
…
end

The variable $label$ takes on successively the values n1, n1+ step, … In the first form, the step is implicitly 1. The loop stops when the value for $label$ exceeds n2. Note that loops can be nested. The following is an example loop:

model.sel
cwd age1
for($x$ = 1:10)
        param1 = $x$
        SimStart 100 1
end

• Conditional commands:

Sometimes it is useful to run a sequence of commands only if a condition is met. The syntax is:

if(condition)
…
end

The condition is treated as a boolean expression. The commands will be repeatedly run until the condition evaluates to false. The following is an example:

model.sel
param1 = 1
if(outputVar < 0)
          param1 = param1 + 1
end
SimStart 100 1

• Conditional Looping commands:

Sometimes it is useful to run a sequence of commands repetitively until a condition is met. The syntax is:

while(condition)
…
end

The condition is treated as a boolean expression. The commands will be repeatedly run until the condition evaluates to false. The following is an example loop:

model.sel
cwd age1
param1 = 1
while(outputVar < 0)
          param1 = param1 + 1
          SimStart 100 1
end

• Scheduling commands:

In some cases, one wishes to perform a set of commands periodically during a simulation (e.g. to make a system call to an external model, or to re-load a time series of layers)

schedule(period)
…
end

The period is an expression that is recomputed at the start of a simulation and after each time the set of commands is run. The value indicates the time step until the next evaluation. If this is 0, it will not be rescheduledThe following is an example:

// Schedule periodic reloading each 25 years
Schedule(25)
      // Re-open dynamic layers
      $x$ = #NextStep#
      StandAge = $dynamicGisDir$\StandAge_1_$x$
end

This example schedules commands to be repeated every 25 time units (assumed to be years here). We assume that the layers are numbered 1, 2, … representing time periods 25, 50, etc. A global variable “NextStep” is assumed to be maintained by the model to set up the next appropriate suffix.

• Appending output files:

Reset Output: %Logical

By default, each time a simulation starts (e.g. with the SimStart command), output files are cleared. This command specifies that output files are to be appended, rather than cleared. Care must be taken to ensure that old information from previous runs gets cleared. This command is especially useful with looping as shown in the following example:

model.sel
$clearFiles$ = TRUE
for($x$ = “age*.grd”)
        StandAge = age$x$.grd
        Reset Output: $clearFiles$
        $clearFiles$ = FALSE
        id = $x$
        SimStart 1001
        Close StandAge
end

This will place all output in a single set of files. Notice, however, that the files are cleared on the first time through the loop. The variable “id” is assumed to be created by the dynamic model file and can be used to differentiate outputs (e.g.. if it is placed in a column in each output file).

Each file name or command is specified on a separate line. Opening a scenario file automatically opens all GIS rasters and sub-models, and executes the commands, in the order specified. While a simulation is running, some commands are blocked until the simulation has finished, in particular models cannot be loaded, layers cannot be saved, simulation, general control and system commands cannot be processed. If encountered, the command interpreter waits until the simulation has completed before continuing. In such cases, the user interface cannot be accessed.

Any GIS layer that does not have the same dimensions as the scenario will be sub- or super-sampled to obtain a set of spatial state layers that all have the same dimensions. If a different algorithm or technique is required to georeference and match the spatial layers, then this should be done prior to loading a scenario in SELES. The dimensions in sub-model files will also be over-ridden by the scenario dimensions.

A Note on Command Ordering

Correct ordering of commands is critical to achieve the desired results.

• All input files loaded in a dynamic model are read at the time the model file is loaded in the scenario. Thus, be sure to do all copy system commands prior to loading a dynamic model. If an input file is changed during a scenario, you must re-load the dynamic model file. Since this will clear the old model and reset variable values, you must then reset any modified initial state variable values.

• Global variables are defined by the dynamic model, and so any changes to initial values must be done after the dynamic model is loaded. If the model is re-loaded, values are reset to their default initial state.

• Care must be taken when changing directories. When loading or reloding models, or copying files, the correct path must be specified relative to the current directory.