Functions

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

A model element's behaviour can depend on dynamic values within the model. Functions allow you to control this behaviour via an arithmetic expression. They are used in places where you might otherwise employ a time series or a single value (eg. a node's feature editor). This page provides general information about working with functions:

Refer to the following sub-pages for more specific information:

• Types of functions and variables - Outlines the types of functions available in Source;

• Available functions, operators, variables and date ranges; and

• Functions Time of Evaluation - relates to simulation phases within a single time step.

Using functions as model inputs

The ability to use a function as a model input is a powerful way to customise model behaviour. For the purposes of discussing functions, a model element is any part of the model that can use a function as an input instead of a data source or value. This includes:

• Nodes

• Links

• Resource assessment

• Rainfall runoff models

The ability to use a function as input is indicated in Source windows in one of two ways:

• As a radio button. In this case, there is always the option of using a value or a data source as an input instead (Figure 1). When enabled, Function Editor will open below the radio button, embedded within the same window; or

• As an ellipsis button. In this case, there is always the option of using a value as an input instead (Figure 1). When selected, the Function Editor will open in a new dialog.

When a function is used directly by a model element, that element is shown under the function in the function tree, see Figure 1. 

Example use of a function

As an example, you can use a function at a Maximum Order Constraint node to limit the maximum orders for each time-step based on predicted inflow and orders. 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 2 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 a function.

In this case, the following modelled variables will be assigned to these components:

• $Orders assigned to the Requested Flow Rate of the Storage node; and

• $predictedInflow assigned to the Inflow of the Inflow node.

Note that both variables will have a date range of Last Time Step, ML/day as designated units and Time of Evaluation as Ordering Phase.

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

Function Management

Functions can be used extensively for defining model elements in Source, as well as being used within other functions and as a stand-alone evaluation tool. This can result in a large number of functions with complex relationships being present in a model. Source has inbuilt function management capability to assist you in keeping track of your functions and variables, which should be used in conjunction with the design of a systematic approach to function organisation during the model conceptualisation process.   

Function Manager

The Function Manager (Figure 3) allows you to centrally manage all functions that have been defined in Source.

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.

It will then open in the main screen. 

Function Tree Display

The Function Manager lists the functions and variables available within the active scenario in a tree menu. Items in this function tree are:

• Folders associated with built-in variables, such as End (refer to Available functions, operators, variables and date ranges);

• Folders;

• Functions;

• Variables (refer to Types of functions and variables); and

• Custom functions.

By default, when a function is used by a model element (in an inflow node for example), that element is shown in the tree under the function (function usage, Figure 3). If a function is used by multiple elements, then all usages are shown under the function in the function tree. The lock icon next to the element's name indicates that it the element is locked to using that function as an input (Crab Creek:Inflow is locked in Figure 3). See below for more information. 

In addition to the function tree, the Function Manager contains a Search bar, in which you can enter text to filter the function tree, and the Function Manager toolbar. 

Shown in Figure 4, the Function Manager toolbar has the following features:

• Add New... creates a new function, or variable of the type selected.

• Add New Folder creates a new folder in the function tree.

• Expand All expands all items in the function tree.

• Collapse All collapses all items in the function tree.

• Edit Functions... opens the Function Editor.

• Filters items shown in tree opens the drop-down Filter menu, which toggles the display in the function tree of function and variables by their type and/or their use. By default all functions and variables are shown, regardless of their type or their use. Note that selections are also affected by text entered into the Function Manager search bar. 

• Delete all unused is only active when Unused functions and variables is selected from the Filter menu. This button deletes all unused functions and variables in the function tree that also match the current filter options and text entered into the search bar. Unused items that meet the selection criteria, folders that contain only unused items, and empty folders will also be deleted. Built-in variables and custom functions will not be deleted.

• Show function evaluation tree opens the Function Editor and displays the function evaluation tree for the selected function. This button is only enabled when a function is selected in the function tree.

• Show all function and variable usages displays the usages of all function and variables in the function tree.

The contextual menus (accessed by right clicking within Function Manager, Figure 3) additionally allow you to:

• Lock All Usages in the selected folder, or in the function tree;

• Unlock All Usages in the selected folder, or in the function tree;

• Rename the selected item;

• Delete the selected item; and

• Unlock or Lock the function usage by the selected model element