Available functions, operators, variables and date ranges
Functions
Table 3. Function Editor (logical operators)
Operator | Meaning | Example | Result |
---|---|---|---|
OR | or | false OR true | true |
AND | and | false AND true | false |
NOT | not | NOT false | true |
Table 4. Function Editor (General mathematical functions)
Function | Meaning | Example use |
---|---|---|
EXP | Returns e raised to the power of a given number | EXP(number) |
LOG10 | Returns the base-10 logarithm of a number | LOG10(number) |
LN | Returns the natural logarithm of a number | LN(number) |
ABS | Returns the absolute value of a number | ABS(number) |
SQRT | Returns a positive square root | SQRT(number) |
MOD | Returns the remainder from division | MOD(number,divisor) |
ROUND | Rounds a number to the nearest integer | ROUND(number) |
INT | Rounds the number down to the nearest integer | INT(number) |
Table 5. Function Editor (Statistical functions)
Function | Meaning | Example use |
---|---|---|
AVERAGE | Returns the average of its arguments | AVERAGE(variable_name) |
COUNT | Counts how many numbers are in the list of arguments | COUNT(variable_name) |
COUNTIF | Counts how many numbers in the list of arguments satisfy the expression | COUNTIF(variable_name,expression) |
MAX | Returns the maximum value in a list of arguments | MAX(variable_name) or MAX(number,number) |
MEDIAN | Returns the median of its arguments | MEDIAN(variable_name) |
MIN | Returns the minimum value in a list of arguments | MIN(variable_name) or MIN(number,number) |
STDEV | Estimates standard deviation based on a sample | STDEV(variable_name) |
SUM | Adds all the values of a modelled variable that has a date range | SUM(variable_name) |
Table 6. Function Editor (Trigonometric functions)
Function | Meaning | Example use |
---|---|---|
ARCCOS | Returns the inverse cosine of a number | ARCCOS(number) |
ARCSIN | Returns the inverse sine of a number | ARCSIN(number) |
ARCTAN | Returns the inverse tangent of a number | ARCTAN(number) |
COS | Returns the cosine of a number | COS(number) |
SIN | Returns the sine of a number | SIN(number) |
TAN | Returns the tangent of a number | TAN(number) |
Table 7. Function Editor (Miscellaneous functions)
Function | Meaning | Example use |
---|---|---|
IF | Specifies a logical test to perform | IF(logical_test,value_if_true,value_if_false) |
LOOKUP | Looks up the Y-value corresponding to an X-value via a piecewise linear variable or looks up the return value that correspond to X and Y values via a bilinear variable. Both lookups use linear interpolation. | LOOKUP(variable_name, number) LOOKUP(variable_name, x, y) |
N1 | Returns 1 if the number is less than zero, 0 otherwise | N1(number) |
P1 | Returns 1 if the number is greater than zero, 0 otherwise | P1(number) |
PI | Returns the mathematical constant π to 14 decimal places | PI() |
/* Comment */ | /* begins a comment and */ ends a comment. Comments can go over multiple lines. | /* Some sort of comment about the function */ 5 + 4 |
// Comment | // begins a single line comment. Can be placed after an expression to make the rest of the line a comment. | 5 + 4 // A comment about the function |
Table 8. Sample expressions using functions
Expression | Result | Expression | Result | Expression | Result |
---|---|---|---|---|---|
Average($var1) | 3 | Median($var1) | 3 | Lookup($var1,13.5) | 2.5 |
Lookup($var1,14) | 3 | Count($var1) | 5 | Max($var1) | 5 |
Min($var1) | 1 | Sum($var1) | 15 | Stdev($var1) | 1.58113883 |
Where: $var1 is the piecewise linear relationship {(12, 1), (13, 2), (14, 3), (15, 4), (16, 5)}
Variables
Table 9. Function Editor (Built-in variables)
Variable | Meaning |
---|---|
$Now.Year | Returns the 4-digit year of the current time-step |
$Now.Month | Returns the month of the current time-step (range: 1...12) |
$Now.Day | Returns the day of the current time-step (range: 1...31) |
$Now.Hour | Returns the hour of the current time-step (range 0...23) |
$Now.DaysInMonth | Returns the number of days in the month for the current time-step (range, 28..31) |
$Now.DayOfYear | Returns the current day in the year for the current time-step (range, 1, 366) |
$Start.Year | Returns the 4-digit year of the simulation start date |
$Start.Month | Returns the month of the start of simulation date(range: 1...12) |
$Start.Day | Returns the day of the simulation start date (range: 1...31) |
$Start.Hour | Returns the hour of the simulation start date (range 0...23) |
$Start.DaysInMonth | Returns the number of days in the month for the simulation start date (range, 28..31) |
$Start.DayOfYear | Returns the current day in the year for the simulation start date(range, 1, 366) |
$End.Year | Returns the 4-digit year of the simulationend date |
$End.Month | Returns the month of the simulation end date (range: 1...12) |
$End.Day | Returns the day of the simulation end date (range: 1...31) |
$End.Hour | Returns the hour of the simulation end date (range 0...23) |
$End.DaysInMonth | Returns the number of days in the month for the simulation end date (range, 28..31) |
$End.DayOfYear | Returns the current day in the year for the simulation end date (range, 1, 366) |
$ActiveInputSet | Returns the simulation input set. Can be used in statements like if($ActiveInputSet = "Wet", 15, 10). It is also possible to reference a child scenario input set, see Referencing scenario input sets in functions. |
Default date ranges
Source provides a set of default date ranges that allow you to specify values to use for modelled and context variables. Tables 10-11 list the default available options. You can also create custom date ranges.
See further details about the use of date ranges and their relation to Time of Evaluation of functions and variables.
Table 10. Function Editor (Date range instances)
Date Range | Meaning |
---|---|
Current Time Step | The most recently updated value. "Current" starts from 0 in Time Step Date Range definition. |
Current Iteration | Only applicable to Ordering with NetLP. The value updated during the last iteration of the solver. |
Current Day | For a sub-daily model, it is the sum of the values for the current day. For a daily model, this is a synonym for Current Time Step. |
Current Month | For a sub-monthly model, it is the sum of the values for the current month. For a monthly model, this is a synonym for Current Time Step. |
Current Calendar Year | For a sub-yearly model, it is the sum of the values for the current calendar year. For a yearly model, this is a synonym for Current Time Step. |
Previous Time Step | The value of the variable at the completion of the previous iteration of the model. |
Previous Day | For a sub-daily model, it is the sum of the values for the previous day. For a daily model, this is a synonym for Last Time Step. |
Previous Month | For a sub-monthly model, this is the sum of the values for the previous month. For a monthly model, this is a synonym for Last Time Step. |
Previous Calendar Year | For a sub-yearly model, it is the sum of the values for the previous calendar year. For a yearly model, this is a synonym for Last Time Step. |
Table 11. Function Editor (Date range sets)
Date Range | Meaning | Example of use |
---|---|---|
Previous Hundred Time Steps (set) | The set of values from the model for the previous 100 time steps. | Lookup($var,35) - finds 35th value |
Previous Seven Days (set) | For a daily model, this is the set of the values from the last seven time steps. For a sub-daily model, this is the set of the sum of the timestep values for each of the previous seven days. | Average($var) - finds the average of the previous seven day totals |
Previous 30 Days (set) | For a daily model, this is the set of the values from the last 30 time steps. For a sub-daily model, this is the set of the sum of the timestep values for each of the previous 30 days. | Sum($var) - finds the sum of the previous 30 days |
Previous 365 Days (set) | For a daily model, this is the set of the values from the last 365 time steps. For a sub-daily model, this is the set of the sum of the timestep values for each of the previous 365 days. | Max($var) - finds the maximum day from the previous 365 days |
Built-in Functions for Data Sources and Probability of Exceedance (PoE)
There are four new built-in Functions for mainly calculating probability of exceedance (PoE). These functions will be useful to calculate PoE of storage inflows, storage spills etc., which in turn will assist in determining storage operating targets, spill assessments etc.
GetDataPeriod
Gets data from a Data Source between the start and end dates. Data is returned as an array.
Example usage:
//Arguments are: Data Source (for files, Name.ColumnName), start year, start month, start day, end year, end month, end day
GetDataPeriod(
"MyDataSource_csv.Column1"
,
2000
,
1
,
1
,
2020
,
12
,
31
)
//Returns an array of values in the units of MyDataSource_csv.Column1.
GetDataTimeSteps
Gets data from a Data Source using a start date and the number of time steps. Data is returned as an array.
Example usage:
//Arguments are: Data Source (For files, name and column name), start year, start month, start day, number of time steps
GetDataTimeSteps(
"MyDataSource_csv.Column1"
,
2000
,
1
,
1
,
365
)
//Returns an array of values in the units of MyDataSource_csv.Column1.
ProbabilityOfExceedanceFlow
Gets the percentage value for the given flow from the probability of exceedance curve. This function is useful to calculate probability of exceedance (PoE) inflows to determine storage operating targets, spill assessments etc.
For example, it calculates probability of exceedance (PoE) flow that is a time series (data source) or a modelled variable such as 95% probability of exceedance (PoE) inflows to a storage.
Example usage:
//Arguments are: Array of values, flow value (in the units of Flow_res_csv.Runoff)
ProbabilityOfExceedanceFlow(GetDataTimeSteps(
"Flow_res_csv.Runoff"
,
2000
,
1
,
1
,
365
),
1000
)
The above function returns the percentage of flow values in the data source period from from 01/01/2000 for 365 days which are equal or above 1000 (the units of the data source and input threshold value must match).
//One can also use a modelled variable to provide the array of values
ProbabilityOfExceedanceFlow($Previous30DaysFlow,
10
)
ProbabilityOfExceedancePercentage
Gets the flow value for the given percentage from the probability of exceedance curve.
Example usage:
//Arguments are: Array of values, percentage
ProbabilityOfExceedancePercentage(GetDataTimeSteps(
"Flow_res_csv.Runoff"
,
2000
,
1
,
1
,
365
),
20
)
The above function returns flow value for which 20% of values in the "Flow_res_csv.Runoff"
are equal or above.
Example model using built-in functions for data sources and probability of exceedance together
The example model as shown in the Figure 1 uses a combination of newly built-in functions 'ProbabilityOfExceedanceFlow' and 'GetDataPeriod' to return the percentage of flow values equal to or above a certain flow.
Figure 1. Example model using built-in function 'ProbabilityOfExceedanceFlow'
For example, a function named '$PoE_Flow' -> ' ProbabilityOfExceedanceFlow(GetDataPeriod("$Variable2", 1990,1,1, 2000,12,31), 600)' is created, where '$Variable2' is a time series variable containing flow data from 1990 to 2000. Once ran, the model returns a percentage value which shows the probability of exceedance of 600 ML in the $Variable2 (in this case 93.25%). In this function, 'GetDataPeriod' is used to get data from 1990 to 2000.It is to be noted that if 'ProbabilityOfExceedanceFlow' is used, the Result Units must be 'percent' and if 'ProbabilityOfExceedancePercentage' is used, the units must be flow units (e.g. megalitre).
Tip for performance enhancement - if you have static inputs as above , its recommended to set the time of evaluation (ToE) to 'Start of Run' to significantly enhance the performance |
---|
One can also use modelled variables as input arguments instead of a static variable (600 in this case) to return varying probability of exceedance (PoE) during the run.
For example, the function, $PoE_Flow -> ProbabilityOfExceedanceFlow(GetDataPeriod("$Variable2", 1990,1,1, 2000,12,31), $Function1) can be used to return the varying PoE over 1990 to 2000. In this case, $Function1>- sum($Variable1), where $Variable1 is a modelled variable with 'Date Range' from April to June and recurring. Therefore, '$PoE_Flow' returns the PoE of sum of flows from April to June every year in the data source $Variable2 from 1990 to 2000 and it will be varying over the simulation period.