diff --git a/.gitattributes b/.gitattributes index 54f708bce85..c66e3049a64 100644 --- a/.gitattributes +++ b/.gitattributes @@ -112,7 +112,7 @@ Algebraic_foundations/doc/Algebraic_foundations/Concepts/RealEmbeddableTraits.h Algebraic_foundations/doc/Algebraic_foundations/Concepts/RingNumberType.h -text Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h -text Algebraic_foundations/doc/Algebraic_foundations/Concepts/Unique_factorization_domain_tag.h -text -Algebraic_foundations/doc/Algebraic_foundations/PkgDescription.txt -text +Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt -text Algebraic_foundations/doc/Algebraic_foundations/fig/AlgebraicConceptHierarchy.gif -text svneol=unset#image/gif Algebraic_foundations/doc/Algebraic_foundations/fig/Algebraic_foundations2.png -text svneol=unset#image/png Algebraic_foundations/doc_tex/Algebraic_foundations/Algebraic_foundations.png -text @@ -3285,10 +3285,12 @@ Modifier/doc_tex/Modifier/modifier.gif -text svneol=unset#image/gif Modifier/doc_tex/Modifier/modifier_small.gif -text svneol=unset#image/gif Modular_arithmetic/doc/Modular_arithmetic/CGAL/Modular_traits.h -text Modular_arithmetic/doc/Modular_arithmetic/CGAL/Residue.h -text +Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImage.h -text +Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImageRepresentative.h -text Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits.h -text Modular_arithmetic/doc/Modular_arithmetic/Concepts/Modularizable.h -text Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt -text -Modular_arithmetic/doc/Modular_arithmetic/PkgDescription.txt -text +Modular_arithmetic/doc/Modular_arithmetic/PackageDescription.txt -text Modular_arithmetic/doc/Modular_arithmetic/fig/Modular_arithmetic.png -text svneol=unset#image/png Modular_arithmetic/doc_tex/Modular_arithmetic/Modular_arithmetic.png -text Modular_arithmetic/doc_tex/Modular_arithmetic/PkgDescription.tex -text diff --git a/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt b/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt index a603a5975a7..a1ba94a2e12 100644 --- a/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt +++ b/Algebraic_foundations/doc/Algebraic_foundations/Algebraic_foundations.txt @@ -1,7 +1,7 @@ namespace CGAL { /*! -\mainpage ChapterAlgebraicFoundations Algebraic Foundations +\mainpage Algebraic Foundations \authors Michael Hemmer # Introduction # diff --git a/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt b/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt new file mode 100644 index 00000000000..0cb8a3aacb3 --- /dev/null +++ b/Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt @@ -0,0 +1,13 @@ +/*! +\addtogroup PkgAlgebraicFoundations +\todo check generated documentation +\PkgDescriptionBegin{Algebraic Foundations} +\PkgPicture{Algebraic_foundations2.png} +\PkgAuthor{Michael Hemmer} +\PkgDesc{This package defines what algebra means for \cgal, in terms of concepts, classes and functions. The main features are: (i) explicit concepts for interoperability of types (ii) separation between algebraic types (not necessarily embeddable into the reals), and number types (embeddable into the reals).} +\PkgSince{3.3} +\cgalbib{cgal:h-af-12} +\license{ \ref licensesLGPL} +\PkgDescriptionEnd +*/ + diff --git a/Algebraic_foundations/doc/Algebraic_foundations/PkgDescription.txt b/Algebraic_foundations/doc/Algebraic_foundations/PkgDescription.txt deleted file mode 100644 index ec134badd24..00000000000 --- a/Algebraic_foundations/doc/Algebraic_foundations/PkgDescription.txt +++ /dev/null @@ -1,26 +0,0 @@ -/*! -\addtogroup PkgAlgebraicFoundations Algebraic Foundations - - - - - - - - -

Algebraic Foundations

\image html fig/Algebraic_foundations2.png "" -\par Michael Hemmer - -\par "" This package defines what algebra means for \cgal, in terms of concepts, classes and functions. The main features are: (i) explicit concepts for interoperability of types (ii) separation between algebraic types (not necessarily embeddable into the reals), and number types (embeddable into the reals). - -\since \cgal 3.3 - -\cgalbib{cgal:h-af-12} - -\license{ \ref licensesLGPL "LGPL" } - -\par Resources: -\ref ChapterAlgebraicFoundations "User Manual" -
-*/ - diff --git a/Mesh_2/doc/Mesh_2/Mesh_2.txt b/Mesh_2/doc/Mesh_2/Mesh_2.txt index d09f8cc0301..cbb368d9f3d 100644 --- a/Mesh_2/doc/Mesh_2/Mesh_2.txt +++ b/Mesh_2/doc/Mesh_2/Mesh_2.txt @@ -1,7 +1,7 @@ namespace CGAL { /*! -\page user_chapter_2D_Meshes 2D Conforming Triangulations and Meshes +\mainpage 2D Conforming Triangulations and Meshes \author Laurent Rineau This package implements Shewchuk's algorithm \cite s-mgdsa-00 to construct diff --git a/Minkowski_sum_3/doc/Minkowski_sum_3/Minkowski_sum_3.txt b/Minkowski_sum_3/doc/Minkowski_sum_3/Minkowski_sum_3.txt index e991a6015e3..421a57d777e 100644 --- a/Minkowski_sum_3/doc/Minkowski_sum_3/Minkowski_sum_3.txt +++ b/Minkowski_sum_3/doc/Minkowski_sum_3/Minkowski_sum_3.txt @@ -254,7 +254,7 @@ selection mark without spoiling the correctness of the Minkowski sum. The function `minkowski_sum_3()` should be used with the ::Exact_predicates_exact_constructions_kernel, which often is the most efficient choice and allows floating-point input. Consult -Section \anchor sectionNef_3IO for more details. +Section \ref sectionNef_3IO for more details. The following example code illustrates the usage of the function `minkowski_sum_3()`. Note that either input polyhedra will be diff --git a/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Modular_traits.h b/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Modular_traits.h index b290887fd90..26122feb9cd 100644 --- a/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Modular_traits.h +++ b/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Modular_traits.h @@ -1,17 +1,20 @@ + namespace CGAL { -/// \ingroup PkgModularArithmetic -/// -/// An instance of `Modular_traits` is a model of `ModularTraits`, -/// where `T` is the associated type. -/// -/// \models ::ModularTraits + +/*! +\ingroup PkgModularArithmetic + +An instance of `Modular_traits` is a model of `ModularTraits`, +where T is the associated type. + +\models ::ModularTraits + +*/ template< typename T > class Modular_traits { public: -}; /* class Modular_traits */ -} /* namespace CGAL */ - - - +/// @} +}; /* end Modular_traits */ +} /* end namespace CGAL */ diff --git a/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Residue.h b/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Residue.h index b86b7a52859..a60e5d4a5e8 100644 --- a/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Residue.h +++ b/Modular_arithmetic/doc/Modular_arithmetic/CGAL/Residue.h @@ -1,163 +1,162 @@ + namespace CGAL { -/// \ingroup PkgModularArithmetic -/// -/// The class `Residue` represents a finite field \f$Z/pZ\f$, for some -/// prime number \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. 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 \f$2^{26}\f$. -/// The initial value of \f$p\f$ is \f$67111067\f$. -/// -/// 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. -/// -/// In case the flag `CGAL_HAS_THREADS` is undefined the prime is just -/// stored in a static member of the class, that is, `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`. -/// -/// \models ::Field + +/*! +\ingroup PkgModularArithmetic + +\anchor Residue + +The class `Residue` represents a finite field \f$ \Z{/p\Z}\f$, +for some prime number \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. +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 \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. + +In case the flag `CGAL_HAS_THREADS` +is undefined the prime is just stored in a static member +of the class, that is, `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`. + +\models ::Field + +*/ + class Residue { public: -/// \name Creation +/// \name Creation /// @{ -/*! - introduces a variable `x`, which is initialized with zero; -*/ -Residue(); -/// @} -/// \name Creation +/*! +introduces a variable `x`, which is initialized with zero; +*/ +Residue(); + +/*! +copy constructor; +*/ +Residue(const Residue& m); + +/*! +introduces a variable `x`, which is initialized with \f$ i \% p\f$; +*/ +Residue(int i); + +/*! +introduces a variable `x`, which is initialized with \f$ i \% p\f$; +*/ +Residue(long i); + +/// @} + +/// \name Operations /// @{ -/*! - copy constructor; -*/ -Residue(const Residue& m); -/// @} -/// \name Creation -/// @{ -/*! - introduces a variable `x`, which is initialized with \f$i \mod p\f$; -*/ -Residue(int i); -/// @} +/*! -/// \name Creation -/// @{ -/*! - introduces a variable `x`, which is initialized with \f$i \mod p\f$; -*/ -Residue(long i); -/// @} +Static member function; -/// \name Operations -/// @{ -/*! - sets current prime to the given value and returns the old prime. -*/ -static int set_current_prime(int p); -/// @} +sets current prime to the given value and returns the old prime. +*/ +static int set_current_prime(int p); -/// \name Operations -/// @{ -/*! - returns the value of the current prime. -*/ -static int get_current_prime(); -/// @} +/*! -/// \name Operations -/// @{ -/*! - Returns the unique representative of `x`within the range \f$[-p/2,p/2]\f$, where \f$p\f$ is the current prime. -*/ -int get_value() const; +Static member function; -/// -/// -Residue operator+(Residue a); +returns the value of the current prime. -/// -/// -Residue operator-(Residue a); +*/ +static int get_current_prime(); -/// -/// -Residue operator+(Residue a,Residue b); +/*! -/// -/// -Residue operator-(Residue a,Residue b); +Returns the unique representative of `x`within the range +\f$ [-p/2,p/2]\f$, where \f$ p\f$ is the current prime. -/// -/// -Residue operator*(Residue a,Residue b); +*/ +int get_value() const; -/// -/// -Residue operator/(Residue a,Residue b); +/*! -/// \name Operations -/// @{ -/*! - -*/ -Residue & operator+=(Residue a); -/// @} +*/ +Residue operator+(Residue a); -/// \name Operations -/// @{ -/*! - -*/ -Residue & operator-=(Residue a); -/// @} +/*! -/// \name Operations -/// @{ -/*! - -*/ -Residue & operator*=(Residue a); -/// @} +*/ +Residue operator-(Residue a); -/// \name Operations -/// @{ -/*! - -*/ -Residue & operator/=(Residue a); -/// @} +/*! -/// -/// -Residue operator==(Residue a,Residue b); +*/ +Residue operator+(Residue a,Residue b); -/// -/// -Residue operator!=(Residue a,Residue b); +/*! + +*/ +Residue operator-(Residue a,Residue b); + +/*! + +*/ +Residue operator*(Residue a,Residue b); + +/*! + +*/ +Residue operator/(Residue a,Residue b); + +/*! + +*/ +Residue & operator+=(Residue a); + +/*! + +*/ +Residue & operator-=(Residue a); + +/*! + +*/ +Residue & operator*=(Residue a); + +/*! + +*/ +Residue & operator/=(Residue a); + +/*! + +*/ +Residue operator==(Residue a,Residue b); + +/*! + +*/ +Residue operator!=(Residue a,Residue b); /// @} - -}; /* class Residue */ -} /* namespace CGAL */ - - - - +}; /* end Residue */ +} /* end namespace CGAL */ diff --git a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImage.h b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImage.h new file mode 100644 index 00000000000..a2eeb544ba9 --- /dev/null +++ b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImage.h @@ -0,0 +1,46 @@ + +/*! +\ingroup PkgModularArithmeticConcepts +\cgalconcept + +This `AdaptableUnaryFunction` computes the modular image of the given value +with respect to a homomorphism \f$ \varphi\f$ from the +`ModularTraits::Type` into the `ModularTraits::Residue_type`. + +The homomorphism preserves the mapping of `int` into both types +, i.e., \f$ \varphi(Type(i)) == Residue\_type(i)\f$. + +\refines ::AdaptableUnaryFunction + +\sa `ModularTraits` + +*/ + +class ModularTraits::ModularImage { +public: + +/// \name Types +/// @{ + +/*! + +*/ +typedef ModularTraits::Residue_type result_type; + +/*! + +*/ +typedef ModularTraits::Type argument_type; + +/*! + +computes \f$ \varphi(x)\f$. + +*/ +result_type +operator()(const argument_type & x); + +/// @} + +}; /* end ModularTraits::ModularImage */ + diff --git a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImageRepresentative.h b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImageRepresentative.h new file mode 100644 index 00000000000..5c0bd343775 --- /dev/null +++ b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits--ModularImageRepresentative.h @@ -0,0 +1,41 @@ + +/*! +\ingroup PkgModularArithmeticConcepts +\cgalconcept + +This `AdaptableUnaryFunction` returns a representative in the original type of a given modular image. More precisely, it implements the \f$ right inverse\f$ of a proper restriction of the homomorphism \f$ \varphi\f$, which is implemented by `ModularTraits::ModularImage`. + +\refines ::AdaptableUnaryFunction + +\sa `ModularTraits` + +*/ + +class ModularTraits::ModularImageRepresentative { +public: + +/// \name Types +/// @{ + +/*! + +*/ +typedef ModularTraits::Type result_type; + +/*! + +*/ +typedef ModularTraits::Residue_type argument_type; + +/*! + +computes \f$ \varphi^{-1}(x)\f$. + +*/ +result_type +operator()(const argument_type &x); + +/// @} + +}; /* end ModularTraits::ModularImageRepresentative */ + diff --git a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits.h b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits.h index a7e9fd928ef..c4404e9e607 100644 --- a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits.h +++ b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/ModularTraits.h @@ -1,152 +1,68 @@ -/// \ingroup PkgModularArithmeticConcepts -/// -/// A model of `ModularTraits` is associated to a specific `Type`. -/// In case this associated type is `Modularizable`, this is indicated by the -/// boolean tag `Is_modularizable`. The mapping into the `Residue_type` is -/// provided by the functor `Modular_image`. -/// -/// A model of `ModularTraits` is supposed to provide: -/// -/// \hasModel CGAL::Modular_traits -/// -/// \sa `CGAL::Residue` -/// \sa `Modularizable` -/// + +/*! +\ingroup PkgModularArithmeticConcepts +\cgalconcept + +A model of `ModularTraits` is associated to a specific `Type`. +In case this associated type is `Modularizable`, this is indicated by the +boolean tag `Is_modularizable`. The mapping into the `Residue_type` is +provided by the functor `Modular_image`. + +\hasModel CGAL::Modular_traits + +\sa `CGAL::Residue` +\sa `Modularizable` + +*/ + class ModularTraits { public: -/// \ingroup PkgModularArithmeticConcepts -/// -/// This `AdaptableUnaryFunction` computes the modular image of the given value -/// with respect to a homomorphism \f$\phi\f$ from the -/// `ModularTraits::Type` into the `ModularTraits::Residue_type`. -/// The homomorphism preserves the mapping of `int` into both types -/// , i.e., \f$\phi(Type(i)) == Residue_type(i)\f$. -/// -/// \refines ::AdaptableUnaryFunction -/// -/// \sa `ModularTraits` -class ModularImage { -public: - -/// \name Types -/// @{ -/*! - -*/ -typedef ModularTraits::Residue_type result_type; -/// @} - -/// \name Types -/// @{ -/*! - -*/ -typedef ModularTraits::Type argument_type; -/// @} - -/// \name Types -/// @{ -/*! - computes \f$\phi(x)\f$. -*/ - -result_type -operator()(const argument_type & x); -/// @} - -}; /* concept ModularTraits::ModularImage */ - -/// \ingroup PkgModularArithmeticConcepts -/// -/// This `AdaptableUnaryFunction` returns a representative in the -/// original type of a given modular image. More precisely, it -/// implements the \f$right inverse\f$ of a proper restriction of the -/// homomorphism \f$\phi\f$, which is implemented by -/// `ModularTraits::ModularImage`. -/// -/// -/// \refines ::AdaptableUnaryFunction -/// \sa `ModularTraits` -/// -class ModularImageRepresentative { -public: - -/// \name Types -/// @{ -/*! - -*/ -typedef ModularTraits::Type result_type; -/// @} - -/// \name Types -/// @{ -/*! - -*/ -typedef ModularTraits::Residue_type argument_type; -/// @} - -/// \name Types -/// @{ -/*! - computes \f$\phi^{-1}(x)\f$. -*/ -result_type -operator()(const argument_type &x); -/// @} - -}; /* concept ModularTraits::ModularImageRepresentative */ - -/// \name Types -/// @{ -/*! - The associated type. -*/ -typedef Hidden_type Type ; -/// @} - -/// \name Types -/// @{ -/*! - - Tag indicating whether the associated type is modularizable. - This is either `CGAL::Tag_true` or `CGAL::Tag_false`. -*/ -typedef Hidden_type Is_modularizable; -/// @} - -/// \name Types -/// @{ -/*! - - The type of the modular image. - In case the type is not `Modularizable` this is undefined. - -*/ -typedef Hidden_type Residue_type; -/// @} - -/// \name Functors -/// In case the associated type is `Modularizable` all functors are provided. -/// In case a functor is not provided, it is set to `CGAL::Null_functor`. +/// \name Types +/// A model of `ModularTraits` is supposed to provide: /// @{ -/*! - A model of `ModularTraits::ModularImage` -*/ -typedef Hidden_type Modular_image; +/*! +The associated type. +*/ +typedef Hidden_type Type ; + +/*! + +Tag indicating whether the associated type is modularizable. + +This is either `CGAL::Tag_true` or `CGAL::Tag_false`. +*/ +typedef Hidden_type Is_modularizable; + +/*! + +The type of the modular image. + +In case the type is not `Modularizable` this is undefined. + +*/ +typedef Hidden_type Residue_type; + +/// @} + +/// \name Functors +/// In case the associated type is `Modularizable` all functors are +/// provided. In case a functor is not provided, it is set to +/// `CGAL::Null_functor`. +/// @{ + +/*! +A model of `ModularTraits::ModularImage` +*/ +typedef Hidden_type Modular_image; + +/*! +A model of `ModularTraits::ModularImageRepresentative` +*/ +typedef Hidden_type Modular_image_representative; -/*! - A model of `ModularTraits::ModularImageRepresentative` -*/ -typedef Hidden_type Modular_image_representative; /// @} -}; /* concept ModularTraits */ -/// - - - +}; /* end ModularTraits */ diff --git a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/Modularizable.h b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/Modularizable.h index 2ec55eee5ef..4faf35608ad 100644 --- a/Modular_arithmetic/doc/Modular_arithmetic/Concepts/Modularizable.h +++ b/Modular_arithmetic/doc/Modular_arithmetic/Concepts/Modularizable.h @@ -1,46 +1,45 @@ -/// \ingroup PkgModularArithmeticConcepts - /// Definition -/// -------------- -/// -/// An algebraic structure is called `Modularizable`, if there is a suitable mapping -/// into an algebraic structure which is based on the type `CGAL::Residue`. -/// For scalar types, e.g. Integers, this mapping is just the canonical homomorphism -/// into the type `CGAL::Residue` with respect to the current prime. -/// For compound types, e.g. Polynomials, -/// the mapping is applied to the coefficients of the compound type. -/// The mapping is provided via `CGAL::Modular_traits`, -/// being a model of `ModularTraits`. -/// Note that types representing rationals, or types which do have some notion -/// of denominator, are not `Modularizable`. -/// This is due to the fact that the denominator may be zero modulo the prime, -/// which can not be represented. -/// -/// -/// Has Models -/// -------------- -/// -/// `int` -/// `long` -/// `CORE::BigInt` -/// `CGAL::Gmpz` -/// `leda::integer` -/// `mpz_class` -/// The following types are `Modularizable` iff their template arguments are. -/// `CGAL::Lazy_exact_nt` -/// `CGAL::Sqrt_extension` -/// `CGAL::Polynomial` -/// See Also -/// -------------- -/// `CGAL::Residue` -/// `CGAL::Modular_traits` -/// -/// }; /* concept Modularizable */ + +/*! +\ingroup PkgModularArithmeticConcepts +\cgalconcept + +An algebraic structure is called `Modularizable`, if there is a suitable mapping +into an algebraic structure which is based on the type `CGAL::Residue`. +For scalar types, e.g. Integers, this mapping is just the canonical homomorphism +into the type `CGAL::Residue` with respect to the current prime. +For compound types, e.g. Polynomials, +the mapping is applied to the coefficients of the compound type. + +The mapping is provided via `CGAL::Modular_traits`, +being a model of `ModularTraits`. + +Note that types representing rationals, or types which do have some notion +of denominator, are not `Modularizable`. +This is due to the fact that the denominator may be zero modulo the prime, +which can not be represented. + +\hasModel int +\hasModel long +\hasModel CORE::BigInt +\hasModel CGAL::Gmpz +\hasModel leda::integer +\hasModel mpz_class + +The following types are `Modularizable` iff their template arguments are. + +\hasModel CGAL::Lazy_exact_nt +\hasModel CGAL::Sqrt_extension +\hasModel CGAL::Polynomial + +\sa `CGAL::Residue` +\sa `CGAL::Modular_traits` + +*/ + class Modularizable { public: -}; /* concept Modularizable */ -/// +/// @} - - +}; /* end Modularizable */ diff --git a/Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt b/Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt index 2ef0c340263..673dbd8b4f2 100644 --- a/Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt +++ b/Modular_arithmetic/doc/Modular_arithmetic/Modular_arithmetic.txt @@ -1,9 +1,10 @@ + namespace CGAL { /*! -\page chap:modular_arithmetic Modular Arithmetic -\authors Michael Hemmer and Sylvain Pion -\par Reference Manual: -\ref PkgModularArithmetic + +\mainpage Modular Arithmetic + +\authors Michael Hemmer and Sylvain Pion # Introduction # @@ -15,46 +16,40 @@ 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_/pZ\f$ for some prime \f$p\f$. -The prime number \f$p\f$ is stored in a static member variable. +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. 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 \f$2^26\f$. -The initial value of \f$p\f$ is 67111067. +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 +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. -\beginadvanced - -In case the flag `CGAL_HAS_THREADS` +\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. +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`. -\endadvanced - 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`. - +the type `CGAL::Residue`. For scalar types, e.g. Integers, this mapping is just the canonical -homomorphism into \f$Z_/pZ\f$ represented by `CGAL::Residue`. +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`. @@ -65,15 +60,16 @@ The class `CGAL::Modular_traits` is designed such that the concept ## Example ## In the following example modular arithmetic is used as a filter. -\cgalexample{Modular_arithmetic/modular_filter.cpp} +\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 Exacus \cite beh-eeeafcs-05 into \cgal. +of the NumeriX library of Exacus \cite beh+-eeeafcs-05 into \cgal. -*/ -} // namespace CGAL +*/ +} /* namespace CGAL */ diff --git a/Modular_arithmetic/doc/Modular_arithmetic/PackageDescription.txt b/Modular_arithmetic/doc/Modular_arithmetic/PackageDescription.txt new file mode 100644 index 00000000000..07e7f55e1dc --- /dev/null +++ b/Modular_arithmetic/doc/Modular_arithmetic/PackageDescription.txt @@ -0,0 +1,18 @@ + + +/// \defgroup PkgModularArithmetic Modular Arithmetic +/// \defgroup PkgModularArithmeticConcepts Concepts +/// \ingroup PkgModularArithmetic +/*! +\addtogroup PkgModularArithmetic +\todo check generated documentation +\PkgDescriptionBegin{Modular Arithmetic } +\PkgPicture{Modular_arithmetic.png} +\PkgAuthor{Michael Hemmer and Sylvain Pion} +\PkgDesc{This package provides arithmetic over finite fields. The provided tools are in particular useful for filters based on modular arithmetic and algorithms based on Chinese remainder. } +\PkgSince{3.4} +\cgalbib{ cgal:h-ma-12 } +\license{ \ref licensesLGPL } +\PkgDescriptionEnd +*/ + diff --git a/Modular_arithmetic/doc/Modular_arithmetic/PkgDescription.txt b/Modular_arithmetic/doc/Modular_arithmetic/PkgDescription.txt deleted file mode 100644 index a1759f725b0..00000000000 --- a/Modular_arithmetic/doc/Modular_arithmetic/PkgDescription.txt +++ /dev/null @@ -1,45 +0,0 @@ -/// \defgroup PkgModularArithmetic Modular Arithmetic -/// \defgroup PkgModularArithmeticConcepts Concepts -/// \ingroup PkgModularArithmetic - -/*! -\addtogroup PkgModularArithmetic - - - - - - - - -

Modular Arithmetic

\image html Modular_arithmetic.png "" -\par Michael Hemmer - -\par "" This package provides arithmetic over finite fields. The provided tools are in particular useful for filters based on modular arithmetic and algorithms based on Chinese remainder. - -\since \cgal 3.4 - -\cgalbib{cgal:h-ma-12} - -\license{ \ref licensesLGPL "LGPL" } - -\par Resources: -\ref chap:modular_arithmetic "User Manual" -
- -# Classified Reference Pages # - -## Concepts ## - -- `Modularizable` -- `ModularTraits` -- `ModularTraits::ModularImage` -- `ModularTraits::ModularImageRepresentative` - -## Types ## - -- `CGAL::Residue` -- `CGAL::Modular_traits` - -*/ -