mirror of https://github.com/CGAL/cgal
76 lines
3.3 KiB
Plaintext
76 lines
3.3 KiB
Plaintext
|
|
namespace CGAL {
|
|
/*!
|
|
|
|
\mainpage Modular Arithmetic
|
|
|
|
\authors Michael Hemmer and Sylvain Pion
|
|
|
|
# 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 `CGAL::Residue`.
|
|
It represents \f$ \Z_{/p\Z}\f$ for some prime \f$ p\f$.
|
|
The prime number \f$ p\f$ is stored in a static member variable.
|
|
The class provides static member functions to change this value.
|
|
<B>Note that changing the prime invalidates already existing objects
|
|
of this type.</B>
|
|
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 \f$ 2^{26}\f$.
|
|
The initial value of \f$ p\f$ is 67111067.
|
|
|
|
Please note that the implementation of class `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 `CGAL::Protect_FPU_rounding` with
|
|
`CGAL_FE_TONEAREST`, which also enforces the required precision as a side effect.
|
|
|
|
\advanced In case the flag `CGAL_HAS_THREADS`
|
|
is undefined the prime is just stored in a static member
|
|
of the class, that is, `CGAL::Residue` is not thread-safe in this case.
|
|
In case `CGAL_HAS_THREADS`
|
|
the implementation of the class is thread safe using
|
|
`boost::thread_specific_ptr`. However, this may cause some performance
|
|
penalty. Hence, it may be advisable to configure \cgal with
|
|
`CGAL_HAS_NO_THREADS`.
|
|
|
|
Moreover, the package introduces the concept `Modularizable`.
|
|
An algebraic structure `T` is considered as `Modularizable` if there
|
|
is a mapping from `T` into an algebraic structure that is based on
|
|
the type `CGAL::Residue`.
|
|
For scalar types, e.g. Integers, this mapping is just the canonical
|
|
homomorphism into \f$ \Z_{/p\Z}\f$ represented by `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 `CGAL::Modular_traits<T>`.
|
|
The class `CGAL::Modular_traits<T>` is designed such that the concept
|
|
`Modularizable` can be considered as optional, i.e.,
|
|
`CGAL::Modular_traits<T>` provides a tag that can be used for dispatching.
|
|
|
|
## Example ##
|
|
|
|
In the following example modular arithmetic is used as a filter.
|
|
\cgalexample{modular_filter.cpp}
|
|
|
|
# Design and Implementation History #
|
|
|
|
The class `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 <span class="textsc">Exacus</span> \cite beh+-eeeafcs-05 into \cgal.
|
|
|
|
*/
|
|
} /* namespace CGAL */
|
|
|