lsmul: "Low-Space" Polynomial Multiplication
========================================================================
Version 0.1, released 26 May 2009
Daniel S. Roche
http://www.cs.uwaterloo.ca/~droche/

Overview
------------------------------------------------------------------------
This package contains experimental implementation of some new algorithms
developed by the author for multiplying polynomials in (Z/mZ)[x] without
using intermediate arrays for auxiliary storage. It is *not* meant to be
used by anyone who actually wants to perform high-performance polynomial
arithmetic; if that is your interest, may I recommend:
NTL - by Victor Shoup, http://www.shoup.net/ntl/
zn_poly - by David Harvey, http://cims.nyu.edu/~harvey/zn_poly/

In fact, I am comparing my software against these two highly efficient
implementations. It tends to be faster than NTL, but slower than
zn_poly (but uses less space than both, of course).

Algorithms Used
------------------------------------------------------------------------
A high-level description of the basic ideas for these algorithms can be
found in "Space- and Time-Efficient Polynomial Multiplication" published
in the proceedings of ISSAC 2009 by Daniel S. Roche (a version is also
available from the author's website above).

The first idea is a variation of Karatsuba's algorithm which achieves
the same time complexity of O(n^1.59) without using any extra space
except O(log n) for the recursive calls. The implementation also
incorporates a space-efficient version of the classical O(n^2)
algorithm.

The second idea is a variation of FFT-based multiplication methods,
which uses no extra space when the size of the result is a power of 2.
This requires that the ring Z/mZ contains a sufficiently high primitive
root of unity, which must also be specified.

Compiling and running some tests
------------------------------------------------------------------------
I know that these programs compile and run on x86_64 Linux with gcc
4.3.3 and GNU make, and have compared against NTL and zn_poly 0.9. If
something doesn't work on your system (or if you have any other
suggestions or comments), feel free to email droche@cs.uwaterloo.ca and
explain your situation.

The first three lines of the Makefile define three variables for the
locations of NTL, GMP, and zn_poly, respectively. If you don't have one
or more of these packages installed, reset these values to blank. If
you're not sure where the package is installed, set the value to
any folder (the default include/lib paths will still be searched).

The default target, "tests", will compile programs to benchmark and
perform correctness tests on the classical/Karatsuba method, the
FFT-based method, NTL, and zn_poly (if these libraries are installed).
The user will be prompted for test parameters to generate the test cases
(in the file testcases.txt) before any tests are performed.

Files in the Package
------------------------------------------------------------------------
* lsmul.h: Primary header file; contains prototypes for calling the main
      algorithms
* basic.c: Implementation of common utility functions, such as I/O
* classikar.c: Implementation of algorithms for Karatsuba-like and
      classical multiplication without extra space
* classikar_body.c: This file is included multiple times from
      classikar.c. It is a so-called "super-macro", and the multiple
      includes result in slightly different versions of the functions.
* fft.c: Implementation of FFT-based multiplication with no extra space
* gen-testdata.c: Program to generate test cases for multiplication
* test-ck.c: Program to test classikar.c for efficiency and correctness
* test-fft.c: Program to test fft.c for efficiency and correctness
* test-NTL.c: Program to compare the implementation of NTL's zz_pX
              multiplication to the algorithms in this package (requires
              NTL and possibly GMP to be installed in the system)
* Makefile
* LICENSE.txt
* README.txt

Licensing and Copying
------------------------------------------------------------------------
This code is released under the X11 license (also called the MIT
license). This license is very permissive, not copyleft, and is
essentially the same as a 2-clause BSD license. The license is part of 
the Open Source Initiative at
http://www.opensource.org/licenses/mit-license.php.
