
\begin{lidia_man}
\markright{\BF{lattice\_gensys}}

\NAME
\BF{lattice\_gensys}  \DOTFILL    computing lattice bases from generating systems

\ABSTRACT
The class \BF{lattice\_gensys} is the interface class for the classes \BF{bigfloat\_lattice\_gensys}
and \BF{bigint\_lattice\_gensys}. The class is supported only to
guarantee the compatibility to previous versions of \LiDIA\ and might not be available in future
versions. We recommend to use the classes \BF{bigfloat\_lattice\_gensys}
and \BF{bigint\_lattice\_gensys} instead. The class \BF{lattice\_gensys} can be used to solve the following 
problems:\\\\
Let \MATH{A=(a_0, \LDOTS, a_{k-1}) \IN M^{n \TIMES k}} (\MATH{n,k \IN \N}) be a generating system
of a lattice \MATH{L}, where \MATH{M} consists of elements of type \BF{bigfloat}
or \BF{bigint}.
Find a relation, i.e., \MATH{x_0, \LDOTS , x_{k-1} \IN \Z \backslash \{0\}} such that
\MATH{\SUM{i=0}{k-1}{x_ia_i} =0} and find a basis of the lattice~\MATH{L}. 
For details see \cite{BUK}.

\DESCRIPTION
Let \MATH{A} be of class \BF{lattice\_gensys}. 
To solve the problem of finding relations
\latex{
\[\SUM{i=0}{k-1}{x_i a_i} = 0\]
}
\html{
\MATH{\SUM{i=0}{k-1}{x_i a_i} = 0}
}
and/or a basis of the lattice \MATH{L}
which is represented by the matrix \MATH{A} the method of \cite{BUK} is used.

This method computes the rank \MATH{r} of \MATH{L} and a matrix 
\MATH{T \IN \Z^{k \TIMES k}} such that \\ \\
\latex{\centerline{\MATH{A \CDOT T=(\underbrace{0, \LDOTS , 0}_{k-r},\underbrace{b_0,\LDOTS , b_{r-1}}_{=B})},}}
\html{
 A \MATH{\CDOT} T = (0, ..., 0, b_0, ..., b_r-1),
                     \__  ___/  \______  _____/
		        \/             \/
			k-r            =B
}
where \MATH{B} is a basis of \MATH{L}. The first \MATH{k-r} columns of 
\MATH{T} are relations of the above mentioned type.

\CONS

For the following constructors the variable \MATH{A} is assumed to represent a lattice.
If in the following constructors \MATH{n\LT 1},  \MATH{k\LT 1},  \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. 


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

\fcode{ct}{lattice\_gensys}{const lattice\_gensys \& A}
{
constructs a copy of \MATH{A}.}

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

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

\fcode{ct}{lattice\_gensys}{const math\_matrix< bigint >\& A}
{
constructs a \BF{lattice\_gensys} initialized with the values of \MATH{A}.}

\fcode{ct}{lattice\_gensys}{const math\_matrix< bigfloat >\& A}
{
constructs a \BF{lattice\_gensys} initialized with the values of \MATH{A}.}

\fcode{dt}{\SIM lattice\_gensys}{}{}


\INIT

Let \MATH{A} be of type \BF{lattice\_gensys}. The order of application of
the various initializations does not matter but has to be done before
other functions can be applied.

\fcode{void}{A.set\_computing\_mode}{sdigit n}
{
All consequent operations on the matrix \MATH{A} will be done according to mode n:\\
\TT{bigint\_mode} (0x00000010) \DOTFILL uses the class \BF{bigint} \\
\TT{bigfloat\_mode} (0x00000100) \DOTFILL uses the class \BF{bigfloat} \\
If no mode is set, all computations will be done in the default
mode namely \TT{bigfloat\_mode}. The \TT{lidia\_error\_handler} will be invoked, if a not documented
mode is used.\\
Warning: Precision loss may occur due to truncation.}

\fcode{void}{A.set\_io\_mode}{long n}
{
Sets the format of the input and output operations to mode n, where n can be one
of the following modes: \\
\TT{own\_io\_mode} (0x00000001) \DOTFILL see section Input/Output \\
\TT{pari\_io\_mode} (0x00000010) \DOTFILL see pari manual \\
\TT{maple\_io\_mode} (0x00000100) \DOTFILL see maple manual \\
\TT{mathematica\_io\_mode} (0x00001000) \DOTFILL see mathematica manual \\

	 The last three modes provide an interface to other
existing computer algebra systems. If no mode is set,
\TT{own\_io\_mode} will be chosen. The \TT{lidia\_error\_handler} will be invoked, if a not documented
mode is used.}

\fcode{void}{A.set\_reduction\_parameter}{double y}
{
sets the reduction parameter \MATH{y~(\FRAC{1}{2}< y\LE
1)}. If \MATH{y} is not in the range ]\MATH{\FRAC{1}{2},1}], \MATH{y}
is set to the default \MATH{y=0.99}.\\
	 Warning: It is not guaranteed that the LLL algorithm terminates 
	 for \MATH{y=1}.}

\fcode{void}{A.set\_reduction\_parameter}{sdigit p\k sdigit q}
{
sets the reduction parameter \MATH{(\FRAC{1}{2}< \FRAC{p}{q}
\LE 1)}. The default is taken as in \TT{
A.set\_reduction\_parameter(double y)}.}

\TYPE

Let \MATH{A} be of type \BF{lattice\_gensys}. This function test whether all
entries of \MATH{A} are of the demanded type.


\fcode{bool}{A.check\_bigint}{}
{
returns \TRUE, if the entries are of type \BF{bigint}, \FALSE\ otherwise.}

\ASGN

Let \MATH{A} be of type \BF{lattice\_gensys}.

The operator \TT{=} is overloaded. For  efficiency reasons the following 
functions are also implemented:


\fcode{void}{A.assign}{const lattice\_gensys \& B}
{
\MATH{A = B}.}

\fcode{void}{A.assign}{const math\_matrix< bigint > \& B}
{
\MATH{A = B}.}

\fcode{void}{A.assign}{const math\_matrix< bigfloat > \& B}
{
\MATH{A = B}.}

\ACCS

Let \MATH{A} be of type \BF{lattice\_gensys}. If \MATH{i,j < 0}, \MATH{i \GE n} or \MATH{j \GE k}
in one of the following functions, the \TT{lidia\_error\_handler} will be invoked. 

\fcode{lidia\_size\_t}{A.get\_no\_of\_columns}{}
{
returns the number of columns of the matrix representing \BF{lattice\_gensys} \MATH{A}.
Each column corresponds to a vector of the generating system of the lattice.}

\fcode{lidia\_size\_t}{A.get\_no\_of\_rows}{}
{
returns the dimension of the vectors generating \BF{lattice\_gensys} \MATH{A}.
	 This corresponds to the number of rows of the matrix representing \BF{lattice\_gensys} \MATH{A}.}

\fcode{void}{A.member}{sdigit i\k sdigit j\k bigint \& b}
{
\MATH{b = A[i][j]}.}

\fcode{void}{A.member}{sdigit i\k sdigit j\k bigfloat \& b}
{
\MATH{b = A[i][j]}.}

\fcode{void}{A.member}{sdigit \& rows\k sdigit \& columns\k bigint** \& B}
{
sets rows = \TT{A.get\_no\_of\_rows()}, columns = \TT{A.get\_no\_of\_columns()} and stores the lattice
in the 2-dimensional array \MATH{B}. The appropriate amount of memory is allocated.}

\fcode{void}{A.member}{sdigit \& rows\k sdigit \& columns\k bigfloat** \& B}
{
sets rows = \TT{A.get\_no\_of\_rows()}, columns = \TT{A.get\_no\_of\_columns()} and stores the lattice
in the 2-dimensional array \MATH{B}. The appropriate amount of memory is allocated.}

\fcode{void}{A.member}{math\_matrix< bigint >\& B}
{
sets rows = \TT{A.get\_no\_of\_rows()}, columns = \TT{A.get\_no\_of\_columns()} and stores the lattice
in \MATH{B}. The appropriate amount of memory is allocated.}

\fcode{void}{A.member}{math\_matrix< bigfloat >\& B}
{
sets rows = \TT{A.get\_no\_of\_rows()}, columns = \TT{A.get\_no\_of\_columns()} and stores the lattice
in \MATH{B}. The appropriate amount of memory is allocated.}

\fcode{void}{A.sto}{sdigit i\k sdigit j\k bigint \& b}
{
\MATH{A[i][j] = b}.}

\fcode{void}{A.sto}{sdigit i\k sdigit j\k bigfloat \& b}
{
\MATH{A[i][j] = b}.}

\BASIC

Let \BF{A} be of type \BF{lattice\_gensys}.


\fcode{void}{A.compute\_basis}{const lattice\_gensys \& B\k const lattice\_gensys \& T}
{
computes \latex{\MATH{A = B \CDOT T = (\underbrace{0, \LDOTS , 0}_{k-r}, 
\underbrace{c_0, \LDOTS , c_{r-1}}_{=C})}.}
\html{
 A = B \CDOT T = (0, ..., 0, c_0, ..., c_r-1)
                  \__  ___/  \_____  ______/
	             \/            \/
		     k-r           =C
}
In order to extract the actual Basis \MATH{C} use the function \TT{C.extract\_basis(A, r)}
of the class \BF{lattice\_basis}.
The \TT{lidia\_error\_handler} will be invoked, if \MATH{A}, \MATH{B} or \MATH{T} do not have appropriate dimension.}

\fcode{sdigit}{A.get\_computing\_mode}{}
{
returns the current computing mode according to \hfill \\
\TT{A.set\_computing\_mode(mode)}.}

\fcode{timer\&}{A.get\_computing\_time}{}
{
returns the amount of time used for the reduction by means of the class \BF{timer}.}

\fcode{sdigit}{A.get\_no\_of\_corrections}{}
{
returns the number of corrections needed for reducing the lattice.}

\fcode{sdigit}{A.get\_no\_of\_reduction\_steps}{}
{
returns the number of reduction steps needed for reducing the lattice.}

\fcode{sdigit}{A.get\_no\_of\_swaps}{}
{
returns the number of swaps needed for reducing the lattice.}

\fcode{double}{A.get\_reduction\_parameter}{}
{
returns \MATH{y} as described in \TT{A.set\_reduction\_parameter(y)}.}

\fcode{void}{A.get\_reduction\_parameter}{sdigit \& p\k sdigit \& q}
{
returns \MATH{\FRAC{p}{q}} as described in \TT{A.set\_reduction\_parameter(p,q)}.}



\fcode{void}{A.lin\_gen\_system}{lattice\_gensys \& T\k lidia\_size\_t \& r}{}
\fcode{lattice\_gensys}{lin\_gen\_system}{const lattice\_gensys \& A, lidia\_size\_t \& r}
{
computes the tranformation matrix \MATH{T} such that \latex{\MATH{A \CDOT T =(\underbrace{0, \LDOTS , 0}_{k-r}, 
\underbrace{b_0, \LDOTS , b_{r-1}}_{=B})}} 
\html{
 A \CDOT T = (0, ..., 0, b_0, ..., b_r-1)
              \__  ___/  \_____  ______/
	         \/            \/
		 k-r           =B
}
as well as the rank \MATH{r} of the basis \MATH{B} by using the Buchmann-Kessler algorithm \cite{BUK}.}

\fcode{void}{lin\_gen\_system}{math\_matrix< bigint > \& T\k const math\_matrix< bigint > \& A\k sdigit \& r}
{
converts \MATH{A} to a \BF{lattice\_gensys} \MATH{C}, computes \TT{C.lin\_gen\_system(S,r)} and converts \MATH{S} to \MATH{T} 
where \MATH{r} is the rank of the computed basis.}

\fcode{void}{lin\_gen\_system}{math\_matrix< bigint > \& T\k const math\_matrix< bigfloat > \& A\k sdigit \& r}
{
converts \MATH{A} to a \BF{lattice\_gensys} \MATH{C}, computes \TT{C.lin\_gen\_system(S,r)} and converts \MATH{S} to \MATH{T} 
where \MATH{r} is the rank of the computed basis.}

\fcode{void}{lin\_gen\_system}{math\_matrix< bigfloat > \& T\k const math\_matrix< bigfloat > \& A\k sdigit \& r}
{
converts \MATH{A} to a \BF{lattice\_gensys} \MATH{C}, computes \TT{C.lin\_gen\_system(S,r)} and converts \MATH{S} to \MATH{T} 
where \MATH{r} is the rank of the computed basis.}


\IO

The \BF{istream} operator \TT{>>} and the \BF{ostream} operator \TT{<<} are
overloaded. \\
Let \MATH{n, k \IN \N} be the number of rows and columns of a \BF{lattice\_gensys} 
\latex{
\[A=(a_{ij})_{0\LE i <n, 0 \LE j < k}. \]
}
\html{
\MATH{A=(a_{ij})_{0\LE i <n, 0 \LE j < k}.}
}
Input and output are of the following format:\\ \\
\centerline{\MATH{n \SQCUP k \SQCUP a_{0,0} \SQCUP a_{0,1} \SQCUP \LDOTS \SQCUP a_{0,k-1} \SQCUP 
a_{1,0} \SQCUP \LDOTS \SQCUP a_{1,k-1}
\SQCUP    \LDOTS \SQCUP   a_{n-1,0} \SQCUP \LDOTS \SQCUP a_{n-1,k-1}}}

\SEEALSO
\BF{lattice\_basis}, \BF{bigint\_lattice\_basis}, \BF{bigfloat\_lattice\_basis},
\BF{bigint\_lattice\_gensys}, \BF{bigfloat\_lattice\_gensys}

\WARNINGS
The functions \TT{A.set\_computing\_precision(precision)} and \TT{A.get\_computing\_precision(precision)} are not needed  
any more. In order to be compatible to previous versions of \LiDIA\ they are supported as dummy functions.

\EXAMPLES
\vspace{-0.5cm}

  \begin{verbatim}
 #include <LiDIA/lattice_gensys.h>  // using class lattice_gensys
 int main()
 { 
   sdigit mode;
   lidia_size_t r;
   lattice_gensys A(1, 1), T(1, 1);
   cout << "\n please enter the matrix:";  
   cout << "\n (format described in the manual) \n";
   cin >> A;
   cout << "\n do you want to change the computing mode?";
   cout << "\n 16(bigint) or 256(bigfloat) (see manual):" 
        << "actual mode is " << A.get_computing_mode();
   cout << "\n enter number:";
   cin >> mode;
   A.set_computing_mode(mode);
   A.lin_gen_system(T, r);
   A.compute_basis(A, T);
   cout << "\n time needed for the reduction:" 
        << (A.get_computing_time()).user_time() << " ms \n"; 
   cout << "\n reduced matrix :  \n \n" << A << "\n";   
   return (0);
 }

  \end{verbatim}

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


