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

\begin{lidia_man}

\def\GFPOL{polynomial\TEMPL{gf\_p\_element}}
%\def\GFPOL{gf\_polynomial}
\def\sfgf{single\_factor\TEMPL{\GFPOL}}

\markright{\BF{\sfgf}}

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

\ABSTRACT
\BF{\sfgf} is used for storing factorizations of polynomials over finite  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{\sfgf}, 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


%\STITLE{Constructor}

\STITLE{Modifying Operations}

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

\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{\sfgf}.

\fcode{factorization\TEMPL{\GFPOL} }
    {square\_free\_decomp}{const \GFPOL \& 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{\GFPOL} }
    {a.square\_free\_decomp}{}{
    returns \MATH{square\_free\_decomp(a.base())}.}

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


\fcode{factorization\TEMPL{\GFPOL} }
    {berlekamp}{const \GFPOL \& 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{\GFPOL} }
    {a.berlekamp}{}{
    returns \MATH{berlekamp(a.base())}.}

\fcode{factorization\TEMPL{\GFPOL} }
    {sf\_berlekamp}{const \GFPOL \& 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{\GFPOL} }
    {a.sf\_berlekamp}{}{
    returns \MATH{sf\_berlekamp(a.base())}.}

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


\fcode{factorization\TEMPL{\GFPOL} }
    {can\_zass}{const \GFPOL \& 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.}

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

\fcode{factorization\TEMPL{\GFPOL} }
    {sf\_can\_zass}{const \GFPOL \& f}{
    returns the complete factorization of \MATH{f} using
    a DDF according to Cantor/Zassenhaus,
    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.}

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


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

\fcode{factorization\TEMPL{\GFPOL} }
    {factor}{const \GFPOL \& 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{\GFPOL} }
    {a.factor}{}{
    returns \MATH{factor(a.base())}.}


\fcode{bool }{det\_irred\_test}{const \GFPOL \& f}{
    performs a deterministic irreducibility test (based on \TT{berlekamp}).}
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  SEE ALSO
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO

  \BF{factorization\TEMPL{T}}
  
  \BF{\GFPOL}



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



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

\EXAMPLES

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


\NOTES
The main ideas for speeding up polynomial computation and factorization algorithms
are attributed to Victor Shoup \cite{ShoupGF}

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

\AUTHOR
Thomas Pfahler

\end{lidia_man}
