%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  gf_poly_modulus.tex       LiDIA documentation
%%
%%  This file contains the documentation of the class poly_modulus
%%
%%  Copyright   (c)   1996   by  LiDIA-Group 
%%
%%  Authors: Thomas Pfahler
%%

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

\begin{lidia_man}
\markright{\BF{gf\_poly\_modulus}}

\NAME
	\BF{gf\_poly\_modulus}  \DOTFILL  class for efficient computations modulo\\
		polynomials over finite fields


\ABSTRACT
	If you need to do a lot of arithmetic modulo a fixed \BF{\GFPOL} 
	\MATH{f}, build a \BF{gf\_poly\_modulus} \MATH{F} for \MATH{f}. This 
	pre-computes information about \MATH{f} that speeds up the computation 
	a great deal, especially for large polynomials.


\DESCRIPTION

	The pre-computations for variables of type \BF{gf\_poly\_modulus} as well 
	consist of evaluating special representations. For further description,
	see \cite{Pfahler96}.

\bigskip

\CONS

\fcode{ct}{gf\_poly\_modulus}{}{
	no initialization is done; you must call the member-function \MATH{build} 
	(see below) before using this \BF{gf\_poly\_modulus} in one of the arithmetical
	functions.}

\fcode{ct}{gf\_poly\_modulus}{const \GFPOL \& f}{
    initializes for computations modulo \MATH{f}.}

\fcode{dt}{\MATH{\sim}gf\_poly\_modulus}{}{}


\BASIC

	Let \MATH{F} be of type \BF{gf\_poly\_modulus}.

\fcode{void }{F.build}{const \GFPOL \& f}{
  	initializes for computations modulo \MATH{f}.}


\ACCS
	
	Let \MATH{F} be of type \BF{gf\_poly\_modulus}.

\cfcode{const \GFPOL \& }{F.modulus}{}{
  	returns a constant reference to the polynomial for which \MATH{F}
	was build.}


\ARTH

	As described in the section \BF{\GFPOL}, each polynomial carries a
	reference to an element of type \BF{gf\_p\_base} representing the
	finite field over which the polynomial is defined.
	Therefore, if the finite fields of the ``const'' arguments are not
	the same, the lidia\_error\_handler is invoked.\\
	The ``resulting'' polynomial receives the finite field of the ``input'' 
	polynomials.

\medskip


\fcode{void }{remainder}{\GFPOL \& g\k const \GFPOL \& a\k const gf\_poly\_modulus \& F}{
  	\MATH{ g \equiv a \pmod{F.modulusl()}}.\\
	No restrictions on \MATH{a.degree()}.}

\fcode{void }{multiply}{\GFPOL \& g\k const \GFPOL \& a\k const \GFPOL \& b\k const gf\_poly\_modulus \& F}{
	\MATH{g \equiv a \CDOT b \pmod{F.modulus()}}.\\
	If \MATH{a.degree()} or \MATH{b.degree() \ge F.modulus().degree()},
	the lidia\_error\_handler is invoked.}

\fcode{void }{square}{\GFPOL \& g\k const \GFPOL \& a\k const gf\_poly\_modulus \& F}{
	\MATH{g \equiv a^2 \pmod{F.modulus()}}.\\
	If \MATH{a.degree() \ge F.modulus().degree()}, the lidia\_error\_handler 
	is invoked.}

\fcode{void }{power}{\GFPOL \& g\k const \GFPOL \& a\k const bigint \& e\k const gf\_poly\_modulus \& F}{
	\MATH{g \equiv a^e \pmod{F.modulus()}}.\\
	If \MATH{e < 0}, the lidia\_error\_handler is invoked.}

\fcode{void }{power\_x}{\GFPOL \& g\k const bigint \& e\k const gf\_poly\_modulus \& F}{
	\MATH{g \equiv x^e \pmod{F.modulus()}}.\\
	If \MATH{e < 0}, the lidia\_error\_handler is invoked.}

\fcode{void }{power\_x\_plus\_a}{\GFPOL \& g\k const bigint \& a\k const bigint \& e\k const gf\_poly\_modulus \& F}{
	\MATH{g \equiv (x + a)^e \pmod{F.modulus()}}.\\
	If \MATH{e < 0}, the lidia\_error\_handler is invoked.}


\medskip

\HIGH
%\fcode{void }{min\_poly}{\GFPOL \& h\k const \GFPOL \& g\k lidia\_size\_t m\k const gf\_poly\_modulus \& F}{
%        computes the monic minimal polynomial \MATH{h} of
%        (\MATH{g} mod \MATH{F.modulus()}).
%        \MATH{m} is an upper bound on the degree of the minimal polynomial.
%        The algorithm is probabilistic, always returns a divisor of
%        the minimal polynomial, and returns a proper divisor with
%        probability at most \MATH{m/g.modulus()}.}
%
%\fcode{void }{checked\_min\_poly}{\GFPOL \& h\k const \GFPOL \& g\k lidia\_size\_t m\k const gf\_poly\_modulus \& F}{
%        same as \MATH{min\_poly}, but guarantees that result is correct.}
%
%\fcode{void }{irred\_poly}{\GFPOL \& h\k const \GFPOL \& g\k lidia\_size\_t m\k const gf\_poly\_modulus \& F}{
%        same as \MATH{min\_poly}, but assumes that \MATH{F.modulus()}
%        is irreducible (or at least that the minimal polynomial of \MATH{g} is
%        itself irreducible).\\
%        The algorithm is deterministic (and hence is always correct).}
%
%\fcode{void }{compose}{\GFPOL \& c\k const \GFPOL \& g\k const \GFPOL \& h\k const gf\_poly\_modulus \& F}{
%	\MATH{c = g(h)} modulo \MATH{F.modulus()}.}
%

\fcode{void }{trace\_map}{\GFPOL \& w\k const \GFPOL \& a\k
lidia\_size\_t d\k const gf\_poly\_modulus \& F\k const \GFPOL \& b}{
	\MATH{w = \SUM{i=0}{d-1}{a^{q^i}}} mod \MATH{F.modulus()}.\\
	It is assumed that \MATH{d \GE 0}, \MATH{q} is a power of
	\MATH{F.modulus().modulus()}, and \MATH{b = x^q} modulo
	\MATH{F.modulus()}, otherwise the behaviour of this function is
	undefined.}
		  

%\fcode{void }{power\_compose}{\GFPOL \& w\k const \GFPOL \& b\k lidia\_size\_t d\k const gf\_poly\_modulus \& F}{
%	\MATH{w = x^{q^d}} mod \MATH{F.modulus()}.\\
%	It is assumed that \MATH{d \GE 0}, \MATH{q} is a power of
%	\MATH{F.modulus().modulus()}, and \MATH{b = x^q} modulo
%	\MATH{F.modulus()}, otherwise the behaviour of this function is
%	undefined.}


\medskip

\SEEALSO

	\BF{\GFPOL}
	\BF{poly\_modulus}


\EXAMPLES
\begin{verbatim}
    #include <LiDIA/polynomial.h>
    #include <LiDIA/gf_p_element.h>

    ...
    polynomial< gf_p_element >  a, b, f, x, y;
    gf_poly_modulus F;

    ...

    multiply_mod(x, a, b, f);

    F.build(f);
    multiply(y, a, b, F);

    //now, x == y

    ...
\end{verbatim}


\AUTHOR
	Victor Shoup (ideas) \\
	Thomas Pfahler

\end{lidia_man}
