% Copyright The Numerical Algorithms Group Limited 1991.
% Certain derivative-work portions Copyright (C) 1988 by Leslie Lamport.
% All rights reserved

% Title: Matrices

\begin{page}{ExMatrixBasicFunction}{Basic Arithmetic Operations on Matrices}
\beginscroll
You can create a matrix using the function \spadfun{matrix}.
The function takes a list of lists of elements of the ring and produces a
matrix whose \spad{i}th row contains the elements of the \spad{i}th list.
For example:
\spadpaste{m1 := matrix([[1,-2,1],[4,2,-4]]) \bound{m1}}
\spadpaste{m2 := matrix([[1,0,2],[20,30,10],[0,200,100]]) \bound{m2}}
\spadpaste{m3 := matrix([[1,2,3],[2,4,6]]) \bound{m3}}
Some of the basic arithmetic operations on matrices are:
\spadpaste{m1 + m3 \free{m1} \free{m3}}
\spadpaste{100 * m1 \free{m1}}
\spadpaste{m1 * m2 \free{m1} \free{m2}}
\spadpaste{-m1 + m3 * m2 \free{m1} \free{m2} \free{m3}}
You can also multiply a matrix and a vector provided
that the matrix and vector have compatible dimensions.
\spadpaste{m3 *vector([1,0,1]) \free{m3}}
However, the dimensions of the matrices must be compatible in order for
\Language{} to perform an operation - otherwise an error message will occur.
\endscroll
\autobuttons\end{page}


\begin{page}{ExConstructMatrix}{Constructing new Matrices}
\beginscroll
A number of functions exist for constructing new matrices from existing ones.

If you want to create a matrix whose entries are 0 except on the main
diagonal you can use \spadfun{diagonalMatrix}.
This function takes a list of ring elements as an argument and returns a
square matrix which has these elements on the main diagonal.
Consider the following example:
\spadpaste{diagonalMatrix([1,2,3,2,1])}

The function \spadfun{subMatrix}(\spad{a},\spad{i},\spad{j},\spad{k},\spad{l}) 
constructs a new matrix
consisting of rows \spad{i} through \spad{j} and columns \spad{k} through 
\spad{l} of \spad{a} , inclusive.
\spadpaste{subMatrix(matrix([[0,1,2,3,4],[5,6,7,8,9],[10,11,12,13,14]]), 1,3,2,4)}


The functions \spadfun{horizConcat} and \spadfun{vertConcat} 
concatenate matrices
horizontally and vertically, respectively.
\spadpaste{horizConcat(matrix([[1,2,3],[6,7,8]]),matrix([[11,12,13],[55,77,88]])) }
\spadpaste{vertConcat(matrix([[1,2,3],[6,7,8]]),matrix([[11,12,13],[55,77,88]])) }


The function \spadfunX{setsubMatrix}(\spad{a},\spad{i},\spad{k},\spad{b}) 
replaces the submatrix of \spad{a}
starting at row \spad{i} and column \spad{k} with the elements of the matrix i\spad{b}.
\spadpaste{b:=matrix([[0,1,2,3,4],[5,6,7,8,9],[10,11,12,13,14]]) \bound{b}}
\spadpaste{setsubMatrix!(b,1,1,transpose(subMatrix(b,1,3,1,3)))\free{b}}
changes the submatrix of \spad{b} consisting of the first 3 rows and columns
to its transpose.
\endscroll
\autobuttons\end{page}


\begin{page}{ExTraceMatrix}{Trace of a Matrix}
\beginscroll
If you have a square matrix, then you can compute its `trace'.
The function \spadfun{trace} computes the sum of all elements on the diagonal
of a matrix.
For example `trace' for a four by four Vandermonde matrix.
\spadpaste{trace( matrix([[1,x,x**2,x**3],[1,y,y**2,y**3],[1,z,z**2,z**3],[1,u,u**2,u**3]]) )}
\endscroll
\autobuttons\end{page}

\begin{page}{ExDeterminantMatrix}{Determinant of a Matrix}
\beginscroll
The function \spadfun{determinant} computes the determinant of a matrix over a
commutative ring, that is a ring whose multiplication is commutative.
\spadpaste{determinant(matrix([[1,2,3,4],[2,3,2,5],[3,4,5,6],[4,1,6,7]]))}
\endscroll
\autobuttons\end{page}

\begin{page}{ExInverseMatrix}{Inverse of a Matrix}
\beginscroll
The function \spadfun{inverse} computes the inverse of a square matrix.
\spadpaste{inverse(matrix([[1,2,1],[-2,3,4],[-1,5,6]])) }
(If the inverse doesn't exist, then \Language{} returns `failed'.)
\endscroll
\autobuttons\end{page}

\begin{page}{ExRankMatrix}{Rank of a Matrix}
\beginscroll
The function \spadfun{rank} gives you the rank of a matrix:
\spadpaste{rank(matrix([[0,4,1],[5,3,-7],[-5,5,9]]))}
\endscroll
\autobuttons\end{page}