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 six types of variables available in Source:
- Pattern variable - creates a dataset of repeating time-dependent values (eg. daily or monthly pattern). Value used is based on the current simulation date and time;
- Time series variable - uses a time series data source as input. Value used is based on the current simulation date and time;
- Piecewise linear variable - creates a lookup table that interpolates a Y value based on an X value.
- Bilinear variable - similar to a piecewise linear variable, but allows you to look up and interpolate between values in two dimensions;
- Modelled variable - uses a model output, eg. the downstream flow of an inflow node; and
- Context variable - for applying the same function in a number of locations that use modelled variables.
There are also built-in Input Sets and Custom Functions.
To define a new pattern variable (as shown in Figure 1):
- Create a new Pattern variable as described in Adding a new variable or function
- Specify either a daily or monthly time step; and
- Enter the amount per time period specified, eg. monthly accepts 12 values; daily accepts 366 values. You can also import a *.csv text file.
Source evaluates the day or month for the current time step and returns the appropriate value.
Figure 1. Pattern variable
For example, you want to use mean monthly inflows for every time step in a monthly model simulation. In the Function Editor, define a pattern variable modelling monthly mean flows, $MonthlyFlowPattern (Figure 1). Then, in the Inflow node's feature editor, select the Function Editor and, create a function, $MonthlyInflow, that refers to the pattern variable (Figure 2).
Figure 2. Pattern variable - example
Time series variables
To work with a time series variable:
- 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 using the drop down menu - 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 3 shows an example of a Time series variable. Refer to Loading data for information on working with the Data Sources panel.
Figure 3. Time Series variable
Piecewise Linear variable
A bilinear variable allows you to interpolate in two dimensions, whereas a piecewise linear variable allows you to look up a value in one dimension.
To define a new piecewise linear relationship (Figure 4):
- Create a new Piecewise Linear variable as described in Adding a new variable or function; and
- Define your lookup and result values by entering them manually or you can import a *.csv text file.
Refer to User Interface - About piecewise linear editors for more information on constructing relations.
Figure 4. Piecewise Linear variable
Once defined, a piecewise variable can be accessed using lookup($var, x), in a similar manner to bilinear variables.
Bilinear variables (Figure 5) allow you to look up and interpolate values in two dimensions. In the top half of the screen, you name the variables; the table below allows you to define the relationship.
To configure a new bilinear variable in the Function editor:
- Add a bilinear variable, as described in Adding a variable or function;
- In the relationship table, use the contextual menu to add a row or column in the table;
- Double click in the individual cell to edit the values. Alternatively import a *.csv text file (Table 1); and
- Re-name the X Axis, Y Axis and Result names using their respective Name fields (by default, these are called 'X', 'Y' and 'Value' respectively). This is useful to remind you what the bilinear variable defines, but is not used elsewhere in Source.
Table 1. Bilinear variable (data file format)
|1||2 … n|
|2 … n||y||value|
desc is a title, it is ignored during import. In exported *.csv files it will have the text 'X across Y down'
x and y are look up values
value is the result that will be returned for the corresponding x and y
In Figure 5, the X values (row headers) are volumes, the Y values (column headers) are years, and the results are the pumping costs per ML.
Figure 5. Bilinear variable
Once defined, a bilinear variable can be accessed using lookup($var, x, y), as shown in Figure 6. In this instance, the function $PumpingCost is looking up the bilinear variable $BiLinear_Cost (defined in Figure 5). The x value used for the lookup is the modelled variable $ExtractedVolume, which is the extracted volume from a supply point; the y value used is $Now.Year, which is the year of the current time-step.
Figure 6. Accessing a bilinear variable
Modelled variables point to model results and allow them to be called by functions as the model runs. To configure a new modelled variable:
- 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 for more information; and
- Time of Evaluation - specifies when the variable will be evaluated. See Functions Time of Evaluation for more information.
Figure 7 shows an example of a modelled variable.
Note: Because functions can be recorded, combining functions with modelled variables allows you to create iterative functions, where a function can use the result of itself from a previous time step. See Using Restriction Curves for a worked example of this usage.
Figure 7. Modelled variable
Date ranges apply to modelled variables and context variables. The default date range is a single value for the current time step. You can choose to set up variables to be a specific timestep in the past or a list of values from previous time steps or time spans.and 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 Ranges toolbar (Figure 8). 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).
Figure 8. Date Ranges toolbar
Custom date ranges fall into four categories:
- Previous year date range - static ( ) 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 Date and End Date is valid for every year during model execution;
- Current year date range - progressive (Figure 10);
- Period (
allows you to specify the date range in terms of a period of time that is relative to the current time-step. Period is commonly used with models that are not daily time step models.A period can range from six minutes 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 Time Step date range option (
) 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 Timesteps Ago (Start) and Y Timesteps 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.
Also note the additional parameters:
- The Update Frequency popup menu offers a choice of Once Per Time Step or Once Per Iteration. 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.
- summarises what is returned if the range represents more than one value. As an example, input is the series [1,2,3,4,5].
Table 2. Function Editor, Date ranges (variables)
|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]|
Figure 9. Date Range, previous year
Figure 10. Date range, current year
Figure 11. Date Range, Period
Figure 12. Date Range, time-step
Context variables are defined and operate in a similar way to modelled variables. As their name suggests, they operate in the context of the function usage they are attached to. Whereas modelled variables point to an instance of a model component eg. Storage 1, context variables change what they are referring to based on where the function is used. For example, if a context variable points to Storage Downstream Flow, the function can be used by multiple storages. However, in each case the context variable will refer to that storage's Downstream flow.
Currently, functions with context variables can't be recorded.
One application of context variables is in rainfall runoff modelling, an example is provided next.
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
|Context variable||Model type||Assigned parameter|
|$Rainfall||Rainfall Runoff Model||Rainfall|
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 13.
Figure 13. Context variable
Allows you to create your own function and then import it for use in the Function manager. Refer to Custom Function Plugins and How to write plugins for Source. The Parameter count column refers to the number of arguments used in the function.