%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  fact.tex       LiDIA documentation
%%
%%  This file contains the documentation of the class
%%  rational_factorization
%%
%%  Copyright   (c)   1995   by  LiDIA-Group
%%      
%%  Authors: Andreas Mueller
%%

\begin{lidia_man}

\markright{\BF{rational\_factorization}}

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

\NAME
\BF{rational\_factorization} \DOTFILL         class for factoring rational
numbers and representing factorizations 
\label{rational_fact_class}

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

\ABSTRACT 
\BF{rational\_factorization} is a class for factoring non-zero 
rational numbers and holding factorizations. At the moment
\EM{ trial division (TD)}, the \EM{ elliptic curve method (ECM)}
(see \cite{lenstra_ecm}) and the \EM{quadratic sieve (QS)} (see 
\cite{pom_qs}) are supported. Depending on the size of the number
to be factored, different combinations of \EM{ TD}, \EM{ECM}
and \EM{QS} are chosen. In addition it is possible to use own
strategies by changing various parameters of \EM{TD} and \EM{ECM}.

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

\DESCRIPTION 
The factorization of a rational number is internally represented by
an int variable \BF{sign} and a vector of pairs
\BF{(base,exp)}, where \MATH{base} is of type \BF{bigint} and
\MATH{exp} of type int. 
Let in the following
\MATH{(base_i,exp_i)} denote the \MATH{i}-th vector component and \MATH{l} the
length of the vector. The length of a \BF{rational\_factorization} is
defined as length of ``its vector''. Then this \BF{rational\_factorization}
represents the rational number
\latex{
\[f\quad =\quad sign \CDOT \prod\limits_{i = 0}^{l-1}\; base_i
^{exp_i}.\]
}

\html{\begin{verbatim}
                             l - 1
                            --------'       exp_i
                           '  |  |           
              f =   sign *    |  |    base_i 
                              |  |        
                              |  |
                             i = 0
        

\end{verbatim}}
The value of \MATH{sign} is either \MATH{1} or \MATH{-1}. The values of
the bases \MATH{base_i} are always positive. 
The vector is sorted according to the
size of the value of the \MATH{base} component. 
Note that the rational
number 0 can not be represented by a \BF{rational\_factorization}.
Different bases \MATH{base_i}, \MATH{base_j} \MATH{(i\NEQ j)} of the
vector are not equal, but not necessarily coprime. In particular, a
\BF{rational\_factorization} does in general not represent the prime
factorization of a rational number.  

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

\CONS
All constructors invoke the \TT{lidia\_error\_handler} if the value of the input
variable is 0. 


\fcode{ct}{rational\_factorization}{}
{
initializes the variable with 1.}

\fcode{ct}{rational\_factorization}{int}{}
\fcode{ct}{rational\_factorization}{unsigned int}{}
\fcode{ct}{rational\_factorization}{long}{}
\fcode{ct}{rational\_factorization}{unsigned long}{}
\fcode{ct}{rational\_factorization}{const bigint \&}{}
\fcode{ct}{rational\_factorization}{const bigrational \&}{}
\fcode{ct}{rational\_factorization}{const rational\_factorization \&}{}
\fcode{dt}{\SIM rational\_factorization}{}{}

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

\ASGN
Let \MATH{a} be of type \BF{rational\_factorization}. The operator \TT{=}
is overloaded and the following assignment functions exist. If you try
to assign 0 to a variable of type \BF{rational\_factorization}, the
\TT{lidia\_error\_handler} will be invoked. 


\fcode{void}{a.assign}{long i}
{
a = i.}

\fcode{void}{a.assign}{const bigint \& I}
{
a = I.}

\fcode{void}{a.assign}{const bigrational \& J}
{
a = J.}

\fcode{void}{a.assign}{const rational\_factorization \& F}
{
a = F.}

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

\ACCS
\cfcode{lidia\_size\_t}{a.no\_of\_comp}{}
{
returns the number of
components of the \BF{rational\_factorization} \MATH{a}, which is the
number of different \MATH{(base,exp)}-pairs.}


\cfcode{int}{a.sign}{}
{
returns the sign of the
rational number represented by \MATH{a}.}


\cfcode{bigint}{a.base}{lidia\_size\_t i}
{
returns \MATH{base_{i}}. If \MATH{i<0}
or if \MATH{i} is greater or equal than the number of components of \MATH{a},
the \TT{lidia\_error\_handler} will be invoked.}


\cfcode{int}{a.exponent}{lidia\_size\_t i}
{
returns \MATH{exp_{i}}. If \MATH{i<0}
or if \MATH{i} is greater or equal than the number of components of \MATH{a},
the \TT{lidia\_error\_handler} will be invoked.}

\fcode{void}{a.set\_exponent}{lidia\_size\_t i, int e} 
{ 
set \MATH{exp_{i}=e}. If \MATH{i<0} or if \MATH{i} is greater or equal
than the number of components of \MATH{a}, the \TT{lidia\_error\_handler} 
will be invoked.}

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

\ARTH
The following operators are overloaded and can be used in exactly the same way
as for machine types in C (e.g.~int) :

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

Let \MATH{a} be of type \BF{rational\_factorization}.

To avoid copying, these operations can also be performed by
the following functions:


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


\fcode{void}{a.square}{}{}

\fcode{void}{square}{rational\_factorization \& c\k const    rational\_factorization \& a}
{
\MATH{c = a^2}.}


\fcode{void}{divide}{rational\_factorization \& c\k const    rational\_factorization \& a\k const rational\_factorization \& b}
{
\MATH{c = a / b}.}


\fcode{void}{a.invert}{}{}

\fcode{void}{invert}{rational\_factorization \& c\k const    rational\_factorization \& a}
{
\MATH{c = a^{-1}}.}

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

\COMP
The binary operators \TT{==} and \TT{!=} are overloaded and can be
used in exactly the same way as for machine types in C (e.g.~int).

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

\HIGH
\STITLE{General High-Level Functions}
\fcode{void}{a.verbose}{int state}
{
sets the amount of information which
is printed during computations. If \MATH{state = 1} then the
factorization functions print information about the strategy, for
\MATH{state = 0} there is no such output. The predefined value is
\MATH{state = 0}.}


\fcode{bool}{a.is\_prime\_factor}{lidia\_size\_t i}
{
returns \TRUE\ if
\MATH{base_{i}} is probably a prime number, otherwise \FALSE . For checking
primality the \BF{bigint} function \TT{is\_prime()} is used, which
uses a probabilistic primality test.}


\fcode{bool}{a.is\_prime\_factorization}{}
{
returns \TRUE\ if
\MATH{a} is probably a prime factorization of a rational number,
\FALSE\ otherwise. For checking primality the \BF{bigint} function
\TT{is\_prime()}, which uses a probabilistic primality test
on each base element of \MATH{a}, is used.}


\fcode{void}{a.refine}{}
{
refines the factorization \MATH{a} such that the
bases of \MATH{a} are pairwise coprime.}


\fcode{bool}{a.refine}{const bigint \& x}
{
refines the factorization
\MATH{a} by computing greatest common divisors of \MATH{x} with every
base occuring in \MATH{a}. If \MATH{x} has a proper common divisor
with at least one base, the return--value of this function will be
\TRUE; otherwise it will be \FALSE.}


\fcode{bool}{a.refine\_comp}{lidia\_size\_t i\k const bigint \& x}
{
refines the factorization \MATH{a} by computing the greatest common
divisor of \MATH{x} with \MATH{base_i} in \MATH{a}. If \MATH{x} has
a proper common divisor with \MATH{base_i}, the return--value of
this function will be \TRUE; otherwise it will be \FALSE.}


\fcode{void}{a.factor\_comp}{lidia\_size\_t i\k int upper\_bound = 34}
{
tries to find factors of \MATH{base_{i}}. A combination of \EM{TD},
\EM{ECM} and \EM{QS} is used. The \MATH{i}-th component of
\MATH{a} is erased, found factors (with appropriate exponents) are
added to the vector of \MATH{a} and the vector is resorted. If the
default parameter \MATH{upper\_bound} is set, \EM{ECM} tries to
find factors up to \MATH{upper\_bound} digits.}


\fcode{void}{a.factor}{int upper\_bound = 34}
{
tries to factor all base
elements of \MATH{a} with a combination of \EM{TD}, \EM{ECM} and
\EM{QS} and changes \MATH{a} appropriately. If you have more
information about all bases (for example no prime factors smaller
than \MATH{10^6} in any base of \MATH{a}) you may get the results
more efficiently by using the function \TT{a.ecm()} or
\TT{a.mpqs\_comp()}. (see below)}


\fcode{rational\_factorization}{factor}{const bigint \& N}
{
tries to
factor the number \MATH{N} with a combination of \EM{TD}, \EM{ECM}
and \EM{QS} and returns the \BF{rational\_factorization}
representing the number \MATH{N}.}

\fcode{sort\_vector < bigint >}{divisors}{rational\_factorization \& f}
{ return a sorted vector of all positive divisors of the number
  represented by \MATH{f} (in ascending order). If \MATH{f} is no prime
  factorization, the function tries to refine \MATH{f} to a
  prime factorization. In this case, the computed prime factorization
  is assigned to \MATH{f}.}

\fcode{sort\_vector < bigint >}{divisors}{const bigint \& N} { return
  a sorted vector of all positive divisors of
  \MATH{N} (in ascending order).}


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

\STITLE{Special High-Level Functions}
\fcode{void}{a.trialdiv\_comp}{lidia\_size\_t i\k unsigned int    upper\_bound = \MATH{1\,000\,000}\k unsigned int lower\_bound =    \MATH{1}}
{
tries to factor the element \MATH{base_{i}} of \MATH{a}
by using \EM{TD} with all primes \MATH{p}
with \IT{lower\_bound}\MATH{< p <}\IT{upper\_bound}. The \MATH{i}-th
component of \MATH{a} is erased, found factors (with appropriate
exponents) are added to the vector of \MATH{a} and the vector is
resorted. \MATH{base_{i}} is not tested for primality.}


\fcode{void}{a.trialdiv}{unsigned int upper\_bound =    \MATH{1\,000\,000}\k unsigned int lower\_bound = \MATH{1}}
{
tries to
factor all base elements of \MATH{a} with \EM{TD} using all primes
\MATH{p} with \IT{lower\_bound}\MATH{< p <}\IT{upper\_bound}. The
vector of \MATH{a} is changed according to the rules used in \TT{a.trialdiv\_comp(i)}. The base elements are not tested for primality.}


\fcode{rational\_factorization}{trialdiv}{const bigint \& N\k unsigned    int upper\_bound = \MATH{1\,000\,000}\k unsigned int lower\_bound =    \MATH{1}}
{
tries to factor the number \MATH{N} with \EM{TD} using
all primes \MATH{p} with \IT{lower\_bound}\MATH{< p <}\IT{upper\_bound} and returns the \BF{rational\_factorization}
representing the number \MATH{N}. \MATH{N} is not tested for primality.}

The following functions require some understanding of the underlying
strategy of ECM.  A detailed description of the implementation of
\EM{TD} and \EM{ECM} can be found in \cite{fberger} and
\cite{amueller}.  \EM{ECM} uses the following strategy, which is
parametrized by the int variables \MATH{lower\_bound},
\MATH{upper\_bound} and \MATH{step}. These variables can be chosen by
the user. It starts to look for factors with \MATH{lower\_bound}
decimal digits.  After having tried a ``few'' curves and not having
found a factor the parameters of \EM{ECM} are changed and we try to
find \MATH{(lower\_bound + step)}-digit factors, \MATH{(lower\_bound +
2\,step)}-digit factors and so on, until the decimal size of the
factors we are looking for exceeds \MATH{upper\_bound}. The number of
curves which is used for finding a \MATH{d}-digit factor is chosen
such that we find a \MATH{d}-digit factor with probability of at least
\MATH{50 \%} if it exists. Note that found factors can be composite.
The built-in default values are \MATH{lower\_bound = 6, step = 3} and
\MATH{upper\_bound} is set to half the decimal length of the number to
be factored. The bounds \MATH{lower\_bound\GE 6} and
\MATH{upper\_bound \LE 34} are limited because we have only
precomputed parameters for \EM{ECM} for factors of that size. 


\fcode{void}{a.ecm\_comp}{lidia\_size\_t i\k int upper\_bound =    \MATH{34}\k int lower\_bound = \MATH{6}\k int step = \MATH{3}}
{
tries
to find factors of \MATH{base_{i}} with decimal length \MATH{k},
\MATH{ lower\_bound \LE k \LE upper\_bound}, by means of \EM{ECM}
according to the strategy explained above. Note that found factors
of \MATH{base_i} can be composite. If the value of
\MATH{upper\_bound} is \MATH{34}, then \MATH{upper\_bound} is set to
\MATH{\mbox{min}(34, \FRAC{1}{2}\, \LFLOOR \log_{10} (base_i)\RFLOOR
+ 1)}. The vector of \MATH{a} is changed appropriately.
Unreasonable input (\MATH{step \LE 0}, \MATH{lower\_bound} or
\MATH{upper\_bound} out of range etc.) leads to a call of the
\TT{lidia\_warning\_handler}, the parameter is set to a predefined value.}


\fcode{void}{a.ecm}{int upper\_bound = \MATH{34}\k int lower\_bound =    \MATH{6}\k int step = \MATH{3}}
{
tries to factor all base elements of
\MATH{a} with \EM{ECM} using the strategy described in
\TT{a.ecm\_comp(i)} and changes \MATH{a} appropriately. Note that the
result is not necessarily a prime factorization.}


\fcode{rational\_factorization}{ecm}{const bigint \& N\k int    upper\_bound = \MATH{34}\k int lower\_bound = \MATH{6}\k int step =    \MATH{3}}
{
tries to factor the number \MATH{N} with \EM{ECM} using
the strategy described in \TT{a.ecm\_comp(i)} and returns the
\BF{rational\_factorization} representing the number \MATH{N}. Note
that the result is not necessarily a prime factorization.}

The version of \EM{QS} used in \LiDIA \ is called self initializing
multiple polynomial quadratic sieve. A description of the algorithm
can be found in \cite{al-pom}, \cite{denny} or \cite{sosnow}. The linear 
equation step uses an implementation of the Gauss algorithm written 
by Arjen Lenstra.

Note that the running time of \EM{QS} depends on the size of the number to
be factored, not on the size of the factors.


\fcode{void}{a.mpqs\_comp}{lidia\_size\_t i}
{
tries to factor \MATH{base_{i}}
using the large prime variation of the quadratic sieve. For bases with more than 75 digits the
\TT{lidia\_warning\_handler} will be invoked, the
\BF{rational\_factorization} \MATH{a} is not changed.
Notice that as \EM{QS} creates temporary files, you need write
permission either in the \/tmp-directory or in the directory from
which \EM{QS} is called.}


\fcode{void}{a.mpqs}{const bigint \& N\k}
{
tries to factor \MATH{N} using \TT{a.mpqs\_comp} (see above).}

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

\IO
The \BF{istream} operator  \TT{>>}  and  the \BF{ostream} operator
\TT{<<} are overloaded. The \BF{istream} operator \TT{>>} expects the
input of a \BF{rational\_factorization} in the following format:\\
\MATH{[(base_0,exp_0)\,(base_1,exp_1)\,\LDOTS \,(base_{l-1},exp_{l-1})]}.
In the input \MATH{base_i} is allowed to be an arbitrary non-zero rational
integer (i.e., of type \BF{bigint}). The input function computes the
internal format which was explained in the beginning. 

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

\SEEALSO
\BF{bigint}, \BF{bigrational}

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

\WARNINGS
\EM{ECM} fails to factor rational numbers  that
only consist of prime factors smaller than \MATH{1000}. Therefore it
is strongly recommended to use the function \TT{factor()} or to ensure
with the function \TT{trialdiv()}, that there are no such small prime
factors left before calling functions which use \EM{ECM}.

The methods for factoring internally use variables of type int. 
If the data type int does not consist of 32 bits on your machine, the 
factoring methods cannot be used on your machine. In this case
calls of them would lead to wrong results.

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

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

 int main()
 {
   rational_factorization f;
   bigint n;

   cout << "enter an integer n: ";
   cin >> n;             //  input n
   f.assign(n);          //  assign n as trivial factorization to f
   f.verbose(1);         //  we want a lot of informations
   f.factor();           //  calculate prime factorization 
                         //  using the factor function
   cout << f;            //  output f


   cout << "enter an integer n: ";
   cin >> n;             //  input n
   f.assign(n);          //  assign n as trivial factorization to f
   f.verbose(1);         //  we want a lot of informations
   f.trialdiv();         //  calculate prime factorization using trialdiv
   cout << f;            //  output f

   cout << "enter an integer n: ";
   cin >> n;             //  input n
   f.assign(n);          //  assign n as trivial factorization to f
   f.verbose(1);         //  we want a lot of informations
   f.ecm_comp(0);        //  calculate prime factorization using ecm
   cout << f;            //  output f

   cout << "enter an integer n: ";
   cin >> n;             //  input n
   f.assign(n);          //  assign n as trivial factorization to f
   f.verbose(1);         //  we want a lot of informations
   f.mpqs_comp(0);       //  calculate prime factorization using
                         //  quadratic sieve
   cout << f;            //  output f
 }
\end{verbatim}

For further references please refer to\\
\TT{LiDIA/src/simple\_classes/factorization/rational\_factorization\_appl.c}

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

\AUTHOR
Franz-Dieter Berger, Thomas F.~Denny, Andreas M\"uller, Volker
M\"uller, Thomas Sosnowski

\end{lidia_man}

