%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  polynomial.tex       LiDIA documentation
%%
%%  This file contains the documentation of the template class polynomial
%%
%%  Copyright   (c)   1996   by  LiDIA-Group 
%%
%%  Authors: Stefan Neis, adding some own code to rewritten code of 
%%  Victor Shoup, Thomas Papanikolaou, Nigel Smart, Damian Weber who each
%%  contributed some part of the original code. 
%%

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

\markright{\BF{\GFPOL}}
\begin{lidia_man}

\NAME
\BF{\GFPOL} \DOTFILL specialization of the polynomials

\ABSTRACT
\BF{\GFPOL} is a class for computations with polynomials over finite fields.
This class is a specialization of the 
general \BF{polynomial\TEMPL{T}}, and you can apply all the functions and
operators of the general class \BF{polynomial\TEMPL{T}}. Moreover these
classes support some  additional functionality.

In the following we will describe the additional functions of the class
\BF{\GFPOL}.

\DESCRIPTION

The specializations use the representation of the general class
\BF{polynomial\TEMPL{T}} in addition with a reference to an element of the
class \BF{gf\_p\_base} characterizing the field over which the polynomial is
defined. So, every element of the class \GFPOL has ``its own field'', allowing
to use polynomials over different finite fields at the same time.
This field must be set explicitely if the polynomial is not the result of an
arithmetical operation.

\CONS

The specialization supports the same constructors as the general type, and the
following one:

\fcode{ct}{\GFPOL}{const gf\_p\_base \& PB}{
	initializes a zero polynomial over the field which is defined by the
	polynomial base \MATH{PB}.}


\BASIC

All arithmetical operations are done in the field over which the polynomials
are defined.
In principal, the lidia\_error\_handler is invoked if the ``const'' arguments
are not defined over the same finite fields.
The ``resulting'' polynomial receives the field of the ``input'' polynomials.

Let \MATH{f} be of type \BF{\GFPOL}:

\cfcode{const gf\_p\_base \&}{f.base}{}{
	returns the polynomial base describing the finite field over which
	\MATH{f} is defined.}
	
\fcode{void }{f.set\_base}{const gf\_p\_base \& PB}{
	sets the field over which \MATH{f} is defined.
	\MATH{f} is set to zero.}
	
\fcode{void }{f.assign\_zero}{const gf\_p\_base \& PB}{
	sets the field over which \MATH{f} is defined.
	\MATH{f} is set to zero.}
	
\fcode{void }{f.assign\_one}{const gf\_p\_base \& PB}{
	sets the field over which \MATH{f} is defined.
	\MATH{f} is set to the polynomial \MATH{1 \CDOT x^0}.}

\fcode{void }{f.assign\_x}{const gf\_p\_base \& PB}{
    sets the field over which \MATH{f} is defined.
    \MATH{f} is set to the polynomial \MATH{1 \CDOT x^1}.}


\ARTH

In addition to the operators of \BF{polynomial\TEMPL{T}} the following
operators are overloaded:

\begin{tabular}{|c|rcl|l|}\hline
binary & \GFPOL & \MATH{op} & \GFPOL & \MATH{op\IN\{\TT{/},\TT{\%}\}}\\\hline
binary with & \GFPOL & \MATH{op} & \GFPOL & \MATH{op\IN\{\TT{/=},\TT{\%=}\}}\\
assignment & & & &\\\hline
binary & \GFPOL & \MATH{op} & gf\_p\_element & \MATH{op \IN\{\TT{/}\}}\\\hline
binary with & \GFPOL & \MATH{op} & gf\_p\_element & \MATH{op \IN\{\TT{/=}\}}\\
assignment & & & &\\\hline
\end{tabular}

To avoid copying, these operations can also be performed by
the following functions (Let \MATH{f} be of type \BF{\GFPOL}.):

\fcode{void }{div\_rem}{\GFPOL \& q\k const
	\GFPOL \& r\k const \GFPOL \& f\k
	const \GFPOL \& g}{ 
	\MATH{f = q \CDOT g + r}, where \MATH{r.\TT{degree}() <
	g.\TT{degree}()}.} 

\fcode{void }{divide}{\GFPOL \& q\k const \GFPOL \& f\k const \GFPOL \& g}{
	Computes a polynomial \MATH{q}, such that \MATH{(f - q \CDOT
	g).\TT{degree}() < g.\TT{degree}()}.}

\fcode{void }{divide}{\GFPOL \& q\k const
	\GFPOL \& f\k const gf\_p\_element \& a}{ 
	\MATH{q = f/a}.}
        
\fcode{void }{remainder}{\GFPOL \& r\k const \GFPOL \& f\k const \GFPOL \& g}{
	Computes \MATH{r} with \MATH{r \equiv f \pmod{g} } and
	\MATH{r.\TT{degree}() < g.\TT{degree}()}.}

\fcode{void }{invert}{\GFPOL \& f\k const \GFPOL \& g\k lidia\_size\_t m}{
	\MATH{f \equiv g^{-1} \pmod{x^{m}}}. \\
	The constant term of \MATH{g} must be non-zero, otherwise the
	lidia\_error\_handler is invoked.}

			    
\STITLE{Greatest Common Divisor}

\fcode{\GFPOL }{gcd}{const \GFPOL \& f\k
  const \GFPOL \& g}{
  returns \MATH{gcd(f, g)}.}

\fcode{\GFPOL }{xgcd}{\GFPOL \& s\k
  \GFPOL \& t\k const \GFPOL \& f\k
  const \GFPOL \& g}{
  returns \MATH{gcd(f, g) = s \CDOT f + t \CDOT g}.}


\STITLE{Modular Arithmetic without pre-conditioning}

\fcode{void }{multiply\_mod}{\GFPOL \& g\k const \GFPOL \& a\k const \GFPOL \& b\k const \GFPOL \& f}{
	\MATH{g \equiv a \CDOT b \pmod{f}}.}

\fcode{void }{square\_mod}{\GFPOL \& g\k const \GFPOL \& a\k const \GFPOL \& f}{
	\MATH{g \equiv a^2 \pmod{f}}.}

\fcode{void }{multiply\_by\_x\_mod}{\GFPOL \& g\k const \GFPOL \& a\k const Fp\_polynomial \& f}{
	\MATH{g \equiv a \CDOT x \pmod{f}}.}

\fcode{void }{invert\_mod}{\GFPOL \& g\k const \GFPOL \& a\k const \GFPOL \& f}{
	\MATH{g \equiv a^{-1} \pmod{f}}. \\
	The lidia\_error\_handler is invoked if \MATH{a} is not invertible.}

\fcode{bool }{invert\_mod\_status}{\GFPOL \& g\k const \GFPOL \& a\k const Fp\_polynomial \& f}{
        returns \TRUE\ and sets \MATH{g \equiv a^{-1} \pmod{f}} if \MATH{gcd(a, f) = 1}; \\
        otherwise returns \FALSE\ and sets \MATH{g = gcd(a, f)}.}

\fcode{void }{power\_mod}{\GFPOL \& g\k const \GFPOL \& a\k const bigint \& e\k const \GFPOL \& f}{
        \MATH{g \equiv a^e \pmod{f}}.\\
        The polynomial \MATH{f} and the exponent \MATH{e} may not alias an output.}

\fcode{void }{power\_x\_mod}{\GFPOL \& g\k const bigint \& e\k const \GFPOL \& f}{
        \MATH{g \equiv x^e \pmod{f}}.\\
        The polynomial \MATH{f} and the exponent \MATH{e} may not alias an output.}

\fcode{void }{power\_x\_plus\_a\_mod}{\GFPOL \& g\k const bigint \& a\k const bigint \& e\k 
const \GFPOL \& f}{
        \MATH{g \equiv (x + a)^e \pmod{f}}.\\
        The polynomial \MATH{f} and the exponent \MATH{e} may not alias an output.}




\HIGH

Let \MATH{f} be an instance of type \BF{\GFPOL}.

\fcode{void }{cyclic\_reduce}{Fp\_polynomial \& f\k const Fp\_polynomial \& g\k lidia\_size\_t m}{
	\MATH{f \equiv g  \pmod{x^{m}-1}}.}

\fcode{base\_vector\TEMPL{bigint} }{find\_roots}{const Fp\_polynomial \& f}{
	returns the list of roots of \MATH{f}.\\
	Assumes that \MATH{f} is monic and has \MATH{f.degree()} distinct
	roots; otherwise the behaviour of this function is undefined.}

\fcode{void }{f.randomize}{const gf\_p\_base \& PB\k lidia\_size\_t n}{
	\MATH{f} is assigned a random polynomial of degree \MATH{n} over
	the field defined by \MATH{PB}.}
			    

\STITLE{Integration}

\fcode{void }{integral}{\GFPOL \& f\k const \GFPOL \& g}{
  computes \MATH{f}, such that \MATH{f'=g}.}

\fcode{\GFPOL}{integral}{const
  \GFPOL \& g}{
  returns a polynomial \MATH{f}, such that \MATH{f'=g}.}

\IO

The \BF{istream}  operator  \TT{>>}  and  the \BF{ostream}  operator \TT{<<}
are overloaded. The input formats and the output format are the same as for
the general class.

\medskip

\SEEALSO

        \BF{gf\_p\_base},
        \BF{polynomial\TEMPL{T}}


%\EXAMPLES
%\begin{verbatim}
%      #include <LiDIA/polynomial.h>
%
%      main()
%      {
%      }
%\end{verbatim}

\AUTHOR
        Thomas Pfahler, Stefan Neis
\end{lidia_man}

