...
Table 10. Function manager (predefined variables)
Function | Meaning |
|---|---|
$now.year | Returns the 4-digit year of the current time-step |
$now.month | Returns the month of the current time-step (range: 1...12) |
$now.day | Returns the day of the current time-step (range: 1...31) |
$now.hour | Returns the hour of the current time-step (range 0...23) |
For example, you can calculate your place in the water year using the calendar date functions.
Writing functions and expressions
The following features in Source help when writing functions:
- When you start writing an expression, Source lists all the available arguments, including the in-built variables (such as $now.day and $now.dayofyear), an example of which is shown in Figure 3. Alternatively, you can press Ctrl + Space on your keyboard to list these options; You can choose the appropriate argument from the list.
- You can drag and drop variable names into a function;
Figure 3. Maximum Constraint node (Function Editor)
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 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 34);
- 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.
Figure
34. Function Editor (Parse)
Figure
45. 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 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.
Figure
56. Function manager (Variables tab)
Piecewise Linear variable
A piecewise linear variable (shown in Figure 67) 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
67. Function Editor (Piecewise Linear relation)
Patterns
You use patterns (Figure 78) 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.
Figure
78. Function Editor (Patterns)
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 89).
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)).
Figure
89. Inflow node (Function Editor - Monthly 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. 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.
Figure
910. Function Editor (Time Series variable)
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
1011. Function Editor (Custom Functions)
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.
- 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
All events occurring during a time-step are independent, such as when a function is evaluated, or when the model variable on which the function depends is updated. You can choose the times in which to carry out certain actions. Tables 11 and 12 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 1213).
Table 11. Function manager (date range instances)
Date Range | Meaning |
|---|---|
Current Time-step | The most-recently-updated value. |
Current Iteration | Only applicable to NetLP. The value updated during the last iteration of the solver. |
Current Day | For a daily model, this is a synonym for Current Time-step. For a sub-daily model, it is the sum of the values for the current day. |
This Month | For a monthly model, this is a synonym for Current Time-step. For a sub-monthly model, it is the sum of the values for the current month. |
This Calendar Year | For a yearly model, this is a synonym for Current Time-step. For a sub-yearly model, it is the sum of the values for the current calendar year. |
This Water Year To Date | For a yearly model, this is a synonym for Current Time-step. For a sub-yearly model, it is the sum of the values for the current water year. |
Last Time-step | The value of the variable at the completion of the previous iteration of the model. |
Previous Day | For a daily model, this is a synonym for Last Time-step. For a sub-daily model, it is the sum of the values for the previous day. |
Last Month | For a monthly model, this is a synonym for Last Time-step. For a sub-monthly model, it is the sum of the values for the previous month. |
Last Calendar Year | For a yearly model, this is a synonym for Last Time-step. For a sub-yearly model, it is the sum of the values for the previous calendar year. |
Last Water Year | For a yearly model, this is a synonym for Last Time-step. For a sub-yearly model, it is the sum of the values for the previous water year. |
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).
Table 12. Function manager (date range sets)
Date Range | Meaning | Example of use |
|---|---|---|
Last Hundred Time-steps | The set of values from the model for the previous 100 iterations. | Lookup($var,35) |
Last Seven Days | For a daily or monthly model, this is the set of the values from the last seven time-steps. For a sub-daily model, it is the set of the average daily values for each of the previous seven days. | Average($var) |
Previous 30 Days | For a daily or monthly model, this is the set of the values from the last 30 time-steps. For a sub-daily model, it is the set of the average daily values for each of the previous 30 days. | Average($var) |
Last 365 Days | For a daily or monthly model, this is the set of the values from the last 365 time-steps. For a sub-daily model, it is the set of the average daily values for each of the previous 365 days. | Average($var) |
Custom date ranges fall into three categories:
- Date Range Calendar (Figure 11) 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 12) 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 13) 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
1112. Function Editor (Date Range, Date range calendar)
Figure
1213. Function Editor (Date Range, period)
Figure
1314. 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 13 summarises what is returned if the range represents more than one value.
Table 13. 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]
| Info | ||
|---|---|---|
| ||
| Note: While the user interface uses the word set to refer to the concept of returning multiple values, because the values are both ordered and can be repeated, it is probably better to think of these as lists. |
Example
As an example, you can used 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 1415 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
1415. 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
The Metaparameter Explorer will be functional from v3.4.2 onwards.
| Anchor | ||||
|---|---|---|---|---|
|
The Metaparameter Explorer allows you to calibrate a variable using a function, where there is no Function manager available and can be accessed using . 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)
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)