-----------------------------------------------------------------------


                            LiDIA

           A library for computational number theory

  Copyright (c) 1994, 1995, 1996, 1997 by the LiDIA Group - Version 1.3 

                Technische Hochschule Darmstadt
                   Fachbereich 20 - Informatik
    	      Institut f"ur Theoretische Informatik
                    Lehrstuhl Prof. Buchmann
                        Alexanderstr. 10 
                      D - 64283 Darmstadt


-----------------------------------------------------------------------


CONTENTS
@@@@@@@@

1) ABSTRACT

2) LiDIA GROUP

3) CONTENTS OF THIS RELEASE

   3.1 What is new ?
   3.2 What is in work ?

4) CHANGES

5) HOW TO GET AND INSTALL LiDIA

   5.1) FTP procedure
   5.2) Unpacking procedure
   5.3) Installation procedure (short version) 
   5.4) Calling a test program
   5.5) Installation procedure (long version) 

6) NOTE

   4.1) Send an email
   4.2) Be a part of it 

7) LiDIA WENT DARMSTADT

8) ACKNOWLEDGEMENTS




1) ABSTRACT 
@@@@@@@@@@@

LiDIA is a *powerful C++ library* for computational number theory
which provides a collection of *highly optimized implementations*
of  various   multiprecision   data   types   and  time-intensive
algorithms.  LiDIA  is  developed  by  the  LiDIA  Group,  at the
Universit"at  des  Saarlandes  and at the TH Darmstadt, and it is
*free* for educational purposes. 


The current version has been tested on

o sparc8, sparc-ultra, mips, intel, hp
 
with the following compilers
 
o g++-2.7.2, cfront-3.01, HP C++, MIPS C++
 
on the following operating systems
 
o SunOS, Solaris, OS/2, IRIX-5.2, Linux, HP-UX9.05
 
supporting the object file formats
 
o a.out, ELF


For  a more detailed description of LiDIA's design and features we 
refer to the manual.



2) LiDIA GROUP 
@@@@@@@@@@@@@@

At the moment the LiDIA Group consists of the following people:

Werner Backes		Franz-Dieter Berger     Ingrid Biehl
Johannes Buchmann	Emre Binisik 		John Cremona
Sascha Demetrio		Thomas Denny	        Friedrich Eisenbrand	
Alexander Hess		Kurt Huwig		Michael Jacobson	
Thorsten Lauer		Markus Maurer		Volker M"uller
Stefan Neis		Thomas Papanikolaou     Sachar Paulus	
Thomas Pfahler		Nigel Smart		Thomas Sosnowski        
Patrick Theobald	Damian Weber		Susanne Wetzel

Old Members
^^^^^^^^^^^
Oliver Braun		Patrik Kirsch	 	Frank Lehmann
Andreas M"uller		Victor Shoup	 	Oliver van Sprang
Ren'e Weiskircher



3) CONTENTS OF THIS RELEASE
@@@@@@@@@@@@@@@@@@@@@@@@@@@

3.1) What is new ?
^^^^^^^^^^^^^^^^^^

The current release offers the following new classes:

o the template classes hash_table<T> and indexed_hash_table<T>

o quadratic_order, qi_class, qi_class_real, quadratic_ideal
  which put at disposal a lot of functions for quadratic 
  number fields.

o a new class for quadratic forms integrated in the quadratic_order
  code (replaces the old quadratic_form class)

o extended version of the classes for algebraic numbers

o Fp_polynomial, poly_modulus, poly_multiplier: polynomial arithmetic
  over finite prime fields with characteristic greater than 2. Especially
  FFT-arithmetic is used to multiply polynomials. The original code
  was written by Victor Shoup. 

o the template class factorization<T>, which will be used for factorizations
  of integers, polynomials and ideals. (factorization<bigint> and factorization
  <ideal> coming soon)

o factoring algorithms for Fp_polynomial which are integrated in the
  class factorization<Fp_polynomial>

o gf_polynomial: polynomial arithmetic over finite fields.

o factorization<gf_polynomial>: factorization for gf_polynomial

o polynomial<T>: a template class for univariate polynomials with special
  algorithms for polynomials over bigint, bigrational, bigfloat, and bigcomplex.

o gf2n: arithemtic in finite fields of characteristic 2.

o bigint_lattice, bigfloat_lattice: a new concept for lattice-algorithms;
  fast because using templates, but not compatible with the old classes.

o xdouble: extended doubles, original version written by Keith Briggs, 

o bigfloat_int: interval arithmetic for bigfloats, written by Nigel Smart,
  
o mpqs: large prime variant for quadratic sieve in the class
  rational_factorization.

o You can now choose gmp as the integer arithmetic of the kernel.
  This LiDIA - release contains gmp version 2.0.2.



NOTE:

Some classes in the LiDIA package are undocumented.
In general, the design of these classes is temporarily
and can be changed in future releases without giving
any comments on it. We recommend, that you send us an
email, if you want to use one of these classes. This 
allows us to inform you on the current status of the
class and maybe to give you a newer version.



3.2) What is in work?
^^^^^^^^^^^^^^^^^^^^^

o In beta testing

  - FUrther factorization algorithms for integers
  - basic number theoretic functions
  - a class for generating prime numbers

o In work
 
  - further algorithms for algebraic number fields
  - Porting of John Cremona's elliptic curve package
  - Discrete logarithms using COS
  - Symbolic computation package
  - Counting points on elliptic curves over |F_p, p > 3
  - Incoprorating PoSSo's Customizable Memory Manager into LiDIA 
  - LiDIA development environment (support for configuring, (remote)
    control version, editing, compiling, running and debugging of
    LiDIA programs)


4) CHANGES
@@@@@@@@@@

We try to avoid changes which cause incompatibility,
but sometimes it is necessary to correct previous
design errors. For a list of important changes in 
this release of LiDIA, please read the chapter
"Changes" in the LiDIA manual.



5) HOW TO GET AND INSTALL LiDIA
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@


5.1) FTP procedure
^^^^^^^^^^^^^^^^^^
LiDIA is available by anonymous ftp from

             ftp.informatik.th-darmstadt.de:/pub/TI/systems/LiDIA

If you have ncftp you can get LiDIA by simply typing

     ncftp ftp.informatik.th-darmstadt.de:/pub/TI/systems/LiDIA/LiDIA.tgz

otherwise use the following ftp session. With > we denote the commands
you have to type in. // denotes a short explanation.

> ftp ftp.informatik.th-darmstadt.de  // connect  to  the ftp server  
> anonymous                           // your     login         name
> <complete email address>            // your password is your email
                                      // address.  PLEASE  give  the 
				      // correct email address. 
> cd pub/TI/systems/LiDIA             // the  directory  where LiDIA
                                      // resides 
> binary                              // set  binary  mode  for data
                                      // transfer
> get README                          // get   the    README    file
> get COPYRIGHT                       // get   the    COPYRIGHT file
> get LiDIA.tgz                       // get      the        package
> get man-ps.gz   (optional)          // get the postscript manual
> get man-dvi.gz  (optional)	      // get the dvi manual
> bye                                 // disconnect

This session  will  get the files README, COPYRIGHT and LiDIA.tgz
and  will place them in the current directory (from now on called 
UNPACKDIR). To reduce the size of the package, we have taken
the postscript and the dvi manual out of the package. Choose the
format you prefer and copy either man-ps.gz or man-dvi.gz. The
LiDIA.tgz file only contains the TeX source code of the manual.




5.2) Unpacking procedure
^^^^^^^^^^^^^^^^^^^^^^^^
Now typing in

               gunzip -c LiDIA.tgz | tar xvf -

will  create  a  directory  named  LiDIA;  in this directory the 
following files/directories should exist:

UNPACKDIR/LiDIA:

Readme        bugs/    doc/       lib/      make-os2.cmd
makefile.os2  bin/     config/    include/  makefile       src/

Readme ............................................... this file
bin ........... holds LiDIA's applications files (see make appl) 
lib .................. holds LiDIA's library and thr primes file
config ...................... contains the configuration scripts
doc .......... contains LiDIA's documentation in various formats
include ............................ holds LiDIA's include files
makefile ............................. for UNIX, Linux, AIX, ... 
makefile.os2 ..................................... for OS/2 only
make-os2.cmd ..................................... for OS/2 only
src ............................................ LiDIA's sources
src/applications.......contains links to the LiDIA test programs


If you have copied the dvi-format of the manual, type in

	 	mv     man-dvi.gz doc/dvi
		gunzip doc/dvi/man-dvi.gz

If you have copied the postscript-format of the manual, type in

		mv     man-ps.gz doc/ps
		gunzip doc/ps/man-ps.gz




5.3) Installation procedure (short version)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the UNPACKDIR/LiDIA directory type

STEP 1.         make configure

and  answer  the  questions  of  the `configure' script. You will
be  asked  for the installation path of LiDIA (this is by default
/usr/local).  Please  enter  an  existing  path on which you have
write  permission, since this is neccessary by the `make install'
command below.

STEP 2.         make

to build the library and (optionally)

STEP 2a.        make appl

to create the applications which test the classes and demonstrate
their  use.  Finally,  if  and  only  if  you have not chosen the 
current path as installation path, type

STEP 3.         make install

to  install  the  library  of  LiDIA (libLiDIA.a) and the include
files on your system. If you want to change the installation path
please  rerun  STEP 1  before   calling  `make install'.  LiDIA's 
library is installed by default on

                /usr/local/lib/LiDIA/$host-cpu/$cpp/libLiDIA.a

where host-cpu is  determined  by  the  command `config.guess' of
the  GNU  software and $cpp is the C++ compiler used (in this way
you  are  allowed  to  create  multiple  libraries   produced  by
different  compilers  on the same machine). LiDIA's include files
are installed by default on

                /usr/local/include/LiDIA

and finally LiDIA's binaries are installed on

		/usr/local/bin/LiDIA/$host-cpu/$cpp


*NOTE*: The 'configure' script chooses the GNU g++ compiler, if it
	can find it. If you have installed the GNU g++ and ,i.e., 
        the AT&T CC compiler, you can force `configure` to use the
        CC compiler.

	Change to the directory config:

		cd config

	Set the environment variables CC and CXX, i.e. in tcsh:

		setenv CC  cc       (the C-Compiler)
		setenv CXX CC	    (the C++-Compiler)

	Remove config.cache if necessary:

		rm config.cache

	Start the 'configure' script:

		./configure

	If you have chosen 'gmp' as the integer arithemtic,
        change to the directory ../src and configure the gmp:

		cd ../src
		make configure




5.4) Calling a test program
^^^^^^^^^^^^^^^^^^^^^^^^^^^
To call a test program, change to the directory 

                UNPACKDIR/LiDIA/bin/$host-cpu/$cpp

by simply typing

		cd UNPACKDIR/LiDIA/bin/$host-cpu/$cpp

The  applications in this directory, try to test all functions of
the  LiDIA  classes.  They are succesful, if they do not print an 
error message.

*NOTE*: -) The directory src/applications contains links to all the
           test programs of LiDIA. This makes it easier for you  to
           examine the source code of the programs  that are  built
           via "make appl". 

	-) Some programs need information which is stored in the files
	
		  LIDIA_PRIMES and GF2n.database.	

           The built-in directory, where programs are looking for
	   those files is

	  	  LIDIA_INSTALL_DIR/lib/LiDIA,

	   which is the correct path, if you have installed the
	   library via "make install". If you have *not installed* the 
	   library, you must *set* the environment variables, i.e. 
	   using tcsh,

	     setenv LIDIA_PRIMES_NAME UNPACKDIR/LiDIA/lib/LIDIA_PRIMES
	     setenv LIDIA_GF2N	      UNPACKDIR/LiDIA/lib/GF2n.database

		
	   
5.5) Installation procedure (long version) 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please read the chapter `Installing' in the manual

      UNPACKDIR/LiDIA/doc/ps/lidiaman.ps

	or

      UNPACKDIR/LiDIA/doc/dvi/lidiaman.dvi

depending on which manual format you have copied and
installed (see unpacking procedure above).



6) NOTE
@@@@@@@

6.1) Send an email
^^^^^^^^^^^^^^^^^^
After  having  installed   LiDIA,  please send us an email saying
that  you have done so. This enables us to inform you about bugs,
bug fixes, new version, etc.

If you successfully installed LiDIA please tell us so  If you had
no  success  at  all  and  this  is likely to be a bug  in LiDIA,
(including  incomplete / incorrect documentation), please report.
Note that we will  probably  not  be able  to reconstruct  a  bug
without  a detailed description. The format suggested in the file
`bug_reports.form'  in  the  LiDIA/bugs directory should  be  the
guide for all bug reports.  Approved bugs will be included in the
file `bugs' which also resides in the LiDIA/bugs directory. You
can send your suggestions, enhancements, etc to

              lidia@cdc.informatik.th-darmstadt.de

Please, send bug reports (and fixes) to

              lidia-bugs@cdc.informatik.th-darmstadt.de


6.2) Be a part of it 
^^^^^^^^^^^^^^^^^^^^
We would also appreciate all sorts of feedback,  bug reports  and
bug  fixes,  enhancements,  contributions  etc. At this point one
short  note  (answering  the  question  posed frequently by LiDIA
users):

For  programs  contributed  to LiDIA the copyright remains to the
author.  However,  once a program is contributed to LiDIA and was
released  for  the public with LiDIA it is not possible to remove
it from the package, since users may have built their work on top
of it.  LiDIA's policy is to put the author's name in the manual,
the  source code and in the announcement of the corresponding re-
lease.  For  more  details, please read the file COPYRIGHT in the
main distribution directory.




7) LiDIA WENT TO DARMSTADT
@@@@@@@@@@@@@@@@@@@@@@@@@@

The LiDIA Group has almost completely moved to Darmstadt (about 
40km from Frankfurt) since May '96. Therefore we have new 
addresses as mentioned above:

    email: lidia@cdc.informatik.th-darmstadt.de

    ftp  : ftp.informatik.th-darmstadt.de/pub/TI/LiDIA

    http : www.informatik.th-darmstadt.de/TI/LiDIA



8) ACKNOWLEDGEMENTS
@@@@@@@@@@@@@@@@@@@

We would like to thank in the name of the LiDIA Group all users who
have  up-loaded,  installed and tested LiDIA in this short amount
of time.

LiDIA  profits  from  user contributions and various public domain
software packages:  special  thanks  to  Arjen  Lenstra  and  Paul
Leyland  for freelip-1.0, Ralf  Dentzer   for   libI, Torbjoern
Granlund for gmp, Keith Briggs for the fast quadruple precision 
floating point package and the GNU project for their superb software.
LiDIA's development environment uses GNU's tools extensively. 

Thanks  also to Hans-J. Boehm and Alan J. Demers for the gc memory
manager. 

Last  but  not  least,  we  would  like  to thank our colleagues John
Cremona (Exeter University)  and Nigel P. Smart (University of Kent
at Canterbury) for many useful comments and discussions.

Best to all of you,

	Thomas Papanikolaou (TP)
	Markus Maurer (MM)


-------------------------------------------------------------------

