diff options
17 files changed, 141 insertions, 45 deletions
diff --git a/.github/how_to_compile_gudhi_in_a_conda_env.md b/.github/how_to_compile_gudhi_in_a_conda_env.md new file mode 100644 index 00000000..4acfca2e --- /dev/null +++ b/.github/how_to_compile_gudhi_in_a_conda_env.md @@ -0,0 +1,93 @@ +# Install a conda development environment to compile GUDHI + +## Install miniconda + +Download the [installer](https://docs.conda.io/en/latest/miniconda.html) required by your system and follow the [instructions](https://conda.io/projects/conda/en/latest/user-guide/install/index.html). + +## Create a dedicated environment + +```bash +conda install -c conda-forge mamba # installation with mamba is faster +conda create --name gudhi +conda activate gudhi +mamba install -c conda-forge python cmake doxygen eigen cgal-cpp +``` + +Some of the requirements are in the gudhi-devel repository (please refer to +[how to use github to contribute to gudhi](how_to_use_github_to_contribute_to_gudhi.md)). +Once the gudhi-devel repository is cloned on your machine (`git clone...`) - let's call it `/workdir/gudhi-devel` i.e. - +and once the submodules are initialised (`git submodule update --init`): + +```bash +pip install -r ext/gudhi-deploy/build-requirements.txt +pip install -r ext/gudhi-deploy/test-requirements.txt # pytorch can be painful to install - not mandatory +``` + +## Compilation + +In order to compile all c++ utilities, examples, benchmarks, unitary tests, and python module: +```bash +cd /workdir/gudhi-devel +rm -rf build; mkdir build # /!\ any existing build folder will be removed +cd build +# To build all even examples and benchmarks +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DWITH_GUDHI_EXAMPLE=ON -DWITH_GUDHI_BENCHMARK=ON .. +``` + +### Specific python compilation + +In order to compile only python module +```bash +cd /workdir/gudhi-devel +rm -rf build; mkdir build # /!\ any existing build folder will be removed +cd build +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX .. +cd src/python +# To build python module in parallel +python setup.py build_ext -j 16 --inplace # 16 is the number of CPU that are used to compile the python module. Can be any other value. +# to clean the build +# python setup.py clean --all +``` + +In order to use freshly compiled gudhi python module: +```bash +PYTHONPATH=/workdir/gudhi-devel/build/src/python python # or ipython, jupyter, ... +``` + +### Specific C++ documentation generation + +```bash +cd /workdir/gudhi-devel +rm -rf build; mkdir build # /!\ any existing build folder will be removed +cd build +# python OFF to prevent python modules search makes cmake faster +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DWITH_GUDHI_PYTHON=OFF -DUSER_VERSION_DIR=version .. +make user_version; +cd version +mkdir build +cd build +# python OFF to prevent python modules search makes cmake faster +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DWITH_GUDHI_PYTHON=OFF .. +make doxygen 2>&1 | tee dox.log +grep warning dox.log # Warnings can be lost with parallel doxygen +firefox html/index.html # [optional] To display the c++ documentation. Anything else than firefox can be used. +``` + +### Specific python documentation generation + +```bash +cd /workdir/gudhi-devel +rm -rf build; mkdir build # /!\ any existing build folder will be removed +cd build +# python OFF to prevent python modules search makes cmake faster - it is the next cmake call in user version that matters +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DWITH_GUDHI_PYTHON=OFF -DUSER_VERSION_DIR=version .. +make user_version; +cd version +mkdir build +cd build +cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$CONDA_PREFIX .. +cd python +# To build python module in parallel +python setup.py build_ext -j 16 --inplace # 16 is the number of CPU that are used to compile the python module. Can be any other value. +firefox sphinx/index.html # [optional] To display the python documentation. Anything else than firefox can be used. +```
\ No newline at end of file diff --git a/biblio/bibliography.bib b/biblio/bibliography.bib index 8462e731..0a3ef43d 100644 --- a/biblio/bibliography.bib +++ b/biblio/bibliography.bib @@ -1151,7 +1151,7 @@ language={English} editor = {Lars Arge and J{\'a}nos Pach}, publisher = {Schloss Dagstuhl--Leibniz-Zentrum fuer Informatik}, address = {Dagstuhl, Germany}, - URL = {https://drops.dagstuhl.de/opus/volltexte/2015/5098}, + URL = {https://drops.dagstuhl.de/opus/volltexte/2015/5098/}, URN = {urn:nbn:de:0030-drops-50981}, doi = {10.4230/LIPIcs.SOCG.2015.642}, annote = {Keywords: Simplicial complex, Compact data structures, Automaton, NP-hard} @@ -1341,7 +1341,7 @@ doi="10.1007/978-3-030-43408-3_2", editor = {Sergio Cabello and Danny Z. Chen}, publisher = {Schloss Dagstuhl--Leibniz-Zentrum f{\"u}r Informatik}, address = {Dagstuhl, Germany}, - URL = {https://drops.dagstuhl.de/opus/volltexte/2020/12177}, + URL = {https://drops.dagstuhl.de/opus/volltexte/2020/12177/}, URN = {urn:nbn:de:0030-drops-121777}, doi = {10.4230/LIPIcs.SoCG.2020.19}, annote = {Keywords: Computational Topology, Topological Data Analysis, Edge Collapse, Simple Collapse, Persistent homology} diff --git a/src/Coxeter_triangulation/include/gudhi/Permutahedral_representation/Permutahedral_representation_iterators.h b/src/Coxeter_triangulation/include/gudhi/Permutahedral_representation/Permutahedral_representation_iterators.h index db145741..1a63d2f7 100644 --- a/src/Coxeter_triangulation/include/gudhi/Permutahedral_representation/Permutahedral_representation_iterators.h +++ b/src/Coxeter_triangulation/include/gudhi/Permutahedral_representation/Permutahedral_representation_iterators.h @@ -26,12 +26,12 @@ namespace Gudhi { namespace coxeter_triangulation { -/* \addtogroup coxeter_triangulation +/** \addtogroup coxeter_triangulation * Iterator types for Permutahedral_representation * @{ */ -/* \brief Iterator over the vertices of a simplex +/** \brief Iterator over the vertices of a simplex * represented by its permutahedral representation. * * Forward iterator, 'value_type' is Permutahedral_representation::Vertex.*/ @@ -83,7 +83,7 @@ class Vertex_iterator }; // Vertex_iterator /*---------------------------------------------------------------------------*/ -/* \brief Iterator over the k-faces of a simplex +/** \brief Iterator over the k-faces of a simplex * given by its permutahedral representation. * * Forward iterator, value_type is Permutahedral_representation. */ @@ -141,7 +141,7 @@ class Face_iterator : public boost::iterator_facade<Face_iterator<Permutahedral_ }; // Face_iterator /*---------------------------------------------------------------------------*/ -/* \brief Iterator over the k-cofaces of a simplex +/** \brief Iterator over the k-cofaces of a simplex * given by its permutahedral representation. * * Forward iterator, value_type is Permutahedral_representation. */ @@ -247,6 +247,8 @@ class Coface_iterator }; // Coface_iterator +/** @} */ + } // namespace coxeter_triangulation } // namespace Gudhi diff --git a/src/Doxyfile.in b/src/Doxyfile.in index 54ec9078..06a74012 100644 --- a/src/Doxyfile.in +++ b/src/Doxyfile.in @@ -2092,14 +2092,7 @@ EXTERNAL_PAGES = YES # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = NO +@GUDHI_DOXYGEN_CLASS_DIAGRAMS@ # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The diff --git a/src/Persistent_cohomology/concept/FilteredComplex.h b/src/Persistent_cohomology/concept/FilteredComplex.h index 26ac7ac8..59ce25e3 100644 --- a/src/Persistent_cohomology/concept/FilteredComplex.h +++ b/src/Persistent_cohomology/concept/FilteredComplex.h @@ -103,7 +103,7 @@ Filtration_simplex_range filtration_simplex_range(); /** @} */ -/* \brief Iterator over the simplices of the complex, +/** \brief Iterator over the simplices of the complex, * in an arbitrary order. * * 'value_type' must be 'Simplex_handle'.*/ diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree.h b/src/Simplex_tree/include/gudhi/Simplex_tree.h index 4d94c037..9059219c 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree.h @@ -42,6 +42,10 @@ namespace Gudhi { +/** \addtogroup simplex_tree + * @{ + */ + /** * \class Extended_simplex_type Simplex_tree.h gudhi/Simplex_tree.h * \brief Extended simplex type data structure for representing the type of simplices in an extended filtration. @@ -97,8 +101,7 @@ class Simplex_tree { // Simplex_key next to each other). typedef typename boost::container::flat_map<Vertex_handle, Node> Dictionary; - /* \brief Set of nodes sharing a same parent in the simplex tree. */ - /* \brief Set of nodes sharing a same parent in the simplex tree. */ + /** \brief Set of nodes sharing a same parent in the simplex tree. */ typedef Simplex_tree_siblings<Simplex_tree, Dictionary> Siblings; @@ -1338,7 +1341,7 @@ class Simplex_tree { } } - /* \private Returns the Simplex_handle composed of the vertex list (from the Simplex_handle), plus the given + /** \private Returns the Simplex_handle composed of the vertex list (from the Simplex_handle), plus the given * Vertex_handle if the Vertex_handle is found in the Simplex_handle children list. * Returns null_simplex() if it does not exist */ @@ -1801,7 +1804,7 @@ struct Simplex_tree_options_fast_persistence { static const bool contiguous_vertices = true; }; -/** @} */ // end defgroup simplex_tree +/** @}*/ // end addtogroup simplex_tree } // namespace Gudhi diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_iterators.h b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_iterators.h index 394c6ee1..b63a5595 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_iterators.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_iterators.h @@ -22,12 +22,12 @@ namespace Gudhi { -/* \addtogroup simplex_tree +/** \addtogroup simplex_tree * Iterators and range types for the Simplex_tree. - * @{ + * @{ */ -/* \brief Iterator over the vertices of a simplex +/** \brief Iterator over the vertices of a simplex * in a SimplexTree. * * Forward iterator, 'value_type' is SimplexTree::Vertex_handle.*/ @@ -73,7 +73,7 @@ class Simplex_tree_simplex_vertex_iterator : public boost::iterator_facade< }; /*---------------------------------------------------------------------------*/ -/* \brief Iterator over the simplices of the boundary of a +/** \brief Iterator over the simplices of the boundary of a * simplex. * * Forward iterator, value_type is SimplexTree::Simplex_handle.*/ @@ -181,7 +181,7 @@ class Simplex_tree_boundary_simplex_iterator : public boost::iterator_facade< SimplexTree * st_; // simplex containing the simplicial complex }; -/* \brief Iterator over the simplices of the boundary of a simplex and their opposite vertices. +/** \brief Iterator over the simplices of the boundary of a simplex and their opposite vertices. * * Forward iterator, value_type is std::pair<SimplexTree::Simplex_handle, SimplexTree::Vertex_handle>.*/ template<class SimplexTree> @@ -291,7 +291,7 @@ class Simplex_tree_boundary_opposite_vertex_simplex_iterator : public boost::ite }; /*---------------------------------------------------------------------------*/ -/* \brief Iterator over the simplices of a simplicial complex. +/** \brief Iterator over the simplices of a simplicial complex. * * Forward iterator, value_type is SimplexTree::Simplex_handle.*/ template<class SimplexTree> @@ -364,7 +364,7 @@ class Simplex_tree_complex_simplex_iterator : public boost::iterator_facade< SimplexTree * st_; }; -/* \brief Iterator over the simplices of the skeleton of a given +/** \brief Iterator over the simplices of the skeleton of a given * dimension of the simplicial complex. * * Forward iterator, value_type is SimplexTree::Simplex_handle.*/ @@ -447,7 +447,8 @@ class Simplex_tree_skeleton_simplex_iterator : public boost::iterator_facade< int curr_dim_; }; -/* @} */ // end addtogroup simplex_tree +/** @}*/ // end addtogroup simplex_tree + } // namespace Gudhi #endif // SIMPLEX_TREE_SIMPLEX_TREE_ITERATORS_H_ diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_node_explicit_storage.h b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_node_explicit_storage.h index ad53710c..63023daa 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_node_explicit_storage.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_node_explicit_storage.h @@ -15,13 +15,12 @@ namespace Gudhi { -/* \addtogroup simplex_tree +/** \addtogroup simplex_tree * Represents a node of a Simplex_tree. * @{ */ -/* - * \brief Node of a simplex tree with filtration value +/** \brief Node of a simplex tree with filtration value * and simplex key. * * It stores explicitly its own filtration value and its own Simplex_key. @@ -54,7 +53,8 @@ struct Simplex_tree_node_explicit_storage : SimplexTree::Filtration_simplex_base Siblings * children_; }; -/* @} */ // end addtogroup simplex_tree +/** @}*/ // end addtogroup simplex_tree + } // namespace Gudhi #endif // SIMPLEX_TREE_SIMPLEX_TREE_NODE_EXPLICIT_STORAGE_H_ diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_siblings.h b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_siblings.h index ae25d290..d849eeba 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_siblings.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree/Simplex_tree_siblings.h @@ -20,12 +20,12 @@ namespace Gudhi { -/* \addtogroup simplex_tree +/** \addtogroup simplex_tree * Represents a set of node of a Simplex_tree that share the same parent. * @{ */ -/* \brief Data structure to store a set of nodes in a SimplexTree sharing +/** \brief Data structure to store a set of nodes in a SimplexTree sharing * the same parent node.*/ template<class SimplexTree, class MapContainer> class Simplex_tree_siblings { @@ -58,7 +58,7 @@ class Simplex_tree_siblings { members_() { } - /* \brief Constructor with initialized set of members. + /** \brief Constructor with initialized set of members. * * 'members' must be sorted and unique.*/ template<typename RandomAccessVertexRange> @@ -72,8 +72,7 @@ class Simplex_tree_siblings { } } - /* - * \brief Inserts a Node in the set of siblings nodes. + /** \brief Inserts a Node in the set of siblings nodes. * * If already present, assigns the minimal filtration value * between input filtration_value and the value already @@ -114,7 +113,8 @@ class Simplex_tree_siblings { Dictionary members_; }; -/* @} */ // end addtogroup simplex_tree +/** @}*/ // end addtogroup simplex_tree + } // namespace Gudhi #endif // SIMPLEX_TREE_SIMPLEX_TREE_SIBLINGS_H_ diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree/indexing_tag.h b/src/Simplex_tree/include/gudhi/Simplex_tree/indexing_tag.h index 3e395ae2..29c76e50 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree/indexing_tag.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree/indexing_tag.h @@ -20,7 +20,7 @@ namespace Gudhi { struct linear_indexing_tag { }; -/* \brief Tag for a zigzag ordering of simplices. */ +/** \brief Tag for a zigzag ordering of simplices. */ // struct zigzag_indexing_tag {}; } // namespace Gudhi diff --git a/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h b/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h index 2ae1d6e0..1aebb045 100644 --- a/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h +++ b/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h @@ -18,7 +18,7 @@ namespace Gudhi { namespace witness_complex { - /* \class Active_witness + /** \class Active_witness * \brief Class representing a list of nearest neighbors to a given witness. * \details Every element is a pair of a landmark identifier and the squared distance to it. */ diff --git a/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h b/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h index 4f8fddba..18f19650 100644 --- a/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h +++ b/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h @@ -18,7 +18,7 @@ namespace Gudhi { namespace witness_complex { -/* \brief Iterator in the nearest landmark list. +/** \brief Iterator in the nearest landmark list. * \details After the iterator reaches the end of the list, * the list is augmented by a (nearest landmark, distance) pair if possible. * If all the landmarks are present in the list, iterator returns the specific end value diff --git a/src/Witness_complex/include/gudhi/Strong_witness_complex.h b/src/Witness_complex/include/gudhi/Strong_witness_complex.h index b3699f77..ddc0da32 100644 --- a/src/Witness_complex/include/gudhi/Strong_witness_complex.h +++ b/src/Witness_complex/include/gudhi/Strong_witness_complex.h @@ -125,7 +125,7 @@ class Strong_witness_complex { //@} private: - /* \brief Adds recursively all the faces of a certain dimension dim-1 witnessed by the same witness. + /** \brief Adds recursively all the faces of a certain dimension dim-1 witnessed by the same witness. * Iterator is needed to know until how far we can take landmarks to form simplexes. * simplex is the prefix of the simplexes to insert. * The landmark pointed by aw_it is added to all formed simplices. diff --git a/src/Witness_complex/include/gudhi/Witness_complex.h b/src/Witness_complex/include/gudhi/Witness_complex.h index d655c7f6..66ae7af2 100644 --- a/src/Witness_complex/include/gudhi/Witness_complex.h +++ b/src/Witness_complex/include/gudhi/Witness_complex.h @@ -127,7 +127,7 @@ class Witness_complex { //@} private: - /* \brief Adds recursively all the faces of a certain dimension dim witnessed by the same witness. + /** \brief Adds recursively all the faces of a certain dimension dim witnessed by the same witness. * Iterator is needed to know until how far we can take landmarks to form simplexes. * simplex is the prefix of the simplexes to insert. * The output value indicates if the witness rests active or not. diff --git a/src/Witness_complex/include/gudhi/Witness_complex/all_faces_in.h b/src/Witness_complex/include/gudhi/Witness_complex/all_faces_in.h index 5845728a..007ab084 100644 --- a/src/Witness_complex/include/gudhi/Witness_complex/all_faces_in.h +++ b/src/Witness_complex/include/gudhi/Witness_complex/all_faces_in.h @@ -11,7 +11,7 @@ #ifndef WITNESS_COMPLEX_ALL_FACES_IN_H_ #define WITNESS_COMPLEX_ALL_FACES_IN_H_ -/* \brief Check if the facets of the k-dimensional simplex witnessed +/** \brief Check if the facets of the k-dimensional simplex witnessed * by witness witness_id are already in the complex. * inserted_vertex is the handle of the (k+1)-th vertex witnessed by witness_id */ diff --git a/src/cmake/modules/GUDHI_doxygen_target.cmake b/src/cmake/modules/GUDHI_doxygen_target.cmake index 6b9514de..327513da 100644 --- a/src/cmake/modules/GUDHI_doxygen_target.cmake +++ b/src/cmake/modules/GUDHI_doxygen_target.cmake @@ -45,6 +45,11 @@ if(DOXYGEN_FOUND) endif() message("++ Doxygen version ${DOXYGEN_VERSION}") + if (DOXYGEN_VERSION VERSION_LESS 1.9.3) + set(GUDHI_DOXYGEN_CLASS_DIAGRAMS "CLASS_DIAGRAMS = NO") + else() + set(GUDHI_DOXYGEN_CLASS_DIAGRAMS "") + endif() if (DOXYGEN_VERSION VERSION_LESS 1.9.2) set(GUDHI_DOXYGEN_MATHJAX_VERSION "MATHJAX_VERSION = MathJax_2") set(GUDHI_DOXYGEN_MATHJAX_EXTENSIONS "TeX/AMSmath TeX/AMSsymbols") @@ -52,6 +57,7 @@ if(DOXYGEN_FOUND) set(GUDHI_DOXYGEN_MATHJAX_VERSION "MATHJAX_VERSION = MathJax_3") set(GUDHI_DOXYGEN_MATHJAX_EXTENSIONS "ams") endif() + configure_file(${GUDHI_DOXYGEN_SOURCE_PREFIX}/Doxyfile.in "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" @ONLY) add_custom_target(doxygen ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile diff --git a/src/cmake/modules/GUDHI_user_version_target.cmake b/src/cmake/modules/GUDHI_user_version_target.cmake index 9e76c3d9..4487ad86 100644 --- a/src/cmake/modules/GUDHI_user_version_target.cmake +++ b/src/cmake/modules/GUDHI_user_version_target.cmake @@ -14,8 +14,6 @@ add_custom_command(TARGET user_version PRE_BUILD COMMAND ${CMAKE_COMMAND} -E make_directory ${GUDHI_USER_VERSION_DIR} COMMENT "user_version creation in ${GUDHI_USER_VERSION_DIR}") -file(COPY "${CMAKE_SOURCE_DIR}/src/Doxyfile.in" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/") - # Generate bib files for Doxygen - cf. root CMakeLists.txt for explanation string(TIMESTAMP GUDHI_VERSION_YEAR "%Y") configure_file(${CMAKE_SOURCE_DIR}/biblio/how_to_cite_gudhi.bib.in "${CMAKE_CURRENT_BINARY_DIR}/biblio/how_to_cite_gudhi.bib" @ONLY) |