Model Builder's Guide Chapter 9

=Expression Language: Specifying Landscape Events and Cell Expressions= This section describes the syntax of the underlying SELES modelling language. There are two types of structures of interest to model builders: landscape events and agents are descriptions of some process acting on the landscape, while a cell expression is a specification of a related set of formulae, which are often evaluated in a spatial context (i.e., cell by cell). Cell expressions are used to specify the spatial relationships in site specific and statistical summary (value) models. See section 3 for general syntax rules.

Landscape Events and Agents
The format of a landscape event is as follows:

LSEVENT: { Definitions } { Property }*

The format of a landscape agent is identical, except the keyword “LEVENT” is replaced by “LSAGENT”.

A property has the following form:

{ PropertyName } { Expression }* { PropertyName } = { Expression } { Expression }* { PropertyEndTag }

If there are no state-change expressions associated with a property, then the enclosing name and end tag are optional. After the Definitions section, properties can be specified in any order. A property should not be specified more than once - the last specification takes precedence. The available property names for events, and their end tags are as follows: INITIALSTATE	ENDIS RETURNTIME	ENDRT EVENTLOCATION	ENDEL NUMCLUSTERS	ENDNC PROBINIT	ENDPI TRANSITIONS	ENDTR SPREADTIME	ENDST SPREADLOCATION	ENDSL NUMRECIPIENTS	ENDNR SPREADPROB	ENDSP ENDCLUSTER	ENDEC ENDEVENT	ENDEE

The available property names for agents, and their end tags are as follows: INITIALSTATE	ENDIS IMMIGRATIONTIME	ENDIM AGENTLOCATION	ENDAL NUMPOPULATIONS	ENDNP NUMGROUPS	ENDNG NUMAGENTS	ENDNA PROBINIT	ENDPI TRANSITIONS	ENDTR POPULATIONTIME	ENDPT MOVELOCATION	ENDML MOVEPROB	ENDMP NUMOFFSPRING	ENDNO

Notes: •	The main expression of the EventLocation, SpreadLocation, AgentLocation and MoveLocation properties must be region functions. The decision expression in the region function may be used to exclude cells in this region. One can also specify for the region to wrap around the edges of the landscape (top to bottom and left to right), which is useful for combating edge effects in theoretical models. The main expression of all other properties cannot be regions. •	If the value of SpreadTime is 0 or more, then spreading is processed normally via the event queue. If the value of SpreadTime is negative, then spreading will occur in immediate mode. That is, once an event initiates in a cell, it will spread before the event attempts to initiate in another cell. This behaviour is useful for modeling patch oriented processes such as some types of decision making (e.g. setting up planning areas or excluding small patches from harvestable forest) or patch-based succession. In these cases, we wish to process a patch starting at an initiating cell (defined by ProbInit, SpreadProb, and/or SpreadLocation) before attempting to initiate in another cell. During the processing of a patch, we can modify the state to prevent any other initiations in this patch.

Cell Expressions
Cell expressions are used to describe pattern and summary specification in site-specific and statistical summary models. Essentially, a cell expression sets up a context for evaluating a main expression and an associated set of expressions. That is, it defines the variables that may be used to parameterize expressions (e.g. elevation, vegetation cover) that are specific to a given cell location. The general form of a cell expression is as follows:

CELLEXPR: { Definitions } { Expression }* = { Expression } { Expression}* ENDCE

Note the expression name or both the colon and expression name following the CELLEXPR keyword are optional. The main expression defines the value of a cell expression. The first set of state-change expressions is evaluated before the main expression, and the second set after.

Macros
Macro files are used to specify sets of expressions that can be accessed via a named macro. They can be useful for operations that need to be performed identically in several parts of a model, or for allowing a generic model to have “expression parameters”. The general form of a macro definition is as follows:

MACRO: { Definitions } { Expression }*

Macro files are declared in a SELES model file (macro section). They can then be defined in a landscape event or agent (as MACRO: macroName), and evaluated as in the same way a value in an array is indexed (e.g. x = macroName[j]).

Definitions
The Definitions section is used to identify the spatial (layer) and global variables and constants accessed by the event or agent, and to declare variables in the hierarchical dynamic state to be used by the event. Defined variables can be used in the expressions in the event properties or cell expressions. Each variable has a "scope", which determines where it is valid to be used, and what spatial context the variable resides in. For example, a variable with global scope may be referred to in any expression and takes on a single value (aspatial), whereas a variable with spatial scope can only be used in expressions that refer to individual cells and potentially takes on a different value at each cell. Note that when a layer variable is referenced in a property definition, the variable generally takes on the value of the layer at the active cell location.

DEFINITIONS { VariableDefinition }+ ENDDEF

A VariableDefinition defines one or more variables of a given type, with the names separated by commas: LAYER:  LAYER: [#NumSubLayers] GLOBAL VARIABLE:  GLOBAL VARIABLE: < Variable Name>[] GLOBAL CONSTANT:  GLOBAL CONSTANT: [] MACRO: [] OUTPUT VARIABLE:  =  LOCAL:  CONSTANT:  = #Value

In addition to the above, landscape events may define: EVENT VARIABLE:  CLUSTER VARIABLE:  CELL VARIABLE: 

In addition to the above, landscape agents may define: POPULATION VARIABLE:  GROUP VARIABLE:  AGENT VARIABLE: 

Notes: 1.	Layers and global variables are the external spatial and aspatial state variables defined in the .sel file. Normally, they will be layers (i.e. rasters) or aspatial parameters or control variables. The other variables are part of the internal state managed by SELES. 2.	Local global variables have a global scope, but are unique to the landscape event in which they are defined (i.e. they are not defined in the .sel file). Local variables can be arrays if dimensions are specified in “[ ]” brackets. They should be considered to have an undefined initial state. 3.	Local constants allow the user to give a name to constant values, which can be used to make models more legible. There are also several built-in system constants that can be used in place of numbers: •	NUMROWS = the number of rows in the scenario. •	NUMCOLS = the number of columns in the scenario. •	NUMCELLS = the number of cells in the scenario (i.e. NUMROWS * NUMCOLS) 4.	Event variables are unique to each instance of an event (e.g. each fire initiation event may have an EventSize variable). Cluster variables are unique to each cluster of an event (e.g. each fire opening may have an OpeningSize variable). Cell variables are unique to each active cell of an event instance (e.g. an active cell may have an intensity variable). These variables are valid only while an event is active. SELES handles all of the memory management to ensure the variables are allocated when they are activated and destroyed when they are deactivated. Modelers simply need to define them as appropriate, and then access/modify them as needed. Before their first assignment, their value is undefined. 5.	Population variables are unique to each agent population. Group variables are unique to each agent group (sub-population). Agent variables are unique to each agent. SELES handles all of the memory management to ensure the variables are allocated when they are activated and destroyed when they are deactivated. Note that before their first assignment, their value is undefined. 6.	Output variables allow users to route output to text files. The user can use a record function with an output variable to save a record in a file that has the format of a relational table. These tables can then, for example, be loaded into a database or spreadsheet for post-simulation analysis and exploration. This is the primary way that simulation information can be recorded in a text file. Other model output is through dynamic value models and raster time-series. 7.	Local variables are not put in the Definitions section, bu are defined on their first appears on the left-hand side of an assignment in a set of expressions. They have a scope limited to the context of those expressions. 8.	System variables are built-in variables that include: 	Time = the current time of the simulation (in the units defined by the model). 	EndTime = the end time of the simulation. 	Location = the current spatial location (location index of the active cell). The Location variable is only valid in spatial contexts (i.e. it cannot be used in an expression with a global context, like ReturnTime). Location is an index; to obtain the actual row and column of the location use the functions ROW(Location) and COL(Location). 	Index = the current index value in an OVER INDEX SEQUENCE expression. 	Run = the number of the current model run in a Monte Carlo simulation. 	EventId = a unique identifier assigned to each instance of an event of a particular type.

Sets, lists and graphs are dynamic linked structures. A set is an unordered collection of items, where an item is defined here as a vector of values (i.e. a one-dimensional array). Common set operations include union, intersection and membership testing. A list is an ordered collection of items. Common list operations include adding or removing a new head or tail element and cycling over all elements. Graphs are two inter-related sets of items: a set of nodes and a set of links, where each link is associated with a start and end node. Variables can be specified as sets, lists or graphs using the following syntax (shown for global variables):

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

The first three define the variable to be a set, list or tree with n elements in each item. The last defines the variable to be a graph with n1 elements in the node items and n2 elements in the link items. See the set, list and graph expressions for how to use these variables. In general, SELES manages all the dynamic allocation/deallocation of memory required, and cleans up the variables upon simulation termination. Also, these types of variables can be specified for array variables (e.g. to create an array of sets). In the dynamic model file, these variables are defined the same as other variables (i.e. as if they are single values rather than collections). These can be applied to any type of variable except output variables.

State-Change Expressions
The general form of a state-change is an assignment of the form:

<Variable Name> = { Expression }

State-changes are either prior to the main expression of a property or cell expression (in the preliminary expressions) or subsequent to it (in the consequent expressions). Preliminary expressions are evaluated immediately before the main expression, and can be used (i) to simplify specification of the main expression by setting up local variables with complex portions of the expression, and (ii) to set up state information prior to evaluation of the main expression. Evaluation of consequent expressions depends on the semantics of the property or cell expression. For site models, the main expression specifies the value to assign to cells on the target layer of the model, and the consequent expressions are always evaluated following the main expression. In a landscape event, each property has a particular behaviour with respect to if and when consequent expressions get evaluated: InitialState: for each event instance created at simulation start-up ReturnTime: when an event initiates EventLocation: for each cell in the defined region NumClusters and ProbInit: for each cell in which the event actually initiates Transitions: if a transition occurs (i.e. if the main expression returns TRUE (1)) SpreadTime: after a cell has finished spreading SpreadLocation: for each cell in the defined spread region NumSpreadRecipients and SpreadProb: for each cell that is actually spread to

In a landscape agent, consequent expressions get evaluated as follows. InitialState: for each immigration instance created at simulation start-up ImmigrationTime: when an immigration instance is processed AgentLocation: for each cell in the defined region NumPopulations: for each population NumGrioups: for each group NumAgents and ProbInit: for each agent created after the initiating cell is selected Transitions: if a the agent survives (i.e. if the main expression returns TRUE (1)) PopulationTime: when the population update process starts MoveLocation: for each cell in the defined move region MoveProb: in the cell selected for movement NumOffspring: for each agent created by reproduction

Notes: 1.	The consequent expressions for ReturnTime, SpreadTime, ImmigrationTime and MoveTime are evaluated at a later (simulated) time than the main expression. For these properties, the preliminary expressions are evaluated before the next event is scheduled to occur or spread, and can be used, for example, to determine when (how far into the future) the event is should occur or spread. However, the consequent expressions are evaluated when the event is taken off the queue, except in the case of SpreadTime in which they are processed after the cell has finished spreading. For example, the consequent expressions for ReturnTime can be used to initialize the new event instance at the time its initiation, while those for SpreadTime can be used for processing prior to an active cell terminating. 2.	If the variable is referred to that has not been defined in the Definitions section, then it is treated as a local variable. Local (context) variables only hold a value within the context of a set of expressions. Local variables used in the Preliminary expressions are also within the scope of the main expression, but not within the scope of the consequent expressions. 3.	LAYER and CELL variables may be preceded by the SOURCE keyword in the SpreadProb property, as well as in the NumRecipients and SpreadLocation consequent expressions. This will refer to the value at the source cell rather than the current cell (i.e., the variable takes on values from the spreading cell rather than the recipient cell). The SOURCE keyword can also be used in region functions in spatial contexts to refer to values in the cell at which the region function is evaluated. 4.	LAYER and AGENT variables may be preceded by the SOURCE keyword in the NumOffspring consequent expressions. This will set the value of the variable at the source cell and parent agent rather than the current cell (i.e., the variable takes on values from the spreading cell rather than the recipient cell). LAYER variables may be preceded by the SOURCE keyword in the MoveProb property, as well as in the MoveLocation consequent expressions.

Expressions:
Expression specifications are the heart of the SELES modeling language. They provide a general structure with which simple or complex, deterministic or stochastic expressions can be constructed. Expression are divided into the following groups: Constants and Macros	Distributions and Probability Density Functions Continuous Functions	Classified Functions Boolean Functions	Bit-Vector Functions Control Expressions	Output Expressions Composite Functions	Region Functions Matrix Functions	Set, List, Tree and Graph Functions

Independent variables referred to in expressions can be any of the variables specified in the Definitions section that is within the context of the expression, or a valid local variable (i.e. a local variable within the context of this expression). Dynamic (cell, agent etc.) variables should have been previously assigned before being used as an independent variable. Often models require the use of Boolean (TRUE or FALSE) valued variables. Some expressions return Boolean values (e.g. EQUAL or GREATER OR EQUAL). If a variable is Boolean valued, then the keywords TRUE and FALSE can be used instead of 1 or 0, respectively, during comparisons and assignments. In SELES, TRUE is equivalent to 1 and FALSE is equivalent to 0. The following subsections define the syntax and meaning of the available expressions and their synonyms and variants. The label “Expr” indicates that a sub-expression is to be substituted (generally a function). Use parentheses to ensure the desired precedence order is used when mixing types (e.g. relations and arithmetic).

Constants
ZERO	return 0.0 ONE	return 1.0 <Constant>	return value of a named constant <Constant>[Expr]	return value of a named vector constant <Constant>[Expr, Expr]	return value of a named array constant <Macro>[Expr]	return value of expression at specified index in macro
 * 1) Number	return value of the number specified

Probability Distributions
In SELES, probability distributions are treated like functions, although they have the behaviour of selecting a value from the distribution, rather than computing the result of a deterministic function. Each time a distribution is evaluated, the value returned may be different. This is one way that stochasticity can be incorporated into SELES models. If these distributions were evaluated many times, and the resulting value frequencies plotted, the histogram should approximate the distribution. A skewed normal distribution is like two normal distributions, with different standard deviations to the left and right. In a normal distribution, the centre is both the mean and the mode. In a skewed normal distribution, the central hump is only the mode. NORMAL(Expr, Expr)	draw a value from a normal distribution, where the first expression specifies the mean and the second specifies the standard deviation

SKEWED NORMAL(Expr, Expr, Expr)	draw a value from a skewed normal distribution, 	where the first expression specifies the mode and the second and third specify the standard deviations to the left and right of the mode LOG NORMAL(Expr, Expr)	draw a value from a log normal distribution, where the first expression specifies the mean and the second specifies the standard deviation of the underlying normal distribution

WEIBULL(Expr, Expr) 	draw a value from a Weibull distribution, where the first expression specifies the beta and the second specifies alpha (Note:terminology varies	between sources. The version here is equivalent	to that in Excel, with reversal of parameters).

NEGEXP(Expr)	draw a value from a negative exponential 	distribution, where the expression specifies the mean

POISSION(Expr)	draw a value from a Poisson distribution

UNIFORM(Expr, Expr)	draw a value from a uniform distribution, where 	the first expression determines the minimum	 	value and the second determines the maximum CLASSIFIED_DIST	draw a value from a discrete distribution, where 	CLASS Number: Expr	each expression determines the relative 		:	probability of its associated class being drawn. ENDFN		The CLASS keyword is optional.

CLASSIFIED_DIST( Number+)	in this form, the classes are assumed to start at 			zero. Only constant probabilities can be given.

CLASSIFIED_DIST	in this form, the classes are assumed to start at Expr		zero   : ENDFN

CLASSIFIED_DIST[M]	In this form, the classes in a one-dimensional array M, and so start at zero.

Probability Density and Cumulative Density Functions
The following are a set of probability and cumulative density expressions. The results from probability density expressions should be multiplied by a width factor to obtain a probability of value X (i.e. the estimated area under the PDF curve). Without a width factor, the assumed class size is 1. A temporal PDF makes a PDF conditional, where the variable X is assumed to be a time or other increasing value. Essentially, a PDF will give the probability of value X occurring, while a TEMPORAL PDF will give the probability of X occurring given that if hasn’t occurred yet (i.e. given that that actual value of this variable will be >= X).

NORMAL PDF(Expr, Expr, Expr)	normal probability density function, where the 			first expression is the value, the second is the 			mean and the third is the standard deviation NORMAL CDF(Expr, Expr, Expr)	normal cumulative density function, where the 			first expression is the value, the second is the			mean and the third is the standard deviation SKEWED NORMAL PDF(Expr, Expr, Expr, Expr)	skewed normal probability density function, where the first expression specifies the value, the second is the mode and the third and fourth	are the standard deviations to the left and right of the mode. SKEWED NORMAL CDF(Expr, Expr, Expr, Expr)	skewed normal cumulative density function, 			where the first expression specifies the value, the second is the mode, and the third and fourth 			are the left and right standard deviations

LOG NORMAL PDF(Expr, Expr, Expr)	log normal probability density function, where the first expression specifies the value, the second is the mean and the third is the standard deviation LOG NORMAL CDF(Expr, Expr, Expr)	log normal cumulative density function, where the first expression specifies the value, the second is the mean and the third is the standard deviation NORMAL TEMPORAL PDF(Expr, Expr, Expr) 	temporal normal probability density function SKEWED NORMAL TEMPORAL PDF(Expr, Expr, Expr, Expr) temporal skewed normal probability density function

LOG NORMAL TEMPORAL PDF(Expr, Expr, Expr) temporal log normal probability density function UNIFORM TEMPORAL PDF(Expr, Expr, Expr)	temporal uniform probability density expression

Continuous Functions (Arithmetic Functions)
<Variable>	value of an independent variable <Variable>[Expr]	value of a vector global variable <Variable>[Expr, Expr]	value of an array global variable

(Expr)	value of the expression Expr + Expr	sum of two expressions Expr - Expr	value of the first expression minus the value of the second expression Expr * Expr	product of two expressions Expr / Expr	value of the first expression divided by value of the second expression Expr ^ Expr	value of the first expression to the power of the value of the second expression. An nth root can be computed with1/n as the power. ABS(Expr)	absolute value of the expression ABSOLUTE(Expr)	absolute value of the expression
 * Expr |	absolute value of the expression

Expr % Expr	value of the first expression modulo the value of	the second expression (assumes that the values	of the expressions are integers) EXP(Expr)	base of the natural logarithm (e) to the power of	the expression LOG(Expr)	natural logarithm of the value of the expression. Logarithms in other bases can be computed as	logb(x) = ln(x) / ln(b)

ROUND(Expr)	expression value rounded to the nearest integer FLOOR(Expr)		largest integer smaller than the expression value CEILING(Expr)	smallest integer larger than the expression value

CLAMP(Expr, MinExpr, MaxExpr)	clamp the value X of the expression to the range [Min, Max]: if X < Min then return Min; if 			X < Max return Max. Otherwise return X.

Continuous Functions (Trigonometric Functions)
Angles are all assumed to be in degrees (not radians). In SELES, angles in compass directions (i.e. zero is north, increasing clockwise, in contrast to geometry where zero is each increasing counter-clockwise). SIN(Expr)	interpret the value of the expression as an angle theta in degrees, and return sin(theta) COS(Expr)	interpret the value of the expression as an angle theta in degrees, and return cos(theta) TAN(Expr)	interpret the value of the expression as an angle theta in degrees, and return tan(theta). ARCSIN(Expr)	inverse sine of the value of the expression ARCCOS(Expr)	inverse cos of the value of the expression ARCTAN(Expr)	inverse tan of the value of the expression ARCTAN(Expr, Expr)	inverse tan where first expression is x offset and second is y offset. Providing two expressions gives more information about the quadrant.

Continuous Functions (Miscellaneous)
RESPONSE(Expr, #A, #B, #C)	two-sided version of a standard response function for the value X of the first expression: if (X < A) return e^(-(X-A)^2/(2*(C^2))			else if (X > B) return e^(-(X-B)^2/(2*(C^2)) else return 1

DISTANCE(Expr, Expr)	distance between two location indices (normally	obtained using the Location variable). Thus, DISTANCE(loc1, loc2) is 	sqrt(sqr(loc1.x – loc2.x) + sqr(loc1.y – loc2.y))

DIRECTION(Expr, Expr)	angle in degrees between two location indices

Classified and Discrete Functions
CLASSIFY(X)	if the value of the variable X is equal to one of CLASS Number: Expr	the classes listed, then return the result of the. :	associated expression. Otherwise return 0. ENDFN

CLASSIFY(X)	return the result of the kth expression in the list, Expr	where k = X – minimum value of the variables :	(this may be non-0 only for layers) : ENDFN

CLASSIFY(X): ( Number+)	return the kth number in the list, where k = X – minimum value of the variable (this may be non-0 only for layers)

CLASSIFY(X): Filename	uses the table in the named file, which is assumed to consist of class:value pairs. Rarely used.

CLASSIFY(X): Filename Key	uses the table in the named file, which is assumed to consist of class:value pairs. The key is used to specify a sub-table in a multi-table file. Rarely used.

Classified functions use the variable as an index into the list of numbers or expressions that follow. The “CLASS” keyword is optional. This variable must be non-negative. If “CLASS # :” is used, then the number refers to the value of the indexing variable. If a class is not specified for a given value, its expression is implicitly ZERO. Interpolation tables are very similar except that the variable is assumed to be continuous instead of classified. An interpolated value between classes is returned. Lookup tables are also similar, except that both the variable and classes are assumed to be continuous values. An interpolated value between classes is also returned. Rarely used.

INTERPOLATE(X)	return an interpolated value where the value of	CLASS Number: Number	variable X is placed between two classes or at :	either end of the table. ENDFN

INTERPOLATE(X): ( Number+)	same as above, except the classes are implicitly 0, …. k-1

INTERPOLATE(X)	same as above, except the values in the CLASS Number: Expr	table are obtained by evaluating expressions :				ENDFN

INTERPOLATE(X)	same as above, except the classes are Expr	implicitly 0, …, k-1 :					ENDFN

INTERPOLATE(X): Filename	uses the table in the named file, which is 		assumed to consist of class:value pairs

INTERPOLATE(X): Filename Key	uses the table in the named file, which is assumed to consist of class:value pairs. The key is used to specify a sub-table in a multi-table file.

LOOKUP(X)	return the interpolated value where the value of	CLASS Number: Number	variable X is placed between two classes or at :	either end of the table, and classes can be any. ENDFN	real values.

LOOKUP(X): ( Number+)	same as above, except the classes are implicitly 0, …. k-1

LOOKUP(X)	same as above, except the values in the CLASS Number: Expr	table are obtained by evaluating expressions :				ENDFN

LOOKUP(X)	same as above, except the classes are Expr	implicitly 0, …, k-1 :					ENDFN

LOOKUP(X): Filename	uses the table in the named file, which is 		assumed to consist of class:value pairs

LOOKUP(X): Filename Key	uses the table in the named file, which is assumed to consist of class:value pairs. The key is used to specify a sub-table in a multi-table file

Boolean Functions
Expr EQ Expr	TRUE if the values of the two expressions are equal; otherwise FALSE Expr == Expr	alternate form of EQ comparison (Note: two equal signs distinguish this from an assignment)

Expr NEQ Expr	TRUE if the values are not equal; otherwise FALSE Expr != Expr	alternate form of NOT EQUAL comparison

Expr < Expr	       TRUE if the value of the first expression is less than the value of the second expression; otherwise FALSE

Expr <= Expr	TRUE if the value of the first expression is less than or equal to the value of the second expression; otherwise FALSE

Expr > Expr 	TRUE if the value of the first expression is greater than the value of the second expression; otherwise FALSE

Expr >= Expr	TRUE if the value of the first expression is greater than or equal to the value of the second expression; otherwise FALSE

!Expr		Negates the expression Boolean value

Expr AND Expr	TRUE if values of both expressions are TRUE and FALSE otherwise

Expr OR Expr	TRUE if value of at least one expression is TRUE and FALSE otherwise

Note that relations can be cascaded, with the interpretation that each operator applies independently to its surrounding pair of expressions. Thus, the expression: Expression <= Expression <= Expression (e.g. 5 <= age <= 50) specifies a “between” relation, which is TRUE only if the value of the centre expression falls in the specified range.

Bit-Vector Functions
Bit-vector functions treat an integer value (the independent variable) as a sequence of bits, each of which can be independently set and accessed. This can allow use of a single layer to hold lots of Boolean information, since each cell as an integer has 8, 16 or 32 bits. For example, bits 0, 1, 2 and 3 can be used to store four different Boolean states (a, b, c and d), and the sequence 0110 means that states a and d are FALSE and states b and c are TRUE. PositionList is a semi-colon separated sequence of integer or ranges (lower-upper) indicating positions in the integer (0-31). For example, the PositionList 1;4-6;27 indicates bits at positions 1, 4, 5, 6 and 27.

SETAT(Expr, PositionList, #Type)	Set the value specified by the expression, at 		the positions in PositionList to: FALSE (0) if Type is 0, TRUE (1) if Type is 1, and flip the bits if Type = 2

SETAT(Expr, PositionList,#Type,#Prob)	Same as above, except each position is set with probability #Prob

SELECTAT(Expr, PositionList)	FALSE(0) if none of the bits in PositionList are set in the specified expression value and TRUE(1) otherwise

MAX POSITION(Expr)	Return the maximum 0-based bit position that is 		set to one in the expression value (interpreted 		as a bit-vector), or –1 if no bits are set

MIN POSITION(Expr)	Return the minimum 0-based bit position that is 		set to one in the expression value (interpreted 		as a bit-vector), or –1 if no bits are set

BITWISE OR(Expr, Expr)	Bitwise OR of two values BITWISE AND(Expr, Expr)	Bitwise AND of two values BITWISE XOR(Expr, Expr)	Bitwise exclusive-OR of two values BITWISE NOT Expr	Bitwise NOT of a value

SHIFT LEFT(Expr, Expr)	Shifts value of first expression to the left by 		number of bits specified by second expression SHIFT RIGHT(Expr, Expr)	Shifts value of first expression to the right by 		number of bits specified by second expression

Control Expressions
Note the difference between the first two “functional if’s” (i.e. a value is returned) and the latter “procedural if’s” (that don’t return a value, but control flow).

IF Expr THEN Expr ELSE Expr	if value of the IF expression is TRUE (>= 1), 	then return the value of the THEN expression, otherwise return value of the ELSE expression

(Expr ? Expr : Expr)	Same as above, but this form can be used as an embedded sub-expression.

IF Expr	Procedural IF statement to process …	sub-expressions denoted by “…” only if the ENDFN	expression evaluates to TRUE

IF Expr	Procedural IF statement to process the first set …	of sub-expressions denoted by “…”if the ELSE	expression evaluates to TRUE and the set of …	sub-expressions after the ELSE otherwise. Note ENDFN	that “ELSE IF expr” forms can be strung together

WHILE Expr	While loop: process sub-expressions denoted by …	 “…” while the expression evaluates to TRUE ENDFN

PAUSE		Halts the simulation and displays a dialog box to which the user must respond to continue

PAUSE IF Expr	If the expression evaluates to TRUE, halts the simulation and displays a dialog box to which the user must respond to continue

PAUSE(#Value)	Pauses the simulation for the specified number of milliseconds and then continues

PAUSE(#Value) IF Expr	If the expression evaluates to TRUE, Pauses the simulation for the specified number of 			milliseconds and then continues

WAIT UNTIL Expr	Suspend execution until the expression returns 			TRUE (1). This is intended for controlling communication and synchronization with an external application. CRITICAL SECTION (Flag)	Enter (if Flag is TRUE) or exit (if Flag is 			FALSE) a critical section. A critical section 			gives priority to this application, and is used for synchronizing access to shared variables (i.e. shared with another application).

DEBUG		Update the simulation probe, if it is loaded and The event is selected. Used to debug/verify event behaviour.

SEED		Gets the random number seed SEED(Expr)		Sets the random number seed. Value returned is next seed.

RESIZE(Variable, Expr)	Changes size (number of entries) in a global variable. Values are not maintained. Useful for when size is not known prior to simulation.

RECOMPUTE	Only valid in consequent expressions of 			ProbInit and also when ProbInit recompute flag has been set. Causes prob. surface to be			recomputed before next selection

Output Expressions
DISPLAY		Display on the screen the labelled 	Label: Expr	values computed with the expressions listed. ….		If no label is given, the expression must ENDFN		be a variable, and this is used for the label.

DISPLAY		Same as above, but only display if the DECISION Expr	decision expression evaluates to TRUE Label: Expr	The keyword DECISION can be replaced by	     ….		a “?” ENDFN

OUTPUT RECORD(OutputVar)	Output to the record file of output variable	the labelled values computed with the Label: Expr	expressions listed. If no label is given, the ….		Expression must be a variable and this is ENDFN		used as label.

OUTPUT RECORD(OutputVar)	Same as above, but only output if the DECISION Expr	decision expression evaluates to TRUE Label: Expr ….		ENDFN

Note: a label/expression pair can be “expanded” by using the form: Label#n1:n2: Expr, where n1 and n2 are integers or constant names. This will create n2-n1+1 columns rather than a single column. The system variable Index can be used in the expression, and will take on values n1, n1+1,…,n2 for each column, respectively.

Composite Functions
Compound expressions all have the same form of an expression name followed by a list of sub-expressions. If the first expression is a region function, then the subsequent expressions are all evaluated over the defined region, instead of only at the current cell (however, it is usually simpler to use an OVER REGION expression). When arithmetic expression become complex, sometimes composite expressions can be written more clearly. The general format is as follows:

CompositeExpressionName Expr : ENDFN

The following composite expressions are supported:

SUM		sum of the sub-expressions

PRODUCT	product of the sub-expressions

DIVIDE	successive division of the sub-expressions

MEAN		average of the sub-expressions

GEOMETRIC MEAN	geometric mean of the sub-expressions (nth 		root of the product for n expressions)

MIN		minimum of the sub-expressions

MAX		maximum of the sub-expressions

EQUAL	TRUE (1) if the sub-expressions all evaluate to		the same value and FALSE (0) otherwise NOT EQUAL	FALSE (0) if the sub-expressions all evaluate to		the same value and TRUE (1) otherwise

OR		TRUE (1) if at least one sub-expression evaluates to TRUE and FALSE (0) otherwise

AND		TRUE (1) if all sub-expressions evaluate to		TRUE and FALSE (0) otherwise

LESS OR EQUAL	TRUE (1) if the sub-expression evaluations are all ordered according to the relation <=, and FALSE (0) otherwise

ORDERED	same as LESS OR EQUAL

LESS THAN	TRUE (1) if the sub-expression evaluations are all ordered according to the relation <, and FALSE (0) otherwise

STRICT ORDERED	same as LESS THAN

GREATER OR EQUAL	TRUE (1) if the sub-expression evaluations are all ordered according to the relation >=, and FALSE (0) otherwise

GREATER THAN	TRUE (1) if the sub-expression evaluations are all ordered according to the relation >, and FALSE (0) otherwise

Region Functions
A region function returns the set of locations, one on each call. Their use is limited to the main expression of EventLocation, SpreadLocation, AgentLocation and MoveLocation properties, as the first expression of composite expressions and in OVER REGION functions.

REGION WHOLE MAP	defines the region consisting of the entire DECISION Expr	landscape. If there is a decision expression, then only those cells for which this expression returns TRUE will be included.

REGION RECT (Expr, Expr, Expr, Expr)	defines a rectangular region. If there is a	DECISION Expr	decision expression defined, then only those cells for which this expression returns TRUE will be included

REGION CENTRED (Expr, Expr [, DistanceType][, WRAPPED]) DECISION Expr	defines a region centred on the current cell. If there is a decision expression, then only those cells for which this expression returns TRUE will be included.

DistanceType is either CARDINAL or EUCLIDEAN (the default). Cardinal distance between two cells is the minimum number of cardinal steps (up, down, left, right) to reach one cell from the other. Euclidean distance is the straight-line distance between two points. The WRAPPED flag, if present indicates that the region wraps around the sides (vertically and horizontally) of the landscape (e.g. a location x positions beyond the right-hand side of a raster will be mapped to x positions in from the left-hand side of the raster). If not present, the landscape does not wrap.

REGION LOCATION LIST(Number+)	defines the region consisting of a set of DECISION Expr	known location indices. If there is a decision 		expression, then only those cells for which this expression returns TRUE will be included.

REGION LOCATION LIST(X,n)	defines the region consisting of a set of n	DECISION Expr	location indices stored in one-dimensional X.

REGION LOCATION (Expr)	defines the region consisting of a of a single DECISION Expr	location index. If there is a decision expression, then only those cells for which this expression returns TRUE will be included.

REGION VECTOR (StartLocation, EndLocation)	defines region consisting of cells along an	DECISION Expr	approximation of line between end cells

Cost surface and least-cost path regions are advanced features that are best understood with an example model.

REGION COST SURFACE(EndLocation, MaxCost, CostSurface) DECISION Expr COST Expr REGION COST SURFACE(EndLocation, MaxCost, CostSurface, LeastCostNeighbs, AnchorLoc) DECISION Expr COST Expr Defines a region surrounding a cell with cumulative costs less than MaxCost. Stops growing when EndLocation is reached or all costs are greater than MaxCost. Second form also records gradient and anchor location layers. The CostSurface layer records the cumulative cost from the cost function

REGION LEAST COST PATH(StartLocation, EndLocation) DECISION Expr COST Expr REGION LEAST COST PATH(StartLocation, EndLocation, LeastCostNeighbs) DECISION Expr REGION LEAST COST PATH(StartLocation, EndLocation, LeastCostNeighbs, AnchorLoc) DECISION Expr Defines a region with cells that approximate the least-cost path between two cells. The first generates the cost function internally. The latter two use input information from a pre-computed cost surface region. Providing both the gradient and anchor location layers provides the most accurate approximation.

Iteration is a common aspect of models (even if it is very procedural). Most programming languages offer a “for-loop” of some kind. SELES presently provides “over index sequence” expressions as a slightly more declarative (although also more cumbersome) expression for iterating. While-loops can also be used.

OVER INDEX SEQUENCE(Expr, Expr)	defines linear sequence of location indices. DECISION Expr	If there is a decision expression, then only those cells for which this expression returns TRUE will be included. The system variable Index holds the value of the index at each value in the sequence

Over region expressions are very frequently used to visit all cells in a landscape that meet some condition (e.g. to compute the size of the forest at initiation).

OVER RegionFunction	Apply a set of sub-expressions at all spatial Expression	locations specified by a region function : ENDFN

AT LOCATION #Expr	Apply a set of state-changes at a specified Expression	location : ENDFN

Matrix Functions
Matrix assignment is indicated using “[=]” instead of “=”. The proper dimensions of the component arrays must be met.

Variable [=] Variable	assign variable of same dimension, or a 	single value to all entries Variable [=] Variable + Variable	sum variables of same dimension (or with a 	constant) Variable [=] Variable - Variable	subtract variables of same dimension (or	with a constant) Variable [=] Variable * Variable	matrix or scalar multiplication.

Variable [=] TRANSPOSE(Variable)	matrix transposition Variable [=] Variable^-1	invert a matrix Variable = SUM(Variable)	sum all entries in a matrix Variable [=] SUM ROWS (Variable)	sum all rows of a matrix (result has one	value per column) Variable [=] SUM COLS(Variable)	sum all columns of a matrix

Variables [=] SORT(Variable, Expr)	sort rows of an input matrix where rank is given by Expr. The system variable “Index” can appear in the expression and will take on the range of indices in the input array. The resulting sorted matrix will be assigned.

Variable [=] MPM_MULT(Variable, Variable)	Performs a “matrix population model” (MPM) integer-based multiplication. Assumes that first matrix is two-dimensional and that second is a vector. The result is 	two-dimensional, where entries above diagonal represent "offspring", entries on the diagonal represent "survivors" and entries below the diagonal represent "succeeders"

Variable [=] CONTAG(Variable, Variable)	Creates a “temporal contagion” matrix. Given probabilities (first parameter) for a set of states and a two-dimensional contagion array (values –1 to 1 indicating affinity), generates a matrix where each row is a prob. dist. For transitions given the row value, and the overall target dist. will be met.

General Set, List and Graph Functions
REMOVE ALL(LinkedVariable)	clears variable. No return value

SIZE(LinkedVariable)	number of elements, entries or nodes

IS EMPTY(LinkedVariable)	TRUE if and only if variable has 0 elements

FIRST(LinkedVariable)	returns position of first element, entry or	node

NEXT(LinkedVariable, PosVariable)	returns position of element, entry or node following position provided

PREV(LinkedVariable, PosVariable)	returns position of element, entry or node preceding position provided

REMOVE(LinkedVariable, PosVariable)	remove and deletes element, entry or node at position

Variable [=] GET(LinkedVariable, PosVariable)	get element, entry or node at position

X [=] GET(LinkedVariable, PosVariable, Index)	get single value in a given index

SET(LinkedVariable, PosVariable, Variable)	set element, entry or node at position

SET(LinkedVariable, PosVariable, entryIndex, Value) set value at specified index of element, entry or node at position

FIND(LinkedVariable, TmpVariable, Condition)	return first position of an element, entry or	node that satisfies the condition

FIND NEXT(LinkedVariable, PosVariable, TmpVariable, Condition) return next position of an element, entry or	node that satisfies the condition

SORT(LinkedVariable, TmpVariable1, TmpVariable2, Condition) sort elements, entries or nodes according to 	condition

Set Functions
CONTAINS(SetVariable, ElementVariable)	TRUE if and only if set variable “contains” variable provided, where two elements are identical if they have identical values

INSERT(SetVariable, ElementVariable)	add element to set. Only changes set if it 	doesn’t already contain the element

SetVariable = UNION(Set1, Set2)	take union of two set variables

SetVariable = INTERSECTION(Sete1, Set2)	take intersection of two set variables

SetVariable = SUBTRACT(Sete1, Set2)	subtract second set variable from first

List Functions
HEAD(ListVariable)	returns position of first entry

TAIL(ListVariable)	returns position of last entry

INSERT HEAD(ListVariable, EntryElement)	add an entry to front of list

INSERT TAIL(ListVariable, EntryElement)	add an entry to end of list

INSERT BEFORE(ListVariable, Index, EntryElement) add an entry before given index

INSERT AFTER(ListVariable, Index, EntryElement) add an entry after given index

INSERT AT(ListVariable, Index, EntryElement)	add an entry at given index

REMOVE HEAD(ListVariable)	removes and deletes first entry

REMOVE TAIL (ListVariable)	removes and deletes last entry

REMOVE AT INDEX(ListVariable, Index)	removes and deletes entry at given index

Variable [=] GET HEAD(ListVariable)	returns first entry

Variable [=] GET TAIL(ListVariable)	returns first entry

Variable [=] GET AT INDEX(ListVariable, Index)	returns entry at given index

Pos = POS AT INDEX(ListVariable, Index)	returns position at given index

Tree Functions
ADD ROOT(TreeVariable, EntryElement)	add root element of a tree

INSERT LEFT CHILD(TreeVariable, PosVariable, EntryElement) add child to a node on the left of current children

INSERT RIGHT CHILD(TreeVariable, PosVariable, EntryElement) add child to a node on the right of current children

INSERT CHILD(TreeVariable, PosVariable, EntryElement, Index) add child to a node at given index (from	left)

n = CHILDREN(TreeVariable, PosVariable)	number of children at a given position

Pos = PARENT(TreeVariable, PosVariable)	Position of parent of a node

Pos = LEFT CHILD(TreeVariable, PosVariable)	Position of leftmost child of a node

Pos = RIGHT CHILD(TreeVariable, PosVariable)	Position of rightmost child of a node

Pos = CHILD(TreeVariable, PosVariable, Index)	Position of indexed (from left) child of a 	node

Pos = NEXT SIBLING(TreeVariable, PosVariable)	Position of next sibling to right of a node

Pos = PREV SIBLING(TreeVariable, PosVariable)	Position of previous sibling to right of a node

Pos = NEXT DFS(TreeVariable, PosVariable)	Position of next node in depth-first pre-order traversal of a tree. If the position variable is NULL, then the root is returned

Pos = NEXT POSTORDER DFS(TreeVariable, PosVariable) Position of next node in depth-first post-order traversal of a tree. If the position variable is NULL, then the root is returned

Variable [=] GET LEFT CHILD(TreeVariable, PosVariable) returns entry of leftmost child for a given node

Variable [=] GET RIGHT CHILD(TreeVariable, PosVariable) returns entry of rightmost child for a given node

Variable [=] GET CHILD(TreeVariable, PosVariable, Index) returns entry of child with given index (from left) for a given node

Graph Functions
REMOVE ALL LINKS(GraphVariable) clears links of a graph variable

SIZE LINKS(GraphVariable) number of links in graph

IS EMPTY LINKS(GraphVariable) TRUE if and only if graph has 0 links

FIRST LINK(GraphVariable) returns position of first link

NEXT LINK (GraphVariable, PosVariable) returns position of link following position provided

PREV LINK (GraphVariable, PosVariable) returns position of link preceding position provided

Variable [=] GET LINK(GraphVariable, PosVariable) get link at position

CONTAINS LINK(GraphVariable, LinkVariable) TRUE if and only if graph variable contains variable provided

REMOVE LINK(GraphVariable, PosVariable) remove and deletes link at position

SET LINK(GraphVariable, PosVariable, LinkVariable) Set link at position

SET LINK(GraphVariable, PosVariable, entryIndex, Value) Set value at specified index of link at	position

FIND LINK(GraphVariable, TmpVariable, Condition) Return first position of link that satisfies the condition

FIND NEXT LINK(GraphVariable, PosVariable, TmpVariable, Condition) Return next position of a link that satisfies the condition

SORT LINKS(GraphVariable, TmpVariable1, TmpVariable2, Condition) Sort links according to condition

LINKED(GraphVariable, NodeVariable1, NodeVariable2, LinkType) TRUE if the nodes are linked. Set LinkType to 0 for direct links and 1 for indirect

Go to... Prev Chapter Next Chapter  Guide Index