%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  bigmod.tex        LiDIA documentation
%%
%%  This file contains the documentation of the class bigmod
%%  
%%  Copyright (c) 1995 by the LiDIA Group 
%%
%%  Authors: Thomas Papanikolaou
%%  

\begin{lidia_man}
\markright{\BF{bigmod}}

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

\NAME
\BF{bigmod}  \DOTFILL   multiprecision modular integer arithmetic

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

\ABSTRACT
\BF{bigmod}  is  a class   for  doing  multiprecision  modular
arithmetic over \MATH{\Z / m \Z}. It supports for example
arithmetic operations, comparisons and exponentiation.

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

\DESCRIPTION
A \BF{bigmod} is a pair of two \BF{bigints} \MATH{(man, m)},
where \MATH{man} is called the \BF{mantissa} and \MATH{m}
the \BF{modulus}. The modulus is global to all \BF{bigmod}s and
must be set before a variable of type \BF{bigmod} can be declared.
This is done by the following statement:

\begin{center}
\TT{bigmod::set\_modulus(const bigint \& m)}
\end{center}

Each equivalence class modulo \MATH{m} is represented by its least
non-negative representative, i.e. the mantissa of a \BF{bigmod}
is chosen in the interval \MATH{[ 0, \LDOTS, |m| - 1 ]}. For
further details, please refer to the description of the
functions \BF{set\_modulus} and \BF{normalize}.  

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

\CONS

\fcode{ct}{bigmod}{}
{
Initializes with 0.}

\fcode{ct}{bigmod}{int \MATH{i}}{
Initializes the mantissa with \MATH{i} mod \MATH{bigmod::modulus()}.}

\fcode{ct}{bigmod}{long \MATH{l}}{
Initializes the mantissa with \MATH{l} mod \MATH{bigmod::modulus()}.}

\fcode{ct}{bigmod}{unsigned long \MATH{ul}}{
Initializes the mantissa with \MATH{ul} mod \MATH{bigmod::modulus()}.}

\fcode{ct}{bigmod}{double \MATH{d}}{
\MATH{d} is casted to a bigint \MATH{D} using the bigint-
assignment operator. Then the mantissa is initialized with 
\MATH{D} mod \MATH{bigmod::modulus()}.}

\fcode{ct}{bigmod}{const bigint \& \MATH{b}}{
Initializes the mantissa with \MATH{i} mod \MATH{bigmod::modulus()}.}

\fcode{ct}{bigmod}{const bigmod \& \MATH{b}}{
Initializes the mantissa with \MATH{b}.}

\fcode{dt}{\SIM bigmod}{}{
Deletes the bigmod object.}


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

\INIT

\label{bigmod_init}
\fcode{{static void}}{set\_modulus}{const bigint \& m}
{
sets the global modulus to \MATH{|m|}; if \MATH{m = 0},
the \TT{lidia\_error\_handler} will be invoked. If you call the
function \TT{set\_modulus(m)} after declaration of variables of
type \BF{bigmod}, all these variables might be incorrect, i.e.
they might have mantissas which are not in the proper range. If
you want to use \BF{bigmod} variables after a global modulus
change, you have to normalize them. This normalization can be
done with the help of the following two functions:}


\fcode{void}{a.normalize}{}
{
normalizes the \BF{bigmod} \MATH{a} such that the mantissa
of \MATH{a} is in the range \MATH{[0, \LDOTS, m-1]}, where \MATH{m}
is the global modulus.}


\fcode{void}{normalize}{bigmod \& a\k const bigmod \& b}
{
sets the mantissa of \MATH{a} to the mantissa of \MATH{b} and
normalizes \MATH{a} such that the mantissa of \MATH{a} is in the
range \MATH{[0, \LDOTS, m - 1]}, where \MATH{m} is the global
modulus.}

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

\TYPE

Before assigning a \BF{bigmod} (i.e.~the mantissa of a \BF{bigmod})
to a machine type (e.g.~int) it is often useful to perform a
test which checks if the assignment can be done without overflow.
The following functions return \TRUE\ if the assignment would be
successful, \FALSE\ otherwise.


\fcode{bool}{is\_char}{const bigmod \&}{}
\fcode{bool}{is\_uchar}{const bigmod \&}{}
\fcode{bool}{is\_short}{const bigmod \&}{}
\fcode{bool}{is\_ushort}{const bigmod \&}{}
\fcode{bool}{is\_int}{const bigmod \&}{}
\fcode{bool}{is\_uint}{const bigmod \&}{}
\fcode{bool}{is\_long}{const bigmod \&}{}
\fcode{bool}{is\_ulong}{const bigmod \&}{}

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

\ASGN

The operator \TT{=} is overloaded. For efficiency reasons the
following functions are also implemented (let \MATH{a} be of
type \BF{bigmod}):


\fcode{void}{a.assign\_zero}{}
{
mantissa(\MATH{a}) = \MATH{0}.}


\fcode{void}{a.assign\_one}{}
{
mantissa(\MATH{a}) = \MATH{1}.}

\fcode{void}{a.assign}{int i}
{
mantissa(\MATH{a}) = \MATH{i}.}

\fcode{void}{a.assign}{long i}
{
mantissa(\MATH{a}) = \MATH{i}.}

\fcode{void}{a.assign}{unsigned long i}
{
mantissa(\MATH{a}) = \MATH{i}.}

\fcode{void}{a.assign}{const bigint \& b}
{
mantissa(\MATH{a}) = \MATH{b}.}

\fcode{void}{a.assign}{const bigmod \& b}
{
mantissa(\MATH{a}) = mantissa(\MATH{0}).}

\fcode{double}{dbl}{const bigmod \& a}
{
returns the mantissa of \MATH{a} as a double approximation.}


\cfcode{bool}{a.intify}{int \& i}
{
performs the assignment \TT{i = mantissa(a)} provided
the assignment can be done without overflow. In that case the
function returns \FALSE, otherwise it returns \TRUE\ and lets
the value of \MATH{i} unchanged.}


\cfcode{bool}{a.longify}{long \& i}
{
performs the assignment \TT{i = mantissa(a)} provided
the assignment can be done without overflow. In that case the
function returns \FALSE, otherwise it returns \TRUE\ and lets
the value of \MATH{i} unchanged.}

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

\ACCS

\fcode{bigint}{mantissa}{const bigmod \& a}
{
returns the mantissa of the \BF{bigmod} \MATH{a}. The mantissa is
chosen in the interval \MATH{[0,\LDOTS , m-1]}, where \MATH{m} is
the global modulus.}


\fcode{{const bigint \&}}{a.mantissa}{}
{
returns the mantissa of the \BF{bigmod} \MATH{a}. The mantissa is
chosen in the interval \MATH{[0,\LDOTS , m-1]}, where \MATH{m} is
the global modulus.}


\cfcode{{static const bigint}}{modulus}{}
{
returns the value of the global modulus.}

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

\ARTH

The following operators are overloaded and can be used in exactly
the same way as in C:

\begin{center}
\TT{(unary) -, ++, --}\\
\TT{(binary) +, -, *, /}\\
\TT{(binary with assignment) +=, -=, *=, /=}
\end{center}

The operators \TT{/} and \TT{/=} denote ``multiplication with the 
inverse''. If the inverse does not exist, the \TT{lidia\_error\_handler}
will be invoked.  To avoid copying all operators also exist 
as functions. Let \MATH{a} be of type \BF{bigmod}.


\fcode{void}{add}{bigmod \& c\k const bigmod \& a\k const bigmod \& b}
{
\MATH{c = a + b}.}


\fcode{void}{add}{bigmod \& c\k const bigmod \& a\k const bigint \& b}
{
\MATH{c = a + b}.}


\fcode{void}{add}{bigmod \& c\k const bigint \& a\k const bigmod \& b}
{
\MATH{c = a + b}.}


\fcode{void}{add}{bigmod \& c\k const bigmod \& a\k long i}
{
\MATH{c = a + i}.}


\fcode{void}{add}{bigmod \& c\k long i\k const bigmod \& b}
{
\MATH{c = i + b}.}


\fcode{void}{subtract}{bigmod \& c\k const bigmod \& a\k const bigmod \& b}
{
\MATH{c = a - b}.}


\fcode{void}{subtract}{bigmod \& c\k const bigmod \& a\k const bigint \& b}
{
\MATH{c = a - b}.}


\fcode{void}{subtract}{bigmod \& c\k const bigint \& a\k const bigmod \& b}
{
\MATH{c = a - b}.}


\fcode{void}{subtract}{bigmod \& c\k const bigmod \& a\k long i}
{
\MATH{c = a - i}.}


\fcode{void}{subtract}{bigmod \& c\k long i\k const bigmod \& b}
{
\MATH{c = i - b}.}


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


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


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


\fcode{void}{multiply}{bigmod \& c\k const bigmod \& a \k long i}
{
\MATH{c = a * i}.}


\fcode{void}{multiply}{bigmod \& c\k long i\k const bigmod \& b}
{
\MATH{c = i * b}.}


\fcode{void}{divide}{bigmod \& c\k const bigmod \& a\k const bigmod \& b}
{
\MATH{c = a * b^{-1}}; if the inverse of \MATH{b} does not exist, 
the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{divide}{bigmod \& c\k const bigmod \& a\k const bigint \& b}
{
\MATH{c = a * b^{-1}}; if the inverse of \MATH{b} does not exist, 
the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{divide}{bigmod \& c\k const bigint \& a\k const bigmod \& b}
{
\MATH{c = a * b^{-1}}; if the inverse of \MATH{b} does not exist, 
the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{divide}{bigmod \& c\k const bigmod \& a\k long i}
{
\MATH{c = a * i^{-1}}; if the inverse of \MATH{i} does not exist, 
the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{divide}{bigmod \& c\k long i\k const bigmod \& b}
{
\MATH{c = i * b^{-1}}; if the inverse of \MATH{b} does not exist, 
the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{a.negate}{}
{
\MATH{a = -a}.}


\fcode{void}{negate}{bigmod \& a\k const bigmod \& b}
{
\MATH{a = -b}.}


\fcode{bigint}{a.invert}{int verbose = 0}
{
sets \MATH{a = a^{-1}} if the inverse of \MATH{a} exists. If the
inverse does not exist and \MATH{verbose = 0},
the \TT{lidia\_error\_handler} will be invoked. If the inverse does not
exist and \MATH{verbose \NEQ 0}, then the function prints a
warning and returns the gcd of \MATH{a} and the global modulus.
In this case \MATH{a} remains unchanged and the program does not
exit.}


\fcode{void}{invert}{bigmod \& a\k const bigmod \& b}
{
sets \MATH{a = b^{-1}} if the inverse of \MATH{b} exists.
Otherwise the \TT{lidia\_error\_handler} will be invoked.}


\fcode{bigmod}{inverse}{const bigmod \& a}
{
returns \MATH{a^{-1}} if the inverse of \MATH{a} exists.
Otherwise the \TT{lidia\_error\_handler} will be invoked.}


\fcode{void}{a.multiply\_by\_2}{}
{
\MATH{a = 2 * a} (done by shifting).}


\fcode{void}{a.divide\_by\_2}{}
{
computes a number \MATH{b \IN [0, \LDOTS, m - 1]} such
that \MATH{2 b \EQUIV a \MOD m}, where \MATH{m} is the global
modulus and sets \MATH{a = b} (NOTE: this is not equivalent to
multiplying \MATH{a} with the inverse of 2). The function invokes
the \TT{lidia\_error\_handler} if the operation is impossible, i.e. if the
mantissa of \MATH{a} is odd and \MATH{m} is even.}


\fcode{void}{inc}{bigmod \& c}
{
\MATH{c = c + 1}.}


\fcode{void}{dec}{bigmod \& c}
{
\MATH{c = c - 1}.}


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


\fcode{void}{power}{bigmod \& c\k const bigmod \& a\k const bigint \& b}
{
\MATH{c = a^b} (done with right-to-left binary exponentiation).}


\fcode{void}{power}{bigmod \& c\k const bigmod \& a\k long i}
{
\MATH{c = a^i} (done with right-to-left binary exponentiation).}


\fcode{void}{swap}{bigmod \& a\k bigmod \& b}
{
exchanges the mantissa of \MATH{a} and \MATH{b}.}

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

\COMP

\BF{bigmod} supports the binary operators \TT{==}, \TT{!=}
and additionally the unary operator \TT! (comparison with zero).
Let \MATH{a} be an instance of type \BF{bigmod}.


\cfcode{bool}{a.is\_zero}{}
{
returns \TRUE\ if \MATH{a = 0}, \FALSE\ otherwise.}


\cfcode{bool}{a.is\_one}{}
{
returns \TRUE\ if \MATH{a = 1}, \FALSE\ otherwise.}

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

\BASIC

Let \MATH{a} be of type \BF{bigmod}.


\cfcode{lidia\_size\_t}{a.bit\_length}{}
{
returns the bit-length of \MATH{a}'s mantissa (see \BF{bigint}, page
\pageref{bigint_class}).}


\cfcode{lidia\_size\_t}{a.length}{}
{
returns the word-length of \MATH{a}'s mantissa (see \BF{bigint}, page
\pageref{bigint_class}).}

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

\HIGH

\fcode{void}{seed}{const bigmod \& a}
{
initializes the random number generator function defined in the
kernel with \MATH{a}.}


\fcode{bigmod}{randomize}{}
{
returns a \BF{bigmod} with random mantissa in the range
\MATH{[0, \LDOTS, m-1]}, where \MATH{m} is the global modulus by
means of the random number generator defined in the kernel.}


\fcode{void}{a.randomize}{}
{
computes a random mantissa of \MATH{a} in the
range \MATH{[0, \LDOTS, m - 1]}, where \MATH{m} is the global
modulus by means of the random number generator defined in the
kernel.}


\fcode{bigmod}{randomize}{const bigmod \& a}
{
returns a random \BF{bigmod} \MATH{b} with random mantissa in the
range \MATH{[0, \LDOTS, \mbox{mantissa}(a) - 1]}.}

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

\IO

Let \MATH{a} be of type \BF{bigmod}.

The \BF{istream} operator  \TT{>>}  and the \BF{ostream}
operator \TT{<<} are overloaded. Furthermore, you can use the
following member functions for writing to and reading from a file
in binary or ASCII format, respectively. The input and output
format of a \BF{bigmod} consists only of its mantissa, since the
modulus is global. Note that you have to manage by yourself that
successive \BF{bigmod}s have to be separated by blanks. 



\fcode{int}{x.read\_from\_file}{FILE *fp}
{
reads \MATH{x} from the binary file \MATH{f\!p} using fread.}


\fcode{int}{x.write\_to\_file}{FILE *fp}
{
writes \MATH{x} to the binary file \MATH{f\!p} using fwrite.}


\fcode{int}{x.scan\_from\_file}{FILE *fp}
{
scans \MATH{x} from the ASCII file \MATH{f\!p} using fscanf.}


\fcode{int}{x.print\_to\_file}{FILE *fp}
{
prints \MATH{x} to the ASCII file \MATH{f\!p} using fprintf.}


\fcode{int}{string\_to\_bigmod}{char *s\k bigmod \& a}
{
converts the string \MATH{s} to a \BF{bigmod} \MATH{a} and returns 
the number of converted characters.}


\fcode{int}{bigmod\_to\_string}{const bigmod \& a\k char *s}
{
converts the \BF{bigmod} \MATH{a} to a string \MATH{s} and returns 
the number of used characters.}

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

\SEEALSO
\BF{bigint}, \BF{multi\_bigmod}

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

\NOTES 
To use multiple moduli at the same time please use the class
\BF{multi\_bigmod}.

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

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/bigmod.h>
 
 int main()
 {
   bigmod a, b, c;

    bigmod::set_modulus(10); // Global for a, b and c

    cout << "Please enter a : "; cin >> a ; 

    cout << "Please enter b : "; cin >> b ;

    cout << "\n";

    c = a + b;

    cout << "a + b = " << c << "\n";

 } 

\end{verbatim}

For further reference please refer to\\
\TT{LiDIA/src/simple\_classes/bigmod\_appl.c} 

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

\AUTHOR
Markus Maurer, Thomas Papanikolaou


\end{lidia_man}

