\cleardoublepage
\ccUserChapter{Modular Arithmetic\label{chap:modular_arithmetic}}
\ccChapterAuthor{Michael Hemmer}

\input{Modular_arithmetic/PkgDescription.tex}

\section{Introduction}

Modular arithmetic is a fundamental tool in modern algebra systems. 
In conjunction with the Chinese remainder theorem it serves as the 
workhorse in several algorithms computing the gcd, resultant etc. 
Moreover, it can serve as a very efficient filter, since it is often 
possible to exclude that some value is zero by computing its modular 
correspondent with respect to one prime only. 

First of all, this package introduces a type \ccc{CGAL::Residue}.
It represents $\Z_{/p\Z}$ for some prime $p$. 
The prime number $p$ is stored in a static member variable. 
The class provides static member functions to change this value. 
{\bf Note that changing the prime invalidates already existing objects 
of this type.}
However, already existing objects do not lose their value with respect to the 
old prime and can be reused after restoring the old prime. 
Since the type is based on double 
arithmetic the prime is restricted to values less than $2^{26}$. 
The initial value of $p$ is 67111067. 

Please note that the implementation of class \ccc{CGAL::Residue} requires a mantissa 
precision according to the IEEE Standard for Floating-Point Arithmetic (IEEE 754). 
However, on some processors the traditional FPU uses an extended precision. Hence, it 
is  indispensable that the proper mantissa length is enforced before performing 
any arithmetic operations. Moreover, it is required that numbers are rounded to the 
next nearest value. This can be ensured using \ccc{CGAL::Protect_FPU_rounding} with 
\ccc{CGAL_FE_TONEAREST}, which also enforces the required precision as a side effect. 

\begin{ccAdvanced}      
In case the flag \ccc{CGAL_HAS_THREADS} 
is undefined the prime is just stored in a static member 
of the class, that is, \ccc{CGAL::Residue} is not thread-safe in this case.  
In case \ccc{CGAL_HAS_THREADS}
the implementation of the class is thread safe using 
\ccc{boost::thread_specific_ptr}. However, this may cause some performance 
penalty. Hence, it may be advisable to configure \ccc{CGAL} with 
\ccc{CGAL_HAS_NO_THREADS}. 
\end{ccAdvanced} 

Moreover, the package introduces the concept \ccc{Modularizable}. 
An algebraic structure \ccc{T} is considered as \ccc{Modularizable} if there 
is a mapping from \ccc{T} into an algebraic structure that is based on 
the type \ccc{CGAL::Residue}.  
For scalar types, e.g. Integers, this mapping is just the canonical 
homomorphism into $\Z_{/p\Z}$ represented by \ccc{CGAL::Residue}. 
For compound types, e.g. Polynomials, the mapping is applied to the 
coefficients of the compound type. 
The mapping is provided by the class \ccc{CGAL::Modular_traits<T>}.
The class \ccc{CGAL::Modular_traits<T>} is designed such that the concept 
\ccc{Modularizable} can be considered as optional, i.e., 
\ccc{CGAL::Modular_traits<T>} provides a tag that can be used for dispatching. 

\subsection{Example}

In the following example modular arithmetic is used as a filter. 
\ccIncludeExampleCode{Modular_arithmetic/modular_filter.cpp}

\section{Design and Implementation History}

The class \ccc{CGAL::Residue} is based on the C-code of Sylvain Pion et. al. 
as it was presented in \cite{bepp-sdrns-99}. 

The remaining part of the package is the result of the integration process
of the NumeriX library of EXACUS \cite{beh+-eeeafcs-05} into CGAL.