If you mark a function as having a number of loops to manage it is a signal to Vensim to let the function manage the last num_loop subscripts loops that Vensim would normally manage. Consider the matrix inversion routine in the example external functions. In Vensim you write the equation
input : i1,i2,i3,i4 ~~|
output <-> input ~~|
a_inverse[output,input] = MATRIX_INVERT(a[output,input]) ~~|
Since the matrix inverse function is marked has managing 2 user loops, Vensim will pass a vector argument pointing to the left hand side (a inverse) and then an argument pointing to a.Instead of doing a nested for loop on output and input, Vensim will simply call the function once, and expect all of a_inverse to be filled in. Vensim assumes the behavior of the external function is proper. Vensim initializes all variables to have the value NA so if an external function fails to update all elements some may be left with this value.
To continue the discussion a little bit, if you were to write the Vensim equation
region : east,west ~~|
a_inverse[region,output,input] =
MATRIX_INVERT(a[region,output,input]) ~~|
Vensim would call the external function MATRIX_INVERT twice, once for EAST and once for WEST.It is important to note that Vensim arrays are stored as Vectors with the last arguments varying fastest (this is like C and unlike FORTRAN). If, for example, you were to use the equation
a_inverse[output,input,region] =
MATRIX_INVERT(a[output,input,region]) ~~|
You would get nonsense results. Be extra careful when using multiply subscripted variable in user loops.
NOTEif you have set user_loops then the function call must set the return value to be the value of the first element of the array. Otherwise this value will be overwritten by the return value when Vensim finishes the function call.
