diff options
| author | Vincent Rouvreau <VincentRouvreau@users.noreply.github.com> | 2019-06-06 11:16:38 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-06-06 11:16:38 +0200 |
| commit | b858862d63ffcdcaed0e0a4913f5d9d42bc0dcbb (patch) | |
| tree | 9f09a820a819fe2886d7050c71cf41a4aa35a3d5 /src | |
| parent | b9ddc3b6f1501fc15e84a8bea5927adae6623e5a (diff) | |
| parent | ef5fcf9e54e0c14f7c2e7eebb5c24fb91018606a (diff) | |
Merge pull request #66 from VincentRouvreau/small_fixes
Small fixes
Diffstat (limited to 'src')
30 files changed, 605 insertions, 466 deletions
diff --git a/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h b/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h index 32dfcc16..0bf12b1a 100644 --- a/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h +++ b/src/Alpha_complex/include/gudhi/Alpha_complex_3d.h @@ -58,7 +58,7 @@ #include <limits> // for numeric_limits<> #if CGAL_VERSION_NR < 1041101000 -// Make compilation fail - required for external projects - https://gitlab.inria.fr/GUDHI/gudhi-devel/issues/10 +// Make compilation fail - required for external projects - https://github.com/GUDHI/gudhi-devel/issues/10 # error Alpha_complex_3d is only available for CGAL >= 4.11 #endif diff --git a/src/Alpha_complex/utilities/alphacomplex.md b/src/Alpha_complex/utilities/alphacomplex.md index 50a39d32..fcd16a3b 100644 --- a/src/Alpha_complex/utilities/alphacomplex.md +++ b/src/Alpha_complex/utilities/alphacomplex.md @@ -33,7 +33,7 @@ a prime number). where
`<input OFF file>` is the path to the input point cloud in
-[nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+[nOFF ASCII format]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsOFF).
**Allowed options**
@@ -87,7 +87,7 @@ a prime number). ```
where `<input OFF file>` is the path to the input point cloud in
-[nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+[nOFF ASCII format]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsOFF).
**Allowed options**
@@ -103,8 +103,10 @@ to be recorded. Enter a negative value to see zero length intervals. * `-c [ --cuboid-file ]` is the path to the file describing the periodic domain.
It must be in the format described
[here]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsIsoCuboid).
+Default version is not periodic.
* `-w [ --weight-file ]` is the path to the file containing the weights of the
points (one value per line).
+Default version is not weighted.
* `-e [ --exact ]` for the exact computation version (not compatible with
weight and periodic version).
* `-f [ --fast ]` for the fast computation version.
diff --git a/src/Doxyfile.in b/src/Doxyfile.in index 1c293d1c..5b1b8ecc 100644 --- a/src/Doxyfile.in +++ b/src/Doxyfile.in @@ -208,7 +208,7 @@ SEPARATE_MEMBER_PAGES = NO # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. -TAB_SIZE = 4 +TAB_SIZE = 2 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: @@ -821,7 +821,8 @@ EXCLUDE_SYMBOLS = EXAMPLE_PATH = biblio/ \ example/ \ - utilities/ + utilities/ \ + data/ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -889,7 +890,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = doc/common/main_page.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -1147,7 +1148,7 @@ HTML_DYNAMIC_SECTIONS = NO # Minimum value: 0, maximum value: 9999, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_INDEX_NUM_ENTRIES = 100 +HTML_INDEX_NUM_ENTRIES = 2 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development diff --git a/src/Nerve_GIC/doc/Intro_graph_induced_complex.h b/src/Nerve_GIC/doc/Intro_graph_induced_complex.h index bc8aecc3..e72d63dd 100644 --- a/src/Nerve_GIC/doc/Intro_graph_induced_complex.h +++ b/src/Nerve_GIC/doc/Intro_graph_induced_complex.h @@ -37,8 +37,7 @@ namespace cover_complex { * neato (from <a target="_blank" href="http://www.graphviz.org/">graphviz</a>), * <a target="_blank" href="http://www.geomview.org/">geomview</a>, * <a target="_blank" href="https://github.com/MLWave/kepler-mapper">KeplerMapper</a>. - * Input point clouds are assumed to be - * <a target="_blank" href="http://www.geomview.org/docs/html/OFF.html">OFF files</a>. + * Input point clouds are assumed to be \ref FileFormatsOFF "OFF files" * * \section covers Covers * diff --git a/src/Persistent_cohomology/concept/FilteredComplex.h b/src/Persistent_cohomology/concept/FilteredComplex.h index 62b9002f..7eb01b01 100644 --- a/src/Persistent_cohomology/concept/FilteredComplex.h +++ b/src/Persistent_cohomology/concept/FilteredComplex.h @@ -27,7 +27,7 @@ */ struct FilteredComplex { -/** Handle to specify a simplex. */ +/** \brief Handle to specify a simplex. */ typedef unspecified Simplex_handle; /** \brief Type for the value of the filtration function. * @@ -39,8 +39,7 @@ struct FilteredComplex * is model of IndexingTag. */ typedef unspecified Indexing_tag; -/** Returns a Simplex_handle that is different from all simplex handles - * of the simplices. */ +/** \brief Returns a Simplex_handle that is different from all simplex handles of the simplices. */ Simplex_handle null_simplex(); /** \brief Returns the number of simplices in the complex. * @@ -58,22 +57,19 @@ struct FilteredComplex * * This is only called on valid indices. */ Simplex_handle simplex ( size_t idx ); -/** \brief Iterator on the simplices belonging to the - * boundary of a simplex. +/** \brief Iterator on the simplices belonging to the boundary of a simplex. * * <CODE>value_type</CODE> must be 'Simplex_handle'. */ typedef unspecified Boundary_simplex_iterator; -/** \brief Range giving access to the simplices in the boundary of - * a simplex. +/** \brief Range giving access to the simplices in the boundary of a simplex. * * .begin() and .end() return type Boundary_simplex_iterator. */ typedef unspecified Boundary_simplex_range; -/** \brief Returns a range giving access to all simplices of the - * boundary of a simplex, i.e. - * the set of codimension 1 subsimplices of the Simplex. +/** \brief Returns a range giving access to all simplices of the boundary of a simplex, i.e. the set of codimension 1 + * subsimplices of the Simplex. * * If the simplex is \f$[v_0, \cdots ,v_d]\f$, with canonical orientation * induced by \f$ v_0 < \cdots < v_d \f$, the iterator enumerates the @@ -84,19 +80,16 @@ typedef unspecified Boundary_simplex_range; * gives the chains corresponding to the boundary of the simplex.*/ Boundary_simplex_range boundary_simplex_range(Simplex_handle sh); -/** \brief Iterator over all simplices of the complex - * in the order of the indexing scheme. +/** \brief Iterator over all simplices of the complex in the order of the indexing scheme. * * 'value_type' must be 'Simplex_handle'. */ typedef unspecified Filtration_simplex_iterator; -/** \brief Range over the simplices of the complex - * in the order of the filtration. +/** \brief Range over the simplices of the complex in the order of the filtration. * * .begin() and .end() return type Filtration_simplex_iterator.*/ typedef unspecified Filtration_simplex_range; -/** \brief Returns a range over the simplices of the complex - * in the order of the filtration. +/** \brief Returns a range over the simplices of the complex in the order of the filtration. * * .begin() and .end() return type Filtration_simplex_iterator.*/ Filtration_simplex_range filtration_simplex_range(); diff --git a/src/Persistent_cohomology/include/gudhi/Persistent_cohomology.h b/src/Persistent_cohomology/include/gudhi/Persistent_cohomology.h index c51e47a5..c57174cb 100644 --- a/src/Persistent_cohomology/include/gudhi/Persistent_cohomology.h +++ b/src/Persistent_cohomology/include/gudhi/Persistent_cohomology.h @@ -63,12 +63,21 @@ namespace persistent_cohomology { template<class FilteredComplex, class CoefficientField> class Persistent_cohomology { public: - typedef FilteredComplex Complex_ds; // Data attached to each simplex to interface with a Property Map. - typedef typename Complex_ds::Simplex_key Simplex_key; - typedef typename Complex_ds::Simplex_handle Simplex_handle; - typedef typename Complex_ds::Filtration_value Filtration_value; + + /** \brief Data stored for each simplex. */ + typedef typename FilteredComplex::Simplex_key Simplex_key; + /** \brief Handle to specify a simplex. */ + typedef typename FilteredComplex::Simplex_handle Simplex_handle; + /** \brief Type for the value of the filtration function. */ + typedef typename FilteredComplex::Filtration_value Filtration_value; + /** \brief Type of element of the field. */ typedef typename CoefficientField::Element Arith_element; + /** \brief Type for birth and death FilteredComplex::Simplex_handle. + * The Arith_element field is used for the multi-field framework. */ + typedef std::tuple<Simplex_handle, Simplex_handle, Arith_element> Persistent_interval; + + private: // Compressed Annotation Matrix types: // Column type typedef Persistent_cohomology_column<Simplex_key, Arith_element> Column; // contains 1 set_hook @@ -83,16 +92,15 @@ class Persistent_cohomology { boost::intrusive::constant_time_size<false> > Cam; // Sparse column type for the annotation of the boundary of an element. typedef std::vector<std::pair<Simplex_key, Arith_element> > A_ds_type; - // Persistent interval type. The Arith_element field is used for the multi-field framework. - typedef std::tuple<Simplex_handle, Simplex_handle, Arith_element> Persistent_interval; + public: /** \brief Initializes the Persistent_cohomology class. * * @param[in] cpx Complex for which the persistent homology is computed. * cpx is a model of FilteredComplex * @exception std::out_of_range In case the number of simplices is more than Simplex_key type numeric limit. */ - explicit Persistent_cohomology(Complex_ds& cpx) + explicit Persistent_cohomology(FilteredComplex& cpx) : cpx_(&cpx), dim_max_(cpx.dimension()), // upper bound on the dimension of the simplices coeff_field_(), // initialize the field coefficient structure. @@ -128,7 +136,7 @@ class Persistent_cohomology { * @param[in] persistence_dim_max if true, the persistent homology for the maximal dimension in the * complex is computed. If false, it is ignored. Default is false. */ - Persistent_cohomology(Complex_ds& cpx, bool persistence_dim_max) + Persistent_cohomology(FilteredComplex& cpx, bool persistence_dim_max) : Persistent_cohomology(cpx) { if (persistence_dim_max) { ++dim_max_; @@ -146,7 +154,7 @@ class Persistent_cohomology { private: struct length_interval { - length_interval(Complex_ds * cpx, Filtration_value min_length) + length_interval(FilteredComplex * cpx, Filtration_value min_length) : cpx_(cpx), min_length_(min_length) { } @@ -159,7 +167,7 @@ class Persistent_cohomology { min_length_ = new_length; } - Complex_ds * cpx_; + FilteredComplex * cpx_; Filtration_value min_length_; }; @@ -552,14 +560,14 @@ class Persistent_cohomology { * Compare two intervals by length. */ struct cmp_intervals_by_length { - explicit cmp_intervals_by_length(Complex_ds * sc) + explicit cmp_intervals_by_length(FilteredComplex * sc) : sc_(sc) { } bool operator()(const Persistent_interval & p1, const Persistent_interval & p2) { return (sc_->filtration(get < 1 > (p1)) - sc_->filtration(get < 0 > (p1)) > sc_->filtration(get < 1 > (p2)) - sc_->filtration(get < 0 > (p2))); } - Complex_ds * sc_; + FilteredComplex * sc_; }; public: @@ -690,9 +698,8 @@ class Persistent_cohomology { return betti_number; } - /** @brief Returns the persistent pairs. - * @return Persistent pairs - * + /** @brief Returns a list of persistence birth and death FilteredComplex::Simplex_handle pairs. + * @return A list of Persistent_cohomology::Persistent_interval */ const std::vector<Persistent_interval>& get_persistent_pairs() const { return persistent_pairs_; @@ -733,7 +740,7 @@ class Persistent_cohomology { }; public: - Complex_ds * cpx_; + FilteredComplex * cpx_; int dim_max_; CoefficientField coeff_field_; size_t num_simplices_; diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree.h b/src/Simplex_tree/include/gudhi/Simplex_tree.h index 4b18651c..343ed472 100644 --- a/src/Simplex_tree/include/gudhi/Simplex_tree.h +++ b/src/Simplex_tree/include/gudhi/Simplex_tree.h @@ -1330,7 +1330,7 @@ class Simplex_tree { public: /** \brief This function ensures that each simplex has a higher filtration value than its faces by increasing the * filtration values. - * @return The filtration modification information. + * @return True if any filtration value was modified, false if the filtration was already non-decreasing. * \post Some simplex tree functions require the filtration to be valid. `make_filtration_non_decreasing()` * function is not launching `initialize_filtration()` but returns the filtration modification information. If the * complex has changed , please call `initialize_filtration()` to recompute it. diff --git a/src/common/doc/file_formats.h b/src/common/doc/file_formats.h index 23214e25..235296d3 100644 --- a/src/common/doc/file_formats.h +++ b/src/common/doc/file_formats.h @@ -29,6 +29,32 @@ namespace Gudhi { \tableofcontents + \section FileFormatsOFF OFF file format + + OFF files must be conform to format described here: http://www.geomview.org/docs/html/OFF.html + + OFF files are mainly used as point cloud inputs. Here is an example of 7 points in a 3-dimensional space. As edges and + faces are not used for point set, there is no need to specify them (just set their numbers to 0): + + \include points/alphacomplexdoc.off + + For dimensions bigger than 3, the dimension can be set like here: + \verbatim + # Dimension is no more 3 + nOFF + # dimension 4 - 7 vertices - 0 face - 0 edge + 4 7 0 0 + # Point set: + 1.0 1.0 0.0 0.0 + 7.0 0.0 0.0 0.0 + 4.0 6.0 0.0 0.0 + 9.0 6.0 0.0 0.0 + 0.0 14.0 0.0 0.0 + 2.0 19.0 0.0 0.0 + 9.0 17.0 0.0 0.0 + \endverbatim + + \section FileFormatsPers Persistence Diagram Such a file, whose extension is usually `.pers`, contains a list of persistence intervals.<br> diff --git a/src/common/doc/installation.h b/src/common/doc/installation.h index 8fb8b330..5d581b08 100644 --- a/src/common/doc/installation.h +++ b/src/common/doc/installation.h @@ -44,7 +44,7 @@ make doxygen \endverbatim * * \subsection helloworld Hello world ! - * The <a target="_blank" href="https://gitlab.inria.fr/GUDHI/hello-gudhi-world">Hello world for GUDHI</a> + * The <a target="_blank" href="https://github.com/GUDHI/hello-gudhi-world">Hello world for GUDHI</a> * project is an example to help developers to make their own C++ project on top of the GUDHI library. * * \section optionallibrary Optional third-party library diff --git a/src/common/doc/main_page.h b/src/common/doc/main_page.md index afe9b68c..e61eee81 100644 --- a/src/common/doc/main_page.h +++ b/src/common/doc/main_page.md @@ -1,261 +1,289 @@ -/*! \mainpage The C++ library - * \tableofcontents - * \image html "Gudhi_banner.png" "" width=20cm - * - * \section Introduction Introduction - * The GUDHI library (Geometry Understanding in Higher Dimensions) is a generic open source - * <a class="el" target="_blank" href="http://gudhi.gforge.inria.fr/doc/latest/">C++ library</a> for - * Computational Topology and Topological Data Analysis - * (<a class="el" target="_blank" href="https://en.wikipedia.org/wiki/Topological_data_analysis">TDA</a>). - * The GUDHI library intends to help the development of new algorithmic solutions in TDA and their transfer to - * applications. It provides robust, efficient, flexible and easy to use implementations of state-of-the-art - * algorithms and data structures. - * - * The current release of the GUDHI library includes: - * - * \li Data structures to represent, construct and manipulate simplicial complexes. - * \li Simplification of simplicial complexes by edge contraction. - * \li Algorithms to compute persistent homology and bottleneck distance. - * - * All data-structures are generic and several of their aspects can be parameterized via template classes. - * We refer to \cite gudhilibrary_ICMS14 for a detailed description of the design of the library. - * - \section DataStructures Data structures - \subsection AlphaComplexDataStructure Alpha complex - \image html "alpha_complex_representation.png" "Alpha complex representation" -<table border="0"> +[TOC] + +# The C++ library {#main_page} +\image html "Gudhi_banner.png" +<br><br><br><br> + +## Complexes {#Complexes} +### Cubical complex + +<table> <tr> - <td width="25%"> - <b>Author:</b> Vincent Rouvreau<br> + <td width="35%" rowspan=2> + \image html "Cubical_complex_representation.png" + </td> + <td width="50%"> + The cubical complex is an example of a structured complex useful in computational mathematics (specially + rigorous numerics) and image analysis.<br> + </td> + <td width="15%"> + <b>Author:</b> Pawel Dlotko<br> <b>Introduced in:</b> GUDHI 1.3.0<br> <b>Copyright:</b> GPL v3<br> - <b>Requires:</b> \ref eigen3 and<br> - \ref cgal ≥ 4.7.0 for Alpha_complex<br> - \ref cgal ≥ 4.11.0 for Alpha_complex_3d </td> - <td width="75%"> - Alpha_complex is a simplicial complex constructed from the finite cells of a Delaunay Triangulation.<br> + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref cubical_complex - <b>Reference manual:</b> Gudhi::cubical_complex::Bitmap_cubical_complex + </td> + </tr> +</table> + +### Simplicial complex + +#### Alpha complex + +<table> + <tr> + <td width="35%" rowspan=2> + \image html "alpha_complex_representation.png" + </td> + <td width="50%"> + Alpha complex is a simplicial complex constructed from the finite cells of a Delaunay Triangulation.<br> The filtration value of each simplex is computed as the square of the circumradius of the simplex if the circumsphere is empty (the simplex is then said to be Gabriel), and as the minimum of the filtration values of the codimension 1 cofaces that make it not Gabriel otherwise. All simplices that have a filtration value strictly greater than a given alpha squared value are not inserted into the complex.<br> + </td> + <td width="15%"> + <b>Author:</b> Vincent Rouvreau<br> + <b>Introduced in:</b> GUDHI 1.3.0<br> + <b>Copyright:</b> GPL v3<br> + <b>Requires:</b> \ref eigen3 and<br> + \ref cgal ≥ 4.7.0 for Alpha_complex<br> + \ref cgal ≥ 4.11.0 for Alpha_complex_3d + </td> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref alpha_complex - <b>Reference manual:</b> Gudhi::alpha_complex::Alpha_complex and Gudhi::alpha_complex::Alpha_complex_3d </td> </tr> </table> - \subsection CechComplexDataStructure Čech complex - \image html "cech_complex_representation.png" "Čech complex representation" -<table border="0"> - <tr> - <td width="25%"> + +#### Čech complex + +<table> + <tr> + <td width="35%" rowspan=2> + \image html "cech_complex_representation.png" + </td> + <td width="50%"> + The Čech complex is a simplicial complex constructed from a proximity graph. + The set of all simplices is filtered by the radius of their minimal enclosing ball. + </td> + <td width="15%"> <b>Author:</b> Vincent Rouvreau<br> <b>Introduced in:</b> GUDHI 2.2.0<br> <b>Copyright:</b> GPL v3<br> </td> - <td width="75%"> - The Čech complex is a simplicial complex constructed from a proximity graph.<br> - The set of all simplices is filtered by the radius of their minimal enclosing ball.<br> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref cech_complex - <b>Reference manual:</b> Gudhi::cech_complex::Cech_complex </td> </tr> </table> - \subsection CubicalComplexDataStructure Cubical complex - \image html "Cubical_complex_representation.png" "Cubical complex representation" -<table border="0"> + +#### Rips complex + +<table> <tr> - <td width="25%"> - <b>Author:</b> Pawel Dlotko<br> - <b>Introduced in:</b> GUDHI 1.3.0<br> - <b>Copyright:</b> GPL v3<br> + <td width="35%" rowspan=2> + \image html "rips_complex_representation.png" </td> - <td width="75%"> - The cubical complex is an example of a structured complex useful in computational mathematics (specially - rigorous numerics) and image analysis.<br> - <b>User manual:</b> \ref cubical_complex - <b>Reference manual:</b> Gudhi::cubical_complex::Bitmap_cubical_complex + <td width="50%"> + Rips complex is a simplicial complex constructed from a one skeleton graph.<br> + The filtration value of each edge is computed from a user-given distance function and is inserted until a + user-given threshold value.<br> + This complex can be built from a point cloud and a distance function, or from a distance matrix. </td> - </tr> -</table> - \subsection RipsComplexDataStructure Rips complex - \image html "rips_complex_representation.png" "Rips complex representation" -<table border="0"> - <tr> - <td width="25%"> + <td width="15%"> <b>Author:</b> Clément Maria, Pawel Dlotko, Vincent Rouvreau, Marc Glisse<br> <b>Introduced in:</b> GUDHI 2.0.0<br> <b>Copyright:</b> GPL v3<br> </td> - <td width="75%"> - Rips_complex is a simplicial complex constructed from a one skeleton graph.<br> - The filtration value of each edge is computed from a user-given distance function and is inserted until a - user-given threshold value.<br> - This complex can be built from a point cloud and a distance function, or from a distance matrix.<br> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref rips_complex - <b>Reference manual:</b> Gudhi::rips_complex::Rips_complex </td> </tr> </table> - \subsection SimplexTreeDataStructure Simplex tree - \image html "Simplex_tree_representation.png" "Simplex tree representation" -<table border="0"> + +#### Witness complex + +<table> <tr> - <td width="25%"> - <b>Author:</b> Clément Maria<br> - <b>Introduced in:</b> GUDHI 1.0.0<br> + <td width="35%" rowspan=2> + \image html "Witness_complex_representation.png" + </td> + <td width="50%"> + Witness complex \f$ Wit(W,L) \f$ is a simplicial complex defined on two sets of points in \f$\mathbb{R}^D\f$. + The data structure is described in \cite boissonnatmariasimplextreealgorithmica . + </td> + <td width="15%"> + <b>Author:</b> Siargey Kachanovich<br> + <b>Introduced in:</b> GUDHI 1.3.0<br> <b>Copyright:</b> GPL v3<br> + <b>Euclidean version requires:</b> \ref cgal ≥ 4.6.0 and \ref eigen3 </td> - <td width="75%"> - The simplex tree is an efficient and flexible - data structure for representing general (filtered) simplicial complexes. The data structure - is described in \cite boissonnatmariasimplextreealgorithmica .<br> - <b>User manual:</b> \ref simplex_tree - <b>Reference manual:</b> Gudhi::Simplex_tree + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref witness_complex - <b>Reference manual:</b> Gudhi::witness_complex::SimplicialComplexForWitness </td> </tr> </table> - \subsection CoverComplexDataStructure Cover Complexes - \image html "gicvisu.jpg" "Graph Induced Complex of a point cloud." -<table border="0"> + +### Cover Complexes +<table> <tr> - <td width="25%"> - <b>Author:</b> Mathieu Carrière<br> - <b>Introduced in:</b> GUDHI 2.1.0<br> - <b>Copyright:</b> GPL v3<br> - <b>Requires:</b> \ref cgal ≥ 4.8.1 + <td width="35%" rowspan=2> + \image html "gicvisu.jpg" </td> - <td width="75%"> + <td width="50%"> Nerves and Graph Induced Complexes are cover complexes, i.e. simplicial complexes that provably contain topological information about the input data. They can be computed with a cover of the data, that comes i.e. from the preimage of a family of intervals covering the image of a scalar-valued function defined on the data. <br> <b>User manual:</b> \ref cover_complex - <b>Reference manual:</b> Gudhi::cover_complex::Cover_complex </td> + <td width="15%"> + <b>Author:</b> Mathieu Carrière<br> + <b>Introduced in:</b> GUDHI 2.1.0<br> + <b>Copyright:</b> GPL v3<br> + <b>Requires:</b> \ref cgal ≥ 4.8.1 + </td> + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref cover_complex - <b>Reference manual:</b> Gudhi::cover_complex::Cover_complex + </td> </tr> </table> - \subsection SkeletonBlockerDataStructure Skeleton blocker - \image html "ds_representation.png" "Skeleton blocker representation" -<table border="0"> + +## Data structures and basic operations {#DataStructuresAndBasicOperations} + +### Data structures + +#### Simplex tree +<table> <tr> - <td width="25%"> - <b>Author:</b> David Salinas<br> - <b>Introduced in:</b> GUDHI 1.1.0<br> + <td width="35%" rowspan=2> + \image html "Simplex_tree_representation.png" + </td> + <td width="50%"> + The simplex tree is an efficient and flexible + data structure for representing general (filtered) simplicial complexes. The data structure + is described in \cite boissonnatmariasimplextreealgorithmica . + </td> + <td width="15%"> + <b>Author:</b> Clément Maria<br> + <b>Introduced in:</b> GUDHI 1.0.0<br> <b>Copyright:</b> GPL v3<br> </td> - <td width="75%"> + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref simplex_tree - <b>Reference manual:</b> Gudhi::Simplex_tree + </td> + </tr> +</table> + +#### Skeleton blocker + +<table> + <tr> + <td width="35%" rowspan=2> + \image html "ds_representation.png" + </td> + <td width="50%"> The Skeleton-Blocker data-structure proposes a light encoding for simplicial complexes by storing only an *implicit* representation of its simplices \cite socg_blockers_2011,\cite blockers2012. Intuitively, it just stores the 1-skeleton of a simplicial complex with a graph and the set of its "missing faces" that is very small in practice. This data-structure handles all simplicial complexes operations such as simplex enumeration or simplex removal but operations that are particularly efficient are operations that do not require simplex enumeration such as edge - iteration, link computation or simplex contraction.<br> - <b>User manual:</b> \ref skbl - <b>Reference manual:</b> Gudhi::skeleton_blocker::Skeleton_blocker_complex + iteration, link computation or simplex contraction. </td> - </tr> -</table> - \subsection TangentialComplexDataStructure Tangential complex - \image html "tc_examples.png" "Tangential complex representation" -<table border="0"> - <tr> - <td width="25%"> - <b>Author:</b> Clément Jamin<br> - <b>Introduced in:</b> GUDHI 2.0.0<br> + <td width="15%"> + <b>Author:</b> David Salinas<br> + <b>Introduced in:</b> GUDHI 1.1.0<br> <b>Copyright:</b> GPL v3<br> - <b>Requires:</b> \ref cgal ≥ 4.8.1 and \ref eigen3 </td> - <td width="75%"> - A Tangential Delaunay complex is a <a target="_blank" href="https://en.wikipedia.org/wiki/Simplicial_complex">simplicial complex</a> - designed to reconstruct a \f$ k \f$-dimensional manifold embedded in \f$ d \f$-dimensional Euclidean space. - The input is a point sample coming from an unknown manifold. - The running time depends only linearly on the extrinsic dimension \f$ d \f$ - and exponentially on the intrinsic dimension \f$ k \f$.<br> - <b>User manual:</b> \ref tangential_complex - <b>Reference manual:</b> Gudhi::tangential_complex::Tangential_complex + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref skbl - <b>Reference manual:</b> Gudhi::skeleton_blocker::Skeleton_blocker_complex </td> </tr> </table> - \subsection ToplexMapDataStructure Toplex Map - \image html "map.png" "Toplex map representation" -<table border="0"> + +#### Toplex Map + +<table> <tr> - <td width="25%"> - <b>Author:</b> François Godi<br> - <b>Introduced in:</b> GUDHI 2.1.0<br> - <b>Copyright:</b> GPL v3<br> + <td width="35%" rowspan=2> + \image html "map.png" </td> - <td width="75%"> + <td width="50%"> The Toplex map data structure is composed firstly of a raw storage of toplices (the maximal simplices) and secondly of a map which associate any vertex to a set of pointers toward all toplices containing this vertex. - <b>User manual:</b> \ref toplex_map - <b>Reference manual:</b> Gudhi::Toplex_map </td> - </tr> - - \subsection WitnessComplexDataStructure Witness complex - \image html "Witness_complex_representation.png" "Witness complex representation" -<table border="0"> - <tr> - <td width="25%"> - <b>Author:</b> Siargey Kachanovich<br> - <b>Introduced in:</b> GUDHI 1.3.0<br> - <b>Copyright:</b> GPL v3<br> - <b>Euclidean version requires:</b> \ref cgal ≥ 4.6.0 and \ref eigen3 - </td> - <td width="75%"> - Witness complex \f$ Wit(W,L) \f$ is a simplicial complex defined on two sets of points in \f$\mathbb{R}^D\f$. - The data structure is described in \cite boissonnatmariasimplextreealgorithmica .<br> - <b>User manual:</b> \ref witness_complex - <b>Reference manual:</b> Gudhi::witness_complex::SimplicialComplexForWitness - </td> - </tr> -</table> - - \section Toolbox Toolbox - - \subsection BottleneckDistanceToolbox Bottleneck distance - \image html "perturb_pd.png" "Bottleneck distance is the length of the longest edge" -<table border="0"> - <tr> - <td width="25%"> + <td width="15%"> <b>Author:</b> François Godi<br> - <b>Introduced in:</b> GUDHI 2.0.0<br> + <b>Introduced in:</b> GUDHI 2.1.0<br> <b>Copyright:</b> GPL v3<br> - <b>Requires:</b> \ref cgal ≥ 4.8.1 </td> - <td width="75%"> - Bottleneck distance measures the similarity between two persistence diagrams. - It's the shortest distance b for which there exists a perfect matching between - the points of the two diagrams (+ all the diagonal points) such that - any couple of matched points are at distance at most b. - <br> - <b>User manual:</b> \ref bottleneck_distance + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref toplex_map - <b>Reference manual:</b> Gudhi::Toplex_map </td> </tr> </table> - \subsection ContractionToolbox Contraction - \image html "sphere_contraction_representation.png" "Sphere contraction example" -<table border="0"> + +### Basic operations + +#### Contraction + +<table> <tr> - <td width="25%"> + <td width="35%" rowspan=2> + \image html "sphere_contraction_representation.png" + </td> + <td width="15%"> <b>Author:</b> David Salinas<br> <b>Introduced in:</b> GUDHI 1.1.0<br> <b>Copyright:</b> GPL v3<br> </td> - <td width="75%"> + <td width="50%"> The purpose of this package is to offer a user-friendly interface for edge contraction simplification of huge simplicial complexes. It uses the \ref skbl data-structure whose size remains small during simplification of most used geometrical complexes of topological data analysis such as the Rips or the Delaunay complexes. In practice, - the size of this data-structure is even much lower than the total number of simplices.<br> + the size of this data-structure is even much lower than the total number of simplices. + </td> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref contr </td> </tr> </table> - \subsection PersistentCohomologyToolbox Persistent Cohomology - \image html "3DTorus_poch.png" "Rips Persistent Cohomology on a 3D Torus" -<table border="0"> + +## Topological descriptors computation {#TopologicalDescriptorsComputation} + +### Persistent Cohomology + +<table> <tr> - <td width="25%"> - <b>Author:</b> Clément Maria<br> - <b>Introduced in:</b> GUDHI 1.0.0<br> - <b>Copyright:</b> GPL v3<br> + <td width="35%" rowspan=2> + \image html "3DTorus_poch.png" </td> - <td width="75%"> + <td width="50%"> The theory of homology consists in attaching to a topological space a sequence of (homology) groups, capturing global topological features like connected components, holes, cavities, etc. Persistent homology studies the evolution -- birth, life and death -- of these features when the topological space is changing. Consequently, the @@ -263,27 +291,101 @@ scheme. Computation of persistent cohomology using the algorithm of \cite DBLP:journals/dcg/SilvaMV11 and \cite DBLP:journals/corr/abs-1208-5018 and the Compressed Annotation Matrix implementation of - \cite DBLP:conf/esa/BoissonnatDM13 .<br> + \cite DBLP:conf/esa/BoissonnatDM13 . + </td> + <td width="15%"> + <b>Author:</b> Clément Maria<br> + <b>Introduced in:</b> GUDHI 1.0.0<br> + <b>Copyright:</b> GPL v3<br> + </td> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref persistent_cohomology - <b>Reference manual:</b> Gudhi::persistent_cohomology::Persistent_cohomology </td> </tr> -</table> - \subsection PersistenceRepresentationsToolbox Persistence representations - \image html "average_landscape.png" "Persistence representations" -<table border="0"> +</table> + +## Manifold reconstruction {#ManifoldReconstruction} + +### Tangential complex + +<table> + <tr> + <td width="35%" rowspan=2> + \image html "tc_examples.png" + </td> + <td width="50%"> + A Tangential Delaunay complex is a <a target="_blank" href="https://en.wikipedia.org/wiki/Simplicial_complex">simplicial complex</a> + designed to reconstruct a \f$ k \f$-dimensional manifold embedded in \f$ d \f$-dimensional Euclidean space. + The input is a point sample coming from an unknown manifold. + The running time depends only linearly on the extrinsic dimension \f$ d \f$ + and exponentially on the intrinsic dimension \f$ k \f$. + </td> + <td width="15%"> + <b>Author:</b> Clément Jamin<br> + <b>Introduced in:</b> GUDHI 2.0.0<br> + <b>Copyright:</b> GPL v3<br> + <b>Requires:</b> \ref cgal ≥ 4.8.1 and \ref eigen3 + </td> + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref tangential_complex - <b>Reference manual:</b> Gudhi::tangential_complex::Tangential_complex + </td> + </tr> +</table> + +## Topological descriptors tools {#TopologicalDescriptorsTools} + +### Bottleneck distance + +<table> + <tr> + <td width="35%" rowspan=2> + \image html "perturb_pd.png" + </td> + <td width="50%"> + Bottleneck distance measures the similarity between two persistence diagrams. + It's the shortest distance b for which there exists a perfect matching between + the points of the two diagrams (+ all the diagonal points) such that + any couple of matched points are at distance at most b. + </td> + <td width="15%"> + <b>Author:</b> François Godi<br> + <b>Introduced in:</b> GUDHI 2.0.0<br> + <b>Copyright:</b> GPL v3<br> + <b>Requires:</b> \ref cgal ≥ 4.8.1 + </td> + </tr> + <tr> + <td colspan=2 height="25"> + <b>User manual:</b> \ref bottleneck_distance + </td> + </tr> +</table> + +### Persistence representations + +<table> <tr> - <td width="25%"> + <td width="35%" rowspan=2> + \image html "average_landscape.png" + </td> + <td width="50%"> + It contains implementation of various representations of persistence diagrams; diagrams themselves, persistence + landscapes (rigorous and grid version), persistence heath maps, vectors and others. It implements basic + functionalities which are neccessary to use persistence in statistics and machine learning. + </td> + <td width="15%"> <b>Author:</b> Pawel Dlotko<br> <b>Introduced in:</b> GUDHI 2.1.0<br> <b>Copyright:</b> GPL v3<br> </td> - <td width="75%"> - It contains implementation of various representations of persistence diagrams; diagrams themselves, persistence - landscapes (rigorous and grid version), persistence heath maps, vectors and others. It implements basic - functionalities which are neccessary to use persistence in statistics and machine learning.<br> + </tr> + <tr> + <td colspan=2 height="25"> <b>User manual:</b> \ref Persistence_representations </td> </tr> </table> - -*/ diff --git a/src/common/example/vectordoubleoffreader_result.txt b/src/common/example/vectordoubleoffreader_result.txt index 1deb8dbd..b399425a 100644 --- a/src/common/example/vectordoubleoffreader_result.txt +++ b/src/common/example/vectordoubleoffreader_result.txt @@ -1,7 +1,7 @@ -Point[0] = 1 1 -Point[1] = 7 0 -Point[2] = 4 6 -Point[3] = 9 6 -Point[4] = 0 14 -Point[5] = 2 19 -Point[6] = 9 17 +Point[0] = 1 1 0 +Point[1] = 7 0 0 +Point[2] = 4 6 0 +Point[3] = 9 6 0 +Point[4] = 0 14 0 +Point[5] = 2 19 0 +Point[6] = 9 17 0 diff --git a/src/common/include/gudhi/Off_reader.h b/src/common/include/gudhi/Off_reader.h index 05a1e145..fc951fe7 100644 --- a/src/common/include/gudhi/Off_reader.h +++ b/src/common/include/gudhi/Off_reader.h @@ -37,8 +37,7 @@ namespace Gudhi { /** \brief OFF file reader top class visitor. * - * OFF file must be conform to format described here : - * http://www.geomview.org/docs/html/OFF.html + * OFF file must be conform to \ref FileFormatsOFF */ class Off_reader { public: diff --git a/src/common/test/test_points_off_reader.cpp b/src/common/test/test_points_off_reader.cpp index ba3bab71..e4b76ed7 100644 --- a/src/common/test/test_points_off_reader.cpp +++ b/src/common/test/test_points_off_reader.cpp @@ -44,19 +44,19 @@ BOOST_AUTO_TEST_CASE( points_doc_test ) BOOST_CHECK(point_cloud.size() == 7); std::vector<Point_d> expected_points; - std::vector<double> point = {1.0, 1.0}; + std::vector<double> point = {1.0, 1.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {7.0, 0.0}; + point = {7.0, 0.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {4.0, 6.0}; + point = {4.0, 6.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {9.0, 6.0}; + point = {9.0, 6.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {0.0, 14.0}; + point = {0.0, 14.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {2.0, 19.0}; + point = {2.0, 19.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); - point = {9.0, 17.0}; + point = {9.0, 17.0, 0.0}; expected_points.push_back(Point_d(point.begin(), point.end())); BOOST_CHECK(point_cloud == expected_points); diff --git a/src/cython/cython/simplex_tree.pyx b/src/cython/cython/simplex_tree.pyx index 0ab97f80..ea99c940 100644 --- a/src/cython/cython/simplex_tree.pyx +++ b/src/cython/cython/simplex_tree.pyx @@ -405,7 +405,8 @@ cdef class SimplexTree: """This function ensures that each simplex has a higher filtration value than its faces by increasing the filtration values. - :returns: The filtration modification information. + :returns: True if any filtration value was modified, + False if the filtration was already non-decreasing. :rtype: bool @@ -513,10 +514,9 @@ cdef class SimplexTree: return intervals_result def persistence_pairs(self): - """This function returns the persistence pairs of the simplicial - complex. + """This function returns a list of persistence birth and death simplices pairs. - :returns: The persistence intervals. + :returns: A list of persistence simplices intervals. :rtype: list of pair of list of int :note: persistence_pairs function requires diff --git a/src/cython/doc/alpha_complex_sum.inc b/src/cython/doc/alpha_complex_sum.inc index 1680a712..806988bb 100644 --- a/src/cython/doc/alpha_complex_sum.inc +++ b/src/cython/doc/alpha_complex_sum.inc @@ -1,22 +1,20 @@ -================================================================= =================================== =================================== -:Author: Vincent Rouvreau :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Requires: CGAL :math:`\geq` 4.7.0 Eigen3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| .. figure:: | Alpha_complex is a simplicial complex constructed from the finite | -| ../../doc/Alpha_complex/alpha_complex_representation.png | cells of a Delaunay Triangulation. | -| :alt: Alpha complex representation | | -| :figclass: align-center | The filtration value of each simplex is computed as the square of the | -| | circumradius of the simplex if the circumsphere is empty (the simplex | -| Alpha complex representation | is then said to be Gabriel), and as the minimum of the filtration | -| | values of the codimension 1 cofaces that make it not Gabriel | -| | otherwise. All simplices that have a filtration value strictly | -| | greater than a given alpha squared value are not inserted into the | -| | complex. | -| | | -| | This package requires having CGAL version 4.7 or higher (4.8.1 is | -| | advised for better performance). | -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| :doc:`alpha_complex_user` | :doc:`alpha_complex_ref` | -+----------------------------------------------------------------+------------------------------------------------------------------------+ + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------+ + | .. figure:: | Alpha complex is a simplicial complex constructed from the finite | :Author: Vincent Rouvreau | + | ../../doc/Alpha_complex/alpha_complex_representation.png | cells of a Delaunay Triangulation. | | + | :alt: Alpha complex representation | | :Introduced in: GUDHI 2.0.0 | + | :figclass: align-center | The filtration value of each simplex is computed as the square of the | | + | | circumradius of the simplex if the circumsphere is empty (the simplex | :Copyright: GPL v3 | + | | is then said to be Gabriel), and as the minimum of the filtration | | + | | values of the codimension 1 cofaces that make it not Gabriel | :Requires: Eigen3 and CGAL :math:`\geq` 4.7.0 | + | | otherwise. All simplices that have a filtration value strictly | | + | | greater than a given alpha squared value are not inserted into the | | + | | complex. | | + | | | | + | | This package requires having CGAL version 4.7 or higher (4.8.1 is | | + | | advised for better performance). | | + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------+ + | * :doc:`alpha_complex_user` | * :doc:`alpha_complex_ref` | + +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/bottleneck_distance_sum.inc b/src/cython/doc/bottleneck_distance_sum.inc index 030fad9e..41b9c5a3 100644 --- a/src/cython/doc/bottleneck_distance_sum.inc +++ b/src/cython/doc/bottleneck_distance_sum.inc @@ -1,15 +1,14 @@ -================================================================= =================================== =================================== -:Author: François Godi :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Requires: CGAL :math:`\geq` 4.8.0 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| .. figure:: | Bottleneck distance measures the similarity between two persistence | -| ../../doc/Bottleneck_distance/perturb_pd.png | diagrams. It's the shortest distance b for which there exists a | -| :figclass: align-center | perfect matching between the points of the two diagrams (+ all the | -| | diagonal points) such that any couple of matched points are at | -| Bottleneck distance is the length of | distance at most b. | -| the longest edge | | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| :doc:`bottleneck_distance_user` | | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ + +-----------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------------------------+ + | .. figure:: | Bottleneck distance measures the similarity between two persistence | :Author: François Godi | + | ../../doc/Bottleneck_distance/perturb_pd.png | diagrams. It's the shortest distance b for which there exists a | | + | :figclass: align-center | perfect matching between the points of the two diagrams (+ all the | :Introduced in: GUDHI 2.0.0 | + | | diagonal points) such that any couple of matched points are at | | + | Bottleneck distance is the length of | distance at most b. | :Copyright: GPL v3 | + | the longest edge | | | + | | | :Requires: CGAL :math:`\geq` 4.8.0 | + +-----------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------------------------+ + | * :doc:`bottleneck_distance_user` | | + +-----------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/conf.py b/src/cython/doc/conf.py index 4a54d4fd..ce08f679 100755 --- a/src/cython/doc/conf.py +++ b/src/cython/doc/conf.py @@ -125,7 +125,7 @@ html_theme_options = { "sidebarbgcolor": "#A1ADCD", "sidebartextcolor": "black", "sidebarlinkcolor": "#334D5C", - "body_max_width": "1200px", + "body_max_width": "100%", } # Add any paths that contain custom themes here, relative to this directory. diff --git a/src/cython/doc/cubical_complex_sum.inc b/src/cython/doc/cubical_complex_sum.inc index 280ad0e0..6dcf8e48 100644 --- a/src/cython/doc/cubical_complex_sum.inc +++ b/src/cython/doc/cubical_complex_sum.inc @@ -1,15 +1,14 @@ -================================================================= =================================== =================================== -:Author: Pawel Dlotko :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+--------------------------------------------------------------------------+----------------------------------------------------------------------+ -| .. figure:: | The cubical complex is an example of a structured complex useful in | -| ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image | -| :alt: Cubical complex representation | analysis. | -| :figclass: align-center | | -| | | -| Cubical complex representation | | -+--------------------------------------------------------------------------+----------------------------------------------------------------------+ -| :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | -| | * :doc:`periodic_cubical_complex_ref` | -+--------------------------------------------------------------------------+----------------------------------------------------------------------+ + +--------------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------+ + | .. figure:: | The cubical complex is an example of a structured complex useful in | :Author: Pawel Dlotko | + | ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | computational mathematics (specially rigorous numerics) and image | | + | :alt: Cubical complex representation | analysis. | :Introduced in: GUDHI 2.0.0 | + | :figclass: align-center | | | + | | | :Copyright: GPL v3 | + | | | | + +--------------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------+ + | * :doc:`cubical_complex_user` | * :doc:`cubical_complex_ref` | + | | * :doc:`periodic_cubical_complex_ref` | + +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/fileformats.rst b/src/cython/doc/fileformats.rst index e205cc8b..345dfdba 100644 --- a/src/cython/doc/fileformats.rst +++ b/src/cython/doc/fileformats.rst @@ -5,6 +5,35 @@ File formats ############ +OFF file format +*************** + +OFF files must be conform to format described here: +http://www.geomview.org/docs/html/OFF.html + +OFF files are mainly used as point cloud inputs. Here is an example of 7 points +in a 3-dimensional space. As edges and faces are not used for point set, there +is no need to specify them (just set their numbers to 0): + +.. literalinclude:: ../../data/points/alphacomplexdoc.off + +.. centered:: ../../points/alphacomplexdoc.off + +For dimensions bigger than 3, the dimension can be set like here:: + + # Dimension is no more 3 + nOFF + # dimension 4 - 7 vertices - 0 face - 0 edge + 4 7 0 0 + # Point set: + 1.0 1.0 0.0 0.0 + 7.0 0.0 0.0 0.0 + 4.0 6.0 0.0 0.0 + 9.0 6.0 0.0 0.0 + 0.0 14.0 0.0 0.0 + 2.0 19.0 0.0 0.0 + 9.0 17.0 0.0 0.0 + Persistence Diagram ******************* diff --git a/src/cython/doc/index.rst b/src/cython/doc/index.rst index 15cbe267..e379bc23 100644 --- a/src/cython/doc/index.rst +++ b/src/cython/doc/index.rst @@ -6,80 +6,73 @@ GUDHI Python module documentation :alt: Gudhi banner :figclass: align-center -Introduction -************ - -The Python interface for the Gudhi library (Geometry Understanding in Higher -Dimensions) is a generic open source -`Python module <http://gudhi.gforge.inria.fr/python/latest/>`_, for -Computational Topology and Topological Data Analysis -(`TDA <https://en.wikipedia.org/wiki/Topological_data_analysis>`_). -The GUDHI library intends to help the development of new algorithmic solutions -in TDA and their transfer to applications. It provides robust, efficient, -flexible and easy to use implementations of state-of-the-art algorithms and -data structures. - -The current release of the GUDHI library includes: +Complexes +********* -* Data structures to represent, construct and manipulate simplicial complexes. -* Simplification of simplicial complexes by edge contraction. -* Algorithms to compute persistent homology and bottleneck distance. +Cubical complexes +================= -We refer to :cite:`gudhilibrary_ICMS14` for a detailed description of the -design of the library. +.. include:: cubical_complex_sum.inc -Data structures -*************** +Simplicial complexes +==================== Alpha complex -============= +------------- .. include:: alpha_complex_sum.inc -Cover complexes -=============== +Rips complex +------------- + +.. include:: rips_complex_sum.inc -.. include:: nerve_gic_complex_sum.rst +Witness complex +--------------- -Cubical complex +.. include:: witness_complex_sum.inc + +Cover complexes =============== -.. include:: cubical_complex_sum.inc +.. include:: nerve_gic_complex_sum.inc -Rips complex -============ +Data structures and basic operations +************************************ -.. include:: rips_complex_sum.inc +Data structures +=============== Simplex tree -============ +------------ .. include:: simplex_tree_sum.inc +Topological descriptors computation +*********************************** + +Persistence cohomology +====================== + +.. include:: persistent_cohomology_sum.inc + +Manifold reconstruction +*********************** + Tangential complex ================== .. include:: tangential_complex_sum.inc -Witness complex -=============== - -.. include:: witness_complex_sum.inc - -Toolbox -******* +Topological descriptors tools +***************************** Bottleneck distance =================== .. include:: bottleneck_distance_sum.inc -Persistence cohomology -====================== - -.. include:: persistent_cohomology_sum.inc - Persistence graphical tools =========================== diff --git a/src/cython/doc/nerve_gic_complex_sum.inc b/src/cython/doc/nerve_gic_complex_sum.inc new file mode 100644 index 00000000..0e606fe1 --- /dev/null +++ b/src/cython/doc/nerve_gic_complex_sum.inc @@ -0,0 +1,16 @@ +.. table:: + :widths: 30 50 20 + + +----------------------------------------------------------------+------------------------------------------------------------------------+------------------------------------+ + | .. figure:: | Nerves and Graph Induced Complexes are cover complexes, i.e. | :Author: Mathieu Carrière | + | ../../doc/Nerve_GIC/gicvisu.jpg | simplicial complexes that provably contain topological information | | + | :alt: Graph Induced Complex of a point cloud. | about the input data. They can be computed with a cover of the data, | :Introduced in: GUDHI 2.3.0 | + | :figclass: align-center | that comes i.e. from the preimage of a family of intervals covering | | + | | the image of a scalar-valued function defined on the data. | :Copyright: GPL v3 | + | | | | + | | | :Requires: CGAL :math:`\geq` 4.8.1 | + | | | | + | | | | + +----------------------------------------------------------------+------------------------------------------------------------------------+------------------------------------+ + | * :doc:`nerve_gic_complex_user` | * :doc:`nerve_gic_complex_ref` | + +----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/nerve_gic_complex_sum.rst b/src/cython/doc/nerve_gic_complex_sum.rst deleted file mode 100644 index 523c119f..00000000 --- a/src/cython/doc/nerve_gic_complex_sum.rst +++ /dev/null @@ -1,15 +0,0 @@ -================================================================= =================================== =================================== -:Author: Mathieu Carrière :Introduced in: GUDHI 2.3.0 :Copyright: GPL v3 -:Requires: CGAL :math:`\geq` 4.8.1 -================================================================= =================================== =================================== - -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| .. figure:: | Nerves and Graph Induced Complexes are cover complexes, i.e. | -| ../../doc/Nerve_GIC/gicvisu.jpg | simplicial complexes that provably contain topological information | -| :alt: Graph Induced Complex of a point cloud. | about the input data. They can be computed with a cover of the data, | -| :figclass: align-center | that comes i.e. from the preimage of a family of intervals covering | -| | the image of a scalar-valued function defined on the data. | -| Graph Induced Complex of a point cloud. | | -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| :doc:`nerve_gic_complex_user` | :doc:`nerve_gic_complex_ref` | -+----------------------------------------------------------------+------------------------------------------------------------------------+ diff --git a/src/cython/doc/nerve_gic_complex_user.rst b/src/cython/doc/nerve_gic_complex_user.rst index 44f30e1a..9101f45d 100644 --- a/src/cython/doc/nerve_gic_complex_user.rst +++ b/src/cython/doc/nerve_gic_complex_user.rst @@ -7,14 +7,13 @@ Cover complexes user manual Definition ---------- -.. include:: nerve_gic_complex_sum.rst +.. include:: nerve_gic_complex_sum.inc Visualizations of the simplicial complexes can be done with either neato (from `graphviz <http://www.graphviz.org/>`_), `geomview <http://www.geomview.org/>`_, `KeplerMapper <https://github.com/MLWave/kepler-mapper>`_. -Input point clouds are assumed to be -`OFF files <http://www.geomview.org/docs/html/OFF.html>`_. +Input point clouds are assumed to be OFF files (cf. :doc:`fileformats`). Covers ------ diff --git a/src/cython/doc/persistence_graphical_tools_sum.inc b/src/cython/doc/persistence_graphical_tools_sum.inc index 5577cf99..b412de56 100644 --- a/src/cython/doc/persistence_graphical_tools_sum.inc +++ b/src/cython/doc/persistence_graphical_tools_sum.inc @@ -1,12 +1,14 @@ -================================================================= =================================== =================================== -:Author: Vincent Rouvreau :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Requires: matplotlib numpy scipy -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ -| .. figure:: | These graphical tools comes on top of persistence results and allows | -| img/graphical_tools_representation.png | the user to build easily persistence barcode, diagram or density. | -| | | -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ -| :doc:`persistence_graphical_tools_user` | :doc:`persistence_graphical_tools_ref` | -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ + +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+ + | .. figure:: | These graphical tools comes on top of persistence results and allows | :Author: Vincent Rouvreau | + | img/graphical_tools_representation.png | the user to build easily persistence barcode, diagram or density. | | + | | | :Introduced in: GUDHI 2.0.0 | + | | | | + | | | :Copyright: GPL v3 | + | | | | + | | | :Requires: matplotlib, numpy and scipy | + +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+ + | * :doc:`persistence_graphical_tools_user` | * :doc:`persistence_graphical_tools_ref` | + +-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/persistent_cohomology_sum.inc b/src/cython/doc/persistent_cohomology_sum.inc index a26df1dc..20ca073c 100644 --- a/src/cython/doc/persistent_cohomology_sum.inc +++ b/src/cython/doc/persistent_cohomology_sum.inc @@ -1,27 +1,26 @@ -================================================================= =================================== =================================== -:Author: Clément Maria :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ -| .. figure:: | The theory of homology consists in attaching to a topological space | -| ../../doc/Persistent_cohomology/3DTorus_poch.png | a sequence of (homology) groups, capturing global topological | -| :figclass: align-center | features like connected components, holes, cavities, etc. Persistent | -| | homology studies the evolution -- birth, life and death -- of these | -| Rips Persistent Cohomology on a 3D | features when the topological space is changing. Consequently, the | -| Torus | theory is essentially composed of three elements: topological spaces, | -| | their homology groups and an evolution scheme. | -| | | -| | Computation of persistent cohomology using the algorithm of | -| | :cite:`DBLP:journals/dcg/SilvaMV11` and | -| | :cite:`DBLP:journals/corr/abs-1208-5018` and the Compressed | -| | Annotation Matrix implementation of | -| | :cite:`DBLP:conf/esa/BoissonnatDM13`. | -| | | -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ -| :doc:`persistent_cohomology_user` | Please refer to each data structure that contains persistence | -| | feature for reference: | -| | | -| | * :doc:`simplex_tree_ref` | -| | * :doc:`cubical_complex_ref` | -| | * :doc:`periodic_cubical_complex_ref` | -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ + +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+ + | .. figure:: | The theory of homology consists in attaching to a topological space | :Author: Clément Maria | + | ../../doc/Persistent_cohomology/3DTorus_poch.png | a sequence of (homology) groups, capturing global topological | | + | :figclass: align-center | features like connected components, holes, cavities, etc. Persistent | :Introduced in: GUDHI 2.0.0 | + | | homology studies the evolution -- birth, life and death -- of these | | + | Rips Persistent Cohomology on a 3D | features when the topological space is changing. Consequently, the | :Copyright: GPL v3 | + | Torus | theory is essentially composed of three elements: topological spaces, | | + | | their homology groups and an evolution scheme. | | + | | | | + | | Computation of persistent cohomology using the algorithm of | | + | | :cite:`DBLP:journals/dcg/SilvaMV11` and | | + | | :cite:`DBLP:journals/corr/abs-1208-5018` and the Compressed | | + | | Annotation Matrix implementation of | | + | | :cite:`DBLP:conf/esa/BoissonnatDM13`. | | + | | | | + +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+ + | * :doc:`persistent_cohomology_user` | Please refer to each data structure that contains persistence | + | | feature for reference: | + | | | + | | * :doc:`simplex_tree_ref` | + | | * :doc:`cubical_complex_ref` | + | | * :doc:`periodic_cubical_complex_ref` | + +-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/rips_complex_sum.inc b/src/cython/doc/rips_complex_sum.inc index ea26769a..e8e505e2 100644 --- a/src/cython/doc/rips_complex_sum.inc +++ b/src/cython/doc/rips_complex_sum.inc @@ -1,17 +1,16 @@ -===================================================================== =========================== =================================== -:Author: Clément Maria, Pawel Dlotko, Vincent Rouvreau, Marc Glisse :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -===================================================================== =========================== =================================== +.. table:: + :widths: 30 50 20 -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| .. figure:: | Rips complex is a simplicial complex constructed from a one skeleton | -| ../../doc/Rips_complex/rips_complex_representation.png | graph. | -| :figclass: align-center | | -| | The filtration value of each edge is computed from a user-given | -| Rips complex representation | distance function and is inserted until a user-given threshold | -| | value. | -| | | -| | This complex can be built from a point cloud and a distance function, | -| | or from a distance matrix. | -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| :doc:`rips_complex_user` | :doc:`rips_complex_ref` | -+----------------------------------------------------------------+------------------------------------------------------------------------+ + +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------+ + | .. figure:: | Rips complex is a simplicial complex constructed from a one skeleton | :Authors: Clément Maria, Pawel Dlotko, Vincent Rouvreau, Marc Glisse | + | ../../doc/Rips_complex/rips_complex_representation.png | graph. | | + | :figclass: align-center | | :Introduced in: GUDHI 2.0.0 | + | | The filtration value of each edge is computed from a user-given | | + | | distance function and is inserted until a user-given threshold | :Copyright: GPL v3 | + | | value. | | + | | | | + | | This complex can be built from a point cloud and a distance function, | | + | | or from a distance matrix. | | + +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------+ + | * :doc:`rips_complex_user` | * :doc:`rips_complex_ref` | + +----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/simplex_tree_sum.inc b/src/cython/doc/simplex_tree_sum.inc index fb0e54c1..086c69d5 100644 --- a/src/cython/doc/simplex_tree_sum.inc +++ b/src/cython/doc/simplex_tree_sum.inc @@ -1,14 +1,13 @@ -================================================================= =================================== =================================== -:Author: Clément Maria :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| .. figure:: | The simplex tree is an efficient and flexible data structure for | -| ../../doc/Simplex_tree/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | -| :alt: Simplex tree representation | | -| :figclass: align-center | The data structure is described in | -| | :cite:`boissonnatmariasimplextreealgorithmica` | -| Simplex tree representation | | -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| :doc:`simplex_tree_user` | :doc:`simplex_tree_ref` | -+----------------------------------------------------------------+------------------------------------------------------------------------+ + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------+ + | .. figure:: | The simplex tree is an efficient and flexible data structure for | :Author: Clément Maria | + | ../../doc/Simplex_tree/Simplex_tree_representation.png | representing general (filtered) simplicial complexes. | | + | :alt: Simplex tree representation | | :Introduced in: GUDHI 2.0.0 | + | :figclass: align-center | The data structure is described in | | + | | :cite:`boissonnatmariasimplextreealgorithmica` | :Copyright: GPL v3 | + | | | | + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------+ + | * :doc:`simplex_tree_user` | * :doc:`simplex_tree_ref` | + +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/tangential_complex_sum.inc b/src/cython/doc/tangential_complex_sum.inc index 72b4d7ba..0f03ffb3 100644 --- a/src/cython/doc/tangential_complex_sum.inc +++ b/src/cython/doc/tangential_complex_sum.inc @@ -1,15 +1,14 @@ -================================================================= =================================== =================================== -:Author: Clément Jamin :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Requires: CGAL :math:`\geq` 4.8.0 Eigen3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| .. figure:: | A Tangential Delaunay complex is a simplicial complex designed to | -| ../../doc/Tangential_complex/tc_examples.png | reconstruct a :math:`k`-dimensional manifold embedded in :math:`d`- | -| :figclass: align-center | dimensional Euclidean space. The input is a point sample coming from | -| | an unknown manifold. The running time depends only linearly on the | -| Tangential complex representation | extrinsic dimension :math:`d` and exponentially on the intrinsic | -| | dimension :math:`k`. | -+----------------------------------------------------------------+------------------------------------------------------------------------+ -| :doc:`tangential_complex_user` | :doc:`tangential_complex_ref` | -+----------------------------------------------------------------+------------------------------------------------------------------------+ + +----------------------------------------------------------------+------------------------------------------------------------------------+------------------------------------+ + | .. figure:: | A Tangential Delaunay complex is a simplicial complex designed to | :Author: Clément Jamin | + | ../../doc/Tangential_complex/tc_examples.png | reconstruct a :math:`k`-dimensional manifold embedded in :math:`d`- | | + | :figclass: align-center | dimensional Euclidean space. The input is a point sample coming from | :Introduced in: GUDHI 2.0.0 | + | | an unknown manifold. The running time depends only linearly on the | | + | | extrinsic dimension :math:`d` and exponentially on the intrinsic | :Copyright: GPL v3 | + | | dimension :math:`k`. | | + | | | :Requires: CGAL :math:`\geq` 4.8.0 | + +----------------------------------------------------------------+------------------------------------------------------------------------+------------------------------------+ + | * :doc:`tangential_complex_user` | * :doc:`tangential_complex_ref` | + +----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/doc/witness_complex_sum.inc b/src/cython/doc/witness_complex_sum.inc index a8a126a0..49577745 100644 --- a/src/cython/doc/witness_complex_sum.inc +++ b/src/cython/doc/witness_complex_sum.inc @@ -1,19 +1,17 @@ -================================================================= =================================== =================================== -:Author: Siargey Kachanovich :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Euclidean version requires: CGAL :math:`\geq` 4.6.0 Eigen3 -================================================================= =================================== =================================== +.. table:: + :widths: 30 50 20 -+-------------------------------------------------------------------+----------------------------------------------------------------------+ -| .. figure:: | Witness complex :math:`Wit(W,L)` is a simplicial complex defined on | -| ../../doc/Witness_complex/Witness_complex_representation.png | two sets of points in :math:`\mathbb{R}^D`. | -| :alt: Witness complex representation | | -| :figclass: align-center | The data structure is described in | -| | :cite:`boissonnatmariasimplextreealgorithmica`. | -| | | -| Witness complex representation | | -+-------------------------------------------------------------------+----------------------------------------------------------------------+ -| :doc:`witness_complex_user` | * :doc:`witness_complex_ref` | -| | * :doc:`strong_witness_complex_ref` | -| | * :doc:`euclidean_witness_complex_ref` | -| | * :doc:`euclidean_strong_witness_complex_ref` | -+-------------------------------------------------------------------+----------------------------------------------------------------------+ + +-------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------------------------------------------------------+ + | .. figure:: | Witness complex :math:`Wit(W,L)` is a simplicial complex defined on | :Author: Siargey Kachanovich | + | ../../doc/Witness_complex/Witness_complex_representation.png | two sets of points in :math:`\mathbb{R}^D`. | | + | :alt: Witness complex representation | | :Introduced in: GUDHI 2.0.0 | + | :figclass: align-center | The data structure is described in | | + | | :cite:`boissonnatmariasimplextreealgorithmica`. | :Copyright: GPL v3 | + | | | | + | | | :Requires: Eigen3 and CGAL :math:`\geq` 4.6.0 for Euclidean versions only | + +-------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------------------------------------------------------+ + | * :doc:`witness_complex_user` | * :doc:`witness_complex_ref` | + | | * :doc:`strong_witness_complex_ref` | + | | * :doc:`euclidean_witness_complex_ref` | + | | * :doc:`euclidean_strong_witness_complex_ref` | + +-------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/cython/include/Simplex_tree_interface.h b/src/cython/include/Simplex_tree_interface.h index 3481eeff..ca98517d 100644 --- a/src/cython/include/Simplex_tree_interface.h +++ b/src/cython/include/Simplex_tree_interface.h @@ -45,7 +45,7 @@ class Simplex_tree_interface : public Simplex_tree<SimplexTreeOptions> { using Simplex_handle = typename Base::Simplex_handle; using Insertion_result = typename std::pair<Simplex_handle, bool>; using Simplex = std::vector<Vertex_handle>; - using Complex = std::vector<std::pair<Simplex, Filtration_value>>; + using Filtered_simplices = std::vector<std::pair<Simplex, Filtration_value>>; public: bool find_simplex(const Simplex& vh) { @@ -94,9 +94,9 @@ class Simplex_tree_interface : public Simplex_tree<SimplexTreeOptions> { Base::initialize_filtration(); } - Complex get_filtration() { + Filtered_simplices get_filtration() { Base::initialize_filtration(); - Complex filtrations; + Filtered_simplices filtrations; for (auto f_simplex : Base::filtration_simplex_range()) { Simplex simplex; for (auto vertex : Base::simplex_vertex_range(f_simplex)) { @@ -107,8 +107,8 @@ class Simplex_tree_interface : public Simplex_tree<SimplexTreeOptions> { return filtrations; } - Complex get_skeleton(int dimension) { - Complex skeletons; + Filtered_simplices get_skeleton(int dimension) { + Filtered_simplices skeletons; for (auto f_simplex : Base::skeleton_simplex_range(dimension)) { Simplex simplex; for (auto vertex : Base::simplex_vertex_range(f_simplex)) { @@ -119,29 +119,25 @@ class Simplex_tree_interface : public Simplex_tree<SimplexTreeOptions> { return skeletons; } - Complex get_star(const Simplex& simplex) { - Complex star; + Filtered_simplices get_star(const Simplex& simplex) { + Filtered_simplices star; for (auto f_simplex : Base::star_simplex_range(Base::find(simplex))) { Simplex simplex_star; for (auto vertex : Base::simplex_vertex_range(f_simplex)) { - std::cout << vertex << " "; simplex_star.insert(simplex_star.begin(), vertex); } - std::cout << std::endl; star.push_back(std::make_pair(simplex_star, Base::filtration(f_simplex))); } return star; } - Complex get_cofaces(const Simplex& simplex, int dimension) { - Complex cofaces; + Filtered_simplices get_cofaces(const Simplex& simplex, int dimension) { + Filtered_simplices cofaces; for (auto f_simplex : Base::cofaces_simplex_range(Base::find(simplex), dimension)) { Simplex simplex_coface; for (auto vertex : Base::simplex_vertex_range(f_simplex)) { - std::cout << vertex << " "; simplex_coface.insert(simplex_coface.begin(), vertex); } - std::cout << std::endl; cofaces.push_back(std::make_pair(simplex_coface, Base::filtration(f_simplex))); } return cofaces; |