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.

## 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 | PI() |

/* Comment */ | /* begins a comment and */ ends a comment. Comments can go over multiple lines. | 5 + 4 /* Some sort of 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 |

## Default date ranges

Source provides a set of default date ranges that allow you to specify values to use for modelled variables. Tables 10-11 list the default available options. You can also create custom date ranges.

###### Table 10. Function Editor (Date range instances)

Date Range | Meaning |
---|---|

Current Time Step | The most recently updated value. |

Current Iteration | Only applicable to 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. |

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

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

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

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

Last 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 |
---|---|---|

Last Hundred Time Steps | The set of values from the model for the previous 100 iterations. | Lookup($var,35) |

Last Seven Days | For a daily or monthly 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 average daily values for each of the previous seven days. | Average($var) |

Previous 30 Days | For a daily or monthly model, this is the set of the values from the last 30 time steps. For a sub-daily model, it is the set of the average daily values for each of the previous 30 days. | Average($var) |

Last 365 Days | For a daily or monthly model, this is the set of the values from the last 365 time steps. For a sub-daily model, it is the set of the average daily values for each of the previous 365 days. | Average($var) |