
OVERALL DESCRIPTION
===================

fpLLL-3.0 is distributed under the GNU Lesser General Public License 
(v2.1) as published by the Free Software Foundation. 

fpLLL-3.0  contains  several  algorithms  on lattices  that  rely on 
floating-point computations.  This includes  implementations  of the 
floating-point   LLL   reduction   algorithm,   offering   different  
speed/guarantees  ratios.  It  contains  a  'wrapper'  choosing  the 
estimated best sequence of variants in order to provide a guaranteed 
output  as  fast  as  possible.  In  the  case  of the  wrapper, the 
succession of  variants is oblivious to  the user. It  also includes
a rigorous floating-point implementation  of the Kannan-Fincke-Pohst 
algorithm that finds a shortest non-zero lattice vector.


DEPENDENCIES
============

.Absolutely needed:
GNU MP 4.2.0 (or higher):
http://www.swox.com/gmp/
 
.Absolutely needed:
MPFR 2.3.0 (COMPLETE INSTALLATION):
http://www.mpfr.org/

If GMP and/or MPFR include and lib files are not in the default 
directories /usr/include and /usr/lib, you have to set the 
environment variables CFLAGS and LDFLAGS for instance through 
the configure command line 
configure CPPFLAGS="-I/mpfrinclude -I/gmpinclude" LDFLAGS="-L/mpfrlib -L/gmplib"
or   
configure CPPFLAGS="-I/mpfrinclude -I/gmpinclude $CPPFLAGD" LDFLAGS="-L/mpfrlib -L/gmplib $LDFLAGS"
if these variables already exist in your environment. 
This should be modified soon for using standard --with-gmp and 
--with-mpfr package specifications.


INSTALLATION
============

To  install files  'cd'  to the  directory containing the  package's
source code and just type

 configure
 make 
 make install

You can remove the program binaries and object files from the source
code directory  by typing 'make  clean'.  To  also remove  the files
that 'configure'  created (so  you can  compile   the package  for a
different kind of computer), type 'make distclean'.
By default, 'make install' installs the package commands under
'/usr/local/bin', include files under '/usr/local/include', etc.  
You can specify an installation directory name other than 
'/usr/local' by giving 'configure' the option '--prefix=dirname'.
Run 'configure --help' for further details.

CHECK 
=====

'cd' to the src directory, and type 

 make check

This tests the LLL wrapper given dim55_in as input. If nothing is
printed during "diff foo dim55_out", the self-test has succeeded.


HOW TO USE
==========

Executable files fplll and generate are installed in the directory 
bin. In the directory src one also finds the file llldiff.

- generate is an utility for generating matrices (rows form input 
   lattice bases).

The options are :
 r <d> <b> : generates a knapsack style matrix of dimension d,d+1 and b bits.
 s <d> <b> <b2> : generates a simdioph matrix.
 u <d> <b> : generates an uniform matrix.
 n <d> <b> <q> : generates an ntru like matrix.
 N <d> <b> <q> : generates an ntru like matrix.
 a <d> <f> : generates an ajtai style matrix.
 A <d> : generates an ajtai style matrix.

The matrix is printed in stdout.

Note that by default, the random bits always use the same seed,
to ensure reproducibility. This can be disabled by commenting
the line "#define REPRODUCIBLE_RANDOMNESS" in nr.cpp.

- fplll does LLL/HKZ/SVP/CVP on a matrix (considered as a set of row 
vectors) given in stdin.

The options are :

-a lll : LLL-reduction (default).
-a hkz : HKZ-reduction.
-a svp : print a shortest vector of the lattice.
-a cvp : print a lattice vector closest to a given target vector.

-r <size>, -c <size> : ignored for compatibility with previous
                       versions of fplll.

Options for LLL-reduction:

-d <delta> : delta (default=0.99)
-e <eta> : eta (default=0.51)
-l <lovasz> : if !=0 Lovasz's condition. Otherwise, Siegel's condition
-p <precision> : precision of the floating-point arithmetic, works 
                 only with -f mpfr.

-f mpfr : sets the floating-point type to MPFR.
-f dpe : sets the floating-point type to DPE. (default)
-f double : sets the floating-point type to double.
-z int : sets the integer type to int.
-z mpz : sets the integer type to mpz, the integer type of GMP. (default)
-z double : sets the integer type to double.

-m wrapper : uses the wrapper. (default)
-m fast : uses the fast method, works only with -f double.
-m fastearly : uses the fast method with early reduction, works only 
               with -f double.
-m heuristic : uses the heuristic method.
-m heuristicearly : uses the heuristic method with early reduction.
-m proved : uses the proved version of the algorithm.


- llldiff compares two bases (b1,...,bd) and (c1,...c_d'): they are considered
equal iff d=d' and for any i, bi = +- ci.


HOW TO USE AS A LIBRARY
=======================

Type #include <fplll.h> at the beginning of your code.
If you use GMP and/or MPFR additionally to fplll, then:

#include <cstdio>
#include <gmp.h>
#include <mpfr.h>
#include <fplll.h>


See the example file test.cpp in the src directory.
To compile it, assuming fplll has been installed in /tmp/fplll:

bash-3.00$ g++ -static -I $MPFR/include -I /tmp/fplll/include test.cpp -L /tmp/fplll/lib -lfplll -lmpfr -lgmp
bash-3.00$ ./a.out
[[4 3 7 ]
[3 0 1 ]
[3 5 3 ]
]
[[3 0 1 ]
[2 2 -3 ]
[0 5 2 ]
]


EXAMPLES
========

1)
./generate r 10 1000 | ./fplll -r 10 -c 11 


2)
If the file 'matrix' contains 
[[ 10 11]
[11 12]]

Then 
./fplll -r 2 -c 2 < matrix
produces
[[0 1 ]
[1 0 ]
]




DEVELOPERS
===========

David Cade, david.cade@ens.fr
Xavier Pujol, xavier.pujol@ens-lyon.fr
Damien Stehle, damien.stehle@gmail.com



ACKNOWLEDGEMENTS
================

Patrick Pelissier and Paul Zimmermann for dpe.

Martin Albrecht, Sylvain Chevillard, Christoph 
Lauter and Gilles Villard for the 
"configure/make/make install" packaging.

Martin Albrecht for the incorporation into SAGE.

Timothy Abbott, Michael Abshoff, Martin Albrecht, Bill Allombert, 
John Cannon, Sylvain Chevillard, Julien Clement, Laurent Fousse, 
Guillaume Hanrot, Christoph Lauter, Andrew Novocin, Willem Jan 
Palenstijn, Patrick Pelissier, Thiemo Seufer, Allan Steel, Gilles 
Villard and Paul Zimmermann for their support and for many suggestions 
that helped debugging and improving this code.



NEW RELEASES AND BUG REPORTS
============================

New releases will be announced at the URL:
http://perso.ens-lyon.fr/damien.stehle

Bug reports may be sent at:
damien.stehle@gmail.com
xavier.pujol@ens-lyon.fr
