Expression Syntax

Expression specifications are the core of the SELES modelling language, used in landscape events, macros, and value summary models. Expressions can be simple or complex, deterministic or stochastic.

Functional expressions return a value (typically assigned to a variable). Procedural expressions do not return a value and cannot be used where a return value is expected. An assignment (e.g. x = Expr) is a special form of procedural expression.

Use parentheses to ensure desired precedence — standard rules apply within types (e.g. x + y * z = x + (y * z)), but there are no standard rules between types (e.g. use (x + y) > 0 rather than x + y > 0 to be explicit).

TRUE and FALSE are equivalent to 1 and 0.

1.1 Constants, Variables and Macros

ZERO                      → 0.0
ONE                       → 1.0
#Number                   → numeric literal value
<Constant>                → value of a named constant
<Constant>[Expr]          → value at index in a 1-D constant array
<Constant>[Expr, Expr]    → value at index in a 2-D constant array
<Variable>                → value of a variable
<Variable>[Expr]          → value at index in a 1-D variable array
<Variable>[Expr, Expr]    → value at index in a 2-D variable array
<Macro>[Expr]             → evaluate macro function at the given index

1.2 Arithmetic Functions

(Expr)                    → expression value (adds parentheses)
Expr + Expr               → sum
Expr - Expr               → difference
Expr * Expr               → product
Expr / Expr               → quotient
Expr % Expr               → modulo (remainder on integer division)
| Expr |                  → absolute value
ABS(Expr)                 → absolute value (same as above)
Expr ^ Expr               → exponentiation (nth root = use 1/n as exponent)
EXP(Expr)                 → e^Expr (natural exponential)
LOG(Expr)                 → natural logarithm; log base b: LOG(x)/LOG(b)
ROUND(Expr)               → round to nearest integer
FLOOR(Expr)               → largest integer ≤ value
CEILING(Expr)             → smallest integer ≥ value
MIN(Expr, Expr)           → smaller of two values
MAX(Expr, Expr)           → larger of two values
CLAMP(Expr, Min, Max)     → restrict to range [Min, Max]

Shorthand assignment forms:

<Variable>++              → Variable = Variable + 1
<Variable>--              → Variable = Variable - 1
<Variable> += Expr        → Variable = Variable + Expr
<Variable> -= Expr        → Variable = Variable - Expr
<Variable> *= Expr        → Variable = Variable * Expr

1.3 Boolean Functions

Expr EQ Expr     (or ==)   → TRUE if equal
Expr NEQ Expr    (or !=)   → TRUE if not equal
Expr < Expr                → TRUE if first < second
Expr <= Expr               → TRUE if first ≤ second
Expr > Expr                → TRUE if first > second
Expr >= Expr               → TRUE if first ≥ second
!Expr                      → negation (TRUE if Expr is FALSE)
Expr AND Expr              → TRUE if both TRUE
Expr OR Expr               → TRUE if at least one TRUE

Relations can be cascaded: a <= b <= c is TRUE only if b falls in the range [a, c].

1.4 Conditional Expressions

IF Expr THEN Expr ELSE Expr        → functional if (returns a value)
(Expr ? Expr : Expr)               → compact functional if (embeddable)

IF Expr                            → procedural if
  …
END

IF Expr                            → procedural if-else
  …
ELSE
  …
END

WHILE Expr                         → procedural while loop
  …
END

ELSE IF expr sections can be chained between IF and ELSE.

1.5 Iteration Expressions

OVER INDEX(Expr, Expr)
DECISION Expr
  …
END

Iterates a set of expressions over a linear sequence of indices. The optional DECISION expression (or ?) filters to indices where it returns TRUE. The built-in variable Index holds the current index value.

1.6 Spatial Functions

DISTANCE(Expr, Expr)       → Euclidean distance between two locations
DIRECTION(Expr, Expr)      → angle in degrees between two locations

AT LOCATION(Expr)          → evaluate sub-expressions at a specified location
  Expr
  :
END

Locations are typically obtained from the Location system variable.

1.7 Output Expressions

DISPLAY                    → print labelled values to screen
  <Label>: Expr
  …
END

DISPLAY                    → same, but conditional
  DECISION Expr
  <Label>: Expr
  …
END

OUTPUT(<OutputVariable>)   → write labelled values to output file
  <Label>: Expr
  …
END

OUTPUT(<OutputVariable>)   → same, but conditional
  DECISION Expr
  <Label>: Expr
  …
END

If no label is given, the expression must be a simple variable (used as the label).

Column expansion: Label#n1:n2 : Expr creates n2 - n1 + 1 columns; Index takes values n1 through n2.

Legend output: prefix an expression with $ to output the legend label instead of the numeric value (e.g. spp: $Species). For variables without a built-in legend, use spp: $x {SpeciesLeg}.

1.8 Probability Distributions

Each call draws a new stochastic value from the specified distribution.

NORMAL(mean, stddev)
SKEWED NORMAL(mode, leftStddev, rightStddev)
LOG NORMAL(mean, stddev)
WEIBULL(beta, alpha)
NEGEXP(mean)
POISSION(mean)
UNIFORM(min, max)

CLASSIFIED_DIST            → discrete distribution (relative probabilities)
  #Number: Expr
  :
END

CLASSIFIED_DIST(#Number+)  → same; classes start at 0; constant probs only

CLASSIFIED_DIST            → probabilities from a 1-D array variable
  Expr
  :
END

note

WEIBULL parameter order matches Excel (beta first, then alpha).

1.9 Probability Density and Cumulative Density Functions

These return the probability (density) for a given value X. Multiply PDF results by a width factor to get a probability (estimated area under the curve; default class size = 1).

Temporal PDFs give the probability of X being selected given that it hasn't been selected yet (i.e. conditional on the true value being > X).

NORMAL PDF(x, mean, stddev)
NORMAL CDF(x, mean, stddev)
SKEWED NORMAL PDF(x, mode, leftStddev, rightStddev)
SKEWED NORMAL CDF(x, mode, leftStddev, rightStddev)
LOG NORMAL PDF(x, mean, stddev)
LOG NORMAL CDF(x, mean, stddev)
NORMAL TEMPORAL PDF(x, mean, stddev)
SKEWED NORMAL TEMPORAL PDF(x, mode, leftStddev, rightStddev)
LOG NORMAL TEMPORAL PDF(x, mean, stddev)
UNIFORM TEMPORAL PDF(x, min, max)

1.10 Trigonometric Functions

Angles are in degrees, measured as compass directions (clockwise from north).

SIN(Expr)                  → sine of angle in degrees
COS(Expr)                  → cosine of angle in degrees
TAN(Expr)                  → tangent of angle in degrees
ARCSIN(Expr)               → inverse sine
ARCCOS(Expr)               → inverse cosine
ARCTAN(Expr)               → inverse tangent
ARCTAN(Expr, Expr)         → inverse tangent (x-offset, y-offset; gives quadrant info)

1.11 Class and Discrete Expressions

CLASSIFY — use a variable as an index into a list:

CLASSIFY(<Variable>)       → returns value of matching expression; 0 if no match
  #Number: Expr
  :
END

CLASSIFY(<Variable>)       → kth expression; k = Variable - minimum value
  Expr
  :
END

CLASSIFY(<Variable>): (#Number+)  → kth number in list; k = Variable - minimum

SWITCH — procedural; selects a block of expressions by class:

SWITCH(<Variable>)
  CLASS #Number:
    …
  CLASS #Number:
    …
END

INTERPOLATE — returns an interpolated value (continuous variable):

INTERPOLATE(<Variable>)
  #Number: Expr
  :
END

INTERPOLATE(<Variable>): (#Number+)   → classes implicitly 0 … k-1

LOOKUP — like INTERPOLATE but classes can be any real values:

LOOKUP(<Variable>)
  #Number: Expr
  :
END

1.12 Bit-Vector Functions

Treat an integer variable as a sequence of up to 64 bits. PositionList is a semicolon-separated sequence of bit positions or ranges (e.g. 1;4-6;27).

SETAT(Expr, PositionList, #Type)         → set bits: 0=FALSE, 1=TRUE, 2=flip
SETAT(Expr, PositionList, #Type, #Prob)  → same, with probability #Prob each
SELECTAT(Expr, PositionList)             → TRUE if any bit in PositionList is set
MAX POSITION(Expr)                        → highest set bit position; -1 if none
MIN POSITION(Expr)                        → lowest set bit position; -1 if none
BITWISE OR(Expr, Expr)
BITWISE AND(Expr, Expr)
BITWISE XOR(Expr, Expr)
BITWISE NOT Expr
SHIFT LEFT(Expr, Expr)                   → shift left by N bits
SHIFT RIGHT(Expr, Expr)                  → shift right by N bits

1.13 Control Expressions

PAUSE                      → halt simulation; user must dismiss dialog to continue
PAUSE IF Expr              → pause only if condition is TRUE
PAUSE(#Value)              → pause for N milliseconds then continue
DEBUG                      → update simulation probe (if loaded and event selected)
SEED()                     → return current random number seed
SEED(Expr)                 → set random number seed; return next seed value
RECOMPUTE                  → re-compute probability surface before next selection
                             (requires RECOMPUTE flag on [ProbInit](/docs/concepts/landscape-events#probinit) or [SpreadProb](/docs/concepts/landscape-events#spreadprob))

1.14 Composite Functions

Composite expressions combine multiple sub-expressions and return an aggregated result:

<CompositeType>
  Expr
  :
END

Composite type	Returns
`SUM`	Sum
`PRODUCT`	Product
`DIVIDE`	Successive division
`MEAN`	Average
`GEOMETRIC MEAN`	Nth root of the product
`MIN`	Minimum
`MAX`	Maximum
`EQUAL`	TRUE if all sub-expressions are the same value
`NOT EQUAL`	TRUE if not all sub-expressions are the same value
`OR`	TRUE if at least one is TRUE
`AND`	TRUE if all are TRUE
`LESS OR EQUAL` / `ORDERED`	TRUE if ordered according to `<=`
`LESS THAN` / `STRICT ORDERED`	TRUE if ordered according to `<`
`GREATER OR EQUAL`	TRUE if ordered according to `>=`
`GREATER THAN`	TRUE if ordered according to `>`

1.15 Region Functions

Region functions return a set of cell locations. They are only valid as:

the main expression of EventLocation or SpreadLocation properties, or
with the OVER keyword.

In all forms, DECISION Expr (or ? Expr) is optional — if present, only cells where the decision returns TRUE are included.

REGION WHOLE MAP

REGION RECT(Expr, Expr, Expr, Expr)

REGION CENTRED(Expr, Expr [, CARDINAL|EUCLIDEAN] [, WRAPPED])

CARDINAL distance = minimum cardinal steps (up/down/left/right).
EUCLIDEAN distance = straight-line (default).
WRAPPED = landscape wraps around edges.

REGION LOCATION LIST(#Number+)              → set of specific known locations
REGION LOCATION LIST(<Variable>, #n)        → n locations stored in a 1-D array
REGION LOCATION(Expr)                       → single location
REGION VECTOR(StartLocation, EndLocation)   → cells along an approximate line

Cost surface regions (advanced):

REGION COST SURFACE(EndLocation, MaxCost, <CostSurface>)
DECISION Expr
COST Expr

REGION COST SURFACE(EndLocation, MaxCost, <CostSurface>, <LeastCostNeighbs>, <AnchorLoc>)
DECISION Expr
COST Expr

Least-cost path regions:

REGION LEAST COST PATH(StartLocation, EndLocation)
DECISION Expr
COST Expr

REGION LEAST COST PATH(StartLocation, EndLocation, <LeastCostNeighbs>)
REGION LEAST COST PATH(StartLocation, EndLocation, <LeastCostNeighbs>, <AnchorLoc>)

OVER region:

OVER RegionFunction
  Expression
  :
END

Apply sub-expressions at all cells in the region. Frequently used to compute statistics over the landscape at event initiation.

1.16 Matrix Expressions

Array assignment uses [=]; array equality testing uses [==].

<Matrix> [=] Expr                        → assign value to all entries
<Matrix> [==] <Matrix>                   → TRUE if all entries are equal
Expr + Expr                              → matrix sum or scalar add
Expr - Expr                              → matrix subtraction or scalar subtract
Expr * Expr                              → matrix multiplication or scalar multiply
TRANSPOSE(<Matrix>)                      → flip rows and columns
<Matrix>^-1                              → matrix inverse
SUM(<Matrix>)                            → sum of all entries (scalar)
SUM ROWS(<Matrix>)                       → sum over rows (1-D array, one per column)
SUM COLS(<Matrix>)                       → sum over columns (1-D array, one per row)
SORT(<Matrix>, Expr)                     → sort rows by Expr; Index = row index
MPM_MULT(<Matrix>, <Matrix>)             → matrix population model integer multiply
CONTAG(<Matrix>, <Matrix>)               → temporal contagion matrix

1.17–1.21 Set, List, Tree and Graph Expressions

Set, List, Tree and Graph variables are dynamic linked structures based on items (1-D arrays of attribute values). A reference to an item is a position (pointer).

Type	Collection	Key characteristic
Set	Elements	Unordered; identity by attribute values
List	Entries	Linear chain with head and tail
Tree	Nodes	Hierarchical; each node has one parent and ordered children
Graph	Nodes + Links	Nodes joined by explicit link items

General functions (all types)

REMOVE ALL(<Linked>)                       → clear all items
SIZE(<Linked>)                             → number of items
IS EMPTY(<Linked>)                         → TRUE if 0 items
FIRST(<Linked>)                            → position of first item; 0 if empty
NEXT(<Linked>, <Pos>)                      → next position; 0 if last
PREV(<Linked>, <Pos>)                      → previous position; 0 if first
REMOVE(<Linked>, <Pos>)                    → remove and delete item at position
GET(<Linked>, <Pos>)                       → get item (use with [=])
GET(<Linked>, <Pos>, #Index)               → get single attribute value
SET(<Linked>, <Pos>, <Item>)               → set item attributes
SET(<Linked>, <Pos>, #Index, <Value>)      → set single attribute value
FIND(<Linked>, <ItemVar>, Condition)       → first matching position; 0 if none
FIND NEXT(<Linked>, <Pos>, <ItemVar>, Condition) → next matching position after Pos
SORT(<Linked>, <ItemVar1>, <ItemVar2>, Condition) → sort items in place

Set functions (1.18)

CONTAINS(<Set>, <Item>)                    → TRUE if item exists in set
INSERT(<Set>, <Item>)                      → add element (no-op if already present)
UNION(<Set>, <Set>)                        → set union
INTERSECTION(<Set>, <Set>)                 → set intersection
SUBTRACT(<Set>, <Set>)                     → remove elements of second from first

List functions (1.19)

HEAD(<List>)                               → position of first entry
TAIL(<List>)                               → position of last entry
INSERT HEAD(<List>, <Item>)                → add entry to front
INSERT TAIL(<List>, <Item>)                → add entry to end
INSERT BEFORE(<List>, #Index, <Item>)      → insert before given index
INSERT AFTER(<List>, #Index, <Item>)       → insert after given index
INSERT AT(<List>, #Index, <Item>)          → insert at given index
REMOVE HEAD(<List>)                        → remove and delete first entry
REMOVE TAIL(<List>)                        → remove and delete last entry
REMOVE AT INDEX(<List>, #Index)            → remove entry at index
GET HEAD(<List>)                           → get first entry (use with [=])
GET TAIL(<List>)                           → get last entry (use with [=])
GET AT INDEX(<List>, #Index)               → get entry at index (use with [=])
POS AT INDEX(<List>, #Index)               → position at index; 0 if not found

Tree functions (1.20)

ROOT(<Tree>)                               → position of root node
ADD ROOT(<Tree>, <Item>)                   → set root node
INSERT LEFT CHILD(<Tree>, <Pos>, <Item>)   → add leftmost child to node
INSERT RIGHT CHILD(<Tree>, <Pos>, <Item>)  → add rightmost child to node
INSERT CHILD(<Tree>, <Pos>, <Item>, #Index) → add child at given index from left
CHILDREN(<Tree>, <Pos>)                    → number of children at node
PARENT(<Tree>, <Pos>)                      → position of parent; 0 for root
LEFT CHILD(<Tree>, <Pos>)                  → position of leftmost child

Graph functions (1.21)

Graphs have two item types: nodes (dimension #n1) and links (dimension #n2). Each link joins a start and end node. See the full graph expression reference for traversal and manipulation functions.

1.1 Constants, Variables and Macros​

1.2 Arithmetic Functions​

1.3 Boolean Functions​

1.4 Conditional Expressions​

1.5 Iteration Expressions​

1.6 Spatial Functions​

1.7 Output Expressions​

1.8 Probability Distributions​

1.9 Probability Density and Cumulative Density Functions​

1.10 Trigonometric Functions​

1.11 Class and Discrete Expressions​

1.12 Bit-Vector Functions​

1.13 Control Expressions​

1.14 Composite Functions​

1.15 Region Functions​

1.16 Matrix Expressions​

1.17–1.21 Set, List, Tree and Graph Expressions​

General functions (all types)​

Set functions (1.18)​

List functions (1.19)​

Tree functions (1.20)​

Graph functions (1.21)​