From 9b0bf475e64d30be0bf430d0759ac13a420efb4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philipp=20M=C3=B6ller?= Date: Wed, 20 Jun 2012 12:10:35 +0000 Subject: [PATCH] Matrix_search --- .gitattributes | 10 ++ Documentation/doc/Doxyfile | 14 ++- .../doc/Matrix_search/CGAL/Dynamic_matrix.h | 115 +++++++++++++++++ .../Sorted_matrix_search_traits_adaptor.h | 116 ++++++++++++++++++ .../CGAL/monotone_matrix_search.h | 65 ++++++++++ .../Matrix_search/CGAL/sorted_matrix_search.h | 79 ++++++++++++ .../doc/Matrix_search/Concepts/BasicMatrix.h | 66 ++++++++++ .../Concepts/MonotoneMatrixSearchTraits.h | 112 +++++++++++++++++ .../Concepts/SortedMatrixSearchTraits.h | 97 +++++++++++++++ .../doc/Matrix_search/Matrix_search.txt | 21 ++++ .../doc/Matrix_search/PkgDescription.txt | 49 ++++++++ .../doc/Matrix_search/fig/matrix.png | Bin 0 -> 43509 bytes .../doc/Modular_arithmetic/CGAL/Residue.h | 8 +- 13 files changed, 743 insertions(+), 9 deletions(-) create mode 100644 Matrix_search/doc/Matrix_search/CGAL/Dynamic_matrix.h create mode 100644 Matrix_search/doc/Matrix_search/CGAL/Sorted_matrix_search_traits_adaptor.h create mode 100644 Matrix_search/doc/Matrix_search/CGAL/monotone_matrix_search.h create mode 100644 Matrix_search/doc/Matrix_search/CGAL/sorted_matrix_search.h create mode 100644 Matrix_search/doc/Matrix_search/Concepts/BasicMatrix.h create mode 100644 Matrix_search/doc/Matrix_search/Concepts/MonotoneMatrixSearchTraits.h create mode 100644 Matrix_search/doc/Matrix_search/Concepts/SortedMatrixSearchTraits.h create mode 100644 Matrix_search/doc/Matrix_search/Matrix_search.txt create mode 100644 Matrix_search/doc/Matrix_search/PkgDescription.txt create mode 100644 Matrix_search/doc/Matrix_search/fig/matrix.png diff --git a/.gitattributes b/.gitattributes index 039146850c3..1d11b1fd86e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2684,6 +2684,16 @@ Manual_tools/test/Manual_tools/cgal_test eol=lf Manual_tools/test/Manual_tools/html.orig.tgz -text svneol=unset#application/gzip Matrix_search/demo/Matrix_search/help/index.html svneol=native#text/html Matrix_search/demo/Matrix_search/help/rindex.html svneol=native#text/html +Matrix_search/doc/Matrix_search/CGAL/Dynamic_matrix.h -text +Matrix_search/doc/Matrix_search/CGAL/Sorted_matrix_search_traits_adaptor.h -text +Matrix_search/doc/Matrix_search/CGAL/monotone_matrix_search.h -text +Matrix_search/doc/Matrix_search/CGAL/sorted_matrix_search.h -text +Matrix_search/doc/Matrix_search/Concepts/BasicMatrix.h -text +Matrix_search/doc/Matrix_search/Concepts/MonotoneMatrixSearchTraits.h -text +Matrix_search/doc/Matrix_search/Concepts/SortedMatrixSearchTraits.h -text +Matrix_search/doc/Matrix_search/Matrix_search.txt -text +Matrix_search/doc/Matrix_search/PkgDescription.txt -text +Matrix_search/doc/Matrix_search/fig/matrix.png -text svneol=unset#image/png Matrix_search/doc_tex/Matrix_search/matrix.png -text Matrix_search/test/Matrix_search/rectangular_p_center_2_random1_test.cmd eol=lf Matrix_search/test/Matrix_search/rectangular_p_center_2_random2_test.cmd eol=lf diff --git a/Documentation/doc/Doxyfile b/Documentation/doc/Doxyfile index 30bca79073c..479ea29d3ae 100644 --- a/Documentation/doc/Doxyfile +++ b/Documentation/doc/Doxyfile @@ -31,7 +31,8 @@ STRIP_FROM_PATH = STRIP_FROM_INC_PATH = ../../Algebraic_foundations/doc/Algebraic_foundations \ ../../Number_types/doc/Number_types \ ../../STL_Extension/doc/STL_Extension \ - ../../Modular_arithmetic/doc/Modular_arithmetic + ../../Modular_arithmetic/doc/Modular_arithmetic \ + ../../Matrix_search/doc/Matrix_search SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES QT_AUTOBRIEF = YES @@ -52,8 +53,9 @@ ALIASES += cgalbib{1}="
BibTeX:
\ ALIASES += license{1}="
License:
\1
" ALIASES += "models=\xrefitem modelss \"Models\" \"Models\"" ALIASES += "refines=\xrefitem refiness \"Refines\" \"Refines\"" +ALIASES += "requires=\xrefitem requiress \"Requirements\" \"Requirements\"" ALIASES += "hasModel=\xrefitem asModelss \"Has Models\" \"Has Models\"" -ALIASES += "advanced=\attention +ALIASES += advanced=\attention ALIASES += "debug=\xrefitem debugs \"Debug\" \"Debug\"" ALIASES += "require=\xrefitem requires \"Requirements\" \"Requirements\"" ALIASES += beginadvanced="" @@ -134,6 +136,7 @@ INPUT = ../../Algebraic_foundations/doc/Algebraic_foundations \ ../../Number_types/doc/Number_types \ ../../STL_Extension/doc/STL_Extension \ ../../Modular_arithmetic/doc/Modular_arithmetic \ + ../../Matrix_search/doc/Matrix_search \ .. \ . # ../../AABB_tree/doc/AABB_tree \ @@ -188,7 +191,6 @@ INPUT = ../../Algebraic_foundations/doc/Algebraic_foundations \ # ../../Min_sphere_d/doc/Min_sphere_d \ # ../../Min_sphere_of_spheres_d/doc/Min_sphere_of_spheres_d \ # ../../Modifier/doc/Modifier \ -# ../../Modular_arithmetic/doc/Modular_arithmetic \ # ../../Nef_2/doc/Nef_2 \ # ../../Nef_3/doc/Nef_3 \ # ../../Nef_S2/doc/Nef_S2 \ @@ -239,13 +241,15 @@ EXAMPLE_PATH = ../../Algebraic_foundations/examples/Algebraic_foundati ../../Number_types/examples/Number_types \ ../../Convex_hull_2/examples/Convex_hull_2 \ ../../STL_Extension/examples/STL_Extension \ - ../../Modular_arithmetic/examples/Modular_arithmetic + ../../Modular_arithmetic/examples/Modular_arithmetic \ + ../../Matrix_search/examples/Matrix_search EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = YES IMAGE_PATH = ../../Algebraic_foundations/doc/Algebraic_foundations/fig \ ../../Number_types/doc/Number_types/fig \ ../../STL_Extension/doc/STL_Extension/fig \ - ../../Modular_arithmetic/doc/Modular_arithmetic/fig + ../../Modular_arithmetic/doc/Modular_arithmetic/fig \ + ../../Matrix_search/doc/Matrix_search/fig INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO diff --git a/Matrix_search/doc/Matrix_search/CGAL/Dynamic_matrix.h b/Matrix_search/doc/Matrix_search/CGAL/Dynamic_matrix.h new file mode 100644 index 00000000000..845de979455 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/CGAL/Dynamic_matrix.h @@ -0,0 +1,115 @@ +namespace CGAL { +/// \ingroup PkgMatrixSearch +/// +/// +/// +/// +/// The class `Dynamic_matrix` is an adaptor for an +/// arbitrary matrix class `M` to provide the dynamic operations +/// needed for monotone matrix search. +/// +/// +/// +/// +/// Requirements +/// -------------- +/// `M` is a model for `BasicMatrix`. +/// +/// +/// +/// +/// +/// \models ::BasicMatrix +/// +/// +/// \sa `BasicMatrix` +/// +/// +/// Implementation +/// -------------- +/// All operations take constant time except for +/// `extract_all_even_rows` which needs time linear in the number +/// of rows. +/// +/// +/// +/// +/// +/// +template< M > +class Dynamic_matrix { +public: + + + + + +/// \name Creation +/// @{ +/*! +\advanced initializes `d` to `m`. `m` is not copied, we only store a reference. +*/ +Dynamic_matrix( const M& m); +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of columns. +*/ +int number_of_columns() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of rows. +*/ +int number_of_rows() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the entry at position (`row`, `column`). + +\pre \f$ 0 \le\f$ `row` \f$ <\f$ `number_of_rows()` +\pre \f$ 0 \le\f$ `column` \f$ <\f$ `number_of_columns()` +*/ +Entry operator()( int row, int column) const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced replace column `old` with column number `new`. +\pre \f$ 0 \le\f$ `old`, `new` \f$ <\f$ `number_of_columns()` +*/ +void replace_column( int old, int new); +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns a new Matrix consisting of all rows of `d` with even index, (i.e. first row is row \f$ 0\f$ of `d`, second row is row \f$ 2\f$ of `d` etc.). \pre `number_of_rows()` \f$ > 0\f$. +*/ +Matrix* extract_all_even_rows() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced deletes the rightmost columns, such that `d` becomes quadratic. + +\pre `number_of_columns()` \f$ \ge\f$ `number_of_rows()` +\post `number_of_rows()` \f$ ==\f$ `number_of_columns()` +*/ +void shrink_to_quadratic_size(); +/// @} + +}; /* class Dynamic_matrix */ +} /* namespace CGAL */ + + + + diff --git a/Matrix_search/doc/Matrix_search/CGAL/Sorted_matrix_search_traits_adaptor.h b/Matrix_search/doc/Matrix_search/CGAL/Sorted_matrix_search_traits_adaptor.h new file mode 100644 index 00000000000..4ba0dda1150 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/CGAL/Sorted_matrix_search_traits_adaptor.h @@ -0,0 +1,116 @@ +namespace CGAL { +/// \ingroup PkgMatrixSearch +/// +/// +/// +/// +/// The class `Sorted_matrix_search_traits_adaptor` can be used as an +/// adaptor to create sorted matrix search traits classes for +/// arbitrary feasibility test and matrix classes `F` resp. +/// `M`. +/// +/// +/// +/// +/// \models ::SortedMatrixSearchTraits +/// +/// +/// Requirements +/// -------------- +/// +///
    +///
  1. `M` is a model for `BasicMatrix` and +///
  2. `F` defines a copy constructor and a monotone `bool +/// operator()( const Value&)`. +///
+/// +/// +/// +/// +/// +template< F,M > +class Sorted_matrix_search_traits_adaptor { +public: + + + + + +/// \name Creation +/// @{ +/*! +\advanced initializes `t` to use `m` for feasibility testing. +*/ +Sorted_matrix_search_traits_adaptor( const F& + m); +/// @} + +/// \name Types +/// @{ +/*! +\advanced typedef to `M`. +*/ +typedef Hidden_type Matrix; +/// @} + +/// \name Types +/// @{ +/*! +\advanced typedef to `Matrix::Value`. +*/ +typedef Hidden_type Value; +/// @} + +/// \name Types +/// @{ +/*! +\advanced typedef to + `std::less`. +*/ +typedef Hidden_type Compare_strictly; +/// @} + +/// \name Types +/// @{ +/*! +\advanced typedef to + `std::less_equal`. +*/ +typedef Hidden_type Compare_non_strictly; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the `Compare_strictly` object to be used for the search. +*/ +Compare_strictly compare_strictly() + const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the `Compare_non_strictly` object to be used for the search. +*/ +Compare_non_strictly compare_non_strictly() + const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced uses the feasibility test given during creation. +*/ +bool is_feasible(const Value& a); +/// @} + + + + +}; /* class Sorted_matrix_search_traits_adaptor */ +} /* namespace CGAL */ + + + + diff --git a/Matrix_search/doc/Matrix_search/CGAL/monotone_matrix_search.h b/Matrix_search/doc/Matrix_search/CGAL/monotone_matrix_search.h new file mode 100644 index 00000000000..5f58ce3b4e1 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/CGAL/monotone_matrix_search.h @@ -0,0 +1,65 @@ +/// +namespace CGAL { +/// \ingroup PkgMatrixSearch +/// +/// +/// +/// +/// +/// The function `monotone_matrix_search` computes the maxima for all +/// rows of a totally monotone matrix. +/// More precisely, monotony for matrices is defined as follows. +/// Let \f$ K\f$ be a totally ordered set, \f$ M \in K^{(n,\, m)}\f$ +/// a matrix over \f$ K\f$ and for \f$ 0 \le i < n\f$: +/// \f[ +/// rmax_M(i) :\in \left\{ \min_{0 \le j < m} j \: \left|\: +/// M[i,\, j] = \max_{0 \le k < m} M[i,\, k] \right.\right\} +/// \f] +/// the (leftmost) column containing the maximum entry in row +/// \f$ i\f$. \f$ M\f$ is called monotone, iff +/// \f[ +/// \forall\, 0 \le i_1 < i_2 < n\: :\: rmax_M(i_1) \le +/// rmax_M(i_2)\; . +/// \f] +/// \f$ M\f$ is totally monotone, iff all of its submatrices are +/// monotone (or equivalently: iff all \f$ 2 \times 2\f$ submatrices are +/// monotone). +/// +/// It computes the maximum (as specified by `compare_strictly`) +/// entry for each row of `m` and writes the corresponding column +/// to `t`, i.e. `t[i]` is set to the index of the column +/// containing the maximum element in row `i`. The maximum \f$ m_r\f$ +/// of a row \f$ r\f$ is the leftmost element for which +/// `compare_strictly`\f$ (m_r,\,x)\f$ is false for all elements \f$ x\f$ in +/// \f$ r\f$. +/// \pre `t` points to a structure of size at least +/// `m.number_of_rows()` +/// \require `Matrix` is a model for `MonotoneMatrixSearchTraits` +/// \require Value type of `RandomAccessIC` is `int`. +/// \require If `compare_strictly` is defined, it is an adaptable binary function: `Matrix::Value` \f$ \times\f$ +/// `Matrix::Value` \f$ \rightarrow\f$ `bool` describing a strict +/// (non-reflexive) total ordering on `Matrix::Value`. +/// +/// +/// \sa `CGAL::extremal_polygon_2` +/// +/// +/// Implementation +/// -------------- +/// The implementation uses an algorithm by Aggarwal +/// et al.\cite akmsw-gamsa-87. The runtime is linear in the number +/// of rows and columns of the matrix. +/// +/// +/// +/// +/// +/// +/// +/// +/// +template < class Matrix, class RandomAccessIC, + class Compare_strictly > void monotone_matrix_search( const + Matrix& m, RandomAccessIC t, const Compare_strictly& + compare_strictly = less< Matrix::Value >()); +} /* namespace CGAL */ diff --git a/Matrix_search/doc/Matrix_search/CGAL/sorted_matrix_search.h b/Matrix_search/doc/Matrix_search/CGAL/sorted_matrix_search.h new file mode 100644 index 00000000000..61c35609a1b --- /dev/null +++ b/Matrix_search/doc/Matrix_search/CGAL/sorted_matrix_search.h @@ -0,0 +1,79 @@ +/// +namespace CGAL { +/// \ingroup PkgMatrixSearch +/// +/// The function `sorted_matrix_search` selects the smallest entry +/// in a set of sorted matrices that fulfills a certain feasibility +/// criterion. +/// More exactly, a matrix \f$ M = (m_{i j}) \in S^{r \times l}\f$ +/// (over a totally ordered set \f$ S\f$) is sorted, iff +/// \f{eqnarray*}{ +/// \forall \, 1 \le i \le r,\; 1 \le j < l\; :\; m_{i j} \le m_{i (j+1)} +/// \;\; {\it and}\\ +/// \forall \, 1 \le i < r,\; 1 \le j \le l\; :\; m_{i j} \le m_{(i+1) j} +/// \;\;. +/// \f} +/// Now let \f$ \mathcal{M}\f$ be a set of \f$ n\f$ sorted matrices over \f$ S\f$ +/// and \f$ f\f$ be a monotone predicate on \f$ S\f$, i.e. +/// +/// \f[ +/// f\: :\: S \longrightarrow\, \textit{bool} \quad{\rm with}\quad f(r) +/// \;\Longrightarrow\; \forall\, t \in S\,,\: t > r \; :\; f(t)\;. +/// \f] +/// +/// If we assume there is any feasible element in one of the matrices +/// in \f$ \mathcal{M}\f$, there certainly is a smallest such element. This is the one +/// we are searching for. +/// The feasibility test as well as some other parameters can (and +/// have to) be customized through a traits class. +/// +/// +/// It returns the element `x` in one of the sorted matrices from the +/// range \f$ \left[ f,\, l \right)\f$, for which `t.is_feasible( x)` +/// is true and `t.compare( x, y)` is true for all other +/// `y` values from any matrix for which `t.is_feasible( +/// y)` is true. +/// \pre All matrices in \f$ \left[f,\, l\right)\f$ are sorted according to `Traits::compare_non_strictly`. +/// \pre There is at least one entry \f$ x\f$ in a matrix \f$ M \in \left[f,\, l\right)\f$ for which `Traits::is_feasible(x)` is true. +/// +/// \require `Traits` is a model for `SortedMatrixSearchTraits`. +/// \require Value type of `RandomAccessIterator` is `Traits::Matrix`. +/// +/// \sa `SortedMatrixSearchTraits` +/// +/// +/// Implementation +/// -------------- +/// The implementation uses an algorithm by +/// Frederickson and Johnson\cite fj-fkppc-83 \cite fj-gsrsm-84 and runs in +/// \f$ \mathcal{O}(n \cdot k + f \cdot \log (n \cdot k))\f$, where \f$ n\f$ is +/// the number of input matrices, \f$ k\f$ denotes the maximal dimension of +/// any input matrix and \f$ f\f$ the time needed for one feasibility test. +/// +/// +/// +/// +/// Example +/// -------------- +/// In the following program we build a random vector \f$ a = +/// (a_i)_{i = 1,\,\ldots,\,5}\f$ (elements drawn uniformly from \f$ \{ +/// 0,\,\ldots,\,99 \}\f$) and construct a Cartesian matrix \f$ M\f$ +/// containing as elements all sums \f$ a_i + a_j,\: i,\,j \in +/// \{1,\,\ldots,\,5\}\f$. If \f$ a\f$ is sorted, \f$ M\f$ is sorted as well. So +/// we can apply `sorted_matrix_search` to compute the upper bound +/// for the maximal entry of \f$ a\f$ in \f$ M\f$. +/// \cgalexample{Matrix_search/sorted_matrix_search.cpp} +/// +/// +/// +/// +/// +/// +/// +/// +/// +template < class RandomAccessIterator, class + Traits > Traits::Value sorted_matrix_search( + RandomAccessIterator f, RandomAccessIterator l, const Traits& + t); +} /* namespace CGAL */ diff --git a/Matrix_search/doc/Matrix_search/Concepts/BasicMatrix.h b/Matrix_search/doc/Matrix_search/Concepts/BasicMatrix.h new file mode 100644 index 00000000000..e2e5cd4391f --- /dev/null +++ b/Matrix_search/doc/Matrix_search/Concepts/BasicMatrix.h @@ -0,0 +1,66 @@ +/// \ingroup PkgMatrixSearchConcepts +/// +/// +/// +/// A class `BasicMatrix` has to provide the following +/// types and operations in order to be a model for +/// `BasicMatrix`. +/// +/// +/// +/// +/// +/// +/// \hasModel CGAL::Dynamic_matrix +/// +/// +/// \sa `SortedMatrixSearchTraits` +/// +class BasicMatrix { +public: + + + + + +/// \name Types +/// @{ +/*! +\advanced The type of a matrix entry. It has to define + a copy constructor. +*/ +typedef Hidden_type Value; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of columns. +*/ +int number_of_columns() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of rows. +*/ +int number_of_rows() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the entry at position (`row`, `column`). + +\pre \f$ 0 \le\f$ `row` \f$ <\f$ `number_of_rows()` +\pre \f$ 0 \le\f$ `column` \f$ <\f$ `number_of_columns()` +*/ +Entry operator()( int row, int column) const; +/// @} + +}; /* concept BasicMatrix */ + + + + diff --git a/Matrix_search/doc/Matrix_search/Concepts/MonotoneMatrixSearchTraits.h b/Matrix_search/doc/Matrix_search/Concepts/MonotoneMatrixSearchTraits.h new file mode 100644 index 00000000000..56af5a69c78 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/Concepts/MonotoneMatrixSearchTraits.h @@ -0,0 +1,112 @@ +/// \ingroup PkgMatrixSearchConcepts +/// +/// +/// +/// +/// The concept `MonotoneMatrixSearchTraits` is a refinement of +/// `BasicMatrix` and defines types and operations needed to +/// compute the maxima for all rows of a totally monotone matrix using +/// the function `monotone_matrix_search`. +/// +/// +/// +/// +/// +/// +/// Notes +/// -------------- +/// +///
    +///
  • For the sake of efficiency (and in order to achieve the time +/// bounds claimed for `monotone_matrix_search`), all these +/// operations have to be realized in constant time - except for +/// `extract_all_even_rows` which may take linear time. +///
  • There is an adaptor `Dynamic_matrix` that can be used to +/// add most of the functionality described above to arbitrary +/// matrix classes. +///
+/// +/// +/// +/// +/// \hasModel CGAL::Dynamic_matrix +/// +/// +/// \sa `CGAL::monotone_matrix_search` +/// +class MonotoneMatrixSearchTraits { +public: + + + + + +/// \name Types +/// @{ +/*! +\advanced The type of a matrix entry. +*/ +typedef Hidden_type Value; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of columns. +*/ +int number_of_columns() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the number of rows. +*/ +int number_of_rows() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the entry at position (`row`, `column`). + +\pre \f$ 0 \le\f$ `row` \f$ <\f$ `number_of_rows()` +\pre \f$ 0 \le\f$ `column` \f$ <\f$ `number_of_columns()` +*/ +Entry operator()( int row, int column) const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced replace column `old` with column number `new`. + +\pre \f$ 0 \le\f$ `old`, `new` \f$ <\f$ `number_of_columns()` +*/ +void replace_column( int old, int new); +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns a new Matrix consisting of all rows of `m` with even index, (i.e. first row is row \f$ 0\f$ of `m`, second row is row \f$ 2\f$ of `m` etc.). \pre `number_of_rows()` \f$ > 0\f$. +*/ +Matrix* extract_all_even_rows() const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced deletes the rightmost columns, such that `m` becomes quadratic. + +\pre `number_of_columns()` \f$ \ge\f$ `number_of_rows()` +\post `number_of_rows()` \f$ ==\f$ `number_of_columns()` +*/ +void shrink_to_quadratic_size(); +/// @} + +}; /* concept MonotoneMatrixSearchTraits */ + + + + diff --git a/Matrix_search/doc/Matrix_search/Concepts/SortedMatrixSearchTraits.h b/Matrix_search/doc/Matrix_search/Concepts/SortedMatrixSearchTraits.h new file mode 100644 index 00000000000..555ad050444 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/Concepts/SortedMatrixSearchTraits.h @@ -0,0 +1,97 @@ +/// \ingroup PkgMatrixSearchConcepts +/// +/// +/// +/// +/// The concept `SortedMatrixSearchTraits` defines types and operations +/// needed to compute the smallest entry in a set of sorted matrices +/// that fulfills a certain feasibility criterion using the function +/// `sorted_matrix_search`. +/// +/// +/// +/// +/// +/// +/// \hasModel CGAL::Sorted_matrix_search_traits_adaptor +/// +/// +/// \sa `BasicMatrix` +/// +class SortedMatrixSearchTraits { +public: + + + + + +/// \name Types +/// @{ +/*! +\advanced The class used for representing matrices. + It has to be a model for `BasicMatrix`. +*/ +typedef Hidden_type Matrix; +/// @} + +/// \name Types +/// @{ +/*! +\advanced The class used for representing the matrix elements. +*/ +typedef Matrix::Value Value; +/// @} + +/// \name Types +/// @{ +/*! +\advanced An adaptable binary function + class: `Value` \f$ \times\f$ `Value` \f$ \rightarrow\f$ `bool` + defining a non-reflexive total order on `Value`. This + determines the direction of the search. +*/ +typedef Hidden_type Compare_strictly; +/// @} + +/// \name Types +/// @{ +/*! +\advanced An adaptable binary function + class: `Value` \f$ \times\f$ `Value` \f$ \rightarrow\f$ `bool` + defining the reflexive total order on `Value` corresponding + to `Compare_strictly`. +*/ +typedef Hidden_type Compare_non_strictly; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the `Compare_strictly` object to be used for the search. +*/ +Compare_strictly compare_strictly() + const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced returns the `Compare_non_strictly` object to be used for the search. +*/ +Compare_non_strictly compare_non_strictly() + const; +/// @} + +/// \name Operations +/// @{ +/*! +\advanced The predicate to determine whether an element `a` is feasible. It has to be monotone in the sense that `compare( a, b)` and `is_feasible( a)` imply `is_feasible( b)`. +*/ +bool is_feasible( const Value& a); +/// @} + +}; /* concept SortedMatrixSearchTraits */ + + + + diff --git a/Matrix_search/doc/Matrix_search/Matrix_search.txt b/Matrix_search/doc/Matrix_search/Matrix_search.txt new file mode 100644 index 00000000000..66cbecd553b --- /dev/null +++ b/Matrix_search/doc/Matrix_search/Matrix_search.txt @@ -0,0 +1,21 @@ + +namespace CGAL { +/*! +\page chap:MatrixSearch Monotone and Sorted Matrix Search +\authors Michael Hoffmann +\par Reference Manual: +\ref PkgMatrixSearch + +`CGAL::monotone_matrix_search` and `CGAL::sorted_matrix_search` +are techniques that deal with the problem of efficiently finding +largest entries in matrices with certain structural properties. Many +concrete problems can be modelled as matrix search problems, and for +some of them we provide explicit solutions that allow you to solve +them without knowing about the matrix search technique. Examples are, +the computation of all furthest neighbors for the vertices of a convex +polygon, maximal \f$ k\f$-gons inscribed into a planar point set, and +computing rectangular \f$ p\f$-centers. + +*/ +} // namespace CGAL + diff --git a/Matrix_search/doc/Matrix_search/PkgDescription.txt b/Matrix_search/doc/Matrix_search/PkgDescription.txt new file mode 100644 index 00000000000..26b71bda8e0 --- /dev/null +++ b/Matrix_search/doc/Matrix_search/PkgDescription.txt @@ -0,0 +1,49 @@ +/// \defgroup PkgMatrixSearch Monotone and Sorted Matrix Search + +/// \defgroup PkgMatrixSearchConcepts Concepts +/// \ingroup PkgMatrixSearch +/*! +\addtogroup PkgMatrixSearch + + + + + + + + +

Monotone and Sorted Matrix Search

\image html matrix.png "" +\par Michael Hoffmann + +\par "" This package provides a matrix search framework, which is the underlying technique for the computation of all furthest neighbors for the vertices of a convex polygon, maximal k-gons inscribed into a planar point set, and computing rectangular p-centers. + +\since \cgal 1.1 + +\cgalbib{cgal:h-msms-12} + +\license{ \ref licensesGPL "GPL" } + +\par Resources: +\ref chap:MatrixSearch "User Manual" +
+ +# Assertions # + +The optimization code uses infix `OPTIMISATION` in the assertions, +e.g. defining the compiler flag +`CGAL_OPTIMISATION_NO_PRECONDITIONS` switches precondition +checking off, cf. Section \ref secchecks . + +# Classified References Pages # + +- `CGAL::monotone_matrix_search` +- `CGAL::Dynamic_matrix` +- `MonotoneMatrixSearchTraits` +- `BasicMatrix` + +- `CGAL::sorted_matrix_search` +- `CGAL::Sorted_matrix_search_traits_adaptor` +- `SortedMatrixSearchTraits` + +*/ + diff --git a/Matrix_search/doc/Matrix_search/fig/matrix.png b/Matrix_search/doc/Matrix_search/fig/matrix.png new file mode 100644 index 0000000000000000000000000000000000000000..504d67ce4a592acd09cb815a5e92c8f89a67851d GIT binary patch literal 43509 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 w$zdsKvOtUQB*(NsCx@k|$pS6HlN@vL%2f3_yC