See Also
Array builtins are designed to supplement the array capabilities of the software. Use these builtins to find the sum, the standard deviation, or the mean across dimensions of arrayed variables. Many of these functions work on array ranges, and there is in-depth discussion of this in Specialized Array Manipulation.
Some of these builtins can also be used for non-arrayed variables.
The array builtins can be applied to either an arrayed variable or an expression. Some can also be applied to conveyors and queues to deal with the elements within the stock.
Note Not all of the builtin functions can be used in Array expressions. You can't use any builtin that has a value depending on previous results (this includes the Delay builtins and Statistical builtins). You also can't use any other array builtins in the expression (it is not possible to nest array builtins.)
When an array builtin is applied to an expression, care must be taken to ensure that the intended dimensions are being reduced as expected.
This section describes the following builtins:
The INTERPOLATE builtin calculates the interpolated value of an N-dimensional set of points based on inputs computed on the unit interval [0,1]. It can be used to provide a continuous lookup mechanism for values that pass through all of the specified points. In 1 dimension this is the same as the behavior of a graphical function based on a vector of values.
The first argument must be an arrayed variable or a subset (slice) of an arrayed variable. For example, if there is a three dimensional array called points, then you could specify points directly with 3 additional arguments, or points[2,*,*] with 2 additional arguments.
The arguments should be normalized so they provide a value between 0 and 1. If the value is less than 0, the first entry in the associated dimension will be used. If the value is above 1, the last entry will be used. Between values the weighted average of the entry before the one associated with the input and the one after will be used. For example, if there are 5 entries, then a value of 0.3 would be between the second entry (at 0.25) and the third entry (at 0.5) and 80% of the value of the second entry and 20% of the value of the third would be used.
There must be at least 2 elements in each dimension of the arrayed variable, but there is no limited to how many there are beyond that, and no requirement that the different dimensions have the same number of entries. In all cases, the entries will be divided into an equal number of regions (n-1 internal and 2 external) and the results based on that.
Examples:
If pts[Dim1] is 0,2,4, then INTERPOLATE(pts, 0.75) would return 3.
If pts2d[Dim1,Dim2] is (0,2,4),(8,6,5) then INTERPOLATE(pts2d, 0.75, 0.25) would return 5.5. You can think of this as taking 25% of (0,2,4) and 75% of (8,6,5) to get (6,5, 4) and then taking the halfway point between 6 and 5 to get 5.5. Alternatively, since the 0.25 position of 3 numbers is half way between the first tow, it works to take the halfway points between 0 and 1 (1) and that between 8 and 6 (7) then take 25% of 1 and 75% of 7 to get 22/4 or 5.5.
The MEAN builtin calculates the arithmetic mean across the elements in the array or expression. The calculation is defined as the sum of the elements, divided by the number of elements in the array.
The MEAN calculation can be done in either an arrayed or a non-arrayed converter or flow.
To report the mean across a subset of the dimensions of the arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension. You can report the arrayed variable's mean in either an arrayed or a non-arrayed converter or flow.
Examples:
Average Salary for Employees = MEAN(Salaries)
Average Salary for Employees in Boston = MEAN(Salaries[Boston,*])
Average Salary for Labor Groups 1 to 3 = MEAN(Salaries[*,1:3])
The PROD builtin calculates the product of all the elements in the array or expression.
To report product across a subset of the dimensions of an arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension, or a range specified (min:max) to report part of the array. You can use the arrayed variable's product in either an arrayed or a non-arrayed variable.
Example:
Interest_Factor[Year] = (1.0 + Interest_Rate[Year])
Compounded_Interest_to_Year[Year] = principal * PROD(Interest_Factor[1:year])
The RANK builtin gives the numerical index of the arrayed variable with the given rank number when the array is sorted in ascending order. The optional secondary sort array specifies the secondary sort field for variables with the same value. The secondary sort array must be the same size as the arrayed variable, or the secondary sort won't occur (this is only enforced when you simulate the model, so you won't be warned).
Example:
If array A contains the values { 6, 2, 8, 5 }
RANK(A, 2) will equal 4 (i.e., the fourth element of array A is the second smallest value)
Using RANK causes the specified array to be sorted once each time step (DT). For multi-dimensional arrays, you can pass one or more dimensions of the array to return the rank of a subset of the array.
Example:
Rank(Salaries[Boston,*],2) returns the rank of the second smallest salary in Boston.
Use the SELF builtin in conjunction with the SIZE, PREVIOUS, and ENDVAL builtins to refer to the current variable.
You can also use SELF[Dim1-1,Dim2] and similar forms to refer to different elements in an array. For example a variable arrayed by position could have the equation
IF position = 1 THEN 0 ELSE SELF[position-1] + width[position-1]
which would add the width of each successive position to compute the next position.
The SIZE builtin gives the number of elements in the array or expression.
Note: You can also use the SIZE builtin to report the length of a queue.
To get the size or dimension size of an array holding the equation, use the SELF builtin.
Examples:
SIZE(SELF) gives the number of elements in this array.
SIZE(SELF[*, 1]) gives the size of the first dimension of this array.
SIZE(SELF[1, *]) gives the size of the second dimension of this array.
SIZE (<queue>) returns the total number of elements contained in the specified queue-type discrete stock.
SIZE (<conveyor>) returns the total number of slots contained in the specified conveyor-type discrete stock.
The STDDEV builtin calculates standard deviation for all the elements in the array or expression.
To report the standard deviation across a subset of the dimensions of an arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension. You can report the arrayed variable's standard deviation in either an arrayed or a non-arrayed converter or flow.
Example:
Standard Deviation of Salary in Boston= STDDEV(Salaries[Boston,*])
The SUM builtin calculates the sum of all the elements in the array or expression.
To report the sum across a subset of the dimensions of an arrayed input variable, specify an asterisk (*) to include all of the elements across a dimension. You can report the arrayed variable's sum in either an arrayed or a non-arrayed converter or flow.
Example:
Total Salary for Employees in Boston = SUM(Salaries[Boston,*])