%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  use_vecmat.tex       LiDIA documentation
%%
%%  This file contains the documentation of the vector classes
%%  
%%  Copyright   (c)   1995   by  LiDIA-Group 
%%
%%  Authors: Frank Lehmann, Markus Maurer,
%%           Patrick Theobald, Stefan Neis
%%

\markright{\BF{using vectors and matrices}}
\begin{lidia_man}
\label{template_introduction}

\DESCRIPTION
In this \LiDIA\ release a new concept for vectors and matrices is realized. 

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

\STITLE{\LARGE{Vector}}
\SSTITLE{Structure}
The base class of this structure is \BF{base\_vector}. By a first derivation step we
obtain the vector classes \BF{math\_vector}, \BF{sort\_vector}, and \BF{file\_vector};
by a second step we merge all these to \BF{lidia\_vector} itself. This structure is shown in the following diagram:

\input epsf

\bigskip
\centerline
{
\epsfxsize=8cm
\epsfbox{EPS/lidia_vector_use.eps}
}
\bigskip

The notation ''B \MATH{\LEFTARROW} D'' indicates class--inclusion and thus says that B is a base class of 
the derived class D.

The different vector classes are distinguished by the requirements on the type \BF{T}, to which the elements 
of a vector belong. Each step of inheritance in the structure requires
more properties for the type \BF{T} 
used in the template. 

In the following tabular \MATH{a} is of type \BF{T}.
\begin{center}
\begin{tabular}{|c|c|}\hline
class & required functions of type \BF{T}\\\hline\hline
base\_vector & \TT{void swap(T \&, T\&)}\\
& \TT{void operator = (T \&, const T \&)}\\\hline
math\_vector & \TT{void swap(T \&, T\&)} \\
& \TT{void operator = (T \&, const T \&)}\\
& \TT{bool operator == (const T \&, const T \&)}\\
& \TT{T operator - (const T \&)}\\
& \TT{T operator + (const T \&, const T \&)}\\
& \TT{T operator - (const T \&, const T \&)}\\
& \TT{T operator * (const T \&, const T \&)}\\
& \TT{T operator / (const T \&, const T \&)}\\\hline
file\_vector & \TT{void swap(T \&, T\&)} \\
& \TT{void operator = (T \&, const T \&)}\\
& \TT{void a.print\_to\_file(FILE *)}\\
& \TT{void a.write\_to\_file(FILE *)}\\\hline
sort\_vector & \TT{void swap(T \&, T\&)} \\
& \TT{void operator = (T \&, const T \&)}\\
& \TT{bool operator == (const T \&, const T \&)}\\
& \TT{bool operator < (const T \&, const T \&)}\\
& \TT{bool operator > (const T \&, const T \&)}\\\hline
lidia\_vector & \TT{void swap(T \&, T\&)} \\
& \TT{void operator = (T \&, const T \&)}\\
& \TT{bool operator == (const T \&, const T \&)}\\
& \TT{T operator - (const T \&)}\\
& \TT{T operator + (const T \&, const T \&)}\\
& \TT{T operator - (const T \&, const T \&)}\\
& \TT{T operator * (const T \&, const T \&)}\\
& \TT{T operator / (const T \&, const T \&)}\\
& \TT{bool operator < (const T \&, const T \&)}\\
& \TT{bool operator > (const T \&, const T \&)}\\
& \TT{void a.print\_to\_file(FILE *)}\\
& \TT{void a.write\_to\_file(FILE *)}\\\hline
\end{tabular}
\end{center}

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

\SSTITLE{Instantiations}

\BF{Using g++}
\medskip\\
To use the new template classes with g++ you must explicitly instantiate all the template instances
you use. By default we instantiate 
\begin{itemize}
\item \BF{base\_vector} for the types 
\begin{itemize}
\item built--in types: char, int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigmod}, \BF{bigfloat}, \BF{bigrational}, \BF{bigcomplex}, \\
\BF{spc \LT bigint \GT}, \BF{spc \LT bigmod \GT}, \BF{spc \LT bigrational \GT}, \BF{spc \LT bigcomplex \GT}, \BF{single\_factor}
\end{itemize}
\item \BF{math\_vector} for the types 
\begin{itemize} 
\item built--in types: int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigmod}, \BF{bigfloat}, \BF{bigrational}, \BF{bigcomplex}  
\end{itemize}
\item \BF{sort\_vector} for the types 
\begin{itemize}
\item built--in types: char, int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigrational}, \BF{spc \LT bigint \GT}, 
\BF{spc \LT bigmod \GT}, \BF{spc \LT bigrational \GT}, \BF{spc \LT
bigcomplex \GT}, \BF{single\_factor}
\end{itemize}
\item \BF{file\_vector} for the types 
\begin{itemize}
\item built--in types: int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigrational}
\end{itemize}
\item \BF{lidia\_vector} for the types 
\begin{itemize}
\item built--in types: int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigrational},
\end{itemize}
\end{itemize}
The creation of a new instantiation is very simple. You have to create
an entry of the form 

\begin{verbatim}
 ###
 ### v_USER_TYPE.o
 ###

 CXXOBJ += v_USER_TYPE.o
 USER_TYPE_para = -DTYPE=USER_TYPE -DMATH_VECTOR \
                  -include /usr/local/USER_TYPE.h

\end{verbatim}
in the file vector\_inst. The parameter -DTYPE (i.e. USER\_TYPE) determines the 
name of the argument type. 

The define 
\TT{-DBASE\_VECTOR} or \TT{-DMATH\_VECTOR} or \TT{-DFILE\_VECTOR} or 
\TT{-DSORT\_VECTOR} or \TT{-DLIDIA\_VECTOR} determine the chosen 
template type and so the requirements to the 
argument type. -include has to contain the path to the header file corresponding 
to the argument type.\\

\ATTENTION

\IT{All -D parameters have to be used at the same time.}

e.g.: 

\begin{verbatim}
 USER_TYPE_para = -DTYPE=USER_TYPE -DFILE_VECTOR -DMATH_VECTOR \
                  -include /usr/local/USER_TYPE.h

\end{verbatim}

\BF{Using AT\&T CC}
\medskip\\
To use the new template classes with AT\&T CC you have to link your programs
with\\ 
LIDIA\_INSTALL\_DIR/lib/LiDIA/LIDIA\_ARCH/compiler\_name/libLiDIA.a instead of 
-lLiDIA. If you use -lLiDIA the instantiation mechanism of AT\&T CC fails.

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

\STITLE{\LARGE{Matrix}}
\label{template_introduction2}
\SSTITLE{Structure}
The hierarchy of the matrix--classes is designed corresponding to the hierachy 
of the vector--classes. The base class of this structure is \BF{base\_matrix}. 
By the first derivation step we obtain the matrix class \BF{math\_matrix}; by 
the second step we obtain \BF{bigint\_matrix} itself. This structure is shown 
in the following diagram:

\input epsf

\bigskip
\centerline
{
\epsfysize=8cm
\epsfbox{EPS/lidia_matrix_use.eps}
}
\bigskip

The notation ''B \MATH{\LEFTARROW} D'' indicates class--inclusion and thus says 
that B is a base class of the derived class D.

The different matrix classes are distinguished by the requirements on the type 
\BF{T} to which the elements of a vector belong. Each step of inheritance in the 
structure requires more properties for the type \BF{T} used in the template.
\begin{center}
\begin{tabular}{|c|c|}\hline
class & requirements for a type \BF{T}\\\hline\hline
base\_matrix & \TT{void swap(T \&, T\&)}\\
& \TT{void operator = (T \&, const T \&)}\\\hline
math\_matrix & \TT{void swap(T \&, T\&)} \\
& \TT{void operator = (T \&, const T \&)}\\
& \TT{bool operator == (const T \&, const T \&)}\\
& \TT{T operator - (const T \&)}\\
& \TT{T operator + (const T \&, const T \&)}\\
& \TT{T operator - (const T \&, const T \&)}\\
& \TT{T operator * (const T \&, const T \&)}\\
& \TT{T operator / (const T \&, const T \&)}\\\hline
\end{tabular}
\end{center}

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

\SSTITLE{Instantiations}
\BF{Using g++}
\medskip\\
To use the new template classes with g++ you must explicitly instantiate all the template instances
you use. By default we instantiate 
\begin{itemize}
\item \BF{base\_matrix} for the types 
\begin{itemize}
\item built--in types: char, int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigmod}, \BF{bigfloat}, \BF{bigrational}, \BF{bigcomplex}
\end{itemize}
\item \BF{math\_matrix} for the types 
\begin{itemize}
\item built--in types: char, int, long, float, double
\item LiDIA types: \BF{bigint}, \BF{bigmod}, \BF{bigfloat}, \BF{bigrational},
\BF{bigcomplex}
\end{itemize}
\end{itemize}
The creation of a new instatiation is very simple. You have to create
an entry of the form 

\begin{verbatim}
 ###
 ### m_USER_TYPE.o
 ###

 CXXOBJ += v_USER_TYPE.o
 USER_TYPE_para = -DTYPE=USER_TYPE -DMATH_MATRIX \
                  -include /usr/local/USER_TYPE.h

\end{verbatim}
in the file matrix\_inst. The parameter -DTYPE (i.e. USER\_TYPE) determines the 
name of the argument type. 
The define 
\TT{-DMATH\_MATRIX} or \TT{-DBASE\_MATRIX} determine the choosen template type and 
so the requirements to the argument type. \TT{-include} has to contain the path to the 
header file corresponding to the argument type.

\BF{Using AT\&T CC}
\medskip\\
To use the new template classes with AT\&T CC you have to link your programs
with\\
LIDIA\_INSTALL\_DIR/lib/LiDIA/LIDIA\_ARCH/compiler\_name/libLiDIA.a instead of 
-lLiDIA. If you use -lLiDIA the instantiation mechanism of AT\&T CC fails.

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

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

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

\AUTHOR
Frank Lehmann, Markus Maurer, Stefan Neis, Thomas Papanikolaou, Patrick Theobald

\end{lidia_man}









