restructure content

Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt

@@ -17,34 +17,21 @@ 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.
 
+# Residue and Modularizable # {#Modular_arithmetic_residue}
+
 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>
+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 \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 
@@ -59,9 +46,32 @@ 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 ##
+## Example ## {#Modular_arithmetic_example}
+
+In the following example modular arithmetic is used as a filter on order
+to avoid unnecessary gcd computations of polynomials. 
+A `gcd` computation can be very costly due to coefficient growth within the 
+Euclidean algorithm. 
+   
+The general idea is that firstly the gcd is computed with respect 
+to one prime only. If this modular gcd is constant we can (in most cases) 
+conclude that the actual gcd is constant as well. 
+   
+For this purpose the example introduces the function `may_have_common_factor`.
+Note that there are two versions of this function, namely for the case 
+that the coefficient type is `Modularizable` and that it is not. 
+If the type is not `Modularizable` the filter is just not applied and the 
+function returns true. 
+
+Further 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.
+
 
-In the following example modular arithmetic is used as a filter. 
 \cgalexample{Modular_arithmetic/modular_filter.cpp}
 
 # Design and Implementation History # {#Modular_arithmeticDesign}