When you set up a function or modelled variable, you can choose which simulation phase to evaluate it in. It is essential that the correct time of evaluation(s) is chosen to ensure that:
- Correct information is used in the function; and
- It is evaluated on time, so it can be used in the selected location.
Types of Time of Evaluations
A total of ten Time of Evaluation phases are available in Source:
- Run Initialisation
- Start of Run
- Start of TimeStep
- Resource Assessment Entry - the function will be evaluated just before the "RAS Pre Entry" is called.
- Resource Assessment Triggers - the function will be evaluated after "RAS Pre Entry" but before "RAS Pre Main". This option allows RAS's to refer to the outcome of Trigger changes in linked Resource Assessment Systems.
- Environmental Flow Prioritisation
- Ordering phase
- Flow phase
- Post flow phase
- End of TimeStep
It is important to understand that each phase has several sub phases, and functions are generally evaluated at the start of the phase, before other phase calculations eg. from simulation phases we can see that the 'Flow phase' is actually
- Evaluate functions and modelled variables - where Time of Evaluation equals Flow Phase and where the function is not used at a network element.
- For each Network Element:
- Evaluate functions and modelled variables - where Time of Evaluation equals Flow Phase, and where the function is used at this network element
- Water Ownership - pre-timestep calculations
- Off Allocation: Generate additional release requests
- The wetland cluster that the element belongs to is solved for this time-step.
- Execute element flow phase calculations
- Water Ownership - post-timestep calculations, and colouring of water
- Calculate Constraint Factors for element
- Constituent modeling is executed.
Ordering/Flow Phase Time of Evaluation
Each function can be used in one or more model inputs. As the ordering phase moves up the network, or as the flow phase moves down the network, the function or modelled variable will be evaluated before each element it is used at. For example, if a function is used at two inflows, and the Order Phase has been selected as the time of evaluation, then the function will be evaluated twice in the order phase - once before each inflow where it is used. If the function or modelled variable is used at an input which is not a network element, then it will be evaluated once before the phase begins.
Choosing the Time of Evaluation(s)
A lot of the power (and confusion) when setting up a function is based around when to choose to evaluate a function or modelled variable. One important note here is that there will most likely be multiple solutions which will work. To understand where each of the choices fits in within the larger scheme of the model phases, refer to Simulation phases details.
Functions Time of Evaluation (T.o.E)
The key to choosing the time of evaluation for a function is to consider its usage. For example, if a function is used in a Resource Assessment system, then it is ideally evaluated in one of the Resource Assessment phases. On the other hand, if the function is used to drive the demand on a time series demand model, then you would want to choose the ordering phase to evaluate the function. In cases where you are using the function at multiple inputs, you may want to evaluate the function at multiple points.
Modelled Variable Time of Evaluation
Modelled variables are designed to read data from the model, which is then used as part of an equation in a function. When used in a function, they can add an extra layer of complexity considering the function's time of evaluation. You must consider the time of evaluation set for the function, the time of evaluation set for the modelled variable, execution order of model elements and have an understanding of the simulation phase the recorder the modelled variable is pointing to is calculated. Time of Evaluation can be set to Use Function T.o.E, or Specify T.o.E.. When using Specify T.o.E, the modelled variable time of evaluation specified pertains to the simulation phase of the model element for the recorder to which it is pointing.
It is also important to note that as for functions, evaluation of modelled variables occurs before everything else in a simulation phase. If the modelled variable is pointing to downstream flow for instance, and is Specify T.O.E is set to flow phase, it will be calculated before the downstream flow value is calculated for the time step, and will therefore return a value for the previous time step. If you wished to obtain the downstream flow value for the current time step, the specified time of evaluation for the modelled variable would need to occur after the other flow phase calculations have occured (post flow phase or later).
If the modelled variable was used in a function, and the function T.o.E was set earlier than that of the modelled variable, and the modelled variable had a T.o.E before the recorder was calculated (as above), this could then mean the modelled variable value used by the function could be from up to two time steps ago.
Effect of Execution Order
If a function is assigned to a model element, and calls a modelled variable that points to a recorder from a different model element, this can also have have an impact on which modelled variable value the function uses to evaluate during a time step due to execution order. If not properly understood, it could also mean that the function uses a value from anything up to two timesteps ago due to execution order. Simulation phases in most case work sequentially through model elements eg. the flow phase of Inflow 1 will be calculated before the flow phase of Inflow 2. Head nodes (nodes at the top of the system) are executed in an alphabetical order unless execution order rules specify otherwise. Using the preceding example, we already know that the modelled variable set to flow phase will always have a downstream flow value from the previous time step. If the function had the same simulation phase set at the modelled variable, but was assigned to a model element that was executed before the model element of the recorder, the modelled variable value would not have been calculated yet and would have a value two steps behind.
At the start of a run, all the modelled variables are set to the initial value specified (0 by default). If the function using the modelled variable has a time of evaluation before that of the modelled variable, the modelled variable will not have obtained it's first value in the first time step, and the set intial value will be used.
Initial values in arrays - If a modelled variable is set to use a date range which results in an array (such as "Previous 30 Days"), the array is populated with this initial value. If a modelled variable is used by a function before it has been evaluated for the first time, or before it has been evaluated to fill in the associated date range array, then it will return the initial value (or an array of initial values).
The order in which functions will be evaluated for each time of evaluation may be viewed in the Function Execution Order dialog. Choose Tools » Function Execution Order to open this dialog (Figure 1).
Figure 1. Function execution order
Example - Does the function ever use a modelled variable's initial value?
The inflow of two nodes are related to each other using a modelled variable and a function. Node 1 is upstream from Node 2.
Node 2 inflow = $Function1 = $ModelledVariable1*1.2, T.o.E Start of TimeStep
$ModelledVariable1 » Downstream Flow of Node 1, T.o.E Start of TimeStep, Initial value 10 ML/d
In this case, $ModelledVariable1 will never use its initial value because it has already been evaluated before the function is evaluated. Although the function and modelled variable are set to evaluate in the same phase, the modelled variable points to node 1, and is therefore first to be evaluated first due to execution order. For its first time step, it will be 0, as the downstream flow of a node is 0 at the start of the first time step, but this is still a valid value. After this, $ModelledVariable1 will be the previous time step value of the downstream flow of the node when it is called by the function.