Ps-i 2.0 - routines
General description
A routine are used to explain ps-i how to compute quantities specific to a particular model.
Writing a routine is very much like using a calculator. In fact the name "routine" was chosen
specifically to remind a person used to C or C++ that these are not functions in the sense of these programming languages.
Using routines
Routines take no arguments. Rather, there is a global notion of "current agent". Before any routine is execute the "current agent" is set to point to a particular agent on a field. Thus
if you routine is told to look for the value of attribute influence the particular value it obtains depends on particular current agent.
There are several types of routines:
- builtin - these routines are implemented in C and are part of ps-i. They are always available no matter what model is running.
Example:
- time routine returns the current time in the model
- agent_x routine returns the X coordinate value of the current agent
- prototype - this is a generalization of builtin type. This routine
cannot be called, rather it is used to produce a customized routine by specifying
parameters specific to the current model.
- customized - this is a routine derived from prototype routine by
specifying certain parameters.
- composite - a routine defined completely by the user. It can consists of arithmetic operations, if statement, attribute values and calls to other routines.
Note:a composite routine can call only routines defined before it or builtin
routines. There are no provisions for cycles, goto statements and recursion. This was done
on purpose - all routines are guaranteed to return. If you want cycles you should instead
write a new builtin routine in C - this would be much faster and just as easy.
You can see the list of all functions currently known to Ps-i (this can depend upon the model loaded) by opening "Main menu->Help->Routine Browser" window.
Section format
Example:
routine "test1" composite
comment "An example"
code "[inactive]*([influence]+6)"
end
Each routine has a distinct name, a type and a comment. Other directives vary depending
on the type of the routine.
Builtin routines and prototype routines
These require no declaration in the model
Customized routines
Example:
routine "cache_activated" from "activated"
comment "Returns activated identity of a current agent"
parameters "cache"
end
This type of routine specifies from which routine it was derived. You should
also specify a parameters directive. The number of parameters vary depending
on which prototype routine was used. In the above example a customized
routine "cache_activated" is derived from prototype routine "activated" by specifying which attribute to use. The routine "cache_activated" will thus return
the activated identity in attribute "cache" (assumed to be of type repertoire).
Note: due to time constraints no type checking was implemented (however the necessary
hooks are in place). Though you can use attribute of any type in the above example only
attributes of repertoire type will produce meaningful numbers.
Composite routines
Example:
routine "test1" composite
comment "An example"
code "[inactive]*([influence]+6)"
end
The only directive specific to the composite routine is code. It takes only
one parameter - a string enclosed in quotes. The string should represent an algebraic expression utilizing operations known to ps-i and references to other functions and
attributes.
The following operations are known (here A,B and C are some other expressions):
- (A) - value of A
- A + B - add values of A and B
- A - B - subtract B from A
- A * B - multiply values of A and B
- A / B - divide A by B (division by 0 produces recoverable error)
- A ? B : C - if value of A is non zero return value of B, otherwise return value of C
- A and B - return 1 if both A and B are non zero, return 0 otherwise
- A or B - return 1 if at least one of A and B is non zero, return 0 otherwise
- not A - return 1 if A is zero, return 0 otherwise
- A < B - return 1 if A is strictly less than B, return 0 otherwise
- A > B - return 1 if A is strictly greater than B, return 0 otherwise
- A = B - return 1 if A and B have equal values
- [aname] - return value of attribute aname of the current agent
- {aname} - return value of function with name aname
Related
See also About Ps-i 2.0.