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


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

\NAME

\CLASS{math_matrix< T >} \dotfill parametrized matrix class with basic mathematical
operations


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

\ABSTRACT

\code{math_matrix< T >} is a class for doing simple mathematical operations over matrices of
type \code{T} which is allowed to be either a built-in type or a class such as matrix
multiplication or addition.

According to the template introduction (see page \pageref{template_introduction2}) the class
\code{math_matrix< T >} is derived from \code{base_matrix< T >}.  So you can apply all the
functions and operators of class \code{base_matrix< T >} to instances of the type
\code{math_matrix< T >}.


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

\DESCRIPTION

A variable of type \code{math_matrix< T >} contains the same components as \code{base_matrix< T
  >}.

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


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

\CONS

If $a\leq 0$ or $b\leq 0$ or $v = \code{NULL}$ in one of the following constructors the \LEH
will be invoked.

\begin{fcode}{ct}{math_matrix< T >}{}
  constructs a $1 \times 1$ matrix initialized with values generated by the default constructor
  for type \code{T}.
\end{fcode}

\begin{fcode}{ct}{math_matrix< T >}{lidia_size_t $a$, lidia_size_t $b$}
  constructs an $a \times b$ matrix initialized with values generated by the default constructor
  for type \code{T}.
\end{fcode}

\begin{fcode}{ct}{math_matrix< T >}{lidia_size_t $a$, lidia_size_t $b$, const T ** $v$}
  constructs an $a \times b$ matrix initialized with the values of the 2-dimensional array $v$.
  The behaviour of this constructor is undefined if the array $v$ has less than $a$ rows or less
  than $b$ columns.
\end{fcode}

\begin{fcode}{ct}{math_matrix< T >}{const math_matrix< T > & $A$}
  constructs a copy of matrix $A$.
\end{fcode}

\begin{fcode}{dt}{~math_matrix< T >}{}
\end{fcode}


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

\ARTH

The class \code{math_matrix< T >} supports the following operators:
\begin{center}
  \begin{tabular}{|c|rcl|l|}\hline
    unary & & $op$ & \code{math_matrix< T >} & $op \in \{ \code{-} \}$ \\\hline
    binary & \code{math_matrix< T >} & $op$ & \code{math_matrix< T >}
    & $op \in \{ \code{+}, \code{-}, \code{*} \}$\\\hline
    binary with & \code{math_matrix< T >} & $op$ & \code{math_matrix< T >}
    & $op \in \{ \code{+=}, \code{-=}, \code{*=} \}$\\
    assignment & & & &\\\hline
    binary & \code{math_matrix< T >} & $op$ & \code{T}
    & $op \in \{ \code{+}, \code{-}, \code{*}, \code{/} \}$\\\hline
    binary & \code{T} & $op$ & \code{math_matrix< T >}
    & $op \in \{ \code{+}, \code{-}, \code{*} \}$\\\hline
    binary with & \code{math_matrix< T >} & $op$ & \code{T}
    & $op \in \{ \code{+=}, \code{-=}, \code{*=}, \code{/=} \}$\\
    assignment & & & &\\\hline
    binary & \code{math_matrix< T >} & $op$ & \code{(T *)} & $op \in \{ \code{*} \}$\\\hline
    binary & \code{(T *)} & $op$ & \code{math_matrix< T >} & $op \in \{ \code{*} \}$\\\hline
    binary & \code{math_matrix< T >} & $op$ & \code{math_vector< T >}
    & $op \in \{ \code{*} \}$\\\hline
    binary & \code{math_vector< T >} & $op$ & \code{math_matrix< T >}
    & $op \in \{ \code{*} \}$\\\hline
  \end{tabular}
\end{center}
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 satisfy the usual
restrictions, the \LEH 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
\begin{center}
  \code{math_matrix< T > * (T *)}\\
  \code{(T *) * math_matrix< T >}\\
  \code{math_matrix< T > * math_vector< T >}\\
  \code{math_vector< T > * math_matrix< T >}
\end{center}
realize the matrix vector multiplication and the vector matrix multiplication.  If the number of
elements does not satisfy the usual restrictions known from linear algebra the \LEH will be
invoked in case of vectors or the behaviour is undefined in case of arrays.

The operators $op$ which have a single element of type \code{T} in their list of arguments
perform the operation $op$ componentwise, e.g.~\code{T * math_matrix< 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}

\begin{fcode}{void}{add}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$}
  $C \assign A + B$.
\end{fcode}

\begin{fcode}{void}{add}{math_matrix< T > & $C$, const math_matrix< T > & $B$, const T & $e$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      b_{0,0}+e & \dots & b_{0,c-1}+e\\
      \vdots & \ddots & \vdots \\
      b_{r-1,0}+e & \dots & b_{r-1,c-1}+e
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}

\begin{fcode}{void}{add}{math_matrix< T > & $C$, const T & $e$, const math_matrix< T > & $B$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      e+b_{0,0} & \dots & e+b_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      e+b_{r-1,0} & \dots & e+b_{r-1,c-1}
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}


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

\SSTITLE{Subtraction}

\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$}
  $C \assign A - B$.
\end{fcode}

\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const math_matrix< T > & $B$, const T & $e$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      b_{0,0}-e & \dots & b_{0,c-1}-e\\
      \vdots & \ddots & \vdots \\
      b_{r-1,0}-e & \dots & b_{r-1,c-1}-e
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}

\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const T & $e$, const math_matrix< T > & $B$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      e-b_{0,0} & \dots & e-b_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      e-b_{r-1,0} & \dots & e-b_{r-1,c-1}
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}


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

\SSTITLE{Multiplication}

\begin{fcode}{void}{multiply}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$}
  $C \assign A \cdot B$.
\end{fcode}

\begin{fcode}{void}{multiply}{math_matrix< T >& $C$, const math_matrix< T > & $B$, const T & $e$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      b_{0,0} \cdot e & \dots & b_{0,c-1} \cdot e\\
      \vdots & \ddots & \vdots \\
      b_{r-1,0} \cdot e & \dots & b_{r-1,c-1} \cdot e
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}

\begin{fcode}{void}{multiply}{math_matrix< T >& $C$, const T & $e$, const math_matrix< T > & $B$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      e \cdot b_{0,0} & \dots & e \cdot b_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      e \cdot b_{r-1,0} & \dots & e \cdot b_{r-1,c-1}
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}


\begin{fcode}{void}{compwise_multiply}{math_matrix< T >& $C$,
    const math_matrix< T > & $A$, const math_matrix< T > & $B$}%
  Let $r = \code{$B$.rows} = \code{$A$.rows}$ and $c = \code{$B$.columns} = \code{$A$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix}=
    \begin{pmatrix}
      a_{0,0} \cdot b_{0,0} & \dots & a_{0,c-1} \cdot b_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      a_{r-1,0} \cdot b_{r-1,0} & \dots & a_{r-1,c-1} \cdot b_{r-1,c-1}
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}

\begin{fcode}{void}{multiply}{T *& $v$, const math_matrix< T > & $A$, const T * $w$}
  assigns the result of the muliplication $A \cdot w$ to $v$ (matrix vector multiplication).  If
  no memory has been allocated for the array $w$, the \LEH will be invoked.  If the array $w$
  has less than \code{$A$.columns} elements, the behaviour of this function is undefined.  Note
  that if $v = \code{NULL}$, this function allocates memory in the right size and if the array
  $v$ has less than \code{$A$.rows} elements, the behaviour of this function is undefined.
\end{fcode}

\begin{fcode}{void}{multiply}{math_vector< T > & $v$, const math_matrix< T > & $A$, const math_vector< T > & $w$}
  assigns the result of the muliplication $A \cdot w$ to vector $v$ (matrix vector
  multiplication).  If $w.size \neq \code{$A$.columns}$, the \LEH will be invoked.  Note, that
  if vector $v$ has less than \code{$A$.rows} elements, the size is adapted automatically.
\end{fcode}

\begin{fcode}{void}{multiply}{T *& $v$, const T * $w$, const math_matrix< T > & $A$}
  assigns the result of the muliplication $w \cdot A$ to $v$ (vector matrix multiplication).  If
  no memory has been allocated for the array $w$, the \LEH will be invoked.  If the array $w$
  has less than \code{$A$.rows} elements, the behaviour of this function is undefined.  Note
  that if $v = \code{NULL}$, this function allocates memory in the right size and if array $v$
  has less than \code{$A$.columns} elements, the behaviour of this function is undefined.
\end{fcode}

\begin{fcode}{void}{multiply}{math_vector< T > & $v$, const math_vector< T > & $w$, const math_matrix< T > & $A$}
  assigns the result of the muliplication $w \cdot A$ to vector $v$ (vector matrix
  multiplication).  If $w.size \neq \code{$A$.rows}$, the \LEH will be invoked.  Note that if
  vector $v$ has less than \code{$A$.columns} elements, the size is adapted automatically.
\end{fcode}


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

\SSTITLE{Division}

\begin{fcode}{void}{divide}{math_matrix< T >& $C$, const math_matrix< T > & $B$, const T & $e$}
  Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      b_{0,0}/e & \dots & b_{0,c-1}/e\\
      \vdots & \ddots & \vdots \\
      b_{r-1,0}/e & \dots & b_{r-1,c-1}/e
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}

\begin{fcode}{void}{compwise_divide}{math_matrix< T >& $C$,
    const math_matrix< T > & $A$, const math_matrix< T > & $B$}%
  Let $r = \code{$B$.rows} = \code{$A$.rows}$ and $c = \code{$B$.columns} = \code{$A$.columns}$.
  \begin{displaymath}
    \begin{pmatrix}
      c_{0,0} & \dots & c_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      c_{r-1,0} & \dots & c_{r-1,c-1}
    \end{pmatrix} =
    \begin{pmatrix}
      a_{0,0}/b_{0,0} & \dots & a_{0,c-1}/b_{0,c-1}\\
      \vdots & \ddots & \vdots \\
      a_{r-1,0}/b_{r-1,0} & \dots & a_{r-1,c-1}/b_{r-1,c-1}
    \end{pmatrix} \enspace.
  \end{displaymath}
\end{fcode}


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

\SSTITLE{Negation}

\begin{fcode}{void}{negate}{math_matrix< T >& $B$, const math_matrix< T > & $A$}
  $B \assign -A$.
\end{fcode}


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

\COMP

The binary operators \code{==} and \code{!=} are overloaded and can be used for comparison by
components.  Let $A$ be an instance of type \code{math_matrix< T >}.

\begin{cfcode}{bool}{$A$.equal}{const math_matrix< T > & $B$}
  returns \TRUE if $A$ and $B$ are identical, \FALSE otherwise.
\end{cfcode}

\begin{fcode}{bool}{equal}{const math_matrix< T > & $A$, const math_matrix< T > & $B$}
  returns \TRUE if $A$ and $B$ are identical, \FALSE otherwise.
\end{fcode}

\begin{cfcode}{bool}{$A$.unequal}{const math_matrix< T > & $B$}
  returns \FALSE if $A$ and $B$ are identical, \TRUE otherwise.
\end{cfcode}

\begin{fcode}{bool}{unequal}{const math_matrix< T > & $A$, const math_matrix< T > & $B$}
  returns \FALSE if $A$ and $B$ are identical, \TRUE otherwise.
\end{fcode}


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

\STITLE{Trace}

\begin{cfcode}{void}{$A$.trace}{T & $\mathit{tr}$}
  assigns the trace of matrix $A$ to $\mathit{tr}$.
\end{cfcode}

\begin{cfcode}{T}{$A$.trace}{}
  returns the trace of matrix $A$.
\end{cfcode}

\begin{fcode}{T}{trace}{const math_matrix< T > & $A$}
  returns the trace of matrix $A$.
\end{fcode}


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

\SEEALSO

\SEE{base_matrix}, \SEE{bigint_matrix},
\SEE{base_vector}, \SEE{math_vector}


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

\NOTES

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


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

\EXAMPLES

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

int main()
{
    math_matrix < double > A, B;

    cin >> A >> B;
    cout << "trace(A) = " << trace(A) << endl;
    cout << "trace(A+B) = " << trace(A+B) << endl;
    cout << "trace(A*B) = " << trace(A*B) << endl;

    return 0;
}
\end{verbatim}
\end{quote}

For further examples please refer to \path{LiDIA/src/simple_classes/math_matrix_appl.cc}.

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

\AUTHOR

Stefan Neis, Patrick Theobald
