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. Users may 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. There are two places where this directory can be; one is within the Simile program files tree (for built-in functions), and the other is under Simile's local directory (for functions to be treated as user-defined). Any functions added by modellers should be placed in the latter location; this has the effect that when a model requiring the functions is saved, they are marked as user-defined, and if the model is subsequently opened on a system where the function definitions are not present, a warning is displayed saying which user-defined functions are missing.
The format of the macro definition 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 or variable, so it must start with a letter, and unlike the built-in function names it is case-sensitive.
- X1, X2 … Xn are a series of one or more variable identifiers. These also have the format of Prolog atoms or variables, so they must start with letters and are case sensitive. These formal arguments to the function are replaced when the function is used, by the actual argument values. 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.
- The symbol '-->' means 'maps onto'. It, and the final period, are part of Prolog syntax.
- Next line shows how to write 0-ary (no arguments) macro definitions (leave parentheses out) and macro definitions calling 0-ary functions or macros (put empty atom in parentheses).
init_time --> at_init(time('')).
Note the argument in the call is two single quotes, not a double quote.
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 .pl files distributed with Simile (and installed in the Functions directory in Simile's program files) contain a number of examples of function definitions. These include 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].
- with_greatest(Arr1, Arr2) Takes two arrays and returns the element of the second in the position corresponding to the largest-valued element of the first
- 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.
Comment lines, starting with a %, can be included in this file, and standard multi-line comments bounded by /*...*/ can 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 >> User-defined functions