Defining Arrays in an Input Field Using Array Constructor Functions

One of the quickest ways to create an array is to use array constructor functions. These are functions that can be entered into an input field that generate an array (a vector or a matrix) 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 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 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 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 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, you should ensure that no elements exist in your model with these names.