Built-in functions are predefined formulae that perform calculations that usually depend on the arguments you supply as parameters. They can be entered manually or by using the pull down menu at the top of the Function Editor. The available operators and functions are summarised in Tables 1-7. Examples of function use are shown in Table 8. Available built-in variables are defined in Table 9. Default date ranges are summarised in Tables 10 and 11.

Note: Any characters not listed on this page are considered invalid, and will result in an error at parse time and run time.

Operators

Table 1. Function Editor (Arithmetic operators)

Operator	Meaning	Example	Result
+	addition	10 + 5	15
-	subtraction; negation	10 - 5 = 5 or 10 + (-5)	5
*	multiplication	10 * 5	50
/	division	10 / 5	2
** or ^	power/exponentiation	10**5 or 10^5	100000
( )	influence order of evaluation	5 * (10 + 5)	75

Table 2. Function Editor (Comparison operators)

Operator	Meaning	Example	Result	Equivalent to
>	greater than	10 > 5	true
<	less than	10 < 5	false
>=	greater than or equal	10 >= 5	true
<=	less than or equal	10 <= 5	false
=	equal	10 = 5	false
<>	not equal	10 <> 5	true
~>	greater than with tolerance	1 ~> 0.999999999	false	ABS(1 - 0.999999999) <= 1e-8 AND 1 > 0.999999999
~<	less than with tolerance	1 ~< 0.999999999	false	ABS(1 - 0.999999999) <= 1e-8 AND 1 < 0.999999999
~>=	greater than or equal with tolerance	1 ~>= 0.99999999	true	ABS(1 - 0.999999999) <= 1e-8 OR 1 > 0.999999999
~<=	less than or equal with tolerance	1 ~<= 0.99999999	true	ABS(1 - 0.999999999) <= 1e-8 OR 1 < 0.999999999
~=	equal with tolerance	1 ~= 0.99999999	true	ABS(1 - 0.999999999) <= 1e-8

Note - the tolerance set for the ~ variants is equal to 1e-8 (the same for many comparisons used within Source).

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

This custom function returns the % probability of exceedance of a given data value based on a set of data values. The data can be any time series, data source or modelled variable accepted in Source. It uses a function that replicates the behaviour of the Microsoft Excel PERCENTRANK.INC function to calculate the percentile rank of a flow value within the data input and then calculates the percentage of values in the dataset that are greater than the specified flow value using the formula (1 - PercentRankInc(dataArray, flow)) * 100.

Two arguments are required: an array of values, a single given data value (in the units of the input array of values)

If the given data value lies between two values in the data array, linear interpolation is used to identify the associated probability of exceedance.

GetDataTimeSteps or GetDataPeriod are used to specify the length of the input data array. This can be a subset of the full data period.

Example usages where the function returns the percentage of flow values in the data source which are equal or above 1000 (the units of the data source and input threshold value must match):

ProbabilityOfExceedanceFlow(GetDataTimeSteps("Flow_res_csv.Runoff", 2000, 1, 1, 365), 1000), where the data source period is specified as 365 time steps starting at 01/01/2000
ProbabilityOfExceedanceFlow(GetDataPeriod("Flow_res_csv.Runoff", 2000, 1, 1, 2020, 12, 31), 1000), where the data source period is specified by entering specific start and end dates
ProbabilityOfExceedanceFlow($Previous30DaysFlow,1000), where a function referencing a modelled variable with a specified data range is used to provide an array of values

ProbabilityOfExceedancePercentage

This custom function is designed to return a specific data value corresponding to a required percentage probability of exceedance. It uses a function that replicates the behaviour of the Microsoft Excel PERCENTILE.INC function to determine the data value associated with the specified % probability of exceedance.

Two arguments are required: Array of values, percentage

Similar to ProbabilityOfExceedanceFlow custom function, if the given percentage references a value between two values in the data array, linear interpolation is used to identify the associated value.

And GetDataTimeSteps or GetDataPeriod are used to specify the length of the input data array. This can be a subset of the full data period.

Example usage where the function returns a data value for which 20% of values in the "Flow_res_csv.Runoff" are equal or above:

ProbabilityOfExceedancePercentage(GetDataTimeSteps("Flow_res_csv.Runoff", 2000, 1, 1, 365), 20), where the data source period is specified as 365 time steps starting at 01/01/2000
ProbabilityOfExceedancePercentage(GetDataPeriod("Flow_res_csv.Runoff", 2000, 1, 1, 2020, 12, 31), 20), where the data source period is specified by entering specific start and end dates
ProbabilityOfExceedanceFlow($Previous30DaysFlow, 20), where a function referencing a modelled variable with a specified data range is used to provide an array of values

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.

Browser not supported