Macro definitions

Macro definitions provide a shorthand for long, complex expressions that would otherwise have to be used in equations, possibly in several different elements. The definitions are stored in one or more external files, which are read each time Simile starts. This allows users to edit the files to include user-defined macros.

Each new macro is defined in a new line in any file with the extension .pl in the Functions directory. This directory is located within the Simile program files tree. The format of the line is:

f(X1, X2 ... Xn) --> F(X1, X2 ... Xn)

where:

• f is the name of the user-defined function. This has the format of a Prolog atom, so it must start with a lowercase letter.
• X1, X2 … Xn are a series of one or more variable identifiers. These have the format of Prolog variables, so they must start with uppercase letters. These arguments to the function are replaced when the function is used, by the symbolic names of the influencing variables. If the function requires no arguments, you must place a pair of single quotes between the empty parentheses.
• F(X1, X2 … Xn) represents any expression that could be used in an element's equation. The variable identifiers can be used as quantities anywhere in this expression. This is the macro itself. As with any expression in the equation language, it may extend over more than one line, with each complete part being separated from the next by a comma.

The function, as it appears on the left side of the arrow, can then be used in any Simile equation, with any sub-expression taking the place of each of the variable identifiers. The result returned by the function will be the same as that which would have been returned by the expression on the right hand side, if the same sub-expressions had been substituted for the variable identifiers.

The macros.pl file distributed with Simile contains a number of examples of function definitions. These do the following:

• subtotals(Arr): Takes an array and returns another array of the same size containing the totals of all the values up to that point in the original array. e.g., subtotals([1,2,4,3]) = [1,3,7,10].

• rankings(Arr) Takes an array and returns an array of integers of the same size each representing the position in the sequence of largest to smallest (largest = 1) of the corresponding value in the original array. e.g., rankings([8.2, -5.1, 2.5]) = [1,3,2].

• colin(Arr) Takes an array and on each time step returns an integer, with the probability of each value being proportional to the value at that position in the original array.

• newton_raphson(Lo_start, Hi_start, Poly) takes two starting values, and a value that is derived from its result by other variables in the model. It returns a new value on each time step, attempting by linear extrapolation from the last two values to return a value for which Poly will be zero.

• true() and false(): return Booleans for true and false respectively.

Comment lines, starting with a %, can be included in this file, although standard multi-line comments bounded by /*...*/ cannot be used.

If there is a syntax error in a user function definition, this will cause a warning to be produced when Simile is started. The other definitions will still be usable.

In: Contents >> Working with equations