Functions Time of Evaluation

Introduction

When you set up a Function or a Modelled Variable, you get to choose which simulation phase(s) you want to evaluate at.  In order for the correct information to be used in the function, and for the function to be evaluated in time to be used in the location selected, its important to choose the correct time of evaluation(s).  

 
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.

Available Time of Evaluations

The table below outlines the different evaluation times available in Source.

Resource Assessment Time of Evaluation

If you choose Resource Assessment, the Function or Modelled Variable  will be evaluated before each Resource Assessment System is processed.  If there are multiple Resource Assessment systems, then there will be multiple evaluations.

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.  As an example, if you have used a function at 2 inflows, and have selected Order Phase 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.

Which Time of Evaluation(s) to choose

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

Functions Time of Evaluation

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 the Resource Assessment phase..  Likewise, if you are using the function 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, to be used as part of an equation in a function.  Which Time of Evaluation you choose will depend on when the data you need will be available.  For example, if your modelled variable is pointing to the downstream flow of a node, then that data will only be available after the flow phase, so using the Post Flow Phase Time of Evaluation would most likely to be correct choice.  End of Time Step would also work in this case.  

Initial value

Its important to understand when the initial value of a modelled variable is used.  At the start of a run, all the modelled variable values are set to their initial value.  If a modelled variable is set to use a date range which results in an array - eg. "Previous 30 Days" - then 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 enough to fill in the associated date range array, then it will return the initial value (or an array of initial values).  If we do a couple of examples:

Example 1:

$Function1 = $ModelledVariable1

Time of Evaluations:

$Function1 = Start of Time Step

$ModelledVariable1 = End of TimeStep

In this case, when $Function1 evaluates it will use the initial value of $ModelledVariable1 for the first time step, after this it will use whatever $ModelledVariable1 evaluates to at the end of the previous timestep.

Example 2:

$Function1 = $ModelledVariable1

Time of Evaluations:

$Function1 = Start of Time Step

$ModelledVariable1 = Start of Time Step

$ModelledVariable1 points to the Downstream Flow of a node.

In this case, $ModelledVariable1 will never use its initial value because its already been evaluated before the function is evaluated.  For its first time step, it most likely be 0 though, as the downstream flow of a node is 0 at the start of the first time step.  After this, $ModelledVariable1 will be yesterdays value of the downstream flow of the node.