Functions Time of Evaluation

Owned by Former user (Deleted)
11 Jun 2014

Introduction 

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 seven Time of Evaluation phases are available in Source:

  1. Start of TimeStep
  2. Resource Assessment
  3. Ordering phase
  4. Flow phase
  5. Post flow phase
  6. End of TimeStep
  7. Post Function Evaluation - Only available for modelled variables.

Resource Assessment

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

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. Additionally, End of TimeStep would also work in this case.  

Initial value

It is 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 (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 enough to fill in the associated date range array, then it will return the initial value (or an array of initial values). The following examples illustrate this principle.

Example 1

$Function1 = $ModelledVariable1

Time of Evaluations:

$Function1 = Start of TimeStep

$ModelledVariable1 = End of TimeStep

In this case, when $Function1 is evaluated it will use the initial value of $ModelledVariable1 for the first time-step. After this, it will use the value that $ModelledVariable1 evaluated to at the end of the previous time-step.

Example 2

$Function1 = $ModelledVariable1

Time of Evaluations:

$Function1 = Start of TimeStep

$ModelledVariable1 = Start of TimeStep

$ModelledVariable1 points to the Downstream Flow of a node.

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