%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  sf_Fp_polynomial.tex       LiDIA documentation
%%
%%  This file contains the documentation of the specialisation
%%  single_factor<Fp_polynomial>, factorization<Fp_polynomial>.
%%
%%  Copyright   (c)   1996   by  LiDIA-Group
%%      
%%  Authors: Thomas Pfahler
%%

\begin{lidia_man}

\def\sfFp{single\_factor\TEMPL{Fp\_polynomial} }

\markright{\BF{\sfFp}}

\NAME
\BF{\sfFp} \DOTFILL a single factor of a polynomial over finite prime fields

\ABSTRACT
\BF{\sfFp} is used for storing factorizations of polynomials over finite prime fields
(see \BF{factorization}). It is a specialization of \BF{single\_factor\TEMPL{T}} with
some additional functionality. All functions for \BF{single\_factor\TEMPL{T}} can be
applied to objects of class \BF{\sfFp}, too. These basic functions are not
described here any further; you will find the description of the latter in 
\BF{single\_factor\TEMPL{T}}.

\DESCRIPTION

%\section{\sfFp}

%\STITLE{Constructor}

\STITLE{Modifying Operations}

Let $a$ be an instance of type \sfFp.

\fcode{bigint}{a.extract\_unit}{}
{ returns the leading coefficient of \MATH{a.base()} and converts it to a monic
polynomial (by dividing it by its leading coefficient).}

\bigskip

\STITLE{Factorization Algorithms}

The implementation of the factorization algorithms is described in
\cite{Pfahler96}.

Let $a$ be an instance of type \BF{\sfFp}.

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {square\_free\_decomp}{const Fp\_polynomial \& f}{
    returns the factorization of \MATH{f} into square--free factors.\\
    \MATH{f} must be monic, otherwise the lidia\_error\_handler is invoked.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.square\_free\_decomp}{}{
    returns \MATH{square\_free\_decomp(a.base())}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\fcode{factorization\TEMPL{Fp\_polynomial} }
    {berlekamp}{const Fp\_polynomial \& f}{
    returns the complete factorization of \MATH{f} using Berlekamp's
    factoring algorithm.\\
    If \MATH{f} is the zero polynomial, the lidia\_error\_handler is invoked.}
    

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.berlekamp}{}{
    returns \MATH{berlekamp(a.base())}.}

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {sf\_berlekamp}{const Fp\_polynomial \& f}{
    returns the complete factorization of \MATH{f} using Berlekamp's
    factoring algorithm. \\
    \MATH{f} must be monic and square--free with a non-zero constant term;
    otherwise the behaviour of this function is undefined.}
 
\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.sf\_berlekamp}{}{
    returns \MATH{sf\_berlekamp(a.base())}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\fcode{factorization\TEMPL{Fp\_polynomial} }
    {can\_zass}{const Fp\_polynomial \& f}{
    returns the complete factorization of \MATH{f} using \TT{sf\_can\_zass}.\\
    If \MATH{f} is the zero polynomial, the lidia\_error\_handler is invoked.
    Note that as \TT{ddf} creates temporary files, you need write
    permission either in the \/tmp-directory or in the directory from
    which it is called.\\
    This function uses less memory then \TT{berlekamp} when factoring
    polynomials of large degrees.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.can\_zass}{}{
    returns \MATH{can\_zass(a.base())}.}

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {sf\_can\_zass}{const Fp\_polynomial \& f}{
    returns the complete factorization of \MATH{f} using
    \TT{ddf} and the von zur Gathen/Shoup algorithm for
    factoring polynomials whose irreducible factors all have the same degree.\\
    \MATH{f} must be monic and square--free, otherwise the
    behaviour of this function is undefined.
    Note that as \TT{ddf} creates temporary files, you need write
    permission either in the \/tmp-directory or in the directory from
    which it is called.\\
    This function uses less memory then \TT{sf\_berlekamp} when factoring 
    polynomials of large degrees.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.sf\_can\_zass}{}{
    returns \MATH{sf\_can\_zass(a.base())}.}

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {ddf}{const Fp\_polynomial \& f}{
    performs a "distinct degree factorization".\\
    Returns the factorization of \MATH{f} into a product of factors, where
    each factor is the product of distinct irreducibles all of the same degree,
    using Shoup's algorithm \cite{ShoupGF}.
    \BF{The exponents of this factorization do not give the multipicities of
    these factors} (which would be 1) \BF{but the degrees of the
    irreducibles}. \\
    \MATH{f} must be monic and square--free, otherwise the
    behaviour of this function is undefined.
    Note that as \TT{ddf} creates temporary files, you need write
    permission either in the \/tmp-directory or in the directory from
    which it is called.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.ddf}{}{
    returns \MATH{ddf(a.base())}.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {edf}{const Fp\_polynomial \& f\k lidia\_size\_t d}{
    performs an "equal degree factorization".
    Assumes that \MATH{f} is a monic polynomial whose irreducible factors
    all have degree \MATH{d} (otherwise, the behaviour of this function
    is undefined); returns the complete factorization of \MATH{f}
    using an algorithm of von zur Gathen/Shoup \cite{GathenShoup}.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.edf}{lidia\_size\_t d}{
    returns \MATH{edf(a.base(),d)}.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\fcode{factorization\TEMPL{Fp\_polynomial} }
    {factor}{const Fp\_polynomial \& f}{
    returns the complete factorization of \MATH{f} using a strategy which tries
    to apply always the fastest of the above algorithms. It also includes
    special variants for factoring binomials. The strategy is explained in
    detail in \cite{Pfahler96}.\\
    If \MATH{f} is the zero polynomial, the lidia\_error\_handler is invoked.}

\cfcode{factorization\TEMPL{Fp\_polynomial} }
    {a.factor}{}{
    returns \MATH{factor(a.base())}.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  SEE ALSO
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
%  \BF{factorization\TEMPL{T}}, \BF{Fp\_polynomial}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  WARNINGS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

  \WARNINGS
  Using \TT{can\_zass}, \TT{sf\_can\_zass} or \TT{ddf} requires write permission
  in the \/tmp-directory or in the directory from which they are called.
  This is necessary because \TT{ddf} creates temporary files.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  EXAMPLES
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
#include <LiDIA/Fp_polynomial.h>
#include <LiDIA/factorization.h>

int main()
{

   Fp_polynomial f;

   factorization< Fp_polynomial > u;

   cout << "Please enter f : "; cin >> f ;

   u = factor(f);

   cout << "\nFactorization of f :\n" << u << "\n";

}
\end{verbatim}

%example:
%
%\TT{Please enter f : X^3 - 2*X - 1 mod 5} 
%
%\TT{Factorization of f :}
%\TT{[ [[1 1] mod 5,1], [[2 1] mod 5,2] ]}
%

For further examples please refer to \\
\TT{LiDIA/src/templates/factorization/Fp\_polynomial/Fp\_pol\_factor\_appl.c}.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  AUTHOR
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Victor Shoup, Thomas Pfahler

\end{lidia_man}
