Functions Time of Evaluation

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

1. Evaluate functions and modelled variables - where Time of Evaluation equals Flow Phase and where the function is not used at a network element.
   
2. For each Network Element:
   1. Evaluate functions and modelled variables - where Time of Evaluation equals Flow Phase, and where the function is used at this network element
   2. Water Ownership - pre-timestep calculations
   3. Off Allocation: Generate additional release requests
   4. The wetland cluster that the element belongs to is solved for this time-step.
   5. Execute element flow phase calculations
   6. Water Ownership - post-timestep calculations, and colouring of water
   7. Calculate Constraint Factors for element
   8. 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, modelled variable, or context 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. All functions, modelled and context variables must have at least one ToE phase set. An assurance rule has been added to validate this.

Function 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. ToE phases specified for constant functions are ignored.

Modelled Variable and Context Variable Time of Evaluation (T.o.E.)

Timestep variables (modelled and context variables) are designed to read data from models at different points during a timestep, which are 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 variable, the date range for the variable, execution order of model elements and have an understanding of the simulation phase the recorder the 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 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 timestep variables occurs before everything else in a simulation phase. If the 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 occurred (post flow phase or later).

If the variable was used in a function, and the function T.o.E. was set earlier than that of the variable, and the variable had a T.o.E before the recorder was calculated (as above), this could then mean the variable value used by the function could be from up to two time steps ago. The date range used by the variable must also be considered together with the T.o.E. for the variable and functions which use the variable.

Effect of Execution Order

If a function is assigned to a model element, and uses 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 cases work sequentially through model elements e.g. 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.    

Initial value

At the start of a run, all functions and timestep variables (modelled and context variables) are set to the initial value specified (0 by default).

If a function using another function variable has a time of evaluation (ToE) before the ToE of the referenced function, the function will not have obtained it's first value in the first time step, and the specified initial value will be used. Constant functions do not use specified initial values.

For timestep variables the specified date range must additionally be taken into account. If a function using a timestep variable has a ToE before the ToE of the referenced variable, and the variable date range includes the current timestep, the variable's current value will have been changed to NaN at the beginning of the first timestep. Only previous values of the variable (such as the previous timestep) will return the specified initial value. An appropriate data range should be specified if the variable is going to be accessed in a ToE prior to the variable's ToE. For timestep variables which use a multi-value set date range (such as "Previous 30 Days"), the set is populated with the initial value at the beginning of the run. Accessing entries of the set which haven't been evaluated yet will return the initial value. See date ranges for further details.

Execution Order

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

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

Case 1

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, Date range: Current timestep

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

Case 2

Node 2 inflow = $Function1 = $ModelledVariable1*1.2, T.o.E: Post Flow Phase

$ModelledVariable1 » Downstream Flow of Node 1, T.o.E: Post Flow Phase, Initial value: 10 ML/d, Date range: Previous timestep

In this case, $Function1 will use the initial value of $ModelledVariable1 because the date range specifies to use the previous timestep's value. On the first timestep there is no previous timestep so the initial value is returned. After this, $ModelledVariable1 will be the previous time step value of the downstream flow of the node when it is called by the function.

Case 3

Node 2 inflow = $Function1 = $ModelledVariable1*1.2, T.o.E: Start of TimeStep

$ModelledVariable1 » Downstream Flow of Node 1, T.o.E: Post Flow Phase, Initial value: 10 ML/d, Date range: Current timestep

In this case the modelled variable would return NaN and there would be an error on the first timestep when the function was evaluated. Variables using the current timestep date range may only be used after the evaluation of the variable in the same timestep.