Skip to main content

Scenario Scripts (.scn)

A SELES scenario script executes a sequence of commands — in the order specified — to perform tasks such as loading spatial data, opening models, and running simulations.

2.1 General Syntax Rules​

  • Every command must be on a separate line (separated by a carriage return).
  • The last command must also be followed by a carriage return (i.e. the last line of the file is blank).
  • All KEYWORDs are shown in upper case and must be spelled exactly as shown (the language is not case sensitive).
  • <Labels> in angle brackets indicate values that the modeller must substitute.
  • Values preceded by # must be integers; values preceded by #.# may be any floating-point value.
  • Values preceded by % are logical values (true or false).
  • Values in double quotes ("…") are text strings or filenames.
  • All other values are identifiers (e.g. variable names, file names).
  • White space (extra spaces, tabs, carriage returns) is ignored.
  • Comments: /* … */ for block comments; // for line-end comments.
  • File names and folder paths may optionally be enclosed in double quotes. Use quotes if the path contains spaces or unusual characters. Examples: 
    ..\outputs\scn1
    "..\my outputs\example scn1"
  • Logical values: 0, OFF, or FALSE = false; 1, ON, or TRUE = true.

2.2 Scenario Commands​

A scenario file must begin with either of the following (the latter is preferred):

Scenario Information
Seles Scenario

The following commands may then appear in any order and number, and are processed in the order encountered.

Load GIS Rasters​

<FileName>
<ViewName> = <FileName>

Opens a raster file into a view. If a view name is omitted, the view takes the name of the raster file (without suffix). Examples:

Elev100.tif
Elevation = Elev100.tif

Supported formats: GeoTiff (preferred), GRASS, ARC GRID ASCII, ERDAS. If the raster format is real-valued, a real-value view is created; otherwise an integer-value view is created.

Scale on load: append * <expression> to multiply each cell value by a factor when loading — useful to scale real-value rasters into fixed-point integer views:

SiteIndex10 = SiteIndex.tif * 10

Save Raster Views​

SAVE <ViewName> <FileName> <Type>

Saves the named raster view to a file. <Type> must be one of: GeoTiff, GRASS, GRASS COMPRESSED, GRASS ASCII, ARC ASCII, ERDAS8, or ERDAS16. Example:

Save StandAge grids\StandAge_year400.tif GeoTiff

Open Dynamic Model Files​

<FileName.sel>

Loads a dynamic model (.sel) file, defining the spatio-temporal state space. Example:

ForestEstateLM.sel

Before loading a dynamic model, all required inputs must already be loaded:

  • Raster views used as spatial variables and constants.
  • Script variables used for input file paths, file names, initial parameter settings, etc.

Only one dynamic model is active at a time — loading a new one supersedes the previous one.

Set Spatial Dimensions​

Model Dimensions: <ViewName>

Sets the scenario dimensions (rows and columns) to match a loaded raster view. Must be specified before loading the dynamic model file. Example:

Model Dimensions: StudyArea
ForestEstateLM.sel

Any input raster that does not match the dynamic model dimensions will be sub- or super-sampled, with a warning. In general, matching georeferencing should be done before loading a scenario.

Simulation Control​

SimStart #RunLength
SimStart #RunLength #Runs
<LandscapeEventFileName> %UseEvent

All simulation control commands must follow loading of a dynamic model file.

  • SimStart #RunLength — Runs a single simulation for the specified number of time units.
  • SimStart #RunLength #Runs — Runs #Runs Monte Carlo replicates, each for #RunLength time units. Example: 
    SimStart 400
    SimStart 400 100
    Simulations start at time 0. Events are processed up to (but not including) #RunLength.
  • <LandscapeEvent.lse> %UseEvent — Activates or deactivates a landscape event loaded in the current dynamic model. Useful for testing. Example: 
    Logging.lse OFF

Expressions​

Expressions assign values to global variables or script variables and can be used in conditions. They evaluate to a numeric or logical value.

#Value
<GlobalConstant>
<GlobalVariable>
(Expression)

Arithmetic operators:

OperatorMeaning
+ - * /Standard arithmetic
^Exponentiation
%Modulo (remainder)
| Expression |Absolute value
ROUND(Expression)Round to nearest integer
CEIL(Expression)Round up
FLOOR(Expression)Round down

Logical operators:

OperatorMeaning
ANDLogical conjunction
ORLogical disjunction
NOTLogical negation
EQ or ==Equality
NEQ or !=Inequality
< <= > >=Comparisons
<< >>Bit-shift left / right

Normal precedence rules apply. Use parentheses to make complex expressions unambiguous, especially when mixing types (e.g. x + y > z).

Setting Global Variables​

<Variable> = Expression
<Variable> = Expression, Expression, …
<Variable> = [Expression, Expression, …]

Changes the initial value of a global variable after loading the dynamic model (the variable must be defined in the .sel file first). The second and third forms are for one-dimensional array variables.

note

If a global variable is used as a logical value, use OR/AND rather than +/*. For example, if x and y are both TRUE (value 1), then x + y evaluates to 2, while x OR y evaluates to TRUE.

Script Variables (String Variables)​

$Label$ = <Value>

Creates and/or sets a script variable named Label. Dollar signs ($) delimit the variable name. The value can be text or a numeric/logical expression.

Script variables can be placed wherever a numeric or text value is required — the variable name is replaced by its value. When used as text, variables can be concatenated:

$x$ = "meso"
$y$ = 5
MesoView = $x$$y$.tif

This opens a raster file named meso5.tif into a view named MesoView.

Accessing a global variable's value (not its name): surround the name with # instead of $:

$x$ = ForestSize    // $x$ = "ForestSize" (the name)
$y$ = #ForestSize#  // $y$ = 200 (the value, if ForestSize = 200)

Capture current directory:

$currDir$ = "."

Common uses for script variables:

  • Managing input/output folder paths.
  • Linking parameter settings with output folder names.
  • Setting up iterative simulation runs.
  • Passing input file names and paths into .sel files.

General Control Commands​

cwd <Directory>
mkdir <Directory>
Close <ViewName>
Close All
  • cwd — Change the current working directory (starts as the folder containing the scenario file). Folders are created if they don't exist. Supports script variables: cwd $outputDir$\$scnDir$.
  • mkdir — Explicitly create a directory or folder structure.
  • Close <ViewName> — Close a specified raster view.
  • Close All — Close all raster views and clear loaded models from memory. Useful for freeing memory between batched simulations.

System Commands​

system "<Command>"

Executes any Windows system command. Example:

system "del /s harvestRate$x$.txt"
system "ren harvestRate.txt harvestRate$x$.txt"
caution

System commands cannot return error messages (e.g. if a file delete fails because the file is open). Use with care and avoid if possible.

Conditional Commands (if statements)​

if (Condition)
  …
else if (Condition)
  …
else
  …
end

The condition is treated as a Boolean expression (result > 0 = true). The else if and else sections are optional. Example:

wildfire.sel
param1 = 1
if (outputVar > 0)
  param1 = param1 + 1
else if (outputVar < 0)
  param1 = param1 - 1
end
SimStart 100 1

Conditional Loops (while)​

while (Condition)
  …
end

Repeats commands until the condition evaluates to false. Example:

wildfire.sel
param1 = 1
outputVar = -1
while (outputVar < 0)
  param1 = param1 + 1
  SimStart 100
end
caution

Ensure the condition will eventually become false. An always-true condition creates an infinite loop that requires forcibly terminating seles.exe.

Iterative Loops (for — numeric range)​

for ($label$ = #n1 : #n2)
  …
end

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

$label$ takes values n1, n1 + step, … stopping when it exceeds n2. Default step is 1. Loops can be nested. Example — run 10 simulations with $x$ = 1 through 10:

wildfire.sel
for ($x$ = 1:10)
  param1 = $x$
  SimStart 100 1
end

File Loops (for — wildcard)​

for ($label$ = "Text*")
  …
end

Iterates over all files matching the wildcard pattern. If there is exactly one *, $label$ is assigned the text matched by the wildcard. If there is more than one *, $label$ is assigned the full matching filename. Loops can be nested. Example:

wildfire.sel
for ($yr$ = "age*.tif")
  StandAge = age$yr$.tif
  cwd ..\age$yr$
  SimStart 100 1
  Close StandAge
end

2.3 How Scenario Files Are Processed​

When a SimStart command is encountered, SELES runs the simulation. While the simulation is running, certain commands are blocked until it completes:

  • Loading a subsequent dynamic model
  • Saving rasters
  • Starting another simulation
  • Changing the current working directory
  • Executing system commands

If such commands follow a SimStart, the command interpreter waits for the simulation to finish. During this wait, the user interface will be non-responsive (including output from DISPLAY commands in landscape events). Ensure a model runs without error before deploying it in a complex scenario.

Command Ordering Relative to .sel Files​

Correct ordering of commands around the .sel file load is critical:

Before loading the dynamic model:

  • Load all rasters used by the .sel file (at least the initial conditions).
  • Set all script variables used in the .sel file. Script variables set after loading will not affect the .sel file load.

When the .sel file is loaded:

  • All input files (tables, legends, sub-models, macros) referenced by the .sel file are read immediately.
  • All global variables and constants are defined and their initial values set.

After loading the dynamic model:

  • Global variables are now defined — any changes to their initial values must be made after the .sel file load.
  • Take care when changing directories: folder paths in a scenario file are relative to the current directory, while folder paths in dynamic model files are relative to the folder containing the .sel file.