Formulae and Functions
Jump to navigation
Jump to search
Formulae can be entered as substitutes for specific values into most fields in EMarket to control the derivation of variable values at run time. A formula can contain any combination of:
- Constants
- Variables
- Operators
- Entities and Traits
- Functions
Constants
Constants can be:
- Numbers: Integers or Reals (e.g. 1, 2.5, -3), they can also be entered in scientific notation e.g. '3E+10'.
- Strings: Written inside double quotes e.g. "A Node"
- Dates: Must be enclosed in single quotes e.g '1/3/2004' or '14 April 2005'
Warning: The format for entering dates should compatible with the computer's local date (locality) setting
Variables
Variables can be regarded as user-defined Entity.Traits which can be defined in the Volatility Matrix or the Schedule. Previously defined variables can be used in formulae.
Note: EMarket provides a 'system' variable the user need not define: 'DateTime' which is of type 'Date' and gives the current simulation date as the model runs.
Operators
Operators are all pre-defined in EMarket. Their purpose is to separate a formula into parts that are then combined to give a single value.
The following operators are shown in descending order of precedence.
| Operator | Meaning | Example | Parameter Type | Return Type |
|---|---|---|---|---|
| \ | Integer Division | 3\2 = 1 | Real; Int | Int |
| % | Modulus | 7%5 = 2 | Real; Int | Int |
| / | Division | 3/2 = 1.5 | Real; Int | Real |
| * | Multiplication | 5*4.2 = 21 | Real; Int | Real |
| - | Subtraction | 7-3.2 = 3.8 | Real; Int | Real |
| + | Addition | 3.5+1.5 = 5 | Real; Int | Real |
Functions
Functions provide a powerful mechanism for deriving field and variable data values from input parameters.
A function has the form FunctionName(Parameter1, Parameter2, ...)
An operator is used in a Function in the following form: <Parameter1>Operator<Parameter2>.
EMarket provides the following function types:
- Arithmetic functions
- Logic functions
- Run information functions
- Time functions
- Other functions
Note: Logic operators and functions evaluate to one for a result that is true (for example 6 = 6), and zero for false.
Arithmetic Functions
The following table lists EMarket's Arithmetic functions:
| Function | Purpose | Parameters | Return Type | Example | Result |
|---|---|---|---|---|---|
| Sqrt | Square root of a number | Integer or Real | Real | Sqrt(546.94) | 23.387 |
| Abs | Absolute value of a number | Integer or Real | Real | Abs(-19.1) | 19.1 |
| Int | Integer portion of a number | Integer or Real | Integer | Int(45.786) | 45 |
| Sum | Total value of numbers in an array | Value Array (Exclude Value), Integer or Real | Real | Sum(Node.Price) | |
| Max | Maximum value of numbers in an array, optionally excluding values with value over an exclude value | Value Array (Exclude Value), Integer or Real | Real | Max(Generator.Generation) | |
| Min | Minimum value of numbers in an array | Value Array (Exclude Value), Integer or Real | Real | Min(Generator.Generation) | |
| StdDev | Standard deviation of numbers in an array | Value Array (Exclude Value), Integer or Real | Real | StdDev(Generator.Generation) | |
| Avg | Average value of numbers in an array | Value Array (Exclude Value), Integer or Real | Real | Avg(Generator.Generation) | |
| WgtAvg | Average of numbers in an array, weighted by numbers in another array | Value Array (Weights Array), Integer or Real | Real | WgtAvg(Generator.Generation,Generator.Cost) | |
| Choke | Returns a collared value (i.e. the value of the referenced variable is returned if it falls within the specified range otherwise the relevant minimum or maximum value is returned) | Integer or Real | Real | Choke(500,200,Generator.Generation) |
Logic Functions
The following table lists EMarket3's Logic functions:
| Operator | Purpose | Parameters | Return Value | Example | Result |
|---|---|---|---|---|---|
| = | Whether two numbers are Equal | 2 numbers, Integer or Real | 0 or 1 | 5 = 6 | 0 |
| < | Whether first number is less than the second | 2 numbers, Integer or Real | 0 or 1 | -2 < 7 | 1 |
| > | Whether first number is Greater than the second | 2 numbers, Integer or Real | 0 or 1 | 9 > 7 | 1 |
| AND | Whether two numbers are both non-zero | 2 numbers, Integer or Real | 0 or 1 | And(6=6,4<3) | 0 |
| OR | Whether either of two numbers are non-zero | 2 numbers, Integer or Real | 0 or 1 | OR(3<5, 2>3) | 1 |
| Between | Whether a number is between two limits | Number: lower limit; upper limit, Integer, real or date | 0 or 1 | Between(5.7,9.7) | 0 |
Run Information Functions
The following table lists EMarket's Run information functions:
| Function | Purpose | Parameters | Return Type |
|---|---|---|---|
| Date | Date of current Tick | None | Date |
| TP | TP number of current Tick | None | Integer |
| Version | The position of a Run in a Batch sequence. For first Run, Version is zero. | None | Integer |
Time Functions
The following table lists EMarket's Time functions:
| Function | Purpose | Parameters | Return Type | Example | Result |
|---|---|---|---|---|---|
| GetDate | Converts a date to a day number | Date | Integer | GetDate('1/4/2004') | |
| hh | Gets the half hourly TP from a date | 'DateTime' | Integer | hh(DateTime) | |
| 4h | Gets the number of the block of 4 hourly trading periods for a given date (e.g. 1 = TP 1-8) | 'DateTime' | Integer | 4h(DateTime) | |
| 6h | Gets the number of the block of 6 hourly trading periods for a given date (e.g. 0 = TP 1-12) | 'DateTime' | Integer | 6h(DateTime) | |
| DOW | Gets the weekday for a date, 0 = Sunday | Date | Integer | Dow('14/6/2004') | 1 |
| WO | Whether a date is a week day rather than a weekend or holiday, 1 = Weekend; 0 = Weekday | Date | 0 or 1 | WO('13/6/2004') | 1 |
| WODN | 0=Week Night(WN); 1=Week Day(WD); 2=Other Night(ON); 3=Other Day(OF) | Date (and time) | 0 to 3 | WODN('1/5/2004 22:00') | 3 |
| WODN6 | 0=Week Night(WN); 1=Week Day(WD); 2=Other Night(ON); 3=Other Day(OF). Using A night period running from Midnight to 6am (not to 8am as in WODN) | Date (and time) | 0 to 3 | WODN6('1/5/2004 22:00') | 3 |
| Month | Gets the month from a date, 0 = January | Date | 0 to 11 | Month('1/5/2004') | 4 |
| WeekOfYear | Gets the week from a date, 0 = 1st full week in April | Date | 0 to 51 | WeekOfYear('1/5/2004') | 4 |
| DateDiff | Calculates the number of days between two date/times | Date 1, Date2 | Real | DateDiff('1/5/2004', '5/5/004') | 4 |
| DateSeq | Gets the position of a required date within a list of ordered dates | Date required, Lists of dates | Integer | DateSeq('5 / 4 / 2004', '1 / 4 / 2004', '2 / 4 / 2004', '3 / 4 / 2004', '4 / 4 / 2004', '5 / 4 / 2004') | 5 |
| TimeSeries | Given a date ordered sequence of values, finds the value for a required date | List of (value, last date applies) | Real | TimeSeries(735 , ' 1/04/2004 ', 760 , ' 1/04/2005 ', 840) |
Other Functions
The following table lists EMarket's other functions:
| Function | Purpose | Parameters | Return Type | Example | Result |
|---|---|---|---|---|---|
| ArrayTable | Uses two indices to retrieve a value from an array (matrix) | Index1, Index2, Value array. May be real or Integer | Real or Integer | ArrayTable(p,q,m,n, V00, V01, V02, ...V0m, V10, V11, ... Vnm) where p,q represent the position of the array; m,n represent the numbers of columns and rows in the array; 0<= p < m and 0 <= q < n would return Vpq. E.g. ArrayTable(1, 1, 2, 3, 4, 32.1, 6.3, 1.8, 31, 5). This defines a 2 * 3 matrix, and looks for the entry indexed by 1, 1. Note that if the indices are out of bounds no error will be given, and an indeterminate value will be returned. |
31 |
| Index | Gets the number in given position (index) in a list of numbers. First number has position zero. | 1 or more numbers, can be integers or real | Real | Index(p, V0, V1, V2, ... Vm) where p is the position (index) in a list of numbers. E.g. Index(3, 4.5, 7, 8.9, -23.4) |
-23.4 |
| PieceWiseLinear | Generates a value based on an extrapolation of existing data. Given a target value (p) and a set of x, y pairings defining a function, the PieceWiseLinear function will find the y value corresponding to p. This function is included primarily for use in defining Demand elasticity. | Set of x,y value pairings, can be integers or real | Real or Integer | PieceWiseLinear(p, x1, y1, x2, y2, ...xn, yn) where p is the target value. Note that you can use internal model variables as the target value, as in this example: PieceWiseLinear(HydroSystem:Waitaki.SystemMWV, 0, 1, 80, 1, 150, 0.8, 400, 0.64) |
Random Functions
| Function | Purpose | Parameters | Return Type | Example |
|---|---|---|---|---|
| RandomBinaryState | Returns values from a random sequence of values which are either 0 or 1 with the properties that proportion of the time spent in the zero state is a given proportion and the average length of time spent in the one state is a given number of days | Seed for random sequence, Date/Time, Zero state proportion, Average One state length | Real | RandomBinaryState(Seed, DateTime, 0.95, 4), will return a random 0/1 series with 0.05 time spent in the one state and an average four day span of each one state |
| MRJD | Returns a value that follows a mean reverting random walk on a logarithmic scale | Seed for random sequence, Date/Time, Starting Value, Mean, Reversion Rate, Volatility[,ProportionalJump, JumpVolatility, JumpFrequency] | Real | MRJD(RandomSeed, DateTime, 5, 10, 11, 5), will return a random walk starting with the value 5 where the average log value is equal to log(10), reversion rate of 10 (half reversion in 1/10 year), volatility of 5 (two times diffusion in 1/5 year). The jump parameters are optional |