Function manager

Functions

A component's behaviour can depend on other dynamic values within a model. Functions allow you to control this behaviour via an arithmetic expression, or function.

About the Function manager

The Function manager (shown in Figure 1) allows you to centrally manage all functions that have been defined in Source. It is used in places where you might otherwise employ a time series or a single value.

Note: As of Source version 3.5.0, the Expression Editor has been superseded by the Function manager. Click here to access documentation for the old Expression Editor.

The Function manager can be accessed in one of two ways:

Choosing View » Function Manager; or
Clicking on the Function Manager icon in the Scenario toolbar.

Figure 1. Function manager

Items in the Function manager are sorted into groups, and then by name. Groups are ordered as follows:

Folders associated with In-built variables, which includes End, Now, Start;
Functions;
Variables - there are four types of variables available in Source. Refer to Types of variables for more information; and
Custom functions.

Usages

When a function is used in the model, as an example at an inflow node, then that usage is shown in the tree under the function. If a function is used in multiple places, then all usages are shown under the function in the Function Manager tree. To link a node to a function, you can either:

Use the node's feature editor; or
Right click the function and choose Add Usage. Then, use the Metaparameter Explorer.

The Function Manager only shows direct uses of a function. For example, if an inflow node has been assigned a function, $ExampleFunction, this is indicated in the Function Manager. If $ExampleFunction is comprised of two separate functions, $ExFn1 and $ExFn2, these two functions will not be part of the Inflow node.

You can also search for a variable or function using the area under the Function manager toolbar. Start entering the search item, and the results will be filtered as you type the text.

Function Editor

The Function Editor (shown in Figure 3) allows you to add, modify and delete individual functions and variables. It can be accessed in one of two ways:

Choosing Edit » Functions…; or
Choose the variable you want to change in the Function manager (Figure 1). Right click on it, then choose Edit from the contextual menu.

Figure 3. Function Editor

Adding a variable or function

To add a variable or function, click on the Add Variable button on the Functions toolbar (as shown in Figure 1) and choose the appropriate drop-down item;

You can define and configure it using the Configuration pane on the right. The view of this pane will depend on the type of variable or function that has been specified.

Adding a note to a function

You can include a text-based message, or note, to be associated with a function. Refer to About notes for more information about notes.

Note: You can add a note to a function only. As of 3.5.0, variables do not have this facility available.

To associate a note with a function (as shown in Figure 4):

Open the Function Editor;
Click on the function you want to add a note to;
In the Function Editor toolbar, click on the Add/Edit Note icon; and
Add the text message in the window that appears.

Figure 4. Function Editor, Adding a note

Deleting and renaming a variable or function

To delete a variable or function, choose the appropriate item in the function list, right click, and choose Delete from the contextual menu.

To rename it, choose Rename from the contextual menu and type the name you wish to assign.

Note: Source warns you if you attempt to delete a modeled variable which is referenced in a function.

The Results Units drop down menu allows you to choose which units the variable or function will evaluate to. The result units of a function have to commensurate to the required units of the model input it is used for. If the result units of the function aren't the same as the required units of the model input, a conversion is done of the function result before it passes the value to the model.

By default, if a function is not referenced at any model input, or any other functions, it is not evaluated during a scenario run. The Force Evaluation scroll toggle (Figure 2) ensures that a function is evaluated during a scenario run. You would use Force Evaluation if you wanted to record a function that wasn't being used, or if you had a modeled variable pointing to a function that wasn't evaluated. The only downside to turning on Force Evaluation for all functions is that the performance will be effected.

The Initial Value for a function is only used when a function references itself. The Initial Value is in this case for the first evaluation of the function.

You can also enable recording of a function using the Project Explorer (choose Miscellaneous).

Note: A function always returns a single value at each time-step. The will be the last evaluated value for the function.

About variables and functions

General rules for functions

The following rules apply to functions:

White-space, including new-line markers, is ignored;
Function names, operator names, variable names and label names are not case sensitive;
All variable names must begin with the "$" character;
All variables used in functions must be defined;
Functions can reference themselves. The initial value is used in this case for the first evaluation of the function.
Circular references are prohibited between multiple functions; and
A blank function returns zero.

Scoping

Functions and variables can have non-unique names, so long as they are in different scopes. For example, consider the following setup in the Function manager:

ANU: CAN WE USE PROPER SCREENSHOT HERE

	Folder1
		$Function1
		$Function2
	Folder2
		$Function3
	$Function4

In this case, $Function1’s expression can reference $Function2 directly as they are both part of Folder1. So, if($Function2, 0, 1) is a valid function;
If $Function3 references $Function2, you must use the full path to reference it - if($Folder1.Function2, 0, 1); and
Any function can reference $Function4 directly because it is in the global scope (ie. it is not part of a folder).

There are several in-built functions and operators that allow you to define otherwise complex functions in simple expressions. These are described next.

Operator precedence

Unless you use parentheses to modify the order of evaluation, operations are performed according to the precedence rules shown in Table 1. Where two operators have the same level of precedence, the operations are performed left-to-right.

Table 1. Function manager (evaluation order)

Order of precedence	Operator Symbol	Meaning

Order of precedence	Operator Symbol	Meaning
1 (highest)	( )	explicit ordering
2	-	negation
3	** and ^	exponentiation
4	* and /	multiplication and division
5	+ and -	addition and subtraction
6 (lowest)	< <= = >= > <>	comparison operators

In-built functions

In-built functions are predefined formulae that perform calculations which usually depend on the arguments you supply as parameters. They can be entered manually or by using the pull down menu at the top of the Function Editor (Figure 2). The available functions are summarised in Tables 6-10. Some examples of function use are shown in Table 2.

Table 2. Sample expressions using functions

Expression	Result	Expression	Result	Expression	Result

Expression	Result	Expression	Result	Expression	Result
Average($var1)	3	Median($var1)	3	Lookup($var1,13.5)	2.5
Lookup($var1,14)	3	Count($var1)	5	Max($var1)	5
Min($var1)	1	Sum($var1)	15	Stdev($var1)	1.58113883

Where: $var1 is the piecewise linear relationship {(12, 1), (13, 2), (14, 3), (15, 4), (16, 5)}

Table 3. Function manager (arithmetic operators)

Operator	Meaning	Example	Result

Operator	Meaning	Example	Result
+	addition	10 + 5	15
-	subtraction; negation	10 - 5 = 5 or 10 + (-5)	5
*	multiplication	10 * 5	50
/	division	10 / 5	2
** or ^	power/exponentiation	10**5 or 10^5	100000
( )	influence order of evaluation	5 * (10 + 5)	75

Table 4. Function manager (comparison operators)

Operator	Meaning	Example	Result

Operator	Meaning	Example	Result
>	greater than	10 > 5	true
<	less than	10 < 5	false
>=	greater than or equal	10 >= 5	true
<=	less than or equal	10 <= 5	false
=	equal	10 = 5	false
<>	not equal	10 <> 5	true

Table 5. Function manager (logical operators)

Operator	Meaning	Example	Result

Operator	Meaning	Example	Result
OR	or	false OR true	true
AND	and	false AND true	false
NOT	not	NOT false	true

Table 6. Function manager (general mathematical functions)

Function	Meaning	Example use

Function	Meaning	Example use
EXP	Returns e raised to the power of a given number	EXP(number)
LOG10	Returns the base-10 logarithm of a number	LOG10(number)
LN	Returns the natural logarithm of a number	LN(number)
ABS	Returns the absolute value of a number	ABS(number)
SQRT	Returns a positive square root	SQRT(number)
MOD	Returns the remainder from division	MOD(number,divisor)
ROUND	Rounds a number to the nearest integer	ROUND(number)
INT	Rounds the number down to the nearest integer	INT(number)

Table 7. Function manager (statistical functions)

Function	Meaning	Example use

Function	Meaning	Example use
AVERAGE	Returns the average of its arguments	AVERAGE(variable_name)
COUNT	Counts how many numbers are in the list of arguments	COUNT(variable_name)
COUNTIF	Counts how many numbers in the list of arguments satisfy the expression	COUNTIF(variable_name,expression)
MAX	Returns the maximum value in a list of arguments	MAX(variable_name) or MAX(number,number)
MEDIAN	Returns the median of its arguments	MEDIAN(variable_name)
MIN	Returns the minimum value in a list of arguments	MIN(variable_name) or MIN(number,number)
STDEV	Estimates standard deviation based on a sample	STDEV(variable_name)
SUM	Adds its arguments	SUM(variable_name)

Table 8. Function manager (trigonometric functions)

Function	Meaning	Example use

Function	Meaning	Example use
ARCCOS	Returns the inverse cosine of a number	ARCCOS(number)
ARCSIN	Returns the inverse sine of a number	ARCSIN(number)
ARCTAN	Returns the inverse tangent of a number	ARCTAN(number)
COS	Returns the cosine of a number	COS(number)
SIN	Returns the sine of a number	SIN(number)
TAN	Returns the tangent of a number	TAN(number)

Table 9. Function manager (miscellaneous functions)

Function	Meaning	Example use

Function	Meaning	Example use
IF	Specifies a logical test to perform	IF(logical_test,value_if_true,value_if_false)
LOOKUP	Looks up the Y-value corresponding to an X-value via a piecewise linear editor (uses linear interpolation)	LOOKUP(variable_name, number)
N1	Returns 1 if the number is less than zero, 0 otherwise	N1(number)
P1	Returns 1 if the number is greater than zero, 0 otherwise	P1(number)
PI	Returns the mathematical constant π to 14 decimal places	PI()
/* Comment */	/* begins a comment and */ ends a comment. Comments can go over multiple lines.	5 + 4 /* Some sort of comment about the function*/