Quantcast

Documentation Center

  • Trial Software
  • Product Updates

array

Create an array

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

array(m1 .. n1, <m2 .. n2, …>)
array(m1 .. n1, <m2 .. n2, …>, index1 = entry1, index2 = entry2, …)
array(m1 .. n1, <m2 .. n2, …>, List)
array(<m1 .. n1, m2 .. n2, …>, ListOfLists)

Description

array(...) creates an array, which is an n-dimensional rectangular structure holding arbitrary data.

array( m_1..n_1, m_2..n_2 , ...) creates an array with uninitialized entries, where the first index runs from m1 to n1, the second index runs from m2 to n2, etc.

array( m_1..n_1, m_2..n_2 , ..., List) creates an array with entries initialized from List.

array(ListOfLists) creates an array with entries initialized from ListOfLists. The dimension of the array is the same as of ListOfLists.

Arrays are container objects for storing data. In contrast to tables, the indices must be sequences of integers. While tables may grow in size dynamically, the number of entries in an array created by array is fixed.

Arrays created via array are of domain type DOM_ARRAY. They may contain arbitrary MuPAD® objects as entries.

For an array A, say, of type DOM_ARRAY or DOM_HFARRAY and a sequence of integers index forming a valid array index, an indexed call A[index] returns the corresponding entry. If the entry of an array of type DOM_ARRAY is uninitialized, then the indexed expression A[index] is returned. SeeExample 1 and Example 5.

An indexed assignment of the form A[index]:=entry initializes or overwrites the entry corresponding to index. See Example 1 and Example 5.

The index boundaries must satisfy m1n1, m2n2, etc. The dimension of the resulting array is the number of given range arguments; at least one range argument must be specified. The total number of entries of the resulting array is (n1 - m1 + 1) (n2 - m2 + 1) ….

If only index range arguments are given to array, then an array with uninitialized entries is created. Hardware float arrays created via hfarray cannot have uninitialized entries. Entries are automatically set to 0.0 if no values are specified. Cf. Example 1.

If equations of the form index=entry are present, then the array entry corresponding to index is initialized with entry. This is useful for selectively initializing some particular array entries.

Each index must be a valid array index of the form i1 for 1-dimensional arrays and (i1, i2, …) for higher-dimensional arrays, where i1, i2, … are integers within the valid boundaries, satisfying m1i1n1, m2i2n2, etc., and the number of integers in index matches the dimension of the array.

If the argument List is present, then the resulting array is initialized with the entries from List. This is useful for initializing all array entries at once. The list must have (n1 - m1 + 1) (n2 - m2 + 1) … elements, each becoming an operand of the array to be created. In case of 2-dimensional arrays, regarded as a matrix, the list contains the entries row after row.

The argument ListOfLists must be a nested list matching the structure of the array exactly. The nesting depth of the list must be greater or equal to the dimension of the array. The number of list entries at the k-th nesting level must be equal to the size of the k-th index range, i.e., nk - mk + 1. Cf. Example 7.

A call of the form delete A[index] deletes the entry corresponding to index, so that it becomes uninitialized. For arrays of domain type DOM_HFARRAY this means that the corresponding entry is set to 0.0. Cf. Example 5.

    Note:   Internally, uninitialized entries of an array of domain type DOM_ARRAY have the value NIL. Thus assigning NIL to an array entry has the same effect as deleting it via delete. Afterwards, an indexed call of the form A[index] returns the symbolic expression A[index], and not NIL, as one might expect. Cf. Example 5.

A 1-dimensional array is printed as a row vector. The index corresponds to the column number.

A 2-dimensional array is printed as a matrix. The first index corresponds to the row number and the second index corresponds to the column number.

A 1- or 2-dimensional array that is so big that it would exceed the maximal output width TEXTWIDTH is printed in the form array( m_1..n_1, m_2..n_2, dots, index_1 = entry_1, index_2 = entry_2, dots ). See Example 10. The same is true for arrays of dimension greater than two. See Example 6 and Example 7.

Arithmetic operations are not defined for arrays of domain type DOM_ARRAY. Use matrix to create 1-dimensional vectors or 2-dimensional matrices in the mathematical sense.

Arithmetic operations are defined for arrays of domain type DOM_HFARRAY!

E.g., linear combination of arrays A, B can be computed via a*A + b*B if A, B have the same format and if the scalar factors a, b are numbers (floats, integers or rationals).

2-dimensional hfarrays A, B are processed like matrices: Operations such as A*B (matrix multiplication), A^n (matrix powers), or 1/A (matrix inversion) are possible wherever this is meaningful mathematically.

Cf. Example 8.

Note the following special feature of arrays of domain type DOM_ARRAY:

    Note:   If an array is evaluated, it is only returned. The evaluation does not map recursively on the array entries! This is due to performance reasons. You have to map the function eval explicitly on the array in order to fully evaluate its entries.

Cf. Example 9.

Examples

Example 1

We create an uninitialized 1-dimensional array with indices ranging from 2 to 4:

A := array(2..4)

The NILs in the output indicate that the array entries are not initialized. We set the middle entry to 5 and last entry to "MuPAD":

A[3] := 5: A[4] := "MuPAD": A

You can access array entries via indexed calls. Since the entry A[2] is not initialized, the symbolic expression A[2] is returned:

A[2], A[3], A[4]

We can initialize an array already when creating it by passing initialization equations to array:

A := array(2..4, 3 = 5, 4 = "MuPAD")

We can initialize all entries of an array when creating it by passing a list of initial values to array:

array(2..4, [PI, 5, "MuPAD"])

Hardware float arrays do not have uninitialized entries. If no initialization value is given, the corrsponding entry is set to 0.0:

hfarray(-1..5)

hfarray(-1..5, 2 = PI, 4 = sqrt(2)*exp(2))

hfarray(-1..5, [frandom() $ i = -1..5])

hfarray(1..2, 1..3, [[1, 2, 3], [4, 5, 6]])

hfarray(1..2, 1..3, [1, 2, 3, 4, 5, 6])

Example 2

Array boundaries may be negative integers as well:

A := array(-1..1, [2, sin(x), FAIL])

A[-1], A[0], A[1]

A := hfarray(-1..2, -3..-1, [[-1, -1, -1],
                             [ 0,  0,  0],
                             [ 1,  1,  1],
                             [ 2,  2,  2]])

A[-1, -2], A[0, -3], A[2, -3]

delete A:

Example 3

If the dimension and size of the array or hfarray are not specified explicitly then both values are taken from the given list:

hfarray([1.0,2.0,3.0,4.0,5.0]) = hfarray(1..5, [1.0,2.0,3.0,4.0,5.0]);
bool(%)

array([[1,2],[3,4],[5,6]]) = array(1..3, 1..2, [[1,2],[3,4],[5,6]]);
bool(%)

Note that all subfields of one dimension must have the same size and dimension. Therefore, the following input leads to an error:

array([[1],[3,4],[5,6]])
Error: The argument is invalid. [array]

Example 4

The $ operator may be used to create a sequence of initialization equations:

array(1..8, i = i^2 $ i = 1..8)

hfarray(1..4, 1..4, (i, i) = 1 $ i = 1..4)

Equivalently, you can use the $ operator to create an initialization list:

array(1..8, [i^2 $ i = 1..8])

hfarray(1..8, [i*PI $ i = 1..8])

Example 5

We create a 2×2 matrix as a 2-dimensional array:

A := array(1..2, 1..2, (1, 2) = 42, (2, 1) = 1 + I)

Internally, array entries are stored in a linearized form. They can be accessed in this form via op. Uninitialized entries internally have the value NIL:

op(A, 1), op(A, 2), op(A, 3), op(A, 4)

Note the difference to the indexed access:

A[1, 1], A[1, 2], A[2, 1], A[2, 2]

We can modify an array entry by an indexed assignment:

A[1, 1] := 0: A[1, 2] := 5:
A

You can delete the value of an array entry via delete. Afterwards, it is uninitialized again:

delete A[2, 1]: A[2, 1], op(A, 3)

Assigning NIL to an array entry has the same effect as deleting it:

A[1, 2] := NIL: A[1, 2], op(A, 2)

Apart from initialization and deleting entries via NIL assignments, hfarrays behave similarly:

A := hfarray(1..2, 1..2, (1, 1) = 1.0, (2, 2) = 1.0)

op(A, 1), op(A, 2), op(A, 3), op(A, 4)

A[1, 1], A[1, 2], A[2, 1], A[2, 2]

A[2, 2] := PI:
A[2, 2]

delete A[2, 2]:
Error: The argument is invalid. [delete]
A

delete A:

Example 6

We define a three-dimensional array with index values between 1 and 8 in each of the three dimensions and initialize two of the entries via initialization equations:

A := array(1..8, 1..8, 1..8, (1, 1, 1) = 111, (8, 8, 8) = 888)

A[1, 1, 1], A[1, 1, 2]

We create a 3-dimensional hfarray:

A := hfarray(1..2, 2..3, 3..4, (1, 2, 3) = 123, (2, 3, 4) = 234)
hfarray(1..2, 2..3, 3..4, [123.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 234.0])
delete A, B:

Example 7

A nested list may be used to initialize a 2-dimensional array. The inner lists are the rows of the created matrix:

array(1..2, 1..3, [[1, 2, 3], [4, 5, 6]])

We create a three-dimensional array and initialize it from a nested list of depth three. The outer list has two entries for the first dimension. Each of these entries is a list with three entries for the second dimension. Finally, the innermost lists each have one entry for the third dimension:

array(2..3, 1..3, 1..1,
      [
        [ [1], [2], [3] ],
        [ [4], [5], [6] ]
      ])

hfarray(2..3, 1..3, 1..1,
        [
          [ [1], [2], [3] ],
          [ [4], [5], [6] ]
        ])
hfarray(2..3, 1..3, 1..1, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0])

Example 8

Basic arithmetic is available for arrays of domain type DOM_HFARRAY:

A := hfarray(1..5, [1, 2, 3, 4, 5]):
B := hfarray(1..5, [5, 4, 3, 2, 1]):
A + B

2*A

2*A - 3* B

2-dimensional arrays of type DOM_ARRAY are regarded as matrices. They can be multiplied accordingly:

A := hfarray(1..3, 1..3, [frandom() $ i = 1..9]):
B := hfarray(1..3, 1..2, [frandom() $ i = 1..6]):
A, B, A * B, A^10 * B

The following command computes the matrix inverse of A:

1/A

Some functions such as norm act on hfarrays:

norm(A)

Example 9

If an array is evaluated, it is only returned. The evaluation does not map recursively on the array entries. Here, the entries a and b are not evaluated:

A := array(1..2, [a, b]):
a := 1:  b := 2:
A, eval(A)

Due to the special evaluation of arrays the index operator evaluates array entries after extracting them from the array:

A[1], A[2]

You have to map the function eval explicitly on the array in order to fully evaluate its entries:

map(A, eval)

Example 10

A 2-dimensional array is usually printed in matrix form:

A := array(1..4, 1..4, (1, 1) = 11, (4, 4) = 44)

B := hfarray(1..2, 1..3, (1, 1) = 11, (2, 3) = 23)

If the output does not fit into TEXTWIDTH, a more compact output is used in print:

PRETTYPRINT := FALSE:
TEXTWIDTH := 20:
print(Plain, A)
array(1..4, 1..4, (\
1, 1) = 11, (4, 4) \
= 44)
PRETTYPRINT := TRUE:
delete A, B, TEXTWIDTH:

Parameters

m1, n1, m2, n2, …

The index boundaries: integers

index1, index2, …

A sequence of integers defining a valid array index

entry1, entry2, …

Arbitrary objects

List

A plain list of entries for initializing the array

ListOfLists

A nested list (of lists of lists of …) of entries for initializing the array

Return Values

Object of type DOM_ARRAY or DOM_HFARRAY, respectively.

See Also

MuPAD Domains

MuPAD Functions

Was this topic helpful?