Landscape Events (.lse)

Landscape events are the heart of SELES. Each .lse file defines one landscape event using two parts:

Definitions — declares the portion of the spatio-temporal state space used by the event (layers, variables, constants).
Properties — specifies the behaviour of the process (when, where, how it initiates, spreads, and causes state change).

All properties are optional with well-defined defaults. All state changes are specified as explicit assignments within property expressions.

General format:

LSEVENT: <EventName>
  { Definitions }
  { Property }*

5.1 Variable Declarations

The definitions section identifies and declares all variables used in the event's property expressions:

DEFINITIONS
  { VariableDefinition }+
ENDDEF

Each variable has a scope that determines where it is valid and what context it resides in (e.g. global scope = single aspatial value; spatial scope = per-cell value in spatial contexts).

Shared state-space variables (must be defined in the `.sel` file)

LAYER: <LayerName>
LAYER: <LayerName>[#NumSubLayers]
GLOBAL CONSTANT: <Constant>
GLOBAL CONSTANT: <Constant>[]
GLOBAL VARIABLE: <Variable>
GLOBAL VARIABLE: <Variable>[]
MACRO: <Macro>[]

Variables internal to the landscape event

OUTPUT VARIABLE: <Variable> = <FileName>
CONSTANT: <Constant> = #Value
LOCAL: <Variable>
LOCAL: <Variable>[#Dim]
EVENT VARIABLE: <Variable>
CLUSTER VARIABLE: <Variable>
CELL VARIABLE: <Variable>

Type	Scope	Notes
`LAYER`	Spatial	Spatial variable or constant from the shared state space
`GLOBAL CONSTANT` / `GLOBAL VARIABLE`	Global	Non-spatial constants/variables from the shared state space
`MACRO`	Global	Array of function expressions from a `.ce` file
`OUTPUT VARIABLE`	Global	Writes records to a tab-delimited output file
`CONSTANT`	Event-local	Named local constant
`LOCAL`	Event-local	Global-scoped but private to this event; undefined initial value
`EVENT VARIABLE`	Event instance	Unique to each active event instance
`CLUSTER VARIABLE`	Cluster	Unique to each active cluster within an instance
`CELL VARIABLE`	Active cell	Unique to each cell on the active front

Multiple variable names may appear on one line separated by commas (except for output variables and local constants).

System constants (always available)

Constant	Value
`NUMROWS`	Number of rows in the scenario
`NUMCOLS`	Number of columns in the scenario
`NUMCELLS`	Total number of cells (`NUMROWS * NUMCOLS`)

System variables (always available)

Variable	Value
`Time`	Current simulation time
`EndTime`	End time of the simulation
`Run`	Current Monte Carlo run number
`Location`	Current spatial location index (in spatial contexts). Use `ROW(Location)` and `COL(Location)` to get row/column.
`Index`	Current index value in an `OVER INDEX` expression
`EventId`	Unique identifier for each instance of this landscape event

Temporary local variables

Any variable that is not declared and not a system variable is treated as a temporary local variable — created automatically on first assignment, with scope limited to the immediately subsequent assignments or main expression of a property.

Advanced: Dynamic linked structures

Sets, lists, trees, and graphs are dynamic linked structures for advanced modelling. Declared in the definitions section using:

GLOBAL SET{#n} VARIABLE: <Variable>
GLOBAL LIST{#n} VARIABLE: <Variable>
GLOBAL TREE{#n} VARIABLE: <Variable>
GLOBAL GRAPH{#n1, #n2} VARIABLE: <Variable>

Each item is a vector of #n values. These are defined in the .sel file as regular global variables (single values) and used only with the corresponding set/list/tree/graph expressions.

5.2 Landscape Event Properties

Each property has three parts:

{ PropertyName }
  { Expression }*     (preliminary expressions — evaluated before main)
  { PropertyName } = { Expression }  (main expression)
  { Expression }*     (consequent expressions — evaluated after main)
{ PropertyEndTag }

Only the main expression is required. The enclosing name and end tag are optional if there are no associated state-change expressions. Properties can appear in any order after the definitions section.

Property keywords and end tags

Property	Keyword	End tag
Initial State	`INITIALSTATE`	`ENDIS`
Return Time	`RETURNTIME`	`ENDRT`
Event Location	`EVENTLOCATION`	`ENDEL`
Number of Clusters	`NUMCLUSTERS`	`ENDNC`
Probability of Initiation	`PROBINIT`	`ENDPI`
Transitions	`TRANSITIONS`	`ENDTR`
Spread Time	`SPREADTIME`	`ENDST`
Spread Location	`SPREADLOCATION`	`ENDSL`
Number of Recipients	`NUMRECIPIENTS`	`ENDNR`
Probability of Spread	`SPREADPROB`	`ENDSP`
End Cluster	`ENDCLUSTER`	`ENDEC`
End Event	`ENDEVENT`	`ENDEE`

Example — Fire event (from Table 1)

RETURNTIME = NEGEXP(5)          /* 5-year avg. negative exponential */

PROBINIT = IF Forested EQ FALSE THEN 0 ELSE ForestAge/10000

NUMCLUSTERS
  NUMCLUSTERS = 1
  FireSize = NORMAL(200,20)     /* mean 200, std. dev. 20 */
ENDNC

TRANSITIONS
  TRANSITIONS = FireSize > 0    /* continue if more cells to burn */
  FireSize = FireSize - 1       /* decrement remaining fire size */
  ForestAge = 0                 /* burn the cell */
ENDTR

Notes on main expressions

Property	Expected value
`InitialState`	Integer > 1 — number of event instances created at simulation start
`ReturnTime`	Real > 0. Value of 0 at time 0 = process immediately; value of 0 later = terminate the event
`EventLocation` / `SpreadLocation`	Region functions (sets of cells). Only these two properties may use region functions.
`NumClusters` / `NumRecipients`	Integer > 0
`ProbInit` / `SpreadProb`	Real > 0. Value of 0 always excludes a cell. Absolute probability if NumClusters/NumRecipients undefined (should be 0–1); relative weight otherwise (any value > 0).
`Transitions`	Logical value — active cell continues only if TRUE
`SpreadTime`	Positive = normal queue-based spread; negative = immediate mode (cluster spreads fully before next initiation)

SpreadTime immediate mode: A negative SpreadTime causes a cluster to spread entirely before the next cluster is initiated. Useful for modelling patches sequentially rather than in parallel. The absolute value is used to prioritise cell ordering within the cluster's temporary queue.

note

The consequent expressions of SpreadTime are processed after spreading finishes (just before the active cell terminates), not when the cell is taken off the queue. Preliminary expressions of SpreadLocation and NumRecipients are processed as soon as the active cell is taken off the queue.

5.3 Specifying State-Change

State changes are specified as assignments in the preliminary or consequent expressions of a property:

<Variable> = { Expr }

Expressions can also use procedural elements (iteration, conditions, etc.) within which assignments are made.

5.4 Expressions

Property expressions form the core of the SELES modelling language. They can range from simple constants to complex stochastic spatial functions. See Expression Syntax for full syntax details.

High-level expression types available:

Category	Description
Constants	Numbers or named constants
Variables	Named variables in the current context; arrays indexed by expressions; macros (execute a function at an index)
`SOURCE` keyword	In spatial spread contexts, refers to values at the source spreading cell rather than the current (recipient) cell
Arithmetic	Standard arithmetic, exponents, logs, modulo
Boolean	Equality, relational (`<`, `>`, etc.), logical (`AND`, `OR`, `NOT`)
Conditional — functional	`IF (expr) THEN result1 ELSE result2` or `(expr ? result1 : result2)`
Conditional — procedural	`IF … ELSE IF … ELSE … END` blocks
While-loops	`WHILE condition … END`
Iteration	`OVER INDEX(n1, n2) … END` (for-loop style)
Spatial functions	Distance, direction, neighbourhood operations
Output expressions	Write records to files; display on screen
Probability distributions	`NEGEXP`, `NORMAL`, `UNIFORM`, `WEIBULL`, etc. — return a stochastic draw each time evaluated
Probability density functions	Return the probability for a given value from a distribution
Trigonometric	`SIN`, `COS`, `TAN` (angles in degrees)
Class / discrete	Switch-style expressions for categorical variables
Bit-vector	Set and test individual bit positions in a variable
Control	Set random number seed; pause on conditions
Composite	Combine multiple sub-functions (e.g. conjunction of conditions)
Region	Define spatial regions — used only in EventLocation, SpreadLocation main expressions, or with the `OVER` keyword
Matrix	Operations on 1-D and 2-D arrays
Set / List / Tree / Graph	Dynamic linked structure operations (advanced)

5.5 Property Options for Initiation/Spread

Optional flags placed to the right of the NUMCLUSTERS, PROBINIT, NUMRECIPIENTS, or SPREADPROB section name modify the default selection algorithm.

Selection with replacement

By default, cells selected for initiation or spread are unique (without replacement). Add WITH REPLACEMENT to allow a cell to be selected more than once:

NUMCLUSTERS WITH REPLACEMENT
  NUMCLUSTERS = 100
ENDNC

Randomised order (`RANDOM`)

Cells are processed for initiation/spread in random shuffled order (rather than the default bottom-left to top-right):

PROBINIT RANDOM
  PROBINIT = 0.1
ENDPI

Sorted order (`ORDERED`)

Cells are processed in decreasing order of their ProbInit/SpreadProb value:

PROBINIT ORDERED
  PROBINIT = StandAge     /* process oldest stands first */
ENDPI

note

Sorting large probability surfaces can take considerable time.

Probability re-computation (`RECOMPUTE`)

By default, probability surfaces are computed once at the start of initiation/spread. Use RECOMPUTE to force re-computation during initiation/spread (e.g. to reflect state changes as they occur):

Add the RECOMPUTE flag to ProbInit or SpreadProb.
Include a RECOMPUTE expression where re-computation should be triggered (typically in Transitions or the consequent of ProbInit).

PROBINIT ORDERED RECOMPUTE
  PROBINIT = FuelLoad
ENDPI

TRANSITIONS
  TRANSITIONS = TRUE
  IF SufficientChange
    RECOMPUTE
  END
ENDTR

If NumClusters/NumRecipients is bounded, re-computation restarts processing of all cells (as if WITH REPLACEMENT is set). Include conditions in ProbInit or Transitions to prevent re-initiation of already-visited cells if needed.

5.6 Property Options for SpreadTime

The sign of the SpreadTime value controls the spread mode:

SpreadTime value	Mode
`> 0`	Normal — spreading cells are placed on the main event queue and processed at the appropriate future time, potentially interleaved with other clusters and events
`< 0`	Immediate — a cluster spreads entirely before the next cluster is initiated; uses the absolute value to prioritise cell ordering within a temporary cluster queue

Mixtures are possible (the decision is made per active cell based on its unique SpreadTime).

5.1 Variable Declarations​

Shared state-space variables (must be defined in the .sel file)​

Variables internal to the landscape event​

System constants (always available)​

System variables (always available)​

Temporary local variables​

Advanced: Dynamic linked structures​

5.2 Landscape Event Properties​

Property keywords and end tags​

Example — Fire event (from Table 1)​

Notes on main expressions​

5.3 Specifying State-Change​

5.4 Expressions​

5.5 Property Options for Initiation/Spread​

Selection with replacement​

Randomised order (RANDOM)​

Sorted order (ORDERED)​

Probability re-computation (RECOMPUTE)​

5.6 Property Options for SpreadTime​