Defining Arrays in an Input Field Using Array Constructor Functions

One of the quickest ways to create an array A collection of variables that share common output attributes and can be manipulated in GoldSim elements or input expressions. is to use array constructor functions. These are functions that can be entered into an input field that generate an array (a vector A one-dimensional array. or a matrix A two-dimensional array.) by specifying the array label set(s) and values as arguments.

For example, the following expression generates a vector based on the Days array label set, in which all the items have a value of 1m:

Vector(days, 1m)

The following expression generates a matrix based on the Days array label set (for rows) and the Months array label set (for columns), in which all the items have a value of 0 g:

Matrix(days, months, 0g )

Note: You do not have to specify the array label set(s) when using an array constructor. If you omit them, GoldSim will assume that the constructed array has the same order and set(s) as that of the input field where it is being defined. For example, if you created an Expression defined as a vector with array label set "days", then to create a vector of zeros, you could enter either "Vector(days, 0)" or simply "Vector(0)".

In addition to creating an array in which all the values for the items are identical (and hence specified by a single argument), you can also specify each item separately:

Vector(days, 1m, 3m, 0m, 5m, 6m, 2m, 7m)

In this example, since the Days array label set was specified, seven items are defined.

Note: When defining a matrix using an array constructor, the first argument represents the row array label set (having n items), the second argument is the column label set (having m items), and if all of the values are specified separately, they are defined as follows: r₁c₁, r₁c₂,...r₁c_m, r₂c₁,...r_nc_m. That is, the items are listed left-to-right-then-down through the matrix.

The units for the values of a constructor do not need to be identical (although the dimensions An output attribute for an element that defines the dimensionality (in terms of Length, Time and other fundamental dimensions) of the output. do). The following expression is valid:

Vector(days, 1m, 3ft, 0km, 5mm, 6m, 2ft, 7m)

Vector and matrix values may be specified as links. For example, if X was a scalar An output consisting of a single value or condition. with dimensions of length, it could be inserted into the example above (i.e., defining the second item in the vector):

Vector(days, 1m, X, 0km, 5mm, 6m, 2ft, 7m)

Note that links such as X do not have to represent constants. They can be functions (including of time).

In addition, when using the Matrix constructor, you can specify vector arguments. That is, you can use the Matrix constructor to build a matrix from specified vectors (either one vector for each row or one vector for each column). The rules for doing so are as follows:

• If you create a matrix that has a different number of rows than columns, you can define the matrix by providing vectors for either all of the rows, or all of the columns. GoldSim automatically determines based on the array label sets whether the vectors should be treated as rows or columns).
• When creating a matrix using vectors, the array label set of the vectors provided do not need to match the array label set specified in the output attributes Three properties of an element's output that determine the kinds of inputs to which it can be linked: type, order and dimensions. for the matrix being defined. What does need to match is the number of items in the array label sets.
• If the matrix is square, the provided input vectors load by columns (i.e. they are treated as column vectors). There is one exception to this: if the array label set of the provided vectors match ONLY the column array label set of the matrix (i.e., the row label set being different), the vector values are loaded into the matrix by row.

These rules can best be illustrated through some examples. These examples utilize array label sets called AL2 and AL2a with two items and AL3 with three items, and vectors V2a, V2b, V2c, V3a and V3b defined below:

V3a = [1, 2, 3], based on AL3

V3b = [6, 7, 8], based on AL3

V2a = [10, 20], based on AL2

V2b = [12, 22], based on AL2

V2c = [30, 40], based on AL2

Expression	Resulting Array	Comments
Matrix(AL2, AL3 , V2a, V2b, V2c)	10     12     30 20     22     40	Expression output attributes defined with AL2 as rows and AL3 as columns. Automatically treats vectors as columns.
Matrix(V2a, V2b, V2c)	10     12     30 20     22     40	Expression output attributes defined with AL2 as rows and AL3 as columns. Automatically treats vectors as columns.
Matrix(V2a, V2b, V2d)	10     12     30 20     22     40	Expression output attributes defined with AL2a as rows and AL3 as columns. Automatically treats vectors as columns. Although input vectors are based on AL2, they have two items so can be automatically mapped to AL2a.
Matrix(AL2, AL3 , V3a, V3b)	1     2     3 6     7     8	Expression output attributes defined with AL2 as rows and AL3 as columns. Automatically treats vectors as rows.
Matrix(V3a, V3b)	1     2     3 6     7     8	Expression output attributes defined with AL2 as rows and AL3 as columns. Automatically treats vectors as rows.
Matrix(V2c, V2c)	30     30 40     40	Expression output attributes defined with AL2 as rows and AL2 as columns. Vectors loaded by columns.
Matrix(V2c, V2c)	30     40 30     40	Expression output attributes defined with AL2a as rows and AL2 as columns. Vectors loaded by rows.

When using array constructors, you can also utilize two specialized variables: row and col. These variables can be used to define values based on the row and the column being referenced. Within constructors, these variables are defined as follows:

• If the array label set representing the row variable is based on a named set, row represents the row number. Likewise, if the array label set representing the column variable is based on a named set, col represents the column number.
• If the array label set representing the row variable is an indexed set, row represents the actual item label. Likewise, if the array label set representing the column variable is an indexed set, col also represents the actual item label.

They are best illustrated through some examples. These examples utilize a named array label set called Set1 with 3 items (A, B and C), an indexed array label set called Set2 with 4 items (1,2,3 and 4), and an indexed array label set called Set3 with 3 items (3,4,5).

Expression	Resulting Array
Vector(Set1,row)	1 2 3
Vector(Set3,row)	3 4 5
Vector(Set1, if(row>=2,1,0))	0 1 1
Vector(Set3, if(row>=2,1,0))	1 1 1
Matrix(Set1, Set2, row)	1     1     1     1 2     2     2     2 3     3     3     3
Matrix(Set1, Set2, col)	1     2     3     4 1     2     3    4 1     2     3     4
Matrix(Set2, Set2, if(col>=row,1,0)	1     1     1     1 0     1     1     1 0     0     1     1 0     0     0     1

One powerful use of array constructors is to take advantage of the ability of arrays to reference variables as arguments. For example,

Vector(days, if(row<=4, A[row], B[row]))

would create a vector of days in which the first 4 items would be drawn from the vector A, and the last 3 items would be drawn from the vector B.

Warning: If you have elements with the names Row or Col, GoldSim will link to the element rather than use the keyword. Therefore, if you want to use these keywords Text delimited by the % symbol (e.g., %x_unit%) that can be used when creating chart styles to insert context sensitive text (e.g., for axis labels)., you should ensure that no elements exist in your model with these names.