Expression Editor

The Expression Editor (Figure 1) allows you to control component behaviour via arithmetic expression. In particular, a component’s behaviour can depend on other dynamic values in the model. The expression editor is used in places where you might otherwise employ a time series or a piecewise linear relationship.

Expression calculation

The expression editor calculates values according to the expression that you create. It performs unit conversions for all variables that you declare. If you load a time series variable and select litres for units, but in the Expression Editor, you select cubic metres in the Units column, the units will be converted from litres to cubic metres. However, the Expression Editor does not check units either within an expression or as a returned value. Neither does it convert or normalise units. For example, if the result of a calculation is 10 megalitres but the return units are set to kilolitres, the result of the expression is 10 kilolitres. Similarly, if the inputs to an expression are a mixture of units, and you do not allow for this in your expression, the result may not be what you expect. Figure 2 describes the units used for the Expression Editor.

Local vs global scope

Expressions are divided into two types according to their scope: local and global. Global expressions are available throughout the scenario whereas local expressions are confined to the feature editor in which they are defined. With respect to the tabs shown in Figure 1, any value defined in the Variables tab is local to the context in which it is defined (eg. the particular feature editor). A value defined in any other tab is global to the scenario.

Played vs non-played variables

The expression editor distinguishes between two classes of variables:

• Played - These are provided via time series or other inputs such as the Piecewise Linear or Patterns tabs of the Expression Editor. Conceptually, any played variable can be viewed as a list with the next value taken from the list each time the time-step advances. Played variables are updated at the start of the time-step and maintain the same value throughout the time-step.
• Non-played - Also known as model variables, in which variables are produced by the operation of the models which execute during a run. You gain access to model variables by defining links in the Variables tab of the expression editor. Within a time-step, the moment when any given model variable is updated depends on the model.

General rules for expressions

The following rules apply to expressions:

• 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 variable names must be unique;
• All variables used in expressions must be defined;
• Circular references are prohibited; and
• A blank expression returns zero.

Source warns you if you attempt to delete a node which is referenced in an expression.

If you accidentally use non-unique variable names, Source will warn you when you run your model.

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. Expression Editor (evaluation order)

Functions

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 Expression Editor (Figure 1). The available functions are summarised in Table 7, Table 9, Table 9 and Table 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)}

Testing expressions

You can test expressions using the Parse button. This opens the Parse Results window (Figure 64) where 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. Your expression is evaluated each time you click the Parse button in the Parse Results window. When you have finished testing, click OK to return to the Expression Editor.

Deleting expression components

The various sub-tabs of the Expression Editor allow you to define terms which can be used in constructing expressions, after which you can rename it or edit its parameters using the respective controls. Deleting a term is a two-step process, shown in Figure 4.

Viewing expressions

To view all the expressions available in the current project, choose View > Expression List... .

Variables tab

The Variables tab provides a connection between your expression and model (non-played) variables. You define a name (or meta-name) by which you will refer to a model variable in your expression and configure other parameters governing its use. Once a variable has been defined, it can be used in an expression. To define a new variable:

• Click on a new row in the table (eg. Figure 5) and enter a name for the variable by editing the contents of the Name column.
• The Initial Value column 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. Set this to an appropriate value.
• The Source column contains a popup menu from which you can select any of the components (nodes, links, etc) that are defined in your model. Choose the appropriate component.
• The Part column contains a popup menu which exposes all of the model variables associated with the component that you selected in the Source popup menu. Choose the appropriate variable.
• Source chooses units which reflect the units of the Part that you selected. Data can be converted to different units by making a different selection in the Units popup menu.
• The ellipsis button in the Date Range column leads to a dialog where you can choose the date range that the Expression Editor 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 expression 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.

Date ranges

All events occuring during a time-step are independent, such as when an expression is evaluated, or when the model variable on which the expression depends is updated. You can choose the times in which to carry out certain actions. Table 11. and Table 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 6).

Figure 6. Expression Editor (Date Range, custom calendar)

Custom date ranges fall into three categories:

• Date Range Calendar (Figure 6) 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 7) 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 is 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 8) 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 7. Expression Editor (Date Range, period)

Figure 8. Expression 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 the set as group of radio buttons control 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. Expression Editor (Variables tab)

Where: input is the series [1,2,3,4,5]

Note that, 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, the Expression Editor can be used in 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 9. shows a fragment of the river network. Downstream demands are represented by a supply point and water user node. In the Expression Editor for the maximum order constraint node, you specify the internal orders and unregulated river gain of the model in the Variables tab of the Expression Editor and determine the maximum orders using an expression. Table 14 shows the relevant variables and Table 15 an expression which returns a value of 3,000 ML/day if flows are above 2,000 ML/day but 80 ML/day otherwise.

Table 14. Expression Editor (variables, expression inputs)

Table 15. Example expression

Piecewise Linear tab

You use the Piecewise Linear tab to create piecewise linear relations for use in expressions. You can find more information about such relations at About piecewise linear editors.

To define a new piecewise linear relation:

• Click on a new row in the table (Figure 10) and enter a name for the relation by editing the contents of the Name column.
• You use the Source Label and Result Label fields to declare names to correspond with the X and Y axis of the piecewise linear editor. The names are only for information and serve no other purpose.
• Set the units appropriate to the X and Y axes using the Source Unit and Result Unit fields. Note that using different units does not imply automatic conversion. If you wish to convert units, you must do this as part of the expression.
• Click the Edit link. This opens the Interpolated Function window (Figure 11). Use this window to enter the piecewise linear relation and then click OK. Refer to About piecewise linear editors for more information on constructing relations.
  
  

Figure 10. Expression Editor (Piecewise Linear tab)

Figure 11. Expression Editor (Piecewise Linear, Interpolated Function)

Patterns tab

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

Input is:

Name

All expression names must start with a $.

Units

The default units for pattern values are the units defined for the simulation. You can enter data values in different units by right-clicking the column header in the pattern data entry window. To convert the entered data to different units for use in the expressions, choose the new units from the drop-down menu adjacent to the user-defined pattern name.

Type

Select time period for the pattern from the drop-down menu.

Edit

To load pattern data, click on the Edit link. Either manually or via a text file, enter the amount per time period specified, eg. monthly accepts 12 values; weekly accepts 53 values; daily accepts 366 values; 6-hourly (over 1 year) accepts 1464 values; hourly accepts 24 values.

Example - Application of the Patterns tab of Expression Editor using an inflow node as an example

As an example, the Expression Editor is used in the Inflow node to specify the values of monthly inflows using the Patterns tab.

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, you select the Expression Editor and enter the twelve (12) monthly values through the Patterns tab of the Expression Editor. Then, specify this data set in the expression box of the Expression Editor.

From the Patterns tab of the inflow node’s Expression Editor, assign a name to the variable (Table 16 and Figure 14). In this example, $MonthlyInflows is the name given to the monthly time-series pattern for the inflow node.

After entering the variable name of $MonthlyInflows, choose Megalitres per Day (ML/day) from the Units drop-down menu. Next, select Monthly from the Type drop-down menu and click Edit. This will open the $MonthlyInflows window (Figure 14). Enter the monthly stream flows and click OK.

Next, specify the equation (or function) type of relationship and enter this in the expression box of the Expression Editor as shown in Table 16. Then configure and run the scenario. Source evaluates the expression (or function) equation for each time-step and returns a value for each time-step.

Time Series tab

Create a named time series (Figure 15).

Input is:

Name

All expression names must start with a $.

Edit

To load a time-series, click on Edit. Upload the file and select the units. Start and end dates are extracted from the file and listed with the name of the time-series.

Start

Loading a time-series automatically provides the start date, which cannot be edited.

End

Loading a time-series automatically provides the end date, which cannot be edited.

Units

The units for the time-series are selected from a drop-down menu. To convert the time-series to different units for use in the expression, choose the new units from the drop-down menu adjacent to the end date.

Example- Application of the Time Series tab of Expression Editor using a water user node

As an example, the Expression Editor is used in a water user node to specify the summation of two sets of water demands along a river segment.

Example A water user node is situated below two stream flow points along a stretch of river in which the water demands for two water users are known. You can incorporate the two water demands into a single water user node by adding the respective values for each corresponding time-steps.

Use Case A water user node is drawn schematically to represent the combined water demands of two water users along a particular river network. In the water user node Expression Editor, specify the water demands of the two water users using the Time Series tab and determine the combined flow using an equation (or function) type of relationship in the expression box.

Firstly, from the Time Series tab of the inflow node’s Expression Editor, specify the variable name and click Edit to import the time series (Figure 16). The start and end periods are automatically entered into their respective fields when the files are imported. The units will correspond to those in the time series. Table 17 shows the variable names for the water demands. Then, enable a Time series demand model (refer to Defining demand models) and choose the Expression Editor as the data input method. Click on the ellipsis button and in the dialog that opens, you can view the time series that was defined in the inflow node.

To check the equation (or function), enter test values and click Parse. For example, use a value of 2 for both $DailyDemand1 and $DailyDemand2. The correct result is 4, which will appear in the Result field.

Figure 17. Expression Editor (Time Series example)

Global Expressions tab

As the name suggests, this tab allows you to use expressions that have defined, globally in Source. This includes the use of expressions within other expressions, breaking largeer expressions into smaller ones, or using them in multiple Expressions Editors.

Create named expressions that are visible from all instances of the Expression Editor (Figure 18).

Input is:

Name

All expression names must start with a $.

Expression

Enter the global expression using the Expression Editor.

Example - Application of the Global Expressions tab of the Expression Editor using a minimum flow requirement node

As an example, the Expression Editor is used with a minimum flow requirement node to determine the value of the minimum flow for each time-step based on a given set of flow requirements.

Example: There are two storages in series on a river segment. A minimum flow requirement node is used to generate orders from the upstream storage so that the downstream storage can meet the orders from further down the valley. It is assumed that the average order from the previous week (last 7 days set) is a good approximation of the water that will be ordered from the lower dam when the water from the upstream storage arrives. In addition there is a flow constraint between the two storages that limits the flow in the channel to a maximum of 4000 ML/day.

Use Case: The minimum flow requirement node sits on the river channel between two storages (Figure 16). The upstream dam is selected as the storage that orders generated by the minimum flow node will be sent to. In the minimum flow requirement Expression Editor, specify an internal model data set (orders) in the Variables tab of the Expression Editor and then calculate the preliminary minimum flow requirements using the Global tab of the Expression Editor. Finally enter an equation (or function) type of relationship into the expression box of the Expression Editor. When the model is configured and run, it calculates the equation (or function).

From the Variables tab of the minimum flow requirement node’s Expression Editor, specify the variable name for developing an expression equation (or function) to determine the time periods in which flows meet the criteria. Next, select the Global tab to calculate the preliminary minimum flow requirement by entering a variable name (for example, $MinimumFlow) and then the expression type relationship. For example, average($OrderWeek) Table 20 and Figure 18 provides an example.

Table 21. Global Expression (example expression)

Next, specify the final expression (or function) to set the minimum flow requirement after consideration of the flow constraint of 4000 ML per day and enter this in the expression box of the Expression Editor (Figure 18).

Next, define the expression average($OrderWeek), as shown in Figure 18. Enter the arithmetic expression (Figure 19). Then, configure and run the scenario. The model evaluates the expression equation for each time-step and returns a value for each time-step.

Figure 19. Expression Editor (Variables, $OrderWeek)

Custom Functions tab

Allows you to create your own expression and then import it for use in the Expression Editor. Refer to the How to write a Source plugin document. The Parameter count column refers to the number of arguments used in the function.

Figure 20. Expression Editor (Custom Functions Tab)

Time of Evaluation tab

Expressions are evaluated at the start of each time-step. Providing a choice of:

• start of the ordering phase;
• end of the ordering phase;
• start of the flow distribution phase; or
• end of the flow distribution phase.

Figure 21. Time of Evaluation

Figure 22. Expression Editor (Time of Evaluation tab)

Metaparameter Explorer

The Metaparameter Explorer allows you to calibrate a variable using an expression, where there is no Expression Editor 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 Expression Editor.

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

Figure 23. Calibration Wizard (Metaparameter Explorer)

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

Figure 24. Expression List Viewer (Metaparameter Explorer)