Types of functions and variables

Using functions is one of several ways of adding data in a Source model. Used in conjunction with variables, they provide a robust and flexible way of data input. There are five types of variables available in Source:

• Context variables - this are ONLY available with the SourcePlugin.FunctionModels.dll plugin. This is not available in Source (public version);
• Modelled variables - provides a a connection between your function and model variables;
• Piecewise linear functions - allow you to create piecewise linear relationships for use in functions;
• Pattern - used create a named dataset of repeating time-dependent values (eg. daily or monthly pattern); and
• Time series variable - assign a variable to use a time series as an input.

Context variables

Context variables are defined and operate in a similar way to modelled variables. As their name suggests, they operate in the context of the variable they are attached to. Whereas modelled variables point to an instance, context variables relate to the context in which they are used. The key to their operation is the ability to transform the input to which they refer to.

Working with context variables is a two-step process:

1. Create and assign a context variable to a parameter, just like a modelled variable; and
2. Create and define a function that uses the context variable.

The function can now be used for differing values input parameters. For each output, the function will change depending on the input value. Use the keyboard to copy (Ctrl+C) and paste (Ctrl+V) the function.

One application of context variables is in rainfall runoff modelling, an example is provided next.

Example

As an example, you can use a context variable when specifying a function for rainfall runoff models. Consider a geographic scenario with rainfall input as a time series. For this exercise, the Catchment surface runoff is a function of Rainfall. This function scales the rainfall (one context variable) according to a parameter (the second context variable). Table 1 shows details of the variables.

Table 1. Context variables setup, example

In the Rainfall Runoff Configuration Model dialog, choose Function based as the model type (refer to Working with rainfall runoff models for more information). Click on the Catchment surface runoff link to specify the input parameters. Define the context variables and function using the Function Editor, as shown in Figure 1.

Figure 1. Function Editor, Context variable

Modelled 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;
• 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 Functions Time of Evaluation for more information.

Figure 2 shows an example of a modelled variable.

Figure 2. Function Editor, Modelled variables

Piecewise Linear variable

A piecewise linear variable allows you to look up a value in one dimension. To define a new piecewise linear relationship (Figure 3):

• 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 3. Function Editor, Piecewise Linear relation

Once defined, a piecewise variable can be accessed using lookup($var, x).

Patterns

To define a new pattern variable (as shown in Figure 4):

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

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

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