The Expression Editor (Figure 57) 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. Expression Editor does not check units either within an expression or as a returned value. Neither does Expression Editor 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.

The Expression Editor always returns a single value at each time step.

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 57, 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. To put this another way, a value defined in the Variables tab can only be seen and used in the Expression Editor in which it is defined whereas a value defined in any other tab can be seen and used from any other location within the same scenario in which it is possible to open an Expression Editor.

Played vs non-played variables

Expression Editor distinguishes between two classes of variable:

• Played variables. These are user-supplied variables which you provide 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 variables. These are also known as model variables, which refers to the fact that the variables are produced by the operation of the models which execute during a run. You gain access to model variables by defining linkages 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.
• The Expression Editor checks that all variables used in expressions are defined.
• The Expression Editor will not allow circular references.
• An expression that is blank 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 31. Where two operators have the same level of precedence, the operations are performed left-to-right.

Functions

Functions are predefined formulae that perform calculations which usually depend on the arguments you supply as parameters. Functions can be entered by hand or by using the pull down menu at the top of the Expression Editor (Figure 57). The available functions are summarised in Table 39, Table 40, Table 41 and Table 42. Some examples of function use are shown in Table 32.

Testing expressions

You can test expressions using the Parse button. This opens the Parse Results window (Figure 58) 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 are then utilised in the construction of expressions. After defining a term you can both rename the term and edit its parameters using the controls in the various columns of the sub-tab.

Deleting a term is a two-step process and involves clicking on the table cell to the left of the name of the term. First, click on that cell. This causes the whole row to become selected. Second, right-click in the same place and choose Delete from the contextual menu. The process is shown in Figure 59.

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 60) and enter a name for the variable by editing the contents of the Name column. Remember that all variable names must start with a "$" character.
• 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 (the application) 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.

Table 33 contains some examples of typical variable declarations.

Date ranges

During a time-step, the moment at which any given expression is evaluated, and the moment at which each model variable on which the expression depends is updated, are all independent events. Without a detailed understanding of the order of events during a time-step, it may not be possible to be certain about the exact state of any model variable. For this reason, Expression Editor allows to you choose between a number of options according to your need. Table 44 and Table 45 define the options which are available by default.

If none of the default options is appropriate, you can define your own date ranges. To define a custom date range, choose one of the options from the Date range type popup menu (Figure 61).

Custom date ranges fall into three categories:

• The Date Range Calendar option (Figure 61) enables you to define a precise start and end date to during which the model variable is considered to be valid. Enabling the Is Recurring checkbox causes the years to be ignored. In other words, the period between [start day/start month] and [end day/end month] is considered to be valid for every year during the model execution.
• The Date Range Period option (Figure 62) allows you to specify the date range in terms of time a period relative to the current time step. The size of 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 means 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 63) 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 means 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.

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 34 summarises what is returned if the range represents more than one value.

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 64 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 33 shows the relevant variables and Table 35 an expression which returns a value of 3,000 ML/day if flows are above 2,000 ML/day but 80 ML/day otherwise.

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 (eg Figure 65) and enter a name for the relation by editing the contents of the Name column. Remember that this is a variable and that all variable names must start with a "$".
• 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 66). Use this window to enter the piecewise linear relation and then click OK. Refer to About piecewise linear editors for more information about constructing relations.

Example

As an example, xxxxxx.

Patterns tab

You use patterns (Figure 67) 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 (eg monthly, weekly, daily, 6-hourly, hourly).

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 time step model simulation.

Use Case The inflow node is connected to the river network. In the inflow node Feature Editor, you select the Expression Editor to access the Time Series tab into which data can be entered. You enter the twelve (12) monthly values through the Patterns tab of the Expression Editor and 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 46 & Figure 67). In this example, $MonthlyInflows is given the name of the monthly time-series pattern for the inflow node.

After entering the variable name of $MonthlyInflows, select "Megalitres per Day (ML/day)" from the Units drop-down menu. Next, select "Monthly" from the Type drop-down menu. Then click "Edit". This will open the $MonthlyInflows window (Figure 68). 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 47 and Figure 69. After entering the expressions, configure and run the scenario. Source then 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).

Input is:

Name

All expression names must start with a $.

Edit

To load a time series, click on the edit link. Then 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 time series are selected from a drop-down menu within the "edit" window. 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 data series 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 particular 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 of the Expression Editor and determine the combined flow using an equation (or function) type of relationship in the expression box.

Select Time Series Demand from the list of available models and select Expression Editor as the source of data to be loaded (FIGURE) Then click on the ellipse button to open the Expression Editor interface.

From the Time Series tab of the Inflow node’s Expression Editor, specify the Variable Name of the time series (remember that variable names are preceded by a $ sign) and then clicks "Edit" to import the time series from the file location.

Table 48 and FIGURE display the variable names for two different daily water demands. The start and end periods will automatically fill in when the files are imported and correspond to the start and end period of the time series. The units will correspond to the units of the time series and no units are specified prior to importing the files.

To check the equation (or function), click Parse. The Parse Results window opens (FIGURE). Manually 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.

Global Expressions tab

The Global Expressions tab is a special case. When editing a global expression, a second copy of Expression Editor is opened. The second Expression Editor window is usually placed directly on top of the first window and this behaviour can sometimes be confusing (eg clicking OK closes the second window but the first window is still present and is usually not greatly different in appearance). For this reason, we recommend moving the second window slightly whenever you edit a global expression.

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

Input is:

Name

All expression names must start with a $.

Expression

Enter the global expression using the Expression Editor.

EXAMPLE - Application of the Global tab of the Expression Editor using a Minimum Flow Constraint node

As an example, the Expression Editor is used with a Minimum Flow constraint 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 72). 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, the model calculates the equation (or function) in the expression box of the Expression Editor.

From the Variables tab of the Minimum Flow Requirement node’s Expression Editor, specify the Variable Name (preceded by a $ sign) for developing an expression equation (or function) similar to Microsoft Excel syntax to determine the time periods in which flows meet the criteria of the example. Next, select the Global tab of the Expression Editor to calculate the preliminary minimum flow requirement by entering a Variable name preceded by the $ sign (for example, $MinimumFlow) and then the expression (or function) type relationship (for example, average($OrderWeek) ) (Table 51 and Figure 73).

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

Next, define the expression average($OrderWeek). Click on the ellipse button to the right of the expression average($OrderWeek) (Figure 73). Notice the words "Expression Editor ($MinimumFlow)" at the top of the schematic in Figure 76. This denotes the expression associated with the variable $MinimumFlow that had been previously defined in the Global tab of the Expression Editor. It is important to remember the difference between this and the Expression Editor shown in Figure 73.

Enter the arithmetic expression in the Expression Editor box as shown in Figure 76. After entering the expressions, the configure and run the model scenario. The model then evaluates the expression equation for each time step and returns a value for each time step.

Custom Functions tab

This functionality is yet to be documented. If you would like assistance, please call 1300-5-WATER (1300-592-837).

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.

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

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

Where: units are the units specified in Expression Editor (eg "ML/day")
month is the full name of the month in order from "January" to "December"
value is the observation to apply for the corresponding month

Where: units are the units specified in Expression Editor (eg "ML/day")
week is the week ordinal from 1 through 53
value is the observation to apply for the corresponding week

Where: units are the units specified in Expression Editor (eg "ML/day")
dd is the day of the month (1...the number of days in the month, assuming 29 for February)
mm is the 3-character abbreviated month name (eg "Jan")
value is the observation to apply for the corresponding day

Where: units are the units specified in Expression Editor (eg "ML/day")
ddd is the Julian day of the year (1...366)
hh is a two digit hour, either "00", "06", "12" or "18"
value is the observation to apply for the corresponding six-hour period

Where: units are the units specified in Expression Editor (eg "ML/day")
hh is a one- or two-digit hour from "0" ... "23"
value is the observation to apply for the corresponding hour