%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  bi_bf_lattice_basis.tex       LiDIA documentation
%%
%%  This file contains the documentation of the lattice classes 
%%
%%  Copyright   (c)   1995   by  LiDIA-Group
%%
%%  Authors: Thorsten Lauer, Susanne Wetzel
%%

\begin{lidia_man}
\markright{\BF{bigint\_lattice\_basis, bigfloat\_lattice\_basis}}

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

\NAME
\BF{bigint\_lattice\_basis,}\\
\BF{bigfloat\_lattice\_basis }  \DOTFILL    lattice basis reduction

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

\ABSTRACT
\BF{bigint\_lattice\_basis} and \BF{bigfloat\_lattice\_basis} are 
derived from the class \BF{bigint\_lattice\_gensys} and 
\BF{bigfloat\_lattice\_gensys} and therefore inherit all their 
functions. In addition the classes \BF{bigint\_lattice\_basis} 
and \BF{bigfloat\_lattice\_basis} are providing several variations 
of the original LLL algorithm \cite{LAK}. Let 
\latex{
\[A=(a_0, \LDOTS, a_{k-1})=(a_{ij})_{0\LE i< n, 0\LE j< k}\IN 
M^{n \TIMES k} \mbox{ } (n,k \IN \N)\]
}
\html{
\MATH{A=(a_0, \LDOTS, a_{k-1})=(a_{ij})_{0\LE i< n, 0\LE j< k}\IN 
M^{n \TIMES k} \mbox{ } (n,k \IN \N)}
}
be a basis of the lattice \MATH{L = \Z a_0 \XOR \dots \XOR \Z a_{k-1}} 
where \MATH{M} consists of elements of type \BF{bigint} or \BF{bigfloat}.
The classes can be used to solve the problem of computing an LLL 
reduced basis of \MATH{L}. 

In this release the classes are supported only to
guarantee the compatibility to previous versions of \LiDIA\ and will
not be available in future versions. We recommend to use the classes 
\BF{bigfloat\_lattice} and \BF{bigint\_lattice\_basis} instead.

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

\DESCRIPTION
In the present version of \LiDIA\ the following
variations of the LLL algorithm are implemented:
\begin{enumerate} \item The original Schnorr-Euchner
algorithm \cite{SEN}, \item For the class
\BF{bigfloat\_lattice\_gensys} a variation of the
original Schnorr-Euchner algorithm is implemented
\cite{SEN} where after suitable transformations most of
the computations are done by using \BF{bigint}s instead
of \BF{bigfloat}s.  \item For the class
\BF{bigint\_lattice\_basis} also the Benne de Weger
variation \cite{BEW} is implemented. This algorithm
avoids floating point arithmetic.  \end{enumerate}

In the following we will explain the constructors, destructors and 
basic functions of the classes \BF{bigint\_lattice\_basis} and 
\BF{bigfloat\_lattice\_basis}. We will use the parameter \BF{type}
to describe the fact that the corresponding function exists in both 
classes and has the same functionality in both cases. Differences 
in the classes will be explained separately. The following description 
is done in respect to column oriented lattices. For row oriented 
lattices you can change the representation. The corresponding computations
will then be adjusted automatically.

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

\CONS

For the following constructors the variable \MATH{A} is assumed to 
represent a lattice.  If in the following constructors \MATH{n\LE 1}, 
\MATH{k\LE 1}, \MATH{n < k}, \MATH{A=NULL} or the dimension of \MATH{A}
does not correspond to the input parameters which declare the dimension,
the \TT{lidia\_error\_handler} will be invoked. (In order to compute 
a reduced basis for a lattice with \MATH{n < k} you will have to use 
the class \BF{bigint\_lattice\_gensys} or \BF{bigfloat\_lattice\_gensys}.) 

\fcode{ct}{type\_lattice\_basis}{}
{
constructs a \MATH{1 \TIMES 1} \BF{type\_lattice\_basis}.
}

\fcode{ct}{type\_lattice\_basis}{lidia\_size\_t n}
{
constructs a \MATH{n \TIMES 1} \BF{type\_lattice\_basis}.
}

\fcode{ct}{type\_lattice\_basis}{lidia\_size\_t n\k lidia\_size\_t k}
{
constructs a \BF{type\_lattice\_basis} of \MATH{k} vectors embedded 
in an \MATH{n}-dimensional vectorspace initialized with zero.
}

\fcode{ct}{type\_lattice\_basis}{const type\_lattice\_basis \& A}
{
constructs a copy of \MATH{A}.
}

\fcode{ct}{type\_lattice\_basis}{lidia\_size\_t n\k lidia\_size\_t k\k type** \& A}
{
constructs an \MATH{n\TIMES k}-\BF{type\_lattice\_basis} initialized 
with the values of the 2-dimensional array \MATH{A} where *\MATH{A} 
is a row vector.
}

\fcode{ct}{type\_lattice\_basis}{const math\_matrix<type>\& A}
{
constructs a \BF{type\_lattice\_basis} initialized with the values 
of \MATH{A}.
}

\fcode{dt}{\SIM type\_lattice\_basis}{}{}

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

\BASIC

Let \MATH{A} be of type \BF{type\_lattice\_basis}.

\fcode{void}{A.extract\_basis}{const type\_lattice\_gensys \& B\k lidia\_size\_t \& r}
{
before this function can be used for extracting a basis it is necessary 
to first apply the function \TT{B.compute\_basis(C,T)} supported by the 
class \BF{type\_lattice\_gensys} for computing a basis of the lattice. 
\MATH{r} is the rank of the basis.
}

\fcode{void}{A.lll}{sdigit factor = 1}{}

\fcode{type\_lattice\_basis}{lll}{const type\_lattice\_basis \& A\k sdigit factor = 1}
{
reduces the lattice \MATH{A} by using the Schnorr-Euchner variation
\cite{SEN} of the LLL algorithm. With \MATH{factor} the precision 
will be determined as (\MATH{factor \CDOT} double precision). 
Therefore for \MATH{factor \LT 2} the approximations are done by 
using doubles, otherwise \BF{bigfloat}s with the appropriate 
precision will be used.
}

\fcode{void}{A.lll}{const math\_matrix<type> \& B\k sdigit factor = 1}
{
assigns \MATH{B} to \MATH{A} and performs \TT{A.lll()}.
}

\fcode{bool}{A.lll\_check}{double y}
{
returns \TRUE , if the basis is reduced for the reduction parameter 
\MATH{y}, \FALSE\ otherwise.
}

\fcode{bool}{A.lll\_check}{sdigit p\k sdigit q}
{
returns \TRUE , if the basis is reduced for the reduction parameter 
\MATH{\FRAC{p}{q}}, \FALSE\ otherwise.
}

\fcode{double}{A.lll\_check\_search}{}
{
if \MATH{A} is LLL reduced, this function will return the largest
\MATH{y\IN ]\FRAC{1}{2},1]} for which \MATH{A} is still LLL reduced, 
see \cite{LAK,SEN}. If \MATH{A} is not LLL reduced, 0 will be returned.
}

\fcode{void}{A.lll\_check\_search}{sdigit p\&\k sdigit\& q}
{
if \MATH{A} is LLL reduced, this function will return the largest
\MATH{\FRAC{p}{q}\IN ]\FRAC{1}{2},1]} for which \MATH{A} is still 
LLL reduced, see \cite{LAK,SEN}. If \MATH{A} is not LLL reduced, 
0 will be returned.
}

\fcode{void}{A.lll\_trans}{math\_matrix<type> \& T\k sdigit factor = 1}{}

\fcode{type\_lattice\_basis}{lll\_trans}{const type\_lattice\_basis \& A\k math\_matrix<type> \&T\k sdigit factor = 1}
{
reduces the lattice \MATH{A} and computes the corresponding unimodular 
matrix \MATH{T} by using the Schnorr-Euchner variation \cite{SEN} of 
the LLL algorithm. With \MATH{factor} the precision will be determined 
as (\MATH{factor \CDOT} double precision). Therefore for \MATH{factor \LT 2} 
the approximations are done by using doubles, otherwise \BF{bigfloat}s
with appropriate dimension will be used.
}

\fcode{bool}{A.make\_basis}{const type\_lattice\_gensys \& B\k lidia\_size\_t r, sdigit factor = 1}
{
tests whether \MATH{B} is a basis. If so, the function only copies 
\MATH{B} to \MATH{A}, otherwise in addition the functions 
\TT{C.lll\_gensys(B,r,factor)} and \TT{A.extract\_basis(C,r)} are 
executed in order to compute a (reduced) basis where C is of type 
\BF{type\_lattice\_gensys}. \MATH{r} is the rank of the basis.
}

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

In addition the class \BF{bigfloat\_lattice\_basis} supports the 
following functions: \\ 

\fcode{void}{A.gram\_schmidt\_orth}{math\_matrix<bigfloat>\& M\k math\_matrix<bigfloat>\& B}
{
computes the Gram-Schmidt basis \MATH{B} corresponding to \MATH{A} 
and the coefficient matrix \MATH{M} as described in \cite{LAK}.
}

\fcode{void}{A.lll\_trans}{math\_matrix<bigint> \& T\k sdigit factor = 1}{}

\fcode{bigfloat\_lattice\_basis}{lll\_trans}{const bigfloat\_lattice\_basis \& A\k math\_matrix<bigint> \&T\k sdigit factor = 1}
{
reduces the lattice \MATH{A} and computes the corresponding unimodular 
matrix \MATH{T} by using the Schnorr-Euchner variation \cite{SEN} of 
the LLL algorithm. With \MATH{factor} the precision will be determined 
as (\MATH{factor \CDOT}~double precision).  Therefore for \MATH{factor \LT 2} 
the approximations are done by using doubles, otherwise \BF{bigfloat}s
with appropriate dimension will be used.
}

\fcode{void}{A.lll\_trans\_var}{math\_matrix<bigint> \& T\k sdigit factor = 1}{}

\fcode{bigfloat\_lattice\_basis}{lll\_trans\_var}{const bigfloat\_lattice\_basis \& A\k math\_matrix<bigint> \&T \k sdigit factor = 1}
{
reduces the lattice \MATH{A} and computes the corresponding unimodular 
matrix \MATH{T} by using a variation of the Schnorr-Euchner algorithm 
\cite{SEN}. With \MATH{factor} the precision will be determined as 
(\MATH{factor \CDOT}~double precision). Therefore for \MATH{factor \LT 2} 
the approximations are done by using doubles, otherwise \BF{bigfloat}s
with appropriate dimension will be used.
}

\fcode{void}{A.lll\_trans\_var}{math\_matrix<bigfloat> \& T\k sdigit factor = 1}{}

\fcode{bigfloat\_lattice\_basis}{lll\_trans\_var}{const bigfloat\_lattice\_basis \& A\k math\_matrix<bigfloat> \&T\k sdigit factor = 1}
{
reduces the lattice \MATH{A} and computes the corresponding unimodular 
matrix \MATH{T} by using a variation of the Schnorr-Euchner algorithm 
\cite{SEN}. With \MATH{factor} the precision will be determined as 
(\MATH{factor \CDOT}~double precision). Therefore for \MATH{factor \LT 2} 
the approximations are done by using doubles, otherwise \BF{bigfloat}s
with appropriate dimension will be used.
}

\fcode{void}{A.lll\_var}{sdigit factor = 1}{}

\fcode{bigfloat\_lattice\_basis}{lll\_var}{const bigfloat\_lattice\_basis \& A\k sdigit factor = 1}
{
reduces the lattice \MATH{A} by using a variation of the Schnorr-Euchner 
algorithm \cite{SEN}. With \MATH{factor} the precision will be determined 
as (\MATH{factor \CDOT}~double precision). Therefore for \MATH{factor \LT 2} 
the approximations are done by using doubles, otherwise \BF{bigfloat}s
with the appropriate precision will be used.
}

\fcode{void}{A.lll\_var}{const math\_matrix<bigfloat> \& B\k sdigit factor = 1}
{
assigns \MATH{B} to \MATH{A} and performs \TT{A.lll\_var()}.
}

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

For the class \BF{bigint\_lattice\_basis} another variation of the 
LLL algorithm is implemented:\\

\fcode{void}{A.lll\_benne\_de\_weger}{}{}

\fcode{bigint\_lattice\_basis}{lll\_benne\_de\_weger}{const bigint\_lattice\_basis \& A}
{
reduces the lattice \MATH{A} by using the algorithm of Benne de 
Weger \cite{BEW}.
}

\fcode{void}{A.lll\_benne\_de\_weger}{const math\_matrix<bigint> \& B}
{
assigns \MATH{B} to \MATH{A} and performs \TT{A.lll\_benne\_de\_weger()}.
}

\fcode{void}{A.lll\_trans\_benne\_de\_weger}{math\_matrix<bigint> \& T}{}

\fcode{bigint\_lattice\_basis}{lll\_trans\_benne\_de\_weger}{const bigint\_lattice\_basis \&A\k math\_matrix<bigint> \&T}
{
reduces the lattice \MATH{A} and computes the corresponding unimodular 
matrix \MATH{T} by using the algorithm of Benne de Weger \cite{BEW}.
}

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

\SEEALSO
\BF{base\_matrix}, \BF{math\_matrix}, \BF{type\_lattice\_gensys}

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

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/bi_lattice_basis.h>  // using class bigint_lattice_basis
 int main()
 { 
   bigint_lattice_basis A;
   cout << "\n please enter the matrix:";  
   cout << "\n (format described in the manual) \n";
   cin >> A;
   A.lll_benne_de_weger();
   cout << "\n reduced matrix :  \n \n" << A << "\n";   
   return (0);
 }

 #include <LiDIA/bf_lattice_basis.h>  // using class bigfloat_lattice_basis
 int main()
 { 
   bigfloat_lattice_basis A;
   math_matrix<bigint> T;
   cout << "\n please enter the matrix:";  
   cout << "\n (format described in the manual) \n";
   cin >> A;
   A.lll_trans(T);
   cout << "\n reduced matrix :  \n \n" << A << "\n";
   cout << "\n transformationmatrix :  \n \n" << T << "\n";   
   return (0);
 }
\end{verbatim}

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

\AUTHOR
Werner Backes, Thorsten Lauer, Oliver van Sprang, Susanne Wetzel\\
(code fragments written by Jutta Bartholomes)


\end{lidia_man}
