Feature Request: Support array style equations (similar to Berkley Madonna's array equations, but with a R twist)

[mattfidler]

Request:

#710 (reply in thread)

Array Equations
Berkeley Madonna supports array equations in addition to scalar equations. This feature is
useful if you have many scalar equations with similar right-hand sides. Arrays can have one,
two, or three dimensions. To define an array equation, the variable name on the left-hand side
includes a range of subscripts enclosed in square brackets like this:
v[1..10] = SIN(2*pi*f)
In this example, v is defined as a vector (one-dimensional array) of 10 elements with subscripts
1 through 10. Note that you don’t need to explicitly define the number of elements in the array;
Berkeley Madonna figures out the size based on the subscript range on the left-hand side.
Arrays with two or three dimensions are defined with two or three subscript ranges. For
example, the following defines a two-dimensional array of 60 elements (5 rows by 12
columns):
a[1..5,1..12] = 10.5
And the following defines a three-dimensional array with 24 elements:
a[1..2, 0..2, 2..5] = -77
This last example is a bit tricky because index for each dimension starts at a different number.
The array’s dimensions are 2 x 3 x 4 and the elements are a[1,0,2], a[1,0,3], a[1,0,4], a[1,0,5],
a[1,1,2], ..., a[1,1,5], ..., a[2,0,2], ..., a[2,2,5].
You can define a single array using more than one equation:
k[0..3] = a * COS(x)
k[4..9] = b * SIN(x)
k[10] = 0.5
In this example, k is an 11-element vector with subscripts 0 through 10. When multiple
equations are used to define an array, they are executed in the order they appear in the
equation file. Within a single equation, the elements are assigned from the first subscript to the
last. In the previous example, the order of assignment is k[0], k[1], k[2], ..., k[9], k[10]. This
execution order can very important as we shall soon see.
-37-
Berkeley Madonna defines special indexing variables named i, j, and k which are valid only in
the context of an array equation. They refer to the subscript of the element being assigned on
the left-hand side. Most often, these variables are used to refer to array elements. For example:
a[1..10] = ...
b[1..10] = ...
total[1..10] = a[i] + b[i]
In two- or three-dimensional array equations, there are two or three index variables. Each
index variable corresponds to one dimension: i to the first dimension, j to the second, and k to
the third. For example, the in following three-dimensional array equation, i goes from 1 to 3, j
goes from 1 to 4, and k remains unchanged at 5:
s[1..3,1..4,5] = f[i,j] * g[j,k]
The rightmost index variable (j in a two-dimensional equation, k in a three dimensional
equation) changes the fastest. For example, in the following equation:
a[1..3,1..3] = ...
the elements are assigned in the following order:
a[1,1] = ...
a[1,2] = ...
a[1,3] = ...
a[2,1] = ...
a[2,2] = ...
a[2,3] = ...
a[3,1] = ...
a[3,2] = ...
a[3,3] = ...
Berkeley Madonna allows you to refer to elements of the array being assigned in the right�hand side of its equation. This permits you to write equations like this:
factorial[1] = 1
factorial[2..30] = factorial[i - 1] * i
In this example, the order of evaluation is extremely important. If the two equations were
reversed, factorial[2] would be undefined because the value of factorial[1] has not yet been
computed. Another situation to avoid is illustrated here:
a[10] = 1000
a[1..9] = a[i+1] * 0.97
This example is invalid because the computation of a[1] depends on the value of a[2] which
hasn’t been computed yet. The correct way to write these equations is:
a[10] = 1000
a[9..1] = a[i+1] * 0.97
Finally, you must watch out for gaps in your arrays. Consider the following:
b[0] = 0
b[1..4] = b[i-1] + sqrt(i)
-38-
b[10] = 100
b[9..6] = b[i+1] * b[10-i]
Everything looks fine here until you realize that b’s subscripts go from 0 to 10, but b[5] is not
defined anywhere. Berkeley Madonna does not check for such errors, so use care.
Arrays can be used with differential, difference, and discrete equations. Just remember to
include the subscript range immediately following the variable name on the left-hand side.16
For example:
y[1](starttime) = 1
y[2..3](starttime) = 1.1 * y[i - 1]
d/dt(y[1..3]) = -0.1 * y[i]
INIT a[1..5] = i
NEXT a[1..5] = a[i] + i
INIT x[1..n] = 0
x[1..n](t) = x(t - dt) + (1 / sqrt(y[i])) * dt
c[1..n] = CONVEYOR(...)
Note that you can’t use multiple equations to define an array of discrete objects. This
restriction is necessary to prevent the creation of schizophrenic arrays such as this:
s[1..3] = CONVEYOR(...)
s[4..6] = QUEUE(...)
s[7..9] = OVEN(...)
Limits can be applied to arrays, but the limit applies equally to all elements. You cannot apply
a limit to only certain elements. For example, to limit each element of vector y in the previous
example to values greater than or equal to 0.5, add the following equation:
LIMIT y >= 0.5
You can use variables in subscript ranges. This capability makes it easy to change the size of
arrays without recompiling your model. For example:
factorial[1] = 1
factorial[2..n] = factorial[i-1] * i
n = 10
Since n is a parameter, you can change its value from the parameter window. Berkeley
Madonna dynamically determines the size of the array before each run and allocates the
necessary memory.
If a subscript range uses an expression whose value changes over time, the size of the array
does not change. The expression’s value during the initialization step determines the size of
the array and this size remains fixed during the run.
 
16
 Berkeley Madonna also permits the subscript range to appear immediately following the variable name on the right-hand side of the
integrator equation in STELLA syntax. This exception enables Berkeley Madonna to compile array equations generated by STELLA.
-39-
Berkeley Madonna does not support STELLA “symbolic indexing” array syntax