%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  single_factor.tex
%
%  This file contains the documentation of the class single_factor
%
%  Copyright (c) 1996 by LiDIA-Group
%
%  Author:  Oliver Braun, Stefan Neis, Thomas Pfahler
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\def \fact  {\BF{factorization\TEMPL{T}}}
\def \ffact {factorization\TEMPL{T}}  % \fact f"ur fcode

\def \factbig {factorization\TEMPL{bigint}}

\def \sing  {\BF{single\_factor\TEMPL{T}}}
\def \fsing {single\_factor\TEMPL{T}}  % \sing f"ur fcode 

\def \base  {\BF{base\_factor\TEMPL{T}}}

\def \int   {\BF{int}}


\begin{lidia_man}

\markright{\sing}


\NAME

  \sing \dotfill parameterized class for factoring elements of type \BF{T}


\ABSTRACT

Including \BF{single\_factor.h} in an application allows the use of the
C++ type
\begin{center}
  \BF{single\_factor\TEMPL{T}}
\end{center}
for some data type \BF{T} which is allowed to be either a built-in type or
a class. 

\sing\ is a class for factoring elements of type \BF{T} and for storing
factors of a \fact. It offers elementary arithmetical operations and
information concerning  the primality of the represented element. This
class is used in the class \fact.

In \LiDIA, factorization algorithms are implemented for the following types:
\begin{itemize}
%\item \BF{single\_factor\TEMPL{bigint}}
%  (factorization of integers)
%\item \BF{single\_factor\TEMPL{ideal}}
%  (factorization of ideals)
\item \BF{single\_factor\TEMPL{Fp\_polynomial}}
  (factorization of polynomials over finite prime fields)
\item \BF{single\_factor\TEMPL{polynomial\TEMPL{gf\_p\_element}}}
  (factorization of polynomials over finite fields).
\end{itemize}
In the next release we plan to offer factorization algorithms for the
following additional types:
\begin{itemize}
\item \BF{single\_factor\TEMPL{bigint}}
  (factorization of integers, replacing \BF{rational\_factorization})
\item \BF{single\_factor\TEMPL{ideal}}
  (factorization of ideals).
\end{itemize}

\DESCRIPTION 

A \sing\ is internally represented by a variable of type \BF{T} named
\MATH{base} and a variable named \MATH{state} containing information about
the primality or compositeness of \MATH{base}.

\MATH{state} can hold '\TT{prime}', '\TT{not\_prime}' or '\TT{unknown}';
the latter indicating that nothing is known about primality or
compositeness of \MATH{base} so far.

A test for primality or compositeness is implemented in the function
\TT{is\_prime\_factor()}. Note that these tests may be based on tests with
limited capabilities. For example in the case of \BF{bigint}s the
Miller--Rabin--test is used which can prove compositeness, however, if an
integer is claimed to be prime, this might actually be wrong -- although
this is highly improbable.


\CONS

\fcode{ct}{\fsing}{}{
  initializes the \sing\ with the identity element (``\MATH{1}'') of the
  multiplication for elements of type \BF{T}.}
\fcode{ct}{\fsing}{const T \& a}{
  initializes the \sing\ with an element \MATH{a} of type \BF{T}. The
  \MATH{state} is set to ``unknown''.}
\fcode{ct}{\fsing}{const \fsing \& a}{
  initializes the \sing\ with the \sing \MATH{a}.}
\fcode{dt}{\MATH{\sim} \fsing}{}{}


\ASGN

The operator \TT{=} is overloaded and moreover the following assignment
functions exist. (Let \MATH{a} be an instance of type \sing.)

\fcode{void}{a.assign}{const \fsing \& b}{
  \MATH{a = b}.}
\fcode{void}{a.assign}{const T \& b}{
  \MATH{base} of \MATH{a} is set to \MATH{b}; \\
  \MATH{state} of \MATH{a} is set to ``unknown''.}


\COMP

The binary operators \TT{==}, \TT{!=}, \TT{<}, \TT{<=}, \TT{>=}, \TT{>} are
overloaded. Note that although these operators may do a meaningful
comparision of the elements represented by a \sing\ (e.g.~for bigints), the
operators may as well implement a completely artifical ordering relation
(e.g.~a lexical ordering), since this relation is only needed for sorting
vectors of type \sing.


\ARTH

The operators \TT{(binary) *, /} are overloaded, however using operator
\TT{/} is only a well--defined operation, if the divisor really divides the
first operand. Multiplication and division can also be performed by the
functions \TT{multiply} and \TT{divide}, which avoid copying and therfore
are faster than the operators. 

\fcode{void}{multiply}{\fsing \& c\k const \fsing \& a\k const \fsing
  \& b}{
  \MATH{c = a * b}.}

\fcode{void}{divide}{\fsing \& c\k const \fsing \& a\k const \fsing
 \& b}{
 \MATH{c = a / b}. Note that the behaviour of this function is undefined if
 \MATH{b} is not a divisor of \MATH{a}.}

\fcode{void}{gcd}{\fsing \& c\k const \fsing \& a\k const \fsing \&
  b}{
  \MATH{c = gcd(a,b)}.}

\fcode{lidia\_size\_t}{ord\_divide}{const \fsing \& a\k \fsing \& b}{
 returns the largest non--negative integer \MATH{e} such that \MATH{a^e}
 divides \MATH{b}. \MATH{b} is divided by \MATH{a^e}.}


\ACCS

Let \MATH{a} be an instance of type \sing.

\fcode{T \&}{a.base}{}
{returns a reference to the element of type \BF{T} represented by \MATH{a}.}

\cfcode{const T \&}{a.base}{}
{returns a reference to the element of type \BF{T} represented by \MATH{a}.}


\HIGH

\bigskip

  Let \MATH{a} be an instance of type \sing.

\STITLE{Queries}

\fcode{bool}{a.is\_prime\_factor}{int test=0}{  
  returns \TRUE, if \MATH{f} is a prime factorization according to a test in
  class \sing.
  This test either can be a {\bf compositeness test}, which decides whether
  \MATH{f} is composite or probably prime or a {\bf primality test} which
  proofs that \MATH{f} is prime. If \MATH{test \neq 0}, an explicit test is
  done if we do not yet know, whether or not \MATH{a} is prime, otherwise
  only \MATH{state} is checked.}
    

%    For type \BF{single\_factor\TEMPL{bigint}}, this primality test is done
%    by the function \BF{is\_prime} (see the description of the class \BF{bigint}).
%    For type \BF{single\_factor\TEMPL{Fp\_polynomial}}, this primality test is done
%    by the function \BF{is\_irreducible} (see the description of the class
%    \BF{Fp\_polynomial}).
%    For type \BF{single\_factor\TEMPL{ideal}}, this primality test is done
%    by the function \BF{is\_prime\_ideal} (see the description of the class
%    \BF{ideal}).}


\STITLE{Modifying Operations}

\fcode{void}{swap}{\fsing a\k \fsing b}{
  swaps the values of \MATH{a} and \MATH{b}.}

\fcode{T}{a.extract\_unit}{}{
 sets \MATH{a} to a fixed representant of the equivalence class \MATH{a}{U}
 where U is the group of units of type \BF{T}. The unit \MATH{\epsilon} by
 which we have to multiply the new value of \MATH{a} to obtain the old one
 is returned.}

\fcode{\ffact}{a.factor}{}{
 returns a factorization of the element of type \BF{T} represented by the
 \sing\ \MATH{a}, if a suitable routine for \sing\ is defined. Otherwise,
 you only get a message saying that no factorization routine has been
 implemented for that type.}


\IO

  The \BF{istream} operator \TT{\MATH{>>}} and the \BF{ostream} operator\TT{\MATH{<<}} are
  overloaded.
  By now, the I/O-format is identical to that of elements of type \BF{T}.

\NOTES

The type \BF{T} has to offer the following functions:
\begin{itemize}
\item the assignment operator \MATH{=}
\item the operator \MATH{=}(\BF{int}), if you don't specialize the
  constructors
\item a swap function \TT{void swap(T\&, T\&)}
\item the friend -- functions \TT{multiply}, \TT{divide}, \TT{gcd}
\item the input--operator \TT{>>} and
\item the output--operator \TT{<<}
\item the comparison--operators \TT{<}, \TT{<=}, \TT{==}, \TT{!=}
\end{itemize}

\SEEALSO
  \fact,
  \BF{bigint}, \BF{Fp\_polynomial}, \BF{polynomial\TEMPL{gf\_p\_element}},
  \BF{module/ideal}

\AUTHOR
%Franz-Dieter Berger,
Oliver Braun, Thomas F.~Denny,
%Andreas M\"uller, Volker M\"uller,
Stefan Neis, Thomas Pfahler
%Thomas Sosnowski

\end{lidia_man}

