Page Comparison

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. 

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.

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

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

The $ActiveInputSet function can be referenced as a model variable in another function. It is used to specify the use of a particular input set (if one has been defined). For the function shown in the example below, different values are assigned to the function depending on the value of the variable.

if($ActiveInputSet = "Wet", 15, if($ActiveInputSet = "Dry", 0, 7))

In this case, for all instances of Wet, the function will return a value of 15; for instances of Dry, a value of 0 will be output. All other instances will result in a value of 7.

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.

Execution of order

You can view the order in which expressions are processed using the Function Execution Order dialog (shown in Figure 2). Choose Tools » Function Execution Order to open this dialog.

Figure 2. Function Execution Order

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. 

Anchor
Adding a note to a function Adding a note to a function

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.

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. 

The Results Units drop down menu allows you to choose which units to display the output in.

By default, if a function or variable is not referenced at any node, it is not recorded during a scenario run. The Force Evaluation scroll toggle (Figure 2) ensures that a function is evaluated and recorded during a scenario run. In some cases (eg. if a function is not used in a model), the function will not be evaluated if the scroll if toggled to OFF.

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

About variables and functions

Played vs non-played variables

The Function manager distinguishes between two classes of variables:

• Played - These are provided via time series or other inputs such as the Piecewise Linear or Patternsvariables of the Function manager. Conceptually, any played variable can be viewed as a list with the next value taken from the list each time the time-step advances. Played variables are updated at the start of the time-step and maintain the same value throughout the time-step.
• Non-played - Also known as model variables, in which variables are produced by the operation of the models which execute during a run. Within a time-step, the moment when any given model variable is updated depends on the model.

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 functions are global;
• All variables used in functions must be defined;
• Circular references are prohibited; and
• A blank function returns zero.

Global functions

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:

	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 expression;
• 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)

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.