The Expression Editor (Figure 5762) 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 expression editor is used in places where you might otherwise employ a time series or a piecewise linear relationship.

 Image Added

Expression calculation

The Expression Editor 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 Expression Editor 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. The Expression Editor always Figure 63 describes the units used for the Expression Editor.

Image Added

Note 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 5762, 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 The expression editor distinguishes between two classes of variablevariables:

• Played variables. - These are user-supplied variables which you provide 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.
• Image RemovedNon-played variables. These are also - Also known as model variables, in 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 links in the Variables tab of the Expression Editorexpression 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 ;
• All variables used in expressions are must be defined.
• The Expression Editor will not allow circular references.
• An expression that is blank ;
• 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 3168. 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 They can be entered by hand manually or by using the pull down menu at the top of the Expression Editor (Figure 5762). The available functions are summarised in Table 3976, Table 4077, Table 4178 and Table 4279. Some examples of function use are shown in Table 3269.

Testing expressions

You can test expressions using the Parse button. This opens the Parse Results window (Figure 5864) 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 can be used in constructing expressions, after which you can rename it or edit its parameters using the controls in the various columns of the sub-tab.respective controls. 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.

Image Removed

, shown in Figure 65.

Image Added

Viewing expressions

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

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 6067) 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 3370 contains some examples of typical variable declarations.

Image Modified

Date ranges

During All events occuring during a time-step , the moment at which any given are independent, such as when an expression is evaluated, and the moment at which each or when the 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 . You can choose the times in which to carry out certain actions. Table 81 and Table 82 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 using one of the options from the Date range type popup menu (Figure 6168).

Image Added

Custom date ranges fall into three categories:

• The Date Range Calendar option (Figure 6168) enables allows 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 ignores 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 6269) allows you to specify the date range in terms of time a period of time that is relative to the current time-step. The size of a 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 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 6370) 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 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.

Image Removed

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

Image Removed

Image Removed

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 6471 shows a fragment of the river network. Downstream demands are represented by a Supply Point and Water User supply point and water user node. In the Expression Editor for the Maximum Order Constraint 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 3370 shows the relevant variables and Table 3572 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.

Image Removed

To define a new piecewise linear relation:

• Click on a new row in the table (eg Figure 6572) 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 6673). Use this window to enter the piecewise linear relation and then click OK. Refer to About piecewise linear editors for more information about on constructing relations.

Example

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

Patterns tab

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

Image Added

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 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 Editornode’s feature editor, you select the Expression Editor to access the Time Series tab into which data can be entered. You and enter the twelve (12) monthly values through the Patterns tab of the Expression Editor and then . Then, specify this data set in the expression box of the Expression Editor.

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

Image Removed

After entering the variable name of $MonthlyInflows, select "Megalitres per Day (choose Megalitres per Day (ML/day)" from the Units drop-down menu. Next, select "Monthly" from the Type drop-down menu . Then and click "Edit". This will open the $MonthlyInflows window (Figure 6875). 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, 84. Then 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.

Image Removed

Time Series tab

Create a named time series (FIGUREFigure 76).

Image Modified

Input is:

Name

All expression names must start with a $.

Edit

To load a time-series, click on the edit link. Then upload 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 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 water user node to specify the summation of two sets of water demands along a particular river segment.

Example A Water User 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 water user node by adding the respective values for each corresponding time-steps.

Use Case A Water User 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 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.

Image Removed

From the Firstly, from the Time Series tab of the Inflow inflow node’s Expression Editor, specify the Variable Name of variable name and click Edit to import 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 Figure 78). The start and end periods will automatically fill in are automatically entered into their respective fields 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 those in the time series and no units are specified prior to importing the files.

. Table 85 shpws 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.

Image Modified

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:

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

Image Added

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 constraint 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 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 minimum flow requirement node sits on the river channel between two storages (Figure 7278). 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 it calculates the equation (or function) in the expression box of the Expression Editor.

Image Removed

From the Variables tab of the Minimum Flow Requirement minimum flow requirement node’s Expression Editor, specify the Variable Name (preceded by a $ sign) variable name 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 variable name preceded by the $ sign (for example, $MinimumFlow) and then the expression (or function) type relationship (for . For example, average($OrderWeek) ) ( Table 5189 and Figure 73)79 provides an example.

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

Image Removed

Image Removed

Image Removed

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.

Image Removed

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:

, as shown in Figure 79. Enter the arithmetic expression (Figure 80). Then, configure and run the scenario. The model evaluates the expression equation for each time-step and returns a value for each time-step.

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.

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.

Image Removed

• end of the flow distribution phase.

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.

Warning The backwards compatability of Source is not guaranteed when you use the Metaparameter Explorer. Additionally, if you encounter problems, or if you would like assistance, please call 1300-5-WATER (1300-592-837)

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

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

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