%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  math_matrix.tex       LiDIA documentation
%%
%%  This file contains the documentation of the class bigint_matrix
%%
%%  Copyright   (c)   1995   by  LiDIA-Group 
%%
%%  Authors: Patrick Theobald
%%  

\markright{\BF{math\_matrix}}
\begin{lidia_man}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{math\_matrix\TEMPL{T}} \DOTFILL parametrized matrix class with basic mathematical operations

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\BF{math\_matrix\TEMPL{T}} is a class for doing simple mathematical operations over matrices 
of type \BF{T} which is allowed to be either a built--in type or a class such as matrix multiplication or addition.
\medskip\\
According to the template introduction (see page \pageref{template_introduction2})
the class \BF{math\_matrix\TEMPL{T}} is derived from 
\BF{base\_matrix\TEMPL{T}}. So you can apply all the functions and operators of class 
\BF{base\_matrix\TEMPL{T}} to instances of the type \BF{math\_matrix\TEMPL{T}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
A variable of type \BF{math\_matrix\TEMPL{T}} contains the same components as \BF{base\_matrix\TEMPL{T}}.

In the following descriptions we use \MATH{A.rows} to label the number of rows and \MATH{A.columns} to 
label the number of columns of matrix \MATH{A}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS
If \MATH{a\LE 0} or \MATH{b\LE 0} or \MATH{v = NULL} in one of the following constructors the 
\TT{lidia\_error\_handler} will be invoked. 


\fcode{ct}{math\_matrix\TEMPL{T}}{}
{
constructs a \MATH{1 \TIMES 1} matrix initialized with values generated by the 
default constructor for type \BF{T}.}

\fcode{ct}{math\_matrix\TEMPL{T}}{lidia\_size\_t a\k lidia\_size\_t b}
{
constructs an \MATH{a \TIMES b} matrix initialized with values generated by the 
default constructor for type \BF{T}.}

\fcode{ct}{math\_matrix\TEMPL{T}}{lidia\_size\_t a\k lidia\_size\_t b\k const T **v}
{
constructs an \MATH{a \TIMES b} matrix initialized with the values of the 2-dimensional array 
\MATH{v}. The behaviour of this constructor is undefined if the array \MATH{v} has less 
than \MATH{a} rows or less than \MATH{b} columns.}

\fcode{ct}{math\_matrix\TEMPL{T}}{const math\_matrix\TEMPL{T} \& A}
{
constructs a copy of matrix A.}

\fcode{dt}{\SIM math\_matrix\TEMPL{T}}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ARTH
The class \BF{math\_matrix\TEMPL{T}} supports the following operators:\hfill\\
\begin{tabular}{|c|rcl|l|}\hline
unary & & \MATH{op} & math\_matrix\TEMPL{T} & \MATH{op\IN\{\TT{-}\}} \\\hline
binary & math\_matrix\TEMPL{T} & \MATH{op} & math\_matrix\TEMPL{T} 
& \MATH{op\IN\{\TT{+},\TT{-},\TT{*}\}}\\\hline
binary with & math\_matrix\TEMPL{T} & \MATH{op} & math\_matrix\TEMPL{T}
& \MATH{op\IN\{\TT{+=},\TT{-=},\TT{*=}\}}\\
assignment & & & &\\\hline
binary & math\_matrix\TEMPL{T} & \MATH{op} & T
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*},\TT{/}\}}\\\hline
binary & T & \MATH{op} & math\_matrix\TEMPL{T}
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*}\}}\\\hline
binary with & math\_matrix\TEMPL{T} & \MATH{op} & T
& \MATH{op \IN\{\TT{+=},\TT{-=},\TT{*=},\TT{/=}\}}\\
assignment & & & &\\\hline
binary & math\_matrix\TEMPL{T} & \MATH{op} & (T *) & \MATH{op \IN\{\TT{*}\}}\\\hline
binary & (T *) & \MATH{op} & math\_matrix\TEMPL{T} & \MATH{op \IN\{\TT{*}\}}\\\hline
binary & math\_matrix\TEMPL{T} & \MATH{op} & math\_vector\TEMPL{T} 
& \MATH{op \IN\{\TT{*}\}}\\\hline
binary & math\_vector\TEMPL{T} & \MATH{op} & math\_matrix\TEMPL{T} 
& \MATH{op \IN\{\TT{*}\}}\\\hline
\end{tabular}

Here the operators operating on two matrices and the unary minus implement the usual operations known from 
linear algebra. If the dimensions of the operands do not fulfill the usual restrictions,
the \TT{lidia\_error\_handler} will be invoked. Note that the dimensions of the resulting matrix are
adapted to the right dimensions known from linear algebra if necessary.

The operators\hfill\\
\centerline{\TT{math\_matrix\TEMPL{T}\ * (T *)}}
\centerline{\TT{(T *) * math\_matrix\TEMPL{T}}}
\centerline{\TT{math\_matrix\TEMPL{T}\ * math\_vector\TEMPL{T}}}
\centerline{\TT{math\_vector\TEMPL{T}\ * math\_matrix\TEMPL{T}}}
realize the matrix vector multiplication and the vector matrix multiplication. If the number of elements
does not fulfill the usual restrictions known from linear algebra the \TT{lidia\_error\_handler} will be invoked in
case of vectors or the behaviour is undefined in case of arrays.

The operators \MATH{op} which have a single element of type \BF{T} in
their list of arguments perform the operation \MATH{op} 
componentwise, e.g.~\TT{T * math\_matrix\TEMPL{T}} multiplies 
each entry of the matrix by the given scalar.

To avoid copying, all operators also exist as functions and of course the restrictions for the dimensions are 
still valid:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Addition}
\fcode{void}{add}{math\_matrix\TEMPL{T} \& C\k const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
\MATH{C=A+B}.}

\fcode{void}{add}{math\_matrix\TEMPL{T} \& C\k const math\_matrix\TEMPL{T} \& B\k const T \& e}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
b_{0,0}+e & \LDOTS & b_{0,c-1}+e\\
\vdots & \ddots & \vdots \\
b_{r-1,0}+e & \LDOTS & b_{r-1,c-1}+e
\end{array}\RIGHT).\]}

\fcode{void}{add}{math\_matrix\TEMPL{T} \& C\k const T \& e\k const math\_matrix\TEMPL{T} \& B}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
e+b_{0,0} & \LDOTS & e+b_{0,c-1}\\
\vdots & \ddots & \vdots \\
e+b_{r-1,0} & \LDOTS & e+b_{r-1,c-1}
\end{array}\RIGHT).\]}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Subtraction}
\fcode{void}{subtract}{math\_matrix\TEMPL{T} \& C\k const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
\MATH{C=A-B}.}

\fcode{void}{subtract}{math\_matrix\TEMPL{T} \& C\k const math\_matrix\TEMPL{T} \& B\k const T \& e}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
b_{0,0}-e & \LDOTS & b_{0,c-1}-e\\
\vdots & \ddots & \vdots \\
b_{r-1,0}-e & \LDOTS & b_{r-1,c-1}-e
\end{array}\RIGHT).\]}

\fcode{void}{subtract}{math\_matrix\TEMPL{T} \& C\k const T \& e\k const math\_matrix\TEMPL{T} \& B}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
e-b_{0,0} & \LDOTS & e-b_{0,c-1}\\
\vdots & \ddots & \vdots \\
e-b_{r-1,0} & \LDOTS & e-b_{r-1,c-1}
\end{array}\RIGHT).\]}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Multiplication}
\fcode{void}{multiply}{math\_matrix\TEMPL{T} \& C\k const math\_matrix\TEMPL{T} \& A\k           const math\_matrix\TEMPL{T} \& B}
{
\MATH{C=A*B}.}


\fcode{void}{multiply}{math\_matrix\TEMPL{T}\& C\k const math\_matrix\TEMPL{T} \& B\k const T \& e}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
b_{0,0}*e & \LDOTS & b_{0,c-1}*e\\
\vdots & \ddots & \vdots \\
b_{r-1,0}*e & \LDOTS & b_{r-1,c-1}*e
\end{array}\RIGHT).\]}

\fcode{void}{multiply}{math\_matrix\TEMPL{T}\& C\k const T \& e\k const math\_matrix\TEMPL{T} \& B}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
e*b_{0,0} & \LDOTS & e*b_{0,c-1}\\
\vdots & \ddots & \vdots \\
e*b_{r-1,0} & \LDOTS & e*b_{r-1,c-1}
\end{array}\RIGHT).\]}


\fcode{void}{compwise\_multiply}{math\_matrix\TEMPL{T}\& C\k const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
Let \MATH{r=B.rows=A.rows} and \MATH{c=B.columns=A.columns}. 
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
a_{0,0}*b_{0,0} & \LDOTS & a_{0,c-1}*b_{0,c-1}\\
\vdots & \ddots & \vdots \\
a_{r-1,0}*b_{r-1,0} & \LDOTS & a_{r-1,c-1}*b_{r-1,c-1}
\end{array}\RIGHT).\]}


\fcode{void}{multiply}{T *\&v\k const math\_matrix\TEMPL{T} \& A\k const T *w}
{
assigns the result of the muliplication \MATH{A * w} to \MATH{v}
(matrix vector multiplication). If no memory has been allocated for the array \MATH{w},
the \TT{lidia\_error\_handler} will be invoked. If the array \MATH{w} has less than \MATH{A.columns} 
elements, the behaviour of this function is undefined. Note
that if \MATH{v=NULL}, this function allocates memory in the
right size and if the array \MATH{v} has less than \MATH{A.rows} elements, the 
behaviour of this function is undefined.}

\fcode{void}{multiply}{math\_vector\TEMPL{T} \& v\k const math\_matrix\TEMPL{T} \& A\k const math\_vector\TEMPL{T} \& w}
{
assigns the result of the muliplication \MATH{A * w} to vector \MATH{v}
(matrix vector multiplication). If \MATH{w.size \not = A.columns}, the 
\TT{lidia\_error\_handler} will be invoked. Note, that if vector \MATH{v} has less than \MATH{A.rows}
elements, the size is adapted automatically.}


\fcode{void}{multiply}{T *\&v\k const T *w\k const math\_matrix\TEMPL{T} \& A}
{
assigns the result of the muliplication \MATH{w * A} to \MATH{v}
(vector matrix multiplication). If no memory has been allocated for the array \MATH{w},
the \TT{lidia\_error\_handler} will be invoked. If the array \MATH{w} has less than \MATH{A.rows} 
elements, the behaviour of this function is undefined. Note
that if \MATH{v=NULL}, this function allocates memory in the
right size and if array \MATH{v} has less than \MATH{A.columns} elements, the 
behaviour of this function is undefined.}

\fcode{void}{multiply}{math\_vector\TEMPL{T} \& v\k const math\_vector\TEMPL{T} \& w\k const math\_matrix\TEMPL{T} \& A}
{
assigns the result of the muliplication \MATH{w * A} to vector \MATH{v}
(vector matrix multiplication). If \MATH{w.size \not = A.rows}, the 
\TT{lidia\_error\_handler} will be invoked. Note that if vector \MATH{v} has less than \MATH{A.columns}
elements, the size is adapted automatically.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Division}
\fcode{void}{divide}{math\_matrix\TEMPL{T}\& C\k const math\_matrix\TEMPL{T} \& B\k const T \& e}
{
Let \MATH{r=B.rows} and \MATH{c=B.columns}.
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
b_{0,0}/e & \LDOTS & b_{0,c-1}/e\\
\vdots & \ddots & \vdots \\
b_{r-1,0}/e & \LDOTS & b_{r-1,c-1}/e
\end{array}\RIGHT).\]}


\fcode{void}{compwise\_divide}{math\_matrix\TEMPL{T}\& C\k const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
Let \MATH{r=B.rows=A.rows} and \MATH{c=B.columns=A.columns}. 
\[\LEFT(\begin{array}{ccc}
c_{0,0} & \LDOTS & c_{0,c-1}\\
\vdots & \ddots & \vdots \\
c_{r-1,0} & \LDOTS & c_{r-1,c-1}
\end{array}\RIGHT)=
\LEFT(\begin{array}{ccc}
a_{0,0}/b_{0,0} & \LDOTS & a_{0,c-1}/b_{0,c-1}\\
\vdots & \ddots & \vdots \\
a_{r-1,0}/b_{r-1,0} & \LDOTS & a_{r-1,c-1}/b_{r-1,c-1}
\end{array}\RIGHT).\]}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Negation}
\fcode{void}{negate}{math\_matrix\TEMPL{T}\& B\k const math\_matrix\TEMPL{T} \& A}
{
\MATH{B = -A}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\COMP
The  binary operators \TT{==} and \TT{!=} are overloaded and can be used for comparison by components. 
Let \MATH{A} be an instance of type \BF{math\_matrix\TEMPL{T}}.


\cfcode{bool}{A.equal}{const math\_matrix\TEMPL{T} \& B}
{
returns \TRUE\ if \MATH{A} and \MATH{B} are identical, \FALSE\ otherwise.}

\fcode{bool}{equal}{const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
returns \TRUE\ if \MATH{A} and \MATH{B} are identical, \FALSE\ otherwise.}

\cfcode{bool}{A.unequal}{const math\_matrix\TEMPL{T} \& B}
{
returns \FALSE\ if \MATH{A} and \MATH{B} are identical, \TRUE\ otherwise.}

\fcode{bool}{unequal}{const math\_matrix\TEMPL{T} \& A\k const math\_matrix\TEMPL{T} \& B}
{
returns \FALSE\ if \MATH{A} and \MATH{B} are identical, \TRUE\ otherwise.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Trace}
\cfcode{void}{A.trace}{T \& tr}
{
assigns the trace of matrix \MATH{A} to \MATH{tr}.}

\cfcode{T}{A.trace}{}
{
returns the trace of matrix \MATH{A}.}

\fcode{T}{trace}{const math\_matrix\TEMPL{T} \& A}
{
returns the trace of matrix \MATH{A}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
\BF{base\_matrix}, \BF{bigint\_matrix}, \BF{base\_vector}, \BF{math\_vector}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NOTES
As described in the template introduction (see page \pageref{template_introduction2})
for using an instance of type \BF{math\_matrix\TEMPL{T}}\ the type \BF{T} has to have at
least
\begin{itemize}
\item a swap--function \TT{void swap(T \&, T\&)},
\item the input--operator \TT{>>},
\item the output--operator \TT{<<},
\item the assignment--operator \TT{=}, 
\item the multiply--operator \TT{*}, 
\item the addition--operator \TT{+}, 
\item the division--operator \TT{/}, 
\item the subtract--operator \TT{-}, 
\item the unary minus \TT{-} and 
\item the equal--operator \TT{==}.
\end{itemize}

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/math_matrix.h>
 #include <LiDIA/lidia.h>

 main()
 {
   math_matrix < double > A, B;
   cin >> A >> B;
   cout << ``trace(A)='' << trace(A) << endl << flush;
   cout << ``trace(A+B)='' << trace(A+B) << endl << flush;
   cout << ``trace(A*B)='' << trace(A*B) << endl << flush;
 }
\end{verbatim}        

For further examples please refer to\\
\TT{LiDIA/src/simple\_classes/math\_matrix\_appl.c}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Stefan Neis, Patrick Theobald

\end{lidia_man}



