Functions are a powerful, complex feature of Source that allow customisation of models by advanced users.

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. This page provides general information about working with functions. Refer to the followin sub-sections for more specific information:

Types of functions and variables - Outlines the types of functions available in Source;
In-built functions and variables, default date ranges;
Functions Time of Evaluation - relates to simulation phases within a single time-step; and
Adding function usages manually - Working with the Metaparameter Explorer.

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. Refer to the User interface reference for more information about the Function Manager toolbar.

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, such as End (refer to In-built functions and variables, default date ranges);
Functions;
Variables - there are five types of variables available in Source. Refer to Types of functions and variables for more information; and
Custom functions.

Usages

When a function is used in a model (in an inflow node for example), 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, either:

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

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 Search field under the Function manager toolbar. Start entering the search item, and results will be filtered as you type the text.

Function Editor

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

Choosing Edit » Functions…; or
In the Function manager, choose the variable you want to change. Right click on it, then choose Edit from the contextual menu.

Figure 2. Function Editor

Features of the Function Editor include:

The pane on the left side is the same as that in the Function Manager. Hence, the contextual menus available are the same as those available in the Function Manager;
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 are not 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 ensures that a function is evaluated during a scenario run. This is generally used when you wish to record a function that is not used, or if a modelled variable points to a function that is not evaluated. Note that if you toggle this on for all functions, system performance is reduced;
For a function, the Initial Value is used when a function references itself and is the first evaluation of the function. For the storage node, initial values are used until the modeled variable or function is used/executed for the first time. For example, the initial value can be used until the function evaluated. This means that even on the first time-step, it may not be used depending on the evaluation times. For arrays, the initial values is used until the array is full - for example, if you have a date range of a week; and
You can also enable recording of a function using the Project Explorer (choose Miscellaneous).

Working with functions

Note the following:

Source evaluates the function equation for each time-step and returns a singlevalue for each time-step. The will be the last evaluated value for the function;
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;
There are several in-built functions and operators that allow you to define otherwise complex functions in simple expressions. A complete list is provided here;
Circular references are prohibited between multiple functions; and
A blank function returns zero.

Other useful features

The following features in Source are available when writing functions:

Source has an auto-complete feature, which assists with code completion. For example, if you enter '$', a list of available choices appears, showing all the variables and functions that can be used (shown in Figure 3);
Press Ctrl + Space to view all the available keywords, such as 'min' or 'average'. These keywords can also be viewed by using the Keyword icon on the toolbar; and
You can drag and drop variable names into a function.

Figure 3. Maximum Constraint node (Function Editor)

Scoping

Functions and variables can have non-unique names, so long as they are in different scopes. For example, consider the setup shown in Figures 4 and 5:

Figure 4. Function Editor, Scoping example 1

Figure 5. Function Editor, Scoping example 2

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

Note: To avoid errors/confusion, it is recommended to reference a function by it's full name. The syntax is $Function.Folder.

Adding a variable or function

Follow these steps to add a variable or function:

Click on the Add Variable button in the Functions toolbar (as shown in Figure 1) and choose the appropriate drop-down item. This can be done in the Function manager (Figure 1) or Function Editor (Figure 2);
A new variable will appear in the position that was selected. Note that at this point, the variable has not been allocated a recorder, so a warning icon will appear; and
The view of the pane on the right will depend on the type of variable or function that has been specified.

The function/variable can now be defined.

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.

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 6):

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 6. 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 variable which is referenced in a function.

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 Editor (Evaluation order)

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

Referencing

A function can reference other functions within the same scenario. It can also reference itself.

For example: $Function1 = $Function1 + $Function2
In this case, $Function1 will use its previous evaluation value to calculate its new one.

Notice that the list shown in Figure 3 contains $Function1 as an option.

Testing Functions

Once you have defined a function, you can test its operation using the Parse button. You can enter values for the various terms in your function and confirm that the result of evaluating your function with those values is correct. The Parse button is, by default, hidden in the Function editor, and is used as follows:

Select the function you wish to test. This will appear in the right side pane of the Function editor;
Click on the arrow next to Parser (as shown in Figure 7);
If the variables/functions used in the function are not in the list, click Parse
The expanded section (shown in Figure 8) provides a table of all the variables used in the function. Enter a value for the variable you wish to test (double-click on the cell, then enter a number);
Click Parse; and
The test result will be displayed in the cell under the Parse button.

To close this area, click on the same arrow.

Figure 7. Function Editor (Parse)

Figure 8. Function Editor (Parse-window)

If the function cannot be parsed, you will get an error icon next to the function in the Function manager. Additionally, an error in the Log Reporter will be available at run time to indicate the same.

Time of Evaluation

Functions are evaluated at the start of each time-step. Simulation phases shows details of all phases involved in a simulation time-step:

start of the ordering phase;
end of the ordering phase;
start of the flow distribution phase; or
end of the flow distribution phase.

Note: The Function Editor dialog allows you to link two resource assessment systems using the Time of Evaluation tab. Normally, fields in the function editor are lagged by a time-step (that is, they get their value from the last time-step to use in the current time-step). Enabling the During Resource Assessment checkbox results in the resource assessment system linked parameters being executed within the current time-step. As long as the resource assessment system appears above another resource assessment system in the hierarchical list, the values will be up-to-date in the time-step. Conversely, if one resource assessment system appears below a linked resource assessment system, its values will be lagged by a time-step.

Date ranges

All events occurring during a time-step are independent, such as when a function is evaluated, or when the modeled variable on which the function depends is updated. You can choose the times in which to carry out certain actions. Tables 10 and 11 here define the options which are available by default.

If none of the default options is appropriate, you can define your own date ranges using one of the options from the Date range type popup menu (Figure 15). To calculate a particular date in the water year using the calendar date functions, you can use $now.dayofyear+184 (to indicate the next calendar year) for example, or $now.dayofyear-181 (represents the current calendar year).

Custom date ranges fall into three categories:

Date Range Calendar (Figure 9) allows you to define a precise start and end date during which the model variable is considered to be valid. Enabling the Is Recurring checkbox ignores the years. In other words, the period between [start day/start month] and [end day/end month] is valid for every year during model execution.
Date Range Period (Figure 10) allows you to specify the date range in terms of a period of time that is relative to the current time-step. A period can range from one hour to one year and is controlled via the Period popup menu. The number of periods included in the range is controlled by the X periods ago(start) and Y periods ago(end) fields where end ≥ start. A value of zero refers to the current period. For example:
- A Daily period where start=0 and end=0 refers to the current day;
- A Daily period where start=1 and end=1 refers to the previous day.
The Date Range Time Step option (Figure 11) allows you to specify the date range in terms of time-steps. The number of time-steps included in the range is controlled by the X time-steps ago(start) and Y time-steps ago(end) fields where where end ≥ start. A value of zero refers to the current time-step. For example:
- If start = 0 and end = 0, this refers to the current time-step;
- If start = 1 and end = 1, this refers to the last time-step;
- If start = 0 and end = 6, this refers to the last seven time-steps including the current time-step.

Figure 9. Function Editor (Date Range, Date range calendar)

Figure 10. Function Editor (Date Range, Period)

Figure 11. Function Editor (Date Range, time-step)

For all three custom calendar options:

The Update Frequency popup menu offers a choice of OncePerTimeStep or OncePerIteration. The latter setting is only applicable to NetLP.
The Return set popup menu controls the granularity of the returned result:
- If the range represents a single value, that value is returned regardless of this setting.
- Table 2 summarises what is returned if the range represents more than one value.

Table 2. Function Editor, Date Ranges (Variables)

Option	Summary	Result
Simple Set	Returns the set of observations without modification	[1,2,3,4,5]
Set of Averages	Returns a set of the same size where each member is the average of all of the members of the set	[3,3,3,3,3]
Set of Progressive Averages	Returns a set of the same size where each member is the original value of that member averaged with the value of the first member.	[1,1.5,2,2.5,3]

Where: input is the series [1,2,3,4,5]

Note: While the interface uses the word set to refer to the concept of returning multiple values, because the values are both ordered and can be repeated, these can be thought of as lists.

Example

As an example, you can use a function or expression at a Maximum Order Constraint node to limit the maximum orders for each time-step. Assume that a channel constraint of 80 ML/day is required to prevent flows going overbank, except during floods (defined as more than 2,000 ML/day) when up to 3,000 ML/day is permitted as an environmental flow.

Figure 12 shows a fragment of the river network. Downstream demands are represented by a supply point and water user node. In the Function Editor, you specify the internal orders and unregulated river gain of the model using modelled variables. Maximum orders are then defined using an expression.

Figure 12. Maximum Order Constraint node (example)

In this case, the following components will be assigned:

Storage 2: Requested flow rate - say, $Orders with a data range of Last time-step; and
Inflow 3: Inflow - $predictedInflow, with the same data range as Storage 2.

Note that both variables will have ML/day as designated units.

Then, the following expression will return a value of 3,000 ML/day if flows are above 2,000 ML/day but 80 ML/day otherwise.

If(($predictedinflow+$orders) > 2000, 3000, 80

Debugging

There are three ways of gathering information required to debug functions:

Recording - This is available for functions, pattern variables and time series variables;
Logging - The result of a function can be logged in the Log Reporter for a given day, by using the Add Log Date contextual menu item (for each function). This will output a log entry for each date specified, and will include the result of the function, as well as all the functions and variables it uses at each time of evaluation; and
Execution Order - This shows the order in which functions are evaluated for each time of evaluation. Choose Tools » Function Execution Order to open this dialog (Figure 13).

Figure 13. Function execution order

Browser not supported