Fapof user guide
================

Fapof stands for factoring polynomials over finite fields.
Actual version allows only finite fields of primal size
less then 2<<31.

Fapof project consists of three executables

1) fapof
- fapof is the main executable for factoring polynomials.
- the input is taken from command line and if there was
  no polynomial to factor, standard input is used.
- whole line of input [one command line argument] is parsed at a time.
  It may start with "gf[num]" to indicate use of finite field of [num] elements.
  It may continue by a polynomial over last specified finite field. Such
    a polynomial is factored and the result is written on one output line.
  An attempt to factor a polynomial without specifiing finite field
    results in an error. But the program continues on next line.
- the parsing continues until the end of standard input / last command line
    argument is found.
- example: fapof gf5 x^9+x^8 x^5-x
    factors two polynomials over GF(5), therefore outputs two output lines.

2) bench
- bench is benchmarking utility. It has three parameters, last is optional.
  First is the size of finite field in bits (1..31 right now),
  second is the degree of a random polynomial to factor,
  third is the number of random polynomials to factor.
- bench benchmarks both multiplication methods.
- example: bench 1 100 5
    factors 5 random polynomials of degree 100 over GF(2) and prints
    the time needed.

3) pc
- pc, polynomial calculator, is very simple polynomial calculator
  written only for personal use. Therefore it does little input checking.
- the first mandatory parameter is finite field size, which can
  be followed by ",[maxdegree]" [eg 5,123] to specifi maximum degree
  of polynomials involved. It defaults to 10000 if not specified.
- all other input must be on the command line. Each command line parameter
  must be
  - operator +(add), -(sub), .(mul)], /(div), %(mod), ^(exp),
     r[num](generate random polynomial of degree num or less),
     i[num](generate Newton inversion for polynomials of num degree),
     g(gcd), c(f g c h computes f(g) % h), [(left bracket), ](right bracket),
     ^%(f ^%5 g computes (f^5) % g), .%(f g .% h computes (f.g)%h).
  - polynomial
  Be carefull, each one must be a whole parameter -> brackets must
    be separated by spaces, on the other side there can be no spaces
    in polynomials.
  Integral parameter for ^ may follow immediately. Otherwise it is
    expected to form next parameter, ie. ^5 and ^ 5 is both possible.
- the result is written onto standard output.
- example: pc 5,123 [ x + x ^%5 x^2+2 ] % x^3-1
    computes ( x + (x^5)%x^2+2)%x^3-1 over GF(5) and every partial
    result must be of degree 123 or less. 

Downloading
===========

The current version can be downloaded from http://www.ucw.cz/~fox/work/factoring/.

Installing
==========

Precompiled binaries for Windows are part of the package.
They can be found in subdirectory bin_win. Tthree types of binaries 
targetting different processors are present. One for generic i586, 
one for pentium-4 and higher processors, and the last 
for athlon-xp and higher processors.

No special install is needed, each binary should work when executed
from any place.

Compiling
=========

The project can be compiled using make and gcc on ia32 architecture. 
No other compiler of platform is supported, because of the use assembler
and extended assembler syntax. It is used to multiply two unsigned modulo
prime in the file field/primal.h

Compiling can be done by executing make in the top level of this package.
Parameters to make are: all          create all three executables [defaut]
                        fapof      \
			bench       =create just the specified executable
			pc         /
			I586=1     \
			PENTIUM4=1  =create code for specified processor
			ATHLONXP=1 /
			STATIC=1     try to link the static version of libc
			BRUTALMUL=1  use better implementation for small
			             polynomial multiplication. Produces
				     generaly better code, but the compilation
				     is very time consuming.
			DEBUG=1      generate debug information. Otherwise,
				     optimize the code and strip it.
			GCC=xxx	     use compiler xxx instead of "g++".
				     Usefull for using another version of g++.
			clean	     remove all binaries & temporary objects