[ Matrices of Numbers ]
[ Matrix Elements ]
[ Matrices of Quantities with Units ]
[ Printing Matrices ]

[ Functions for Matrix Allocation ]
[ Row Units and Column Units ]

[ Printing Matrices with Scaled Row/Column Units ]

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

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 ];

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[1][1] = ", Z[1][1], "\n"; print "Z[2][1] = ", Z[2][1], "\n"; print "Z[1][2] = ", Z[1][2], "\n"; print "Z[2][2] = ", Z[2][2], "\n";and the output will be

Z[1][1] = 1 Z[2][1] = 2 Z[1][2] = 3 Z[2][2] = 4

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

Z[1][1], Z[1][2] ...

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.

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[1][1]*box[1][2]*box[1][3], "\n";

The output is:

volume of box = 162 m^3

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.

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.

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([30]); /* [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([30]); 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]);

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 [1][1] = 10 N/m; stiff [2][2] = 20 N/m; stiff [3][3] = 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 ] );

** 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 [1][1] = 10 N/m; stiff [2][2] = 20 N/m; stiff [3][3] = 30 N/rad; PrintMatrixCast(stiff, [ N/cm, kN/rad ] );

generates the output:

MATRIX : "stiff" row/col 1 2 3 units N/cm N/cm kN/rad 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], [1]); spectra = ColumnUnits( spectra, [cm/sec^2], [2]); spectra [ 1][1] = 0.0 sec; spectra [ 1][2] = 981.0*0.15 cm/sec/sec; spectra [ 2][1] = 0.1 sec; spectra [ 2][2] = 981.0*0.18 cm/sec/sec; spectra [ 3][1] = 0.2 sec; spectra [ 3][2] = 981.0*0.25 cm/sec/sec; PrintMatrix (spectra); spectra = ColumnUnits( spectra, [ft/sec^2], [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.