# Definition and Printing of Matrices

For more details and examples, please consult Technical Report T.R. 95-74.

### MATRICES OF NUMBERS

In ALADDIN, floating point numbers should be thought of as dimensionless physical quantities.

Example 1 : Small matrices of numbers may be defined as follows :

```   /* [a] : Define a (1x3) matrix called X */

X = [ 1, 2, 3 ];

/* [b] : Define a (3x1) matrix called Y */

Y = [ 1; 2; 3 ];

/* [c] : Define a (2x2) matrix called Z */

Z = [ 1, 3; 2, 4];
```

Each matrix definition begins with a "[" and ends with a "]". The elements along a matrix row are separated by commas. A semi-colon between matrix elements indicates the end of a matrix row. Don't forget to terminate the matrix definition with a semi-colon !

The name of the matrix is given on the left-hand side of the assignment (i.e. "=") operator. Please ensure that you choose a matrix name that will not conflict with a keyword or function name in the ALADDIN language.

Matrices may be defined over multiple lines of input.

Example 2 : Matrix Z could have also been written:

```   /* [c] : Define a (2x2) matrix Z */

Z = [ 1, 3;
2, 4 ];
```

### MATRIX ELEMENTS

To extract an element of a matrix, simply append the matrix name with the row and column number enclosed in brackets.

Example 3 : From example 2, we can write

```    print "Z = ", Z, "\n";
print "Z = ", Z, "\n";
print "Z = ", Z, "\n";
print "Z = ", Z, "\n";
```
and the output will be
```    Z =       1
Z =       2
Z =       3
Z =       4
```

In ALADDIN, matrix row and column numbers begin with one. The matrix elements,

```    Z, Z ...
```

are physical quantities. If a matrix element has units (see examples below) then the units will be printed along with the numerical value of the matrix element.

### MATRICES OF QUANTITIES WITH UNITS

ALADDIN supports the specification of rectangular arrays of physical quantities.

Example 4 : The statement:

```    box = [ 3 m, 6 m, 9 m ];
```

defines a (1x3) matrix containing length quantities. Now let's suppose that the elements of Z represent the side lengths of a rectangular box. The box volume can be computed and printed by simply typing:

```    print "volume of box = ", box*box*box, "\n";
```

The output is:

```    volume of box =       162 m^3
```

### PRINTING MATRICES

The PrintMatrix() function can print one or more matrices.

Example 5 : The pair of statements:

```    PrintMatrix(X);
PrintMatrix(Y,Z);
```

print matrices X, Y and Z, as defined in Examples 1 and 2. The output is:

```    MATRIX : "X"

row/col                  1            2            3
units
1            1.00000e+00  2.00000e+00  3.00000e+00

MATRIX : "Y"

row/col                  1
units
1            1.00000e+00
2            2.00000e+00
3            3.00000e+00

MATRIX : "Z"

row/col                  1            2
units
1            1.00000e+00  3.00000e+00
2            2.00000e+00  4.00000e+00
```

In the second function call, matrices Y and Z are printed with only one function call to PrintMatrix().

Example 6 : The function call (from Example 3)

```    PrintMatrix( box );
```

generates the output:

```    MATRIX : "box"

row/col                  1            2            3
units            m            m            m
1            3.00000e+00  6.00000e+00  9.00000e+00
```

Notice that the units of "m" are aligned along each column.

### FUNCTIONS FOR MATRIX ALLOCATION

The explicit definition of matrices is really only practical for matrix sizes less than about 3-5 rows and columns. For all other cases, ALADDIN provides a suite of functions for the generation of matrices commonly used in numerical, matrix, and/or finite element applications.

## Functions for the Defintion of Matrices

```    FUNCTION		PURPOSE
=========================================================================

Matrix([s,t])        Allocate a s x t matrix
Diag([s, n])         Allocate s x s diagonal matrix with n along diagonal
One([s, t])          Allocate s x t matrix full of ones
One([s])             Allocate s x s matrix full of ones
Zero([s])            Allocate s x s matrix full of zeros
Zero([s, t])         Allocate s x t matrix full of zeros
```

Example 7 : The following script exercises each of these matrix allocation functions:

```    /* [a] : Allocate a 20 by 30 matrix */

W = Matrix([20,30]);

/* [b] : Allocate a 1 by 30 matrix full of zeros */

X = Zero([1,30]);

/* [c] : Allocate a 30 by 30 matrix full of zeros */

X = Zero([30,30]);
Y = Zero();

/* [d] : Allocate a matrix full of zeros, the size the same as [W] */

X = Zero( Dimension(W) );

/* [e] : Allocate a 30 by 30 matrix full of ones */

Y = One();
X = One([30,30]);

/* [f] : Allocate a 30 by 30 diagonal matrix with 2 along the */
/*	    the diagonal and a 44 by 44 identity matrix          */

X = Diag([30,2]);
Y = Diag([44,1]);
```

### ROW UNITS AND COLUMN UNITS

The functions

```    FUNCTION		PURPOSE
======================================================

ColumnUnits(A, [u])  Assign column units u to matrix A
RowUnits(A, [u])     Assign row units u to matrix
```

allow for the definition of matrices with specified row and column units.

Example 8 : The block of statements:

```    stiff = Matrix([3,3]);
stiff = ColumnUnits ( stiff, [ N/m ] );

stiff  = 10 N/m;
stiff  = 20 N/m;
stiff  = 30 N/m;

PrintMatrix(stiff);
```

generates the output:

```    MATRIX : "stiff"

row/col                  1            2            3
units          N/m          N/m          N/m
1            1.00000e+01  0.00000e+00  0.00000e+00
2            0.00000e+00  2.00000e+01  0.00000e+00
3            0.00000e+00  0.00000e+00  3.00000e+01
```

The Matrix() function takes care of the dynamic allocation of memory for "stiff" ... and the ColumnUnits() function assigns the units of Newtons per meter to each column.

Example 9 : Only one command line is needed to specify a matrix having a common set of column units. As a case in point, our test matrix "stiff" could have been allocated with :

```    stiff = ColumnUnits ( Matrix([3,3]) , [ N/m ] );
```

### PRINTING MATRICES WITH SCALED ROW/COLUMN UNITS

Note : Text in this section applies to ALADDIN 2.0 (scheduled for release in July-August 1997).

Matrices may be printed with either the row units (or column units) scaled to a desirable range.

The function syntax is:

```    PrintMatrixCast ( matrix1, ..., matrixN, [ units matrix ] );
```

Here matrix1 through matrixN are N matrices having the row or column units listed in

```    [ units matrix ]
```

Column units are scaled by supplying a units matrix having one row and more than one column. Row units are scaled by supplying a units matrix having more than one row and only one column.

An error condition will occur if terms in the units matrix do not match any of the terms in matrices matrix1 through matrixN.

Example 10 : The block of statements:

```    stiff = Matrix([3,3]);
stiff = ColumnUnits ( stiff, [ N/m , N/m , N/rad ] );

stiff  = 10 N/m;
stiff  = 20 N/m;

PrintMatrixCast(stiff, [ N/cm, kN/rad ] );
```

generates the output:

```    MATRIX : "stiff"

row/col                  1            2            3
1            1.00000e-01  0.00000e+00  0.00000e+00
2            0.00000e+00  2.00000e-01  0.00000e+00
3            0.00000e+00  0.00000e+00  3.00000e-02
```

Example 11 : The block of statements:

```    spectra = Matrix( [3,2] );
spectra = ColumnUnits( spectra, [sec],      );
spectra = ColumnUnits( spectra, [cm/sec^2], );

spectra [ 1] = 0.0 sec;  spectra [ 1] = 981.0*0.15 cm/sec/sec;
spectra [ 2] = 0.1 sec;  spectra [ 2] = 981.0*0.18 cm/sec/sec;
spectra [ 3] = 0.2 sec;  spectra [ 3] = 981.0*0.25 cm/sec/sec;

PrintMatrix (spectra);

spectra = ColumnUnits( spectra, [ft/sec^2], );
PrintMatrixCast (spectra , [sec, cm/sec^2] );
PrintMatrixCast (spectra , [sec, in/sec^2] );
```

generates the output:

```    MATRIX : "spectra"

row/col                  1            2
units          sec      m/sec^2
1            0.00000e+00  1.47150e+00
2            1.00000e-01  1.76580e+00
3            2.00000e-01  2.45250e+00

MATRIX : "spectra"

row/col                  1            2
units          sec     cm/sec^2
1            0.00000e+00  1.47150e+02
2            1.00000e-01  1.76580e+02
3            2.00000e-01  2.45250e+02

MATRIX : "spectra"

row/col                  1            2
units          sec     in/sec^2
1            0.00000e+00  5.79331e+01
2            1.00000e-01  6.95197e+01
3            2.00000e-01  9.65551e+01
```

The first and second columns of "spectra" contain quantities of time and acceleration, respectively. Here we define the accelerations in terms of cm/sec/sec, and then use the PrintMatrixCast function to scale the output to an appropriate set of units.

Developed in April 1996 by Mark Austin