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


\begin{lidia_man}

\markright{\bf factorization}

\NAME
  \fact \dotfill parametrized class for computing with factorizations


\ABSTRACT
  Including \BF{factorization.h} in an application allows the use of the
  C++ type \fact\ for some data type \BF{T} which is allowed to be either a
  built-in type or a class.

  \fact\ is a class for holding factorizations.
  There are elementary access functions, functions for computing with
  factorizations and modifying operations.

  The class \fact\ is the return type of the factorization algorithms in
  the class \sing.

\DESCRIPTION
  The factorization of an element of type \BF{T} is internally represented by 
  \begin{itemize}
  \item a unit \MATH{\epsilon}, which is automatically extracted from all
    bases (see function \TT{extract\_unit()} of class \sing) and
  \item two \BF{vector}s \MATH{p} and \MATH{c} of pairs
    \MATH{p_i = (ibase_i(p),exp_i(p))} and \MATH{c_i =
    (ibase_i(c),exp_i(c))} with \MATH{l(p)} and \MATH{l(c)} components,
    respectively. These vectors represent the factors assumed to be prime
    (or irreducible) and those where we know nothing about primality (or
    irreducibility), respectively. In an abuse of language, we call the
    bases of the components of \MATH{c}, i.e.~the components which might be
    composite factors, the ``composite components'', although this is not
    generally correct.

    \MATH{(ibase_i(x),exp_i(x))} denotes the \MATH{i}-th component of the
    vector \MATH{x}, where
    \begin{itemize}
    \item \MATH{ibase_i(x)} is of type \sing, and
    \item \MATH{exp_i(x)} is of type lidia\_size\_t.
    \end{itemize}
  \end{itemize}
 
  So a \fact\ \MATH{f} represents the element

  \begin{latexonly}
   \[f \quad = \quad \epsilon \quad \cdot \quad \prod\limits_{i =
     0}^{l(p)-1}\; ibase_i.base(p) ^ {exp_i(p)} \quad \prod\limits_{i =
     0}^{l(c)-1}\; ibase_i.base(c) ^ {exp_i(c)} \quad.\]
  \end{latexonly}
  \html{\begin{verbatim}
              l(p) - 1                       l(c) - 1
             ---------                      ---------
               |   |               exp_i(p)   |   |               exp_i(c)
f =   eps *    |   | ibase_i.base(p)          |   | ibase_i.base(c)
               |   |                          |   |
               i = 0                          i = 0

  \end{verbatim}}

  Different bases \MATH{ibase_i(x), ibase_j(y) (i\neq j)} of the vectors
  are not necessarily coprime. Especially, a \fact\ does not generally
  represent a prime factorization. 

\CONS

\fcode{ct}{\ffact}{}{
  initializes a factorization of length zero.
  \MATH{\epsilon} is set to ``\MATH{1}'' (the identity element of the
  multiplication for elements of type \BF{T}).}

\fcode{ct}{\ffact}{const \ffact \& f}{
  initializes the factorization with a copy of \MATH{f}.}

\fcode{ct}{\ffact}{const \fsing \& a}{
  initializes the factorization with \MATH{a}.}

\fcode{dt}{\MATH{\sim}\ffact}{}
   {}


\ASGN

The operator \TT{=} is overloaded and additionally the following assignment
functions exist: \\
Let \MATH{f} be an instance of type \fact.

\fcode{void}{f.assign}{const \ffact \& g}{
  \MATH{f} = \MATH{g}.}
\fcode{void}{f.assign}{const \fsing \& a}{
  \MATH{f} = \MATH{a}.}


\COMP

The binary operators \TT{==} and \TT{!=} are overloaded.

%Let \MATH{f} and \MATH{g} be two \fact.
%  Let \MATH{f'} and \MATH{g'} be the normalized factorizations of \MATH{f} and \MATH{g}, respectively (see
%  function \TT{normalize()}).
%  Then \MATH{f} and \MATH{g} are considered to be equal if
%  \begin{itemize}
%     \item \MATH{f'.unit() == g'.unit()}
%     \item \MATH{f'.no\_of\_components() = g'.no\_of\_components()} \ \ and
%     \item \MATH{f'.ibase(i) == g'.ibase(i)} for \MATH{i = 0,\LDOTS,f'.no\_of\_components()-1} ,
%  \end{itemize}
%  where ``=='' is the operator defined for the data type \BF{T} and the class \sing,
%  respectively.
Two \fact s \MATH{f} and \MATH{g} are considered to be equal if the value
represented by \MATH{f} is equal to the value represented by \MATH{g}. Note
that this can be checked efficiently by using factor refinement.


\ARTH

The following operators are overloaded:

\begin{center}
  \TT{(binary) *, /}
\end{center}

These operations can also be performed by the functions \TT{multiply()} and
\TT{divide()} (which avoid copying and are therefore faster than the
operators).

\fcode{void}{multiply}{\ffact \& h\k  const \ffact \& f\k  const \ffact
   \& g}{
   \MATH{h = f * g}, i.e.~the components of the factorizations of \MATH{f}
   and \MATH{g} are combined to the factorization \MATH{h}, such that
   \MATH{h} represents the element \MATH{f \cdot g}.}

  \fcode{void}{multiply}{\ffact \& h\k  const \ffact \& f\k  const
   \fsing \& a}{
   \MATH{h = f * a}, i.e.~the components of the factorization of \MATH{f}
   and the \sing\ \MATH{a} are combined to the factorization \MATH{h},
   such that \MATH{h} represents the element \MATH{f \cdot a}.}

  \fcode{void}{divide}{\ffact \& h\k  const \ffact \& f\k  const \ffact
   \& g}{
   \MATH{h = f / g}, i.e.~the components of the factorizations of \MATH{f}
   and \MATH{g} are combined to the factorization \MATH{h}, such that
   \MATH{h} represents the element \MATH{f / g}.}

  In the following, let \MATH{f} be an instance of type \fact.

  \fcode{void}{f.invert}{}{
    \MATH{f} is inverted (by negating the exponents).}

%     All exponents of \MATH{f} are negated and \MATH{\epsilon} is set to \MATH{1/\epsilon},
%     where `1' is the identity element of the multiplication for elements of type
%     \bf{T}.}

  \fcode{void}{invert}{\ffact \& h\k  const \ffact \& f}
   { sets \MATH{h = f^{-1}}.}

  \fcode{\ffact}{inverse}{\ffact \& f}
   { returns \MATH{f^{-1}}.}

  \fcode{void}{f.square}{}
   { sets \MATH{f = f^2}, i.e.~all exponents in the representation of
   \MATH{f} are multiplied by 2 and the unit is squared.}
 \fcode{void}{square}{\ffact\& h\k  const \ffact\& f}
   { sets \MATH{h = f^2}.}

  \fcode{void}{f.power}{lidia\_size\_t i}{
    sets \MATH{f = f^i}, i.e.~all exponents in the represenation of
    \MATH{f} are multiplied by i and the unit is replaced by its \MATH{i}-th
    power.} 
  \fcode{void}{power}{\ffact\& h\k  const \ffact\& f\k  lidia\_size\_t i}
   { sets \MATH{h = f^i}.}


\ACCS

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

\fcode{\fsing}{f.prime\_base}{lidia\_size\_t i}{
  returns \MATH{ibase_{i}(p)}. If \MATH{i<0} or if \MATH{i} is greater than
  or equal to the number of components of \MATH{p}, the \TT{error\_handler}
  will be invoked.}
\fcode{\fsing}{f.composite\_base}{lidia\_size\_t i}{
  returns \MATH{ibase_{i}(c)}. If \MATH{i<0} or if \MATH{i} is greater than
  or equal to the number of components of \MATH{c}, the \TT{error\_handler}
  will be invoked.}

\fcode{lidia\_size\_t}{f.prime\_exponent}{lidia\_size\_t i}{
  returns \MATH{exp_{i}(p)}. If \MATH{i<0} or if \MATH{i} is greater than
  or equal to the number of components of \MATH{p}, the \TT{error\_handler}
  will be invoked.}
\fcode{lidia\_size\_t}{f.composite\_exponent}{lidia\_size\_t i}{
  returns \MATH{exp_{i}(c)}. If \MATH{i<0} or if \MATH{i} is greater than
  or equal to the number of components of \MATH{c}, the \TT{error\_handler}
  will be invoked.}
\fcode{lidia\_size\_t}{f.no\_of\_prime\_components}{}{
  returns the number of components of \MATH{p}, which is the number of
  \MATH{(ibase,exp)} -- pairs of \MATH{p}.}
\fcode{lidia\_size\_t}{f.no\_of\_composite\_components}{}{
  returns the number of components of \MATH{c}, which is the number of
  \MATH{(ibase,exp)} -- pairs of \MATH{c}.}
\fcode{lidia\_size\_t}{f.no\_of\_components}{}{
  returns the number of components of \MATH{f}, which is the sum of the
  number of prime and composite components.}
\fcode{T}{f.unit}{}{
  returns the unit \MATH{\epsilon}.}
\fcode{T}{f.value}{}{
  returns the element of type \BF{T} that is represented by the
  factorization of \MATH{f}. Note that this computation will take a long
  time and will consume lots of memory, if the exponents involved in the
  computation are large.}


\HIGH

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


\STITLE{Modifying Operations}

\fcode{void}{f.replace}{lidia\_size\_t pos\k \ffact\ g}{
  This function is used to replace a composite component by its
  factorization. It replaces the composite component at position \MATH{pos}
  by the composite components of the factorization \MATH{g}. The prime
  components of \MATH{g} are appended to the prime components of \MATH{f}.}

\fcode{void}{f.sort}{}{
  sorts the prime components as well as the composite componentes of the
  factorization in ascending order according to the size of the \sing\ and
  the size of the exponents, so that \MATH{f.ibase(i) \ <= f.ibase(j)} for
  all \MATH{i < j} and, if \MATH{f.ibase(i) == f.ibase(j)}, \MATH{f.exp(i)
  \leq f.exp(j)}. 
  The operators ``\MATH{<=}'' and ``\MATH{==}'' are to be defined in the
  class \sing.}

\fcode{void}{f.normalize}{}{
  sorts the factorization \MATH{f} and collects equal bases, such that
  \MATH{f.ibase_i(p) \ != f.ibase_j(p)}, \MATH{f.ibase_i(c) \ !=
  f.ibase_j(c)} for all \MATH{i \neq j}, and \MATH{f.ibase_i(p) \ !=
  f.ibase_j(c)} for all \MATH{i,j}. ``\MATH{!=}'' has to be defined in
  the class \sing.}

\fcode{void}{f.refine}{}{
  refines the factorization \MATH{f} such that the bases of \MATH{f} are
  pairwise coprime, i.e. \MATH{gcd(f.ibase_i(x), f.ibase_j(y))) == '1'} for
  \MATH{x,y \in\{p,c\}} and all \MATH{i,j}. The function \TT{gcd} has to be
  defined in the class \sing.}

\fcode{void}{f.factor}{}{
  factors all composite components and replaces each such component
  \MATH{f.ibase_i(c)} by its factorization
  \TT{factor(}\MATH{f.ibase_i(c)}\TT{)}, \MATH{i = 0,\LDOTS,} 
  \MATH{f.no\_of\_composite\_components()-1} using the function
  \TT{replace} describe above. The function \TT{factor} must be defined in
  the class \sing.}


\STITLE{Queries}

\fcode{bool}{f.is\_prime\_factorization}{int test=0}{
  returns \TRUE, if \MATH{f} is a prime factorization according to the test
  in class \sing.
  This test can either 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 for every composite
  component with unknown prime state, otherwise we only check, whether
  there are composite components.}
%     returns \TRUE, if \MATH{f} is a prime factorization according to the (compositeness)
%     primality test in class \sing.
%     If \MATH{test \neq 0}, an explicit primality test is done for every base (if
%     necessary), otherwise only flags are checked.
%     Therefore, the return value \FALSE\ may not be correct if \MATH{test = 0}.
%     The return value \TRUE\ is always correct
%     (as stated above, according to the primality test in class \sing).

\fcode{bool}{f.is\_sorted}{}{
  returns \TRUE, if \MATH{f} has already been sorted using the function
  \TT{f.sort()} (which is decided by checking a flag).}
%  returns \TRUE, if \MATH{f.ibase_i(x) <= f.ibase_j(x)} for all \MATH{i < j}
%  and, if \MATH{f.ibase_i(x) == f.ibase_j(x)}, \MATH{f.exp_i(x) \leq
%  f.exp_j(x)} for both \MATH{x=p} and \MATH{x=c};
%  otherwise, \FALSE\ is returned. The operators ``\MATH{<=}'' and
%  ``\MATH{==}'' are defined in the class \sing.}

\fcode{bool}{f.is\_normalized}{}{
  returns \TRUE, if \MATH{f} has been normalized using the function
  \TT{f.normalize()} (which is decided by checking a flag).}
%  returns \TRUE, if \MATH{f} is normalized, i.e. \MATH{f} is sorted and
%  \MATH{f.ibase(i)\ != f.ibase(j)} for all \MATH{i \neq j}, where
%  ``\MATH{!=}'' is defined in the class \sing. Otherwise, \FALSE\ is
%  returned.}

\fcode{bool}{f.is\_refined}{}{
  returns \TRUE, if \MATH{f} has been refined using the function
  \TT{f.refine()}. (which is decided by checking a flag)}
%  returns \TRUE, if \MATH{f} is normalized and \MATH{gcd(f.ibase(i),
%  f.ibase(j)) == '1'} for all \MATH{i \neq j}, where the function \TT{gcd}
%  is defined in the class \sing). Otherwise, \FALSE\ is returned.}

\IO

The \BF{istream} operator \TT{>>} and the \BF{ostream} operator\TT{<<} are
overloaded. 
The \BF{ostream} operator \TT{<<} prints a \fact\ in the following format:
  \begin{center}
   \MATH{[\ \epsilon\ ,\ [ibase_0(p).base,exp_0(p)],\,
                         [ibase_1(p).base,exp_1(p)],\,\ldots \,,
                         [ibase_{l-1}(p).base,exp_{l(p)-1}(p)],}\\
   \MATH{                [ibase_0(c).base,exp_0(c)],\,
                         [ibase_1(c).base,exp_1(c)],\,\ldots \,,
                         [ibase_{l-1}(c).base,exp_{l(c)-1}(c)]\,]}
  \end{center}

  where \MATH{\epsilon} is a unit (as explained at the beginning),
  If this unit is the neutral element of multiplication, it is omitted
  unless \MATH{l(p)=l(c)=0}. 

  The \BF{istream} operator \TT{>>} assumes all components to be composite,
  so the input format is the following (again, the unit is optional unless
  \MATH{l(c)=0}):

  \begin{center}
   \MATH{[\ \epsilon\ ,\ [ibase_0(c).base,exp_0(c)],
            \,\ldots \,, [ibase_{l-1}(c).base,exp_{l(c)-1}(c)]\,]}
  \end{center}

  So in practice input/output looks like
\begin{verbatim}
[ [ x^2 - 1 mod 5, 1], [x^2 + 1 mod 5, 2] ].
\end{verbatim}

\NOTES

\begin{itemize}
\item The type \MATH{T} must at least have the following functions:
  \begin{itemize}
  \item the assignment operator $=$
  \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}
\item The numeration of the components in a \fact\ starts with zero.
  (As usually in ``C / \CPP'')
\end{itemize}

\SEEALSO

\sing, \BF{sort\_vector\TEMPL{T}}


\EXAMPLES

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

main()
{
    factorization<Fp_polynomial> f;
    cout<<"Please enter a factorization of type Fp_polynomial:";
    cout<<endl;

    cin >> f;

    cout << "You entered a factorization with ";
    cout << f.no_of_components();
    cout << " components." << endl << endl;

    cout << "The value represented by the factorization is " << endl;
    cout << f.value() << "." << endl << endl;

    f.factor_all_components();

    cout << "The prime factorization is :" << endl;
    cout << f <<endl;
}
\end{verbatim}


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

\end{lidia_man}
