From 41d554fe585c8442f6a765c24d5d6a9060b9d2e9 Mon Sep 17 00:00:00 2001 From: Simon Giraudot Date: Mon, 16 Apr 2018 15:33:36 +0200 Subject: [PATCH] Deprecating Diagonalize_traits: document dependency to Eigen --- .../CGAL/Approximate_min_ellipsoid_d.h | 2 ++ .../CGAL/Classification/Local_eigen_analysis.h | 7 +++---- .../Classification/Point_set_feature_generator.h | 6 ++---- .../CGAL/Classification/Point_set_neighborhood.h | 1 - .../Jet_fitting_3/CGAL/Monge_via_jet_fitting.h | 1 + Mesh_3/doc/Mesh_3/CGAL/lloyd_optimize_mesh_3.h | 1 + .../Point_set_processing_3/NamedParameters.txt | 2 +- .../CGAL/linear_least_squares_fitting_2.h | 2 +- .../CGAL/linear_least_squares_fitting_3.h | 7 +++---- .../Weighted_PCA_smoother.h | 9 ++++----- .../Solver_interface/Concepts/DiagonalizeTraits.h | 2 -- .../doc/Solver_interface/Solver_interface.txt | 15 ++------------- .../include/CGAL/Default_diagonalize_traits.h | 4 ++++ .../include/CGAL/Diagonalize_traits.h | 4 ++++ 14 files changed, 28 insertions(+), 35 deletions(-) diff --git a/Bounding_volumes/doc/Bounding_volumes/CGAL/Approximate_min_ellipsoid_d.h b/Bounding_volumes/doc/Bounding_volumes/CGAL/Approximate_min_ellipsoid_d.h index c162a00c5aa..8fbe5d25734 100644 --- a/Bounding_volumes/doc/Bounding_volumes/CGAL/Approximate_min_ellipsoid_d.h +++ b/Bounding_volumes/doc/Bounding_volumes/CGAL/Approximate_min_ellipsoid_d.h @@ -137,6 +137,8 @@ for display in Maplesoft's Maple. \cgalExample{Approximate_min_ellipsoid_d/ellipsoid_for_maple.cpp} +\note This class requires the \ref thirdpartyEigen library. + */ template< typename Traits > class Approximate_min_ellipsoid_d { diff --git a/Classification/include/CGAL/Classification/Local_eigen_analysis.h b/Classification/include/CGAL/Classification/Local_eigen_analysis.h index 7fcdb9d2ba1..f8ca6bf1903 100644 --- a/Classification/include/CGAL/Classification/Local_eigen_analysis.h +++ b/Classification/include/CGAL/Classification/Local_eigen_analysis.h @@ -184,10 +184,9 @@ public: algorithm. Possible values are `Parallel_tag` (default value is %CGAL is linked with TBB) or `Sequential_tag` (default value otherwise). \tparam DiagonalizeTraits model of `DiagonalizeTraits` used for - matrix diagonalization. It can be omitted: if Eigen 3 (or greater) - is available and `CGAL_EIGEN3_ENABLED` is defined then an overload - using `Eigen_diagonalize_traits` is provided. Otherwise, the - internal implementation `Diagonalize_traits` is used. + matrix diagonalization. It can be omitted if Eigen 3 (or greater) + is available and `CGAL_EIGEN3_ENABLED` is defined. In that case, + an overload using `Eigen_diagonalize_traits` is provided. \param input point range. \param point_map property map to access the input points. diff --git a/Classification/include/CGAL/Classification/Point_set_feature_generator.h b/Classification/include/CGAL/Classification/Point_set_feature_generator.h index b74ef1d16f6..8108c671422 100644 --- a/Classification/include/CGAL/Classification/Point_set_feature_generator.h +++ b/Classification/include/CGAL/Classification/Point_set_feature_generator.h @@ -87,10 +87,8 @@ namespace Classification { is linked with TBB) or `Sequential_tag` (default value otherwise). \tparam DiagonalizeTraits model of `DiagonalizeTraits` used for matrix diagonalization. It can be omitted: if Eigen 3 (or greater) - is available and `CGAL_EIGEN3_ENABLED` is defined then an overload - using `Eigen_diagonalize_traits` is provided. Otherwise, the - internal implementation `Diagonalize_traits` is used. - + is available and `CGAL_EIGEN3_ENABLED` is defined: in that case, an + overload using `Eigen_diagonalize_traits` is provided. */ template #include #include -#include #include #include #include diff --git a/Jet_fitting_3/doc/Jet_fitting_3/CGAL/Monge_via_jet_fitting.h b/Jet_fitting_3/doc/Jet_fitting_3/CGAL/Monge_via_jet_fitting.h index f9df0ee5b65..7f31a429a16 100644 --- a/Jet_fitting_3/doc/Jet_fitting_3/CGAL/Monge_via_jet_fitting.h +++ b/Jet_fitting_3/doc/Jet_fitting_3/CGAL/Monge_via_jet_fitting.h @@ -29,6 +29,7 @@ algebra algorithm required by the fitting method. The scalar type, `SvdTraits:: \sa `Eigen_svd` \sa `Monge_form` +\note This class requires the \ref thirdpartyEigen library. */ template< typename DataKernel, typename LocalKernel, typename SvdTraits > class Monge_via_jet_fitting { diff --git a/Mesh_3/doc/Mesh_3/CGAL/lloyd_optimize_mesh_3.h b/Mesh_3/doc/Mesh_3/CGAL/lloyd_optimize_mesh_3.h index 498e582d500..c6d3e76f4ea 100644 --- a/Mesh_3/doc/Mesh_3/CGAL/lloyd_optimize_mesh_3.h +++ b/Mesh_3/doc/Mesh_3/CGAL/lloyd_optimize_mesh_3.h @@ -100,6 +100,7 @@ lloyd_optimize_mesh_3(c3t3, \sa `CGAL::perturb_mesh_3()` \sa `CGAL::odt_optimize_mesh_3()` +\note This function requires the \ref thirdpartyEigen library. */ template diff --git a/Point_set_processing_3/doc/Point_set_processing_3/NamedParameters.txt b/Point_set_processing_3/doc/Point_set_processing_3/NamedParameters.txt index ee2acdba8f2..ee5322600c1 100644 --- a/Point_set_processing_3/doc/Point_set_processing_3/NamedParameters.txt +++ b/Point_set_processing_3/doc/Point_set_processing_3/NamedParameters.txt @@ -49,7 +49,7 @@ No default value. \cgalNPBegin{diagonalize_traits} \anchor PSP_diagonalize_traits is the solver used for diagonalizing covariance matrices.\n \b Type: a class model of `DiagonalizeTraits`.\n -\b Default: if \ref thirdpartyEigen "Eigen" 3.2 (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined, then `CGAL::Eigen_diagonalize_traits` is used. Otherwise, the fallback `CGAL::Diagonalize_traits` is used (note that it is significantly slower, so using Eigen is strongly advised).\n +\b Default: `CGAL::Eigen_diagonalize_traits` if \ref thirdpartyEigen "Eigen" 3.2 (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined.\n \cgalNPEnd \cgalNPBegin{svd_traits} \anchor PSP_svd_traits diff --git a/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_2.h b/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_2.h index 1668552b251..16c458413a7 100644 --- a/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_2.h +++ b/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_2.h @@ -13,7 +13,7 @@ The tag `tag` identifies the dimension to be considered from the objects. For po The class `K` is the kernel in which the value type of the `InputIterator` is defined. It can be omitted and deduced automatically from the value type. -The class `DiagonalizeTraits_` is a model of `DiagonalizeTraits`. It can be omitted: if Eigen 3 (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined then an overload using `Eigen_diagonalize_traits` is provided. Otherwise, the internal implementation `Diagonalize_traits` is used. +The class `DiagonalizeTraits_` is a model of `DiagonalizeTraits`. It can be omitted if Eigen 3 (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined: in that case, an overload using `Eigen_diagonalize_traits` is provided. \cgalHeading{Requirements} diff --git a/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_3.h b/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_3.h index 9a6812e1e27..4a01d3bc784 100644 --- a/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_3.h +++ b/Principal_component_analysis/doc/Principal_component_analysis/CGAL/linear_least_squares_fitting_3.h @@ -65,10 +65,9 @@ value type of `InputIterator` is defined. It can be omitted and deduced automatically from the value type. The class `DiagonalizeTraits_` is a model of `DiagonalizeTraits`. It -can be omitted: if Eigen 3 (or greater) is available and -`CGAL_EIGEN3_ENABLED` is defined then an overload using -`Eigen_diagonalize_traits` is provided. Otherwise, the internal -implementation `Diagonalize_traits` is used. +can be omitted if Eigen 3 (or greater) is available and +`CGAL_EIGEN3_ENABLED` is defined: in that case, an overload using +`Eigen_diagonalize_traits` is provided. \note This function is significantly faster when using `Eigen_diagonalize_traits` and it is strongly advised to use this diff --git a/Scale_space_reconstruction_3/include/CGAL/Scale_space_reconstruction_3/Weighted_PCA_smoother.h b/Scale_space_reconstruction_3/include/CGAL/Scale_space_reconstruction_3/Weighted_PCA_smoother.h index 6f991ed6d74..f2f1fb39555 100644 --- a/Scale_space_reconstruction_3/include/CGAL/Scale_space_reconstruction_3/Weighted_PCA_smoother.h +++ b/Scale_space_reconstruction_3/include/CGAL/Scale_space_reconstruction_3/Weighted_PCA_smoother.h @@ -61,11 +61,10 @@ namespace Scale_space_reconstruction_3 * \tparam DiagonalizeTraits model of `DiagonalizeTraits` that * determines how to diagonalize a weighted covariance matrix to - * approximate a weighted point set. It can be omitted: if Eigen 3 - * (or greater) is available and `CGAL_EIGEN3_ENABLED` is defined - * then an overload using `Eigen_diagonalize_traits` is - * provided. Otherwise, the internal implementation - * `Diagonalize_traits` is used. + * approximate a weighted point set. It can be omitted if Eigen 3 (or + * greater) is available and `CGAL_EIGEN3_ENABLED` is defined: in + * that case, an overload using `Eigen_diagonalize_traits` is + * provided. * \tparam ConcurrencyTag indicates whether to use concurrent * processing. It can be omitted: if TBB (or greater) is available * and `CGAL_LINKED_WITH_TBB` is defined then `Parallel_tag` is diff --git a/Solver_interface/doc/Solver_interface/Concepts/DiagonalizeTraits.h b/Solver_interface/doc/Solver_interface/Concepts/DiagonalizeTraits.h index 345bd48dd39..1badaed4564 100644 --- a/Solver_interface/doc/Solver_interface/Concepts/DiagonalizeTraits.h +++ b/Solver_interface/doc/Solver_interface/Concepts/DiagonalizeTraits.h @@ -17,8 +17,6 @@ follows: \tparam FT Number type \tparam dim Dimension of the matrices and vectors -\cgalHasModel `CGAL::Default_diagonalize_traits` -\cgalHasModel `CGAL::Diagonalize_traits` \cgalHasModel `CGAL::Eigen_diagonalize_traits` */ diff --git a/Solver_interface/doc/Solver_interface/Solver_interface.txt b/Solver_interface/doc/Solver_interface/Solver_interface.txt index f613ce32e74..8025bd5cafd 100644 --- a/Solver_interface/doc/Solver_interface/Solver_interface.txt +++ b/Solver_interface/doc/Solver_interface/Solver_interface.txt @@ -26,23 +26,12 @@ Library (MKL). The concept `DiagonalizeTraits` defines an interface for the diagonalization and computation of eigenvectors and eigenvalues of a symmetric matrix. `T` is the number type and `dim` is the dimension of -the matrices and vector (set to 3 by default). We provide two models -for this concept: - -- `Eigen_diagonalize_traits` uses the \ref thirdpartyEigen library. -- `Diagonalize_traits` is an internal implementation that does not -depend on another library. - -Although both models achieve the same computation, -`Eigen_diagonalize_traits` is more precise and faster: it -should thus be used if the \ref thirdpartyEigen library is -available. The eigenvalues are stored in ascending order and -eigenvectors are stored in accordance. +the matrices and vector (set to 3 by default). We provide the model +`Eigen_diagonalize_traits` that uses the \ref thirdpartyEigen library. This is an example of an eigen decomposition of a matrix using this class: - \cgalExample{Solver_interface/diagonalize_matrix.cpp} diff --git a/Solver_interface/include/CGAL/Default_diagonalize_traits.h b/Solver_interface/include/CGAL/Default_diagonalize_traits.h index 6dc31b4aa35..7dd97adf522 100644 --- a/Solver_interface/include/CGAL/Default_diagonalize_traits.h +++ b/Solver_interface/include/CGAL/Default_diagonalize_traits.h @@ -26,6 +26,8 @@ #include #endif +/// \cond SKIP_IN_MANUAL + namespace CGAL { /// \ingroup PkgSolver @@ -84,4 +86,6 @@ public: } // namespace CGAL +/// \endcond + #endif // CGAL_DEFAULT_DIAGONALIZE_TRAITS_H diff --git a/Solver_interface/include/CGAL/Diagonalize_traits.h b/Solver_interface/include/CGAL/Diagonalize_traits.h index f1c29fa74db..57c086ef6b2 100644 --- a/Solver_interface/include/CGAL/Diagonalize_traits.h +++ b/Solver_interface/include/CGAL/Diagonalize_traits.h @@ -30,6 +30,8 @@ CGAL_DEPRECATED_MSG("CGAL::Diagonalize_traits is a deprecated class that can \ lead to precision issues, please use CGAL::Eigen_diagonalize_traits") +/// \cond SKIP_IN_MANUAL + namespace CGAL { /// \ingroup PkgSolver @@ -299,4 +301,6 @@ public: } // namespace CGAL +/// \endcond + #endif // CGAL_DIAGONALIZE_TRAITS_H