EMK:Formulae and Functions

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 in a 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.

Special Variables

These variable names are automatically included in the schedule

Variable Name	Definition
DateTime	This returns the date/time of the current time step
TimeInterval	This returns the duration, in half hours, of the current time step
Date	Date of current Tick
TP	TP number of current Tick
Version	The number of the current version in the volatility matrix, numbered from zero
RandomSeed	This variable is set up according to the 'Random Seed' option in the Run Resource. It allows the generation of random sequences to be coordinated for all Random Functions within the run

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

Array Functions

The following table lists EMarket's array functions:

Function	Purpose	Parameters	Return Type	Example	Result
Sum	Total value of numbers in an array	Integer or Real Array, [Exclude Value]	Real	Sum(Node.Price)
Max	Maximum value of numbers in an array, optionally excluding values with value over an exclude value	Integer or Real Array, [Exclude Value]	Real	Max(Generator.Generation)
Min	Minimum value of numbers in an array	Integer or Real Array, [Exclude Value]	Real	Min(Generator.Generation)
StdDev	Standard deviation of numbers in an array	Integer or Real Array, [Exclude Value]	Real	StdDev(Generator.Generation)
Avg	Average value of numbers in an array	Integer or Real Array, [Exclude Value]	Real	Avg(Generator.Generation)
WgtAvg	Average of numbers in an array, weighted by numbers in another array	2 x Integer or Real Array, (Values, Weights)	Real	WgtAvg(Generator.Generation,Generator.Cost)
ArrMult	Creates a new array, whose elements are the product of the elements in an array and a scalar value	Integer or Real Array, Integer or Real Value	Real Value Array	ArrMult(Node.Demand, Duration)
AddElements	Creates a new array, whose elements are the sum of the elements in two arrays (the arrays must be of the same size)	2 x Integer or Real Arrays	Real Value Array	AddElements(Node.Demand, Node.Losses)
SubElements	Creates a new array, whose elements are the difference of the elements in two arrays (the arrays must be of the same size)	2 x Integer or Real Arrays	Real Value Array	SubElements(Circuit.Flow, Circuit.Losses)
MultiplyElements	Creates a new array, whose elements are the product of the elements in two arrays (the arrays must be of the same size)	2 x Integer or Real Arrays	Real Value Array	MultiplyElements(Node.Demand, Node.Price)

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

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/Time	Integer	GetDate('1/4/2004')
hh	Gets the half hourly TP from a date	Date/Time	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)	Date/Time	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)	Date/Time	Integer	6h(DateTime)
DOW	Gets the weekday for a date, 0 = Sunday	Date/Time	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/Time	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/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/Time	0 to 3	WODN6('1/5/2004 22:00')	3
Month	Gets the month from a date, 0 = January	Date/Time	0 to 11	Month('1/5/2004')	4
WeekOfYear	Gets the week from a date, 0 = 1st full week in April	Date/Time	0 to 51	WeekOfYear('1/5/2004')	4
DateDiff	Calculates the number of days between two date/times	Date/Time, Date/Time	Real	DateDiff('1/5/2004', '5/5/004')	4
DateSeq	Gets the position of a required date within a list of ordered dates	Date/Time being looked up, List of Date/Time	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. Date format is Date:TimePeriod 'DD/MM/YYYY:TP' , if no TP then TP '01' is used	List of (Initial value, first date and time period applies for value2, value2 , ....)	Real	TimeSeries(735 , '1/04/2004:24', 760 , ' 1/04/2005', 840)

Other Functions

The following table lists EMarket's other functions:

Function	Purpose	Parameters	Return Type	Example	Result
LastVal	Returns the value of the named variable in the last tick or, in the initial tick, a default value	Variable Name, Default Value (Real or Integer)	Real	LastVal(Var, 100)	100 in the first tick, the previous value of 'Var' in following ticks
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)
RunningAverage	This function facilitates the smoothing of a value over time by applying a running average to the given value. The formula used is V = MV' + (1 - M)v, where V is the running average value, V' is the last value of the running average, v is the value being averaged. M is given by the formula: M = Exp(-Ln(2) * (D / H)) where D is the duration in days of the time step and H is the half-life parameter. On the first step M = 0.	The current Date/Time, input value (Real or Integer), half-life days (Real or Integer)	Real	RunningAverage(DateTime, Generator:ABC.Generation, 7)
FileInput	This function accesses a CSV file in the 'Misc' subdirectory of the data directory and returns values from this file. This file will a set of time dependent value series which are each given a series number (e.g. inflow years). The format of the input file can be found in Ancillary Files	The file name string, the date for which a value is being looked up, the integer series number	Real or Integer	FileInput("MyGenCapacity.csv", DateTime, InflowYearNo)
CurrentInflowYear	Returns the year of the inflow sequence being used given the starting inflow year and the current date/time	Current Date/Time, Inflow Sequence (integer)	Integer	CurrentInflowYear(DateTime, InflowYear)

Random Functions

The following functions create a random sequence, the results of which depends on the seed given, the start date of the sequence and the order of definition and exact formula used to define the function. The RandomSeed variable should usually be used as the seed as this will ensure a unique sequence is generated based on the "Random Seed" option chosen for the run

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

Back to User Manual Main Page