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 . Groups are ordered as follows:

• Folders associated with In-built functionsvariables, which includes End, Now, Start and $ActiveInputSet;
• Functions;
• 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))

• .

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 23) 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. 

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.

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.

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.

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

Image Added

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. 

About variables and functions

Played vs non-played variables

The Function manager distinguishes between two classes of variables:

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).

Writing functions

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.

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

Table 3. Function manager (arithmetic operators)

For example, you can calculate your place in the water year using the calendar date functions.  

The following features in the Function Manager make it easier to write expressions:

• When you start writing an expression, Source lists all the available arguments, including the in-built variables (such as $now.day and $now.dayofyear). Alternatively, you can press Ctrl + Space on your keyboard to list these options; 
• You can drag and drop variable names into a function;

Testing Functions

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

• Highlight the function you wish to test. This will appear in the Configuration pane of the Function editor;
• Click on the area below the Configuration pane (as shown in Figure 3);
• The expanded section (shown in Figure 4) provides a table of all the variables used in the expression. 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 position.

Image Removed

Figure 4. Function Editor (Parse-window)

Image Removed

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 indicate the same.

Types of variables

Modelled variables

A modelled variable provides a connection between your function and model (non-played) variables. You define a name (or meta-name) by which you will refer to a model variable in your function and configure other parameters governing its use. Once a variable has been defined, it can be used in a function. To configure a new modelled variable using the Function Editor:

• Add a modelled variable, as described in Adding a variable or function;
• 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;
• The Configuration pane will show a list of all the recorder variables available (this will depend on the model);
• Using the disclosure triangles, choose the appropriate recorder that you wish to be associated with the variable;
• Depending on the recorder you choose, you can also specify the following:
  • Result Units - units of the results;
  • The variable's Initial Value - this defines the value that the variable takes on between the start of the first time-step and the point during that time-step when the corresponding model variable acquires a defined value;
  • Date Range - the date range that the Function manager uses as a filter when obtaining data during each time-step. For example, you can choose to use the value from the current time-step (assuming it has been updated by the time the function is evaluated) or the previous time-step. You can also use values like the average of the last 100 time-steps. See Date ranges for more information; and 
  • Time of Evaluation - specifies when the variable will be evaluated.

Image Removed

Piecewise Linear variable

A piecewise linear variable (shown in Figure 6) allows you to create piecewise linear relations for use in functions. You can find more information about such relations at About piecewise linear editors.

To define a new piecewise linear relation:

• Create a new Piecewise Linear variable as described in Adding a new variable or function;
• In the Configuration pane, either import a table to assign a piecewise linear relation, or enter one manually; and
• Set the units appropriate to the X and Y axes using the appropriate drop down menus.

Refer to About piecewise linear editors for more information on constructing relations.

Figure 6. Function Editor (Piecewise Linear relation)

Image Removed

Patterns

You use patterns (Figure 7) to create a named dataset of repeating time-dependent values (eg. daily or monthly pattern).

To define a new pattern variable:

• Create a new Pattern variable as described in Adding a new variable or function;
• In the Configuration pane, either manually or via a text file, enter the amount per time period specified, eg. monthly accepts 12 values;daily accepts 366 values;
• Specify either a daily or monthly time-step; and
• The default units for pattern values are the units defined for the simulation. To convert the entered data to different units for use in the functions, choose the new units from the Result Units drop-down menu.

Source evaluates the expression (or function) equation for each time-step and returns a value for each time-step.

Image Removed

Example - Application of the Patterns variable using an inflow node as an example

As an example, the Function Editor is used in the Inflow node to specify the values of monthly inflows using a Patterns variable (Figure 8).

Example: You want to use mean monthly inflows for every time-step in a monthly model simulation.

Use Case: The inflow node is connected to the river network. In the node’s feature editor, select the Function Editor as the preferred data input method. Then, choose a function that refers to the pattern (eg. Lookup($Pattern, $Now.Month)).

Time Series variable

You can assign a variable to use a time series as an input:

• Create a new time series variable as described in Adding a new variable or function;
• In the Configuration pane, assign a time series (using the Data Sources panel) to the variable; and
• Specify the Result Units - this will be assigned depending on the time series. To convert the time-series to different units for use in the expression, choose the new units from the Result Units drop-down menu.

Figure 9 shows an example of a Time series variable. Refer to Importing data for information on working with the Data Sources panel.

Image Removed

Custom Functions

Allows you to create your own expression and then import it for use in the Function manager. Refer to Source Plugins. The Parameter count column refers to the number of arguments used in the function.

Figure 10. Function Editor (Custom Functions)

Image Removed

Time of Evaluation

Functions are evaluated at the start of each time-step. 3.5.0 Simulation phases shows details of all phases involved in a simulation time-step and Basic Concepts provides a diagrammatic representation.

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).

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)

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.

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

Table 3. Function manager (arithmetic operators)

Writing functions

The following features in Source are available when writing functions: 

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

Figure 5. Maximum Constraint node (Function Editor)

Image Added

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 Configuration pane of the Function editor;
• Click on the area below the Configuration pane (as shown in Figure 6);
• If the variables/functions used in the function aren't in the list, click Parse
• The expanded section (shown in Figure 7) 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 position.

Image Added

Figure 7. Function Editor (Parse-window)

Image Added

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.

Types of variables

Modelled variables

A modelled variable provides a connection between your function and model variables. You define a name (or meta-name) by which you will refer to a model variable in your function and configure other parameters governing its use. Once a variable has been defined, it can be used in a function. To configure a new modelled variable using the Function Editor:

• Add a modelled variable, as described in Adding a variable or function;
• 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;
• The Configuration pane will show a list of all the recorder variables available (this will depend on the model);
• Using the disclosure triangles, choose the appropriate recorder that you wish to be associated with the variable;
• Depending on the recorder you choose, you can also specify the following:
  • Result Units - units of the results;  
  • The variable's Initial Value - this defines the value that the variable takes on between the start of the first time-step and the point during that time-step when the corresponding model variable acquires a defined value;
  • Date Range - the date range that the Function manager uses as a filter when obtaining data during each time-step. For example, you can choose to use the value from the current time-step or the previous time-step. You can also use values like the average of the last 100 time-steps. See Date ranges for more information; and 
  • Time of Evaluation - specifies when the variable will be evaluated. See Time of Evaluation for more information; and 

Image Added

Piecewise Linear variable

A piecewise linear variable (shown in Figure 9) allows you to create piecewise linear relationships for use in functions. You can find more information about such relations at About piecewise linear editors.

To define a new piecewise linear relationship:

• Create a new Piecewise Linear variable as described in Adding a new variable or function;
• In the Configuration pane, either import a table to assign a piecewise linear relation, or enter one manually; and
• Set the units appropriate to the X and Y axes using the appropriate drop down menus.

Refer to About piecewise linear editors for more information on constructing relations.

Figure 9. Function Editor (Piecewise Linear relation)

Image Added

Patterns

You use patterns (Figure 10) to create a named dataset of repeating time-dependent values (eg. daily or monthly pattern).

To define a new pattern variable:

• Create a new Pattern variable as described in Adding a new variable or function;
• In the Configuration pane, either manually or via a text file, enter the amount per time period specified, eg. monthly accepts 12 values ;daily accepts 366 values;
• Specify either a daily or monthly time-step; and
• The units for pattern values are the units defined for the simulation. To convert the entered data to different units for use in the functions, choose the new units from the Result Units drop-down menu.

Source evaluates the function equation for each time-step and returns a value for each time-step.

Image Added

Example - Application of the Patterns variable using an inflow node as an example

As an example, the Function Editor is used in the Inflow node to specify the values of monthly inflows using a Patterns variable (Figure 11).

Example: You want to use mean monthly inflows for every time-step in a monthly model simulation.

Use Case: The inflow node is connected to the river network. In the node’s feature editor, select the Function Editor as the preferred data input method. Then, choose a function that refers to the pattern (eg. $Pattern).

Time Series variable

You can assign a variable to use a time series as an input:

• Create a new time series variable as described in Adding a new variable or function;
• In the Configuration pane, assign a time series (using the Data Sources panel) to the variable; and
• Specify the Result Units - this will be assigned depending on the time series. The function system will convert the time series value each time step from the units of the time series, to the Result Units of the time series variable.

Figure 12 shows an example of a Time series variable. Refer to Importing data for information on working with the Data Sources panel.

Image Added

Custom Functions

Allows you to create your own expression and then import it for use in the Function manager. Refer to /wiki/spaces/SC/pages/51643422. The Parameter count column refers to the number of arguments used in the function.

Figure 13. Function Editor (Custom Functions)

Image Added

Anchor
Time of Evaluation Time of Evaluation

Time of Evaluation

Functions are evaluated at the start of each time-step. 3.5.0 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.

Date ranges

The Metaparameter Explorer will be functional from v3.4.2 onwards.

The Metaparameter Explorer allows you to calibrate a variable using a function, where there is no Function manager available and can be accessed using Tools » MetaParameter Explorer. For example, if you want to calibrate a link variable, you can specify this in the Metaparameter Explorer, and then assign it a value using the Function manager.

Suppose you want to calibrate the storage routing exponent (m) on one of the reaches in a Source model. Initially, idenitfy which link in the model you want to place the expression in. Then, use the Metaparameter Explorer to allocate a parameter to the variable (steps outlined in Figure 15).

Figure 15. Calibration Wizard (Metaparameter Explorer)

Image Removed

Finally, to define the value of the variable, m in the Function manager, choose View » Expression List... to open the Expression List Viewer (Figure 16). Click on the hyperlink (circled in orange) to open the Function manager and set the value of m to 2.

Figure 16. Expression List Viewer (Metaparameter Explorer)

Image Removed

Debugging