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 way to decide which time of evaluation to choose, is to look at where the function is being used. As an example, if you are using the function in a Resource Assessment System, then ideally the function will be 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 in multiple places, you will have to decide whether its appropriate to evaluate the function in multiple phases.
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.