diff options
| author | Gard Spreemann <gspreemann@gmail.com> | 2018-02-02 14:03:28 +0100 |
|---|---|---|
| committer | Gard Spreemann <gspreemann@gmail.com> | 2018-02-02 14:03:28 +0100 |
| commit | 8e51c74d8855a641c006765ee246402e218828f3 (patch) | |
| tree | fcd070128c18c0b8cb16c841911c2fba3e209e96 /doc | |
| parent | 0b7c2ce340ece752c4d1b799a94419ca248eb71f (diff) | |
| parent | 9899ae167f281d10b1684dfcd02c6838c5bf28df (diff) | |
Merge branch 'upstream/latest' into dfsg/latest
Diffstat (limited to 'doc')
29 files changed, 1000 insertions, 366 deletions
diff --git a/doc/Alpha_complex/Intro_alpha_complex.h b/doc/Alpha_complex/Intro_alpha_complex.h index cf1a946a..a08663ca 100644 --- a/doc/Alpha_complex/Intro_alpha_complex.h +++ b/doc/Alpha_complex/Intro_alpha_complex.h @@ -31,7 +31,7 @@ namespace alpha_complex { /** \defgroup alpha_complex Alpha complex * * \author Vincent Rouvreau - * + * * @{ * * \section definition Definition @@ -195,8 +195,6 @@ namespace alpha_complex { * * \include Alpha_complex/alphaoffreader_for_doc_32.txt * - * \copyright GNU General Public License v3. - * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim */ /** @} */ // end defgroup alpha_complex diff --git a/doc/Bitmap_cubical_complex/Gudhi_Cubical_Complex_doc.h b/doc/Bitmap_cubical_complex/Gudhi_Cubical_Complex_doc.h index 5963caa3..a5d7b60f 100644 --- a/doc/Bitmap_cubical_complex/Gudhi_Cubical_Complex_doc.h +++ b/doc/Bitmap_cubical_complex/Gudhi_Cubical_Complex_doc.h @@ -63,7 +63,7 @@ namespace cubical_complex { * For further details and theory of cubical complexes, please consult \cite kaczynski2004computational as well as the * following paper \cite peikert2012topological . * - * \section cubicalcomplexdatastructure Data structure. + * \section cubicalcomplexdatastructure Data structure * * The implementation of Cubical complex provides a representation of complexes that occupy a rectangular region in * \f$\mathbb{R}^n\f$. This extra assumption allows for a memory efficient way of storing cubical complexes in a form @@ -85,37 +85,14 @@ namespace cubical_complex { * present in the product that gives the cube \f$C\f$. In a similar way, we can compute boundary and the coboundary of * each cube. Further details can be found in the literature. * - * \section inputformat Input Format. + * \section inputformat Input Format * * In the current implantation, filtration is given at the maximal cubes, and it is then extended by the lower star * filtration to all cubes. There are a number of constructors that can be used to construct cubical complex by users * who want to use the code directly. They can be found in the \a Bitmap_cubical_complex class. * Currently one input from a text file is used. It uses a format used already in Perseus software - * (http://www.sas.upenn.edu/~vnanda/perseus/) by Vidit Nanda. - * Below we are providing a description of the format. The first line contains a number d begin the dimension of the - * bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3 - * in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8 - * 20 4 7 6 5 in the example below). - * - * - * \image html "exampleBitmap.png" "Example of a input data." - * - * The input file for the following complex is: - * \verbatim -2 -3 -3 -1 -4 -6 -8 -20 -4 -7 -6 -5 -\endverbatim - + * (http://www.sas.upenn.edu/~vnanda/perseus/) by Vidit Nanda. The file format is described here: \ref FileFormatsPerseus. + * * \section PeriodicBoundaryConditions Periodic boundary conditions * Often one would like to impose periodic boundary conditions to the cubical complex. Let \f$ I_1\times ... \times * I_n \f$ be a box that is decomposed with a cubical complex \f$ \mathcal{K} \f$. Imposing periodic boundary @@ -123,30 +100,11 @@ namespace cubical_complex { * considered the same. In particular, if for a bitmap \f$ \mathcal{K} \f$ periodic boundary conditions are imposed * in all directions, then complex \f$ \mathcal{K} \f$ became n-dimensional torus. One can use various constructors * from the file Bitmap_cubical_complex_periodic_boundary_conditions_base.h to construct cubical complex with periodic - * boundary conditions. One can also use Perseus style input files. To indicate periodic boundary conditions in a - * given direction, then number of top dimensional cells in this direction have to be multiplied by -1. For instance: - - *\verbatim -2 --3 -3 -1 -4 -6 -8 -20 -4 -7 -6 -5 -\endverbatim - - * Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y. - + * boundary conditions. One can also use Perseus style input files (see \ref FileFormatsPerseus). + * * \section BitmapExamples Examples - * End user programs are available in example/Bitmap_cubical_complex folder. + * End user programs are available in example/Bitmap_cubical_complex and utilities/Bitmap_cubical_complex folders. * - * \copyright GNU General Public License v3. */ /** @} */ // end defgroup cubical_complex diff --git a/doc/Nerve_GIC/COPYRIGHT b/doc/Nerve_GIC/COPYRIGHT new file mode 100644 index 00000000..0c36a526 --- /dev/null +++ b/doc/Nerve_GIC/COPYRIGHT @@ -0,0 +1,19 @@ +The files of this directory are part of the Gudhi Library. The Gudhi library +(Geometric Understanding in Higher Dimensions) is a generic C++ library for +computational topology. + +Author(s): Mathieu Carrière + +Copyright (C) 2017 INRIA + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <http://www.gnu.org/licenses/>. diff --git a/doc/Nerve_GIC/GIC.jpg b/doc/Nerve_GIC/GIC.jpg Binary files differnew file mode 100644 index 00000000..cb1b9b7f --- /dev/null +++ b/doc/Nerve_GIC/GIC.jpg diff --git a/doc/Nerve_GIC/GIC.pdf b/doc/Nerve_GIC/GIC.pdf Binary files differnew file mode 100644 index 00000000..30525745 --- /dev/null +++ b/doc/Nerve_GIC/GIC.pdf diff --git a/doc/Nerve_GIC/Intro_graph_induced_complex.h b/doc/Nerve_GIC/Intro_graph_induced_complex.h new file mode 100644 index 00000000..2b648425 --- /dev/null +++ b/doc/Nerve_GIC/Intro_graph_induced_complex.h @@ -0,0 +1,186 @@ +/* This file is part of the Gudhi Library. The Gudhi library + * (Geometric Understanding in Higher Dimensions) is a generic C++ + * library for computational topology. + * + * Author(s): Mathieu Carriere + * + * Copyright (C) 2017 INRIA + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +#ifndef DOC_COVER_COMPLEX_INTRO_COVER_COMPLEX_H_ +#define DOC_COVER_COMPLEX_INTRO_COVER_COMPLEX_H_ + +namespace Gudhi { + +namespace cover_complex { + +/** \defgroup cover_complex Cover complex + * + * \author Mathieu Carrière + * + * @{ + * + * Visualizations of the simplicial complexes can be done with either + * 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>. + * + * \section covers Covers + * + * Nerves and Graph Induced Complexes require a cover C of the input point cloud P, + * that is a set of subsets of P whose union is P itself. + * Very often, this cover is obtained from the preimage of a family of intervals covering + * the image of some scalar-valued function f defined on P. This family is parameterized + * by its resolution, which can be either the number or the length of the intervals, + * and its gain, which is the overlap percentage between consecutive intervals (ordered by their first values). + * + * \section nerves Nerves + * + * \subsection nervedefinition Nerve definition + * + * Assume you are given a cover C of your point cloud P. Then, the Nerve of this cover + * is the simplicial complex that has one k-simplex per k-fold intersection of cover elements. + * See also <a target="_blank" href="https://en.wikipedia.org/wiki/Nerve_of_a_covering"> Wikipedia </a>. + * + * \image html "nerve.png" "Nerve of a double torus" + * + * \subsection nerveexample Example + * + * This example builds the Nerve of a point cloud sampled on a 3D human shape (human.off). + * The cover C comes from the preimages of intervals (10 intervals with gain 0.3) + * covering the height function (coordinate 2), + * which are then refined into their connected components using the triangulation of the .OFF file. + * + * \include Nerve_GIC/Nerve.cpp + * + * When launching: + * + * \code $> ./Nerve ../../data/points/human.off 2 10 0.3 -v + * \endcode + * + * the program output is: + * + * \include Nerve_GIC/Nerve.txt + * + * The program also writes a file ../../data/points/human_sc.txt. The first three lines in this file are the location + * of the input point cloud and the function used to compute the cover. + * The fourth line contains the number of vertices nv and edges ne of the Nerve. + * The next nv lines represent the vertices. Each line contains the vertex ID, + * the number of data points it contains, and their average color function value. + * Finally, the next ne lines represent the edges, characterized by the ID of their vertices. + * + * Using KeplerMapper, one can obtain the following visualization: + * + * \image html "nervevisu.jpg" "Visualization with KeplerMapper" + * + * \section gic Graph Induced Complexes (GIC) + * + * \subsection gicdefinition GIC definition + * + * Again, assume you are given a cover C of your point cloud P. Moreover, assume + * you are also given a graph G built on top of P. Then, for any clique in G + * whose nodes all belong to different elements of C, the GIC includes a corresponding + * simplex, whose dimension is the number of nodes in the clique minus one. + * See \cite Dey13 for more details. + * + * \image html "GIC.jpg" "GIC of a point cloud." + * + * \subsection gicexamplevor Example with cover from Voronoï + * + * This example builds the GIC of a point cloud sampled on a 3D human shape (human.off). + * We randomly subsampled 100 points in the point cloud, which act as seeds of + * a geodesic Voronoï diagram. Each cell of the diagram is then an element of C. + * The graph G (used to compute both the geodesics for Voronoï and the GIC) + * comes from the triangulation of the human shape. Note that the resulting simplicial complex is in dimension 3 + * in this example. + * + * \include Nerve_GIC/VoronoiGIC.cpp + * + * When launching: + * + * \code $> ./VoronoiGIC ../../data/points/human.off 700 -v + * \endcode + * + * the program outputs SC.off. Using e.g. + * + * \code $> geomview ../../data/points/human_sc.off + * \endcode + * + * one can obtain the following visualization: + * + * \image html "gicvoronoivisu.jpg" "Visualization with Geomview" + * + * \subsection functionalGICdefinition Functional GIC + * + * If one restricts to the cliques in G whose nodes all belong to preimages of consecutive + * intervals (assuming the cover of the height function is minimal, i.e. no more than + * two intervals can intersect at a time), the GIC is of dimension one, i.e. a graph. + * We call this graph the functional GIC. See \cite Carriere16 for more details. + * + * \subsection functionalGICexample Example + * + * Functional GIC comes with automatic selection of the Rips threshold, + * the resolution and the gain of the function cover. See \cite Carriere17c for more details. In this example, + * we compute the functional GIC of a Klein bottle embedded in R^5, + * where the graph G comes from a Rips complex with automatic threshold, + * and the cover C comes from the preimages of intervals covering the first coordinate, + * with automatic resolution and gain. Note that automatic threshold, resolution and gain + * can be computed as well for the Nerve. + * + * \include Nerve_GIC/CoordGIC.cpp + * + * When launching: + * + * \code $> ./CoordGIC ../../data/points/KleinBottle5D.off 0 -v + * \endcode + * + * the program outputs SC.dot. Using e.g. + * + * \code $> neato SC.dot -Tpdf -o SC.pdf + * \endcode + * + * one can obtain the following visualization: + * + * \image html "coordGICvisu2.jpg" "Visualization with Neato" + * + * where nodes are colored by the filter function values and, for each node, the first number is its ID + * and the second is the number of data points that its contain. + * + * We also provide an example on a set of 72 pictures taken around the same object (lucky_cat.off). + * The function is now the first eigenfunction given by PCA, whose values + * are written in a file (lucky_cat_PCA1). Threshold, resolution and gain are automatically selected as before. + * + * \include Nerve_GIC/FuncGIC.cpp + * + * When launching: + * + * \code $> ./FuncGIC ../../data/points/COIL_database/lucky_cat.off ../../data/points/COIL_database/lucky_cat_PCA1 -v + * \endcode + * + * the program outputs again SC.dot which gives the following visualization after using neato: + * + * \image html "funcGICvisu.jpg" "Visualization with neato" + * + */ +/** @} */ // end defgroup cover_complex + +} // namespace cover_complex + +} // namespace Gudhi + +#endif // DOC_COVER_COMPLEX_INTRO_COVER_COMPLEX_H_ diff --git a/doc/Nerve_GIC/coordGICvisu.pdf b/doc/Nerve_GIC/coordGICvisu.pdf Binary files differnew file mode 100644 index 00000000..313aa1b5 --- /dev/null +++ b/doc/Nerve_GIC/coordGICvisu.pdf diff --git a/doc/Nerve_GIC/coordGICvisu2.jpg b/doc/Nerve_GIC/coordGICvisu2.jpg Binary files differnew file mode 100644 index 00000000..046feb2a --- /dev/null +++ b/doc/Nerve_GIC/coordGICvisu2.jpg diff --git a/doc/Nerve_GIC/funcGICvisu.jpg b/doc/Nerve_GIC/funcGICvisu.jpg Binary files differnew file mode 100644 index 00000000..36b64dde --- /dev/null +++ b/doc/Nerve_GIC/funcGICvisu.jpg diff --git a/doc/Nerve_GIC/funcGICvisu.pdf b/doc/Nerve_GIC/funcGICvisu.pdf Binary files differnew file mode 100644 index 00000000..d7456cd3 --- /dev/null +++ b/doc/Nerve_GIC/funcGICvisu.pdf diff --git a/doc/Nerve_GIC/gicvisu.jpg b/doc/Nerve_GIC/gicvisu.jpg Binary files differnew file mode 100644 index 00000000..576dae47 --- /dev/null +++ b/doc/Nerve_GIC/gicvisu.jpg diff --git a/doc/Nerve_GIC/gicvoronoivisu.jpg b/doc/Nerve_GIC/gicvoronoivisu.jpg Binary files differnew file mode 100644 index 00000000..cd86c411 --- /dev/null +++ b/doc/Nerve_GIC/gicvoronoivisu.jpg diff --git a/doc/Nerve_GIC/nerve.png b/doc/Nerve_GIC/nerve.png Binary files differnew file mode 100644 index 00000000..b66da4a4 --- /dev/null +++ b/doc/Nerve_GIC/nerve.png diff --git a/doc/Nerve_GIC/nervevisu.jpg b/doc/Nerve_GIC/nervevisu.jpg Binary files differnew file mode 100644 index 00000000..67ae1d7e --- /dev/null +++ b/doc/Nerve_GIC/nervevisu.jpg diff --git a/doc/Persistence_representations/Persistence_representations_doc.h b/doc/Persistence_representations/Persistence_representations_doc.h new file mode 100644 index 00000000..38bd3a21 --- /dev/null +++ b/doc/Persistence_representations/Persistence_representations_doc.h @@ -0,0 +1,259 @@ +/* This file is part of the Gudhi Library. The Gudhi library + * (Geometric Understanding in Higher Dimensions) is a generic C++ + * library for computational topology. + * + * Author(s): Pawel Dlotko + * + * Copyright (C) 2016 INRIA Sophia-Saclay (France) + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +#ifndef DOC_GUDHI_STAT_H_ +#define DOC_GUDHI_STAT_H_ + +namespace Gudhi { + +namespace Persistence_representations { + +/** \defgroup Persistence_representations Persistence representations + * + * \author Pawel Dlotko + * + * @{ + *\section Persistence_representations_idea Idea + + In order to perform most of the statistical tests and machine learning algorithms on a data one need to be able to + perform only a very limited number of operations on them. Let us fix a representation of + data of a type A. To perform most of the statistical and machine learning operations one need to be able to compute + average of objects of type A (so that the averaged object is also of a type A), to + compute distance between objects of a type A, to vectorize object of a type A and to compute scalar product of a pair + objects of a type A. + + To put this statement into a context, let us assume we have two collections \f$ c_1,\ldots,c_n\f$ and + \f$d_1,...,d_n\f$ of objects of a type A. We want to verify if the average of those two collections + are different by performing a permutation test. + First of all, we compute averages of those two collections: C average of \f$ c_1,\ldots,c_n \f$ and D average of + \f$d_1,\ldots,d_n\f$. Note that both C and D are of a type A. Then we compute \f$d(C,D)\f$, + a distance between C and D. + Later we put the two collections into one bin: + \f[B = \{ c_1,...,c_n,d_1,...,d_n \}\f] + Then we shuffle B, and we divide the shuffled version of B into two classes: \f$B_1\f$ and \f$B_2\f$ (in this case, of + the same cardinality). Then we compute averages \f$\hat{B_1}\f$ and \f$\hat{B_2}\f$ + of elements in \f$B_1\f$ and \f$B_2\f$. Note that again, \f$\hat{B_1}\f$ and \f$\hat{B_2}\f$ are of a type A. + Then we compute their distance \f$d(\hat{B_1},\hat{B_2})\f$. The procedure of shuffling and dividing the set \f$B\f$ + is repeated \f$N\f$ times (where \f$N\f$ is reasonably large number). + Then the p-value of a statement that the averages of \f$c_1,...,c_n\f$ and \f$d_1,...,d_n\f$ is approximated by the + number of times \f$d(\hat{B_1},\hat{B_2}) > d(C,D)\f$ divided by \f$N\f$. + + The permutation test reminded above can be performed for any type A which can be averaged, and which allows for + computations of distances. + + The Persistence\_representations contains a collection of various representations of persistent homology that + implements various concepts described below: + + \li Concept of a representation of persistence that allows averaging (so that the average object is of the same type). + \li Concept of representation of persistence that allows computations of distances. + \li Concept of representation of persistence that allows computations of scalar products. + \li Concept of representation of persistence that allows vectorization. + \li Concept of representation of persistence that allows computations of real-valued characteristics of objects. + + + At the moment an implementation of the following representations of persistence are available (further details of + those representations will be discussed later): + + \li Exact persistence landscapes (allow averaging, computation of distances, scalar products, vectorizations and real + value characteristics). + \li Persistence landscapes on a grid (allow averaging, computation of distances scalar products, vectorizations and + real value characteristics). + \li Persistence heat maps – various representations where one put some weighted or not Gaussian kernel for each point + of diagram (allow averaging, computation of distances, scalar products, + vectorizations and real value characteristics). + \li Persistence vectors (allow averaging, computation of distances, scalar products, vectorizations and real value + characteristics). + \li Persistence diagrams / barcodes (allow computation of distances, vectorizations and real value characteristics). + + + Note that at the while functionalities like averaging, distances and scalar products are fixed, there is no canonical + way of vectorizing and computing real valued characteristics of objects. Therefore the + vectorizations and computation of real value characteristics procedures are quite likely to evolve in the furthering + versions of the library. + + The main aim of this implementation is to be able to implement various statistical methods, both on the level of C++ + and on the level of python. The methods will operate on the functionalities offered + by concepts. That means that the statistical and ML methods will be able to operate on any representation that + implement the required concept (including the ones that are not in the library at the moment). + That gives provides a framework, that is very easy to extend, for topological statistics. + + Below we are discussing the representations which are currently implemented in Persistence\_representations package: + + \section sec_persistence_landscapes Persistence Landscapes + <b>Reference manual:</b> \ref Gudhi::Persistence_representations::Persistence_landscape <br> + Persistence landscapes were originally proposed by Bubenik in \cite bubenik_landscapes_2015. Efficient algorithms to + compute them rigorously were proposed by Bubenik and Dlotko in \cite bubenik_dlotko_landscapes_2016. The idea of + persistence landscapes is shortly summarized in below. + + To begin with, suppose we are given a point \f$(b,d) \in \mathbb{R}^2\f$ in a + persistence diagram. With this point, we associate a piecewise + linear function \f$f_{(b,d)} : \mathbb{R} \rightarrow [0,\infty)\f$, which is + defined as + + \f[f_{(b,d)}(x) = + \left\{ \begin{array}{ccl} + 0 & \mbox{ if } & x \not\in (b, d) \; , \\ + x - b & \mbox{ if } & x \in \left( b, \frac{b+d}{2} + \right] \; , \\ + d - x & \mbox{ if } & x \in \left(\frac{b+d}{2}, + d \right) \; . + \end{array} \right. + \f] + + A persistence landscape of the birth-death + pairs \f$(b_i , d_i)\f$, where \f$i = 1,\ldots,m\f$, which constitute the given + persistence diagram is the sequence of functions \f$\lambda_k : \mathbb{R} \rightarrow [0,\infty)\f$ for \f$k \in + \mathbb{N}\f$, where \f$\lambda_k(x)\f$ + denotes the \f$k^{\rm th}\f$ largest value of the numbers \f$f_{(b_i,d_i)}(x)\f$, + for \f$i = 1, \ldots, m\f$, and we define \f$\lambda_k(x) = 0\f$ if \f$k > m\f$. + Equivalently, this sequence of functions can be combined into a single + function \f$L : \mathbb{N} \times \mathbb{R} \to [0,\infty)\f$ of two + variables, if we define \f$L(k,t) = \lambda_k(t)\f$. + + The detailed description of algorithms used to compute persistence landscapes can be found in + \cite bubenik_dlotko_landscapes_2016. + Note that this implementation provides exact representation of landscapes. That have many advantages, but also a few + drawbacks. For instance, as discussed + in \cite bubenik_dlotko_landscapes_2016, the exact representation of landscape may be of quadratic size with respect + to the input persistence diagram. It may therefore happen + that, for very large diagrams, using this representation may be memory--prohibitive. In such a case, there are two + possible ways to proceed: + + \li Use non exact representation on a grid described in the Section \ref sec_landscapes_on_grid. + \li Compute just a number of initial nonzero landscapes. This option is available from C++ level as a last parameter of + the constructor of persistence landscape (set by default to std::numeric_limits<size_t>::max()). + + + + \section sec_landscapes_on_grid Persistence Landscapes on a grid + <b>Reference manual:</b> \ref Gudhi::Persistence_representations::Persistence_landscape_on_grid <br> + This is an alternative, not--exact, representation of persistence landscapes defined in the Section \ref + sec_persistence_landscapes. Unlike in the Section \ref sec_persistence_landscapes we build a + representation of persistence landscape by sampling its values on a finite, equally distributed grid of points. + Since, the persistence landscapes that originate from persistence diagrams have slope \f$1\f$ or \f$-1\f$, we have an + estimate of a region between the grid points where the landscape cab be located. + That allows to estimate an error make when performing various operations on landscape. Note that for average + landscapes the slope is in range \f$[-1,1]\f$ and similar estimate can be used. + + Due to a lack of rigorous description of the algorithms to deal with this non--rigorous representation of persistence + landscapes in the literature, we are providing a short discussion of them in below. + + Let us assume that we want to compute persistence landscape on a interval \f$[x,y]\f$. Let us assume that we want to + use \f$N\f$ grid points for that purpose. + Then we will sample the persistence landscape on points \f$x_1 = x , x_2 = x + \frac{y-x}{N}, \ldots , x_{N} = y\f$. + Persistence landscapes are represented as a vector of + vectors of real numbers. Assume that i-th vector consist of \f$n_i\f$ numbers sorted from larger to smaller. They + represent the values of the functions + \f$\lambda_1,\ldots,\lambda_{n_i}\f$ ,\f$\lambda_{n_i+1}\f$ and the functions with larger indices are then zero + functions) on the i-th point of a grid, i.e. \f$x + i \frac{y-x}{N}\f$. + + When averaging two persistence landscapes represented by a grid we need to make sure that they are defined in a + compatible grids. I.e. the intervals \f$[x,y]\f$ on which they are defined are + the same, and the numbers of grid points \f$N\f$ are the same in both cases. If this is the case, we simply compute + point-wise averages of the entries of corresponding + vectors (In this whole section we assume that if one vector of numbers is shorter than another, we extend the shorter + one with zeros so that they have the same length.) + + Computations of distances between two persistence landscapes on a grid is not much different than in the rigorous + case. In this case, we sum up the distances between the same levels of + corresponding landscapes. For fixed level, we approximate the landscapes between the corresponding constitutive + points of landscapes by linear functions, and compute the \f$L^p\f$ distance between them. + + Similarly as in case of distance, when computing the scalar product of two persistence landscapes on a grid, we sum up + the scalar products of corresponding levels of landscapes. For each level, + we assume that the persistence landscape on a grid between two grid points is approximated by linear function. + Therefore to compute scalar product of two corresponding levels of landscapes, + we sum up the integrals of products of line segments for every pair of constitutive grid points. + + Note that for this representation we need to specify a few parameters: + + \li Begin and end point of a grid -- the interval \f$[x,y]\f$ (real numbers). + \li Number of points in a grid (positive integer \f$N\f$). + + + Note that the same representation is used in TDA R-package \cite Fasy_Kim_Lecci_Maria_tda. + + \section sec_persistence_heat_maps Persistence heat maps + <b>Reference manual:</b> \ref Gudhi::Persistence_representations::Persistence_heat_maps <br> + This is a general class of discrete structures which are based on idea of placing a kernel in the points of + persistence diagrams. + This idea appeared in work by many authors over the last 15 years. As far as we know this idea was firstly described + in the work of Bologna group in \cite Ferri_Frosini_comparision_sheme_1 and \cite Ferri_Frosini_comparision_sheme_2. + Later it has been described by Colorado State University group in \cite Persistence_Images_2017. The presented paper + in the first time provide a discussion of stability of the representation. + Also, the same ideas are used in construction of two recent kernels used for machine learning: + \cite Kusano_Fukumizu_Hiraoka_PWGK and \cite Reininghaus_Huber_ALL_PSSK. Both the kernel's construction uses + interesting ideas to ensure stability of the representation with respect to Wasserstein metric. In the kernel + presented in \cite Kusano_Fukumizu_Hiraoka_PWGK, a scaling function is used to multiply the Gaussian kernel in the + way that the points close to diagonal got low weight and consequently do not have a big influence on the resulting + distribution. In \cite Reininghaus_Huber_ALL_PSSK for every point \f$(b,d)\f$ two Gaussian kernels + are added: first, with a weight 1 in a point \f$(b,d)\f$, and the second, with the weight -1 for a point \f$(b,d)\f$. + In both cases, the representations are stable with respect to 1-Wasserstein distance. + + In Persistence\_representations package we currently implement a discretization of the distributions described above. + The base of this implementation is 2-dimensional array of pixels. Each pixel have assigned a real value which + is a sum of values of distributions induced by each point of the persistence diagram. At the moment we compute the + sum of values on a center of a pixels. It can be easily extended to any other function + (like for instance sum of integrals of the intermediate distribution on a pixel). + + The parameters that determine the structure are the following: + + \li A positive integer k determining the size of the kernel we used (we always assume that the kernels are square). + \li A filter: in practice a square matrix of a size \f$2k+1 \times 2k+1\f$. By default, this is a discretization of + N(0,1) kernel. + \li The box \f$[x_0,x_1]\times [y_0,y_1]\f$ bounding the domain of the persistence image. + \li Scaling function. Each Gaussian kernel at point \f$(p,q)\f$ gets multiplied by the value of this function at the + point \f$(p,q)\f$. + \li A boolean value determining if the space below diagonal should be erased or not. To be precise: when points close + to diagonal are given then sometimes the kernel have support that reaches the region + below the diagonal. If the value of this parameter is true, then the values below diagonal can be erased. + + + \section sec_persistence_vectors Persistence vectors + <b>Reference manual:</b> \ref Gudhi::Persistence_representations::Vector_distances_in_diagram <br> + This is a representation of persistent homology in a form of a vector which was designed for an application in 3d + graphic in \cite Carriere_Oudot_Ovsjanikov_top_signatures_3d. Below we provide a short description of this + representation. + + Given a persistence diagram \f$D = \{ (b_i,d_i) \}\f$, for every pair of birth--death points \f$(b_1,d_1)\f$ and + \f$(b_2,d_2)\f$ we compute the following three distances: + + \li \f$d( (b_1,d_1) , (b_2,d_2) )\f$. + \li \f$d( (b_1,d_1) , (\frac{b_1,d_1}{2},\frac{b_1,d_1}{2}) )\f$. + \li \f$d( (b_2,d_2) , (\frac{b_2,d_2}{2},\frac{b_2,d_2}{2}) )\f$. + + We pick the smallest of those and add it to a vector. The obtained vector of numbers is then sorted in decreasing + order. This way we obtain a persistence vector representing the diagram. + + Given two persistence vectors, the computation of distances, averages and scalar products is straightforward. Average + is simply a coordinate-wise average of a collection of vectors. In this section we + assume that the vectors are extended by zeros if they are of a different size. To compute distances we compute + absolute value of differences between coordinates. A scalar product is a sum of products of + values at the corresponding positions of two vectors. + + */ +/** @} */ // end defgroup Persistence_representations + +} // namespace Persistence_representations +} // namespace Gudhi + +#endif // Persistence_representations diff --git a/doc/Persistence_representations/average_landscape.png b/doc/Persistence_representations/average_landscape.png Binary files differnew file mode 100644 index 00000000..ea59926b --- /dev/null +++ b/doc/Persistence_representations/average_landscape.png diff --git a/doc/Persistent_cohomology/Intro_persistent_cohomology.h b/doc/Persistent_cohomology/Intro_persistent_cohomology.h index 6400116b..4dbe82c7 100644 --- a/doc/Persistent_cohomology/Intro_persistent_cohomology.h +++ b/doc/Persistent_cohomology/Intro_persistent_cohomology.h @@ -143,8 +143,8 @@ namespace persistent_cohomology { We provide several example files: run these examples with -h for details on their use, and read the README file. -\li <a href="_persistent_cohomology_2rips_persistence_8cpp-example.html"> -Persistent_cohomology/rips_persistence.cpp</a> computes the Rips complex of a point cloud and outputs its persistence +\li <a href="_rips_complex_2rips_persistence_8cpp-example.html"> +Rips_complex/rips_persistence.cpp</a> computes the Rips complex of a point cloud and outputs its persistence diagram. \code $> ./rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 3 \endcode \code The complex contains 177838 simplices @@ -158,44 +158,44 @@ diagram. Persistent_cohomology/rips_multifield_persistence.cpp</a> computes the Rips complex of a point cloud and outputs its persistence diagram with a family of field coefficients. -\li <a href="_persistent_cohomology_2rips_distance_matrix_persistence_8cpp-example.html"> -Persistent_cohomology/rips_distance_matrix_persistence.cpp</a> computes the Rips complex of a distance matrix and +\li <a href="_rips_complex_2rips_distance_matrix_persistence_8cpp-example.html"> +Rips_complex/rips_distance_matrix_persistence.cpp</a> computes the Rips complex of a distance matrix and outputs its persistence diagram. -\li <a href="_persistent_cohomology_2alpha_complex_3d_persistence_8cpp-example.html"> -Persistent_cohomology/alpha_complex_3d_persistence.cpp</a> computes the persistent homology with +\li <a href="_alpha_complex_2alpha_complex_3d_persistence_8cpp-example.html"> +Alpha_complex/alpha_complex_3d_persistence.cpp</a> computes the persistent homology with \f$\mathbb{Z}/2\mathbb{Z}\f$ coefficients of the alpha complex on points sampling from an OFF file. -\code $> ./alpha_complex_3d_persistence ../../data/points/tore3D_300.off 2 0.45 \endcode +\code $> ./alpha_complex_3d_persistence ../../data/points/tore3D_300.off -p 2 -m 0.45 \endcode \code Simplex_tree dim: 3 2 0 0 inf 2 1 0.0682162 1.0001 2 1 0.0934117 1.00003 2 2 0.56444 1.03938 \endcode -\li <a href="_persistent_cohomology_2exact_alpha_complex_3d_persistence_8cpp-example.html"> -Persistent_cohomology/exact_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with +\li <a href="_alpha_complex_2exact_alpha_complex_3d_persistence_8cpp-example.html"> +Alpha_complex/exact_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with \f$\mathbb{Z}/2\mathbb{Z}\f$ coefficients of the alpha complex on points sampling from an OFF file. Here, as CGAL computes the exact values, it is slower, but it is necessary when points are on a grid for instance. -\code $> ./exact_alpha_complex_3d_persistence ../../data/points/sphere3D_pts_on_grid.off 2 0.1 \endcode +\code $> ./exact_alpha_complex_3d_persistence ../../data/points/sphere3D_pts_on_grid.off -p 2 -m 0.1 \endcode \code Simplex_tree dim: 3 2 0 0 inf 2 2 0.0002 0.2028 \endcode -\li <a href="_persistent_cohomology_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> -Persistent_cohomology/weighted_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with +\li <a href="_alpha_complex_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> +Alpha_complex/weighted_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with \f$\mathbb{Z}/2\mathbb{Z}\f$ coefficients of the weighted alpha complex on points sampling from an OFF file and a weights file. \code $> ./weighted_alpha_complex_3d_persistence ../../data/points/tore3D_300.off -../../data/points/tore3D_300.weights 2 0.45 \endcode +../../data/points/tore3D_300.weights -p 2 -m 0.45 \endcode \code Simplex_tree dim: 3 2 0 -1 inf 2 1 -0.931784 0.000103311 2 1 -0.906588 2.60165e-05 2 2 -0.43556 0.0393798 \endcode -\li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> -Persistent_cohomology/alpha_complex_persistence.cpp</a> computes the persistent homology with +\li <a href="_alpha_complex_2alpha_complex_persistence_8cpp-example.html"> +Alpha_complex/alpha_complex_persistence.cpp</a> computes the persistent homology with \f$\mathbb{Z}/p\mathbb{Z}\f$ coefficients of the alpha complex on points sampling from an OFF file. \code $> ./alpha_complex_persistence -r 32 -p 2 -m 0.45 ../../data/points/tore3D_300.off \endcode \code Alpha complex is of dimension 3 - 9273 simplices - 300 vertices. @@ -205,11 +205,13 @@ Simplex_tree dim: 3 2 1 0.0934117 1.00003 2 2 0.56444 1.03938 \endcode -\li <a href="_persistent_cohomology_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> -Persistent_cohomology/periodic_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with +\li <a href="_alpha_complex_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> +Alpha_complex/periodic_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with \f$\mathbb{Z}/2\mathbb{Z}\f$ coefficients of the periodic alpha complex on points sampling from an OFF file. +The second parameter is a \ref FileFormatsIsoCuboid file with coordinates of the periodic cuboid. +Note that the lengths of the sides of the periodic cuboid have to be the same. \code $> ./periodic_alpha_complex_3d_persistence ../../data/points/grid_10_10_10_in_0_1.off -../../data/points/iso_cuboid_3_in_0_1.txt 3 1.0 \endcode +../../data/points/iso_cuboid_3_in_0_1.txt -p 3 -m 1.0 \endcode \code Periodic Delaunay computed. Simplex_tree dim: 3 3 0 0 inf @@ -221,11 +223,31 @@ Simplex_tree dim: 3 3 2 0.005 inf 3 3 0.0075 inf \endcode +\li <a href="_persistent_cohomology_2weighted_periodic_alpha_complex_3d_persistence_8cpp-example.html"> +Persistent_cohomology/weighted_periodic_alpha_complex_3d_persistence.cpp</a> computes the persistent homology with +\f$\mathbb{Z}/2\mathbb{Z}\f$ coefficients of the periodic alpha complex on weighted points from an OFF file. The +additional parameters of this program are:<br> +(a) The file with the weights of points. The file consist of a sequence of numbers (as many as points). +Note that the weight of each single point have to be bounded by 1/64 times the square of the cuboid edge length.<br> +(b) A \ref FileFormatsIsoCuboid file with coordinates of the periodic cuboid. +Note that the lengths of the sides of the periodic cuboid have to be the same.<br> +\code $> ./weighted_periodic_alpha_complex_3d_persistence ../../data/points/shifted_sphere.off +../../data/points/shifted_sphere.weights ../../data/points/iso_cuboid_3_in_0_10.txt 3 1.0 \endcode +\code Weighted Periodic Delaunay computed. +Simplex_tree dim: 3 +3 0 -0.0001 inf +3 1 16.0264 inf +3 1 16.0273 inf +3 1 16.0303 inf +3 2 36.8635 inf +3 2 36.8704 inf +3 2 36.8838 inf +3 3 58.6783 inf \endcode + \li <a href="_persistent_cohomology_2plain_homology_8cpp-example.html"> Persistent_cohomology/plain_homology.cpp</a> computes the plain homology of a simple simplicial complex without filtration values. - \copyright GNU General Public License v3. */ } // namespace persistent_cohomology diff --git a/doc/Rips_complex/Intro_rips_complex.h b/doc/Rips_complex/Intro_rips_complex.h index 124dfec9..8c517516 100644 --- a/doc/Rips_complex/Intro_rips_complex.h +++ b/doc/Rips_complex/Intro_rips_complex.h @@ -146,8 +146,6 @@ namespace rips_complex { * * \include Rips_complex/full_skeleton_rips_for_doc.txt * - * \copyright GNU General Public License v3. - * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim */ /** @} */ // end defgroup rips_complex diff --git a/doc/Simplex_tree/Intro_simplex_tree.h b/doc/Simplex_tree/Intro_simplex_tree.h index f5b72ff6..6b80d1c9 100644 --- a/doc/Simplex_tree/Intro_simplex_tree.h +++ b/doc/Simplex_tree/Intro_simplex_tree.h @@ -67,16 +67,18 @@ Information of the Simplex Tree: Number of vertices = 10 Number of simplices = 98 \endcode * * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html"> - * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> - Simplex tree is computed and displayed from a 3D alpha - * complex (Requires CGAL, GMP and GMPXX to be installed) - * + * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> - Simplex tree is computed and displayed + * from a 3D alpha complex (Requires CGAL, GMP and GMPXX to be installed). * + * \li <a href="_simplex_tree_2graph_expansion_with_blocker_8cpp-example.html"> + * Simplex_tree/graph_expansion_with_blocker.cpp</a> - Simple simplex tree construction from a one-skeleton graph with + * a simple blocker expansion method. + * * \subsection filteredcomplexeshassecomplex Hasse complex * The second one is the Hasse_complex. The Hasse complex is a data structure representing explicitly all co-dimension * 1 incidence relations in a complex. It is consequently faster when accessing the boundary of a simplex, but is less * compact and harder to construct from scratch. * - * \copyright GNU General Public License v3. * @} */ diff --git a/doc/Spatial_searching/Intro_spatial_searching.h b/doc/Spatial_searching/Intro_spatial_searching.h index 1ee5e92e..52ed65e4 100644 --- a/doc/Spatial_searching/Intro_spatial_searching.h +++ b/doc/Spatial_searching/Intro_spatial_searching.h @@ -50,8 +50,6 @@ namespace spatial_searching { * * \include Spatial_searching/example_spatial_searching.cpp * - * \copyright GNU General Public License v3. - * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim */ /** @} */ // end defgroup spatial_searching diff --git a/doc/Subsampling/Intro_subsampling.h b/doc/Subsampling/Intro_subsampling.h index c84616dd..ab9cdc37 100644 --- a/doc/Subsampling/Intro_subsampling.h +++ b/doc/Subsampling/Intro_subsampling.h @@ -58,8 +58,6 @@ namespace subsampling { * This example outputs a subset of 100 points picked randomly. * * \include Subsampling/example_pick_n_random_points.cpp - * \copyright GNU General Public License v3. - * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim */ /** @} */ // end defgroup subsampling diff --git a/doc/Tangential_complex/Intro_tangential_complex.h b/doc/Tangential_complex/Intro_tangential_complex.h index 3d687c1d..00e00c52 100644 --- a/doc/Tangential_complex/Intro_tangential_complex.h +++ b/doc/Tangential_complex/Intro_tangential_complex.h @@ -107,8 +107,6 @@ dimensions are known at compile-time. \include Tangential_complex/example_with_perturb.cpp -\copyright GNU General Public License v3. -\verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim */ /** @} */ // end defgroup tangential_complex diff --git a/doc/Witness_complex/Witness_complex_doc.h b/doc/Witness_complex/Witness_complex_doc.h index 171a185f..62203054 100644 --- a/doc/Witness_complex/Witness_complex_doc.h +++ b/doc/Witness_complex/Witness_complex_doc.h @@ -90,8 +90,9 @@ int main(int argc, char * const argv[]) { Gudhi::Points_off_reader<Point_d> off_reader(file_name); point_vector = Point_vector(off_reader.get_point_cloud()); - // Choose landmarks - Gudhi::subsampling::pick_n_random_points(point_vector, nbL, std::back_inserter(landmarks)); + // Choose landmarks (one can choose either of the two methods below) + // Gudhi::subsampling::pick_n_random_points(point_vector, nbL, std::back_inserter(landmarks)); + Gudhi::subsampling::choose_n_farthest_points(K(), point_vector, nbL, Gudhi::subsampling::random_starting_point, std::back_inserter(landmarks)); // Compute witness complex Witness_complex witness_complex(landmarks, @@ -107,10 +108,14 @@ int main(int argc, char * const argv[]) { Here is an example of constructing a strong witness complex filtration and computing persistence on it: - \include Witness_complex/example_strong_witness_persistence.cpp + \include Witness_complex/strong_witness_persistence.cpp - \copyright GNU General Public License v3. + \section witnessexample3 Example3: Computing relaxed witness complex persistence from a distance matrix + In this example we compute the relaxed witness complex persistence from a given matrix of closest landmarks to each witness. + Each landmark is given as the couple (index, distance). + + \include Witness_complex/example_nearest_landmark_table.cpp */ diff --git a/doc/common/examples.h b/doc/common/examples.h new file mode 100644 index 00000000..40f202c7 --- /dev/null +++ b/doc/common/examples.h @@ -0,0 +1,99 @@ +// List of GUDHI examples - Doxygen needs at least a file tag to analyse comments +// In user_version, `find . -name "*.cpp"` in example and utilities folders +/*! @file Examples + * @example Alpha_complex/Alpha_complex_from_off.cpp + * @example Alpha_complex/Alpha_complex_from_points.cpp + * @example Bottleneck_distance/bottleneck_basic_example.cpp + * @example Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp + * @example Witness_complex/example_nearest_landmark_table.cpp + * @example Witness_complex/example_witness_complex_off.cpp + * @example Witness_complex/example_witness_complex_sphere.cpp + * @example Witness_complex/example_strong_witness_complex_off.cpp + * @example Simplex_tree/mini_simplex_tree.cpp + * @example Simplex_tree/graph_expansion_with_blocker.cpp + * @example Simplex_tree/simple_simplex_tree.cpp + * @example Simplex_tree/simplex_tree_from_cliques_of_graph.cpp + * @example Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp + * @example Simplex_tree/cech_complex_cgal_mini_sphere_3d.cpp + * @example Persistent_cohomology/plain_homology.cpp + * @example Persistent_cohomology/persistence_from_file.cpp + * @example Persistent_cohomology/rips_persistence_step_by_step.cpp + * @example Persistent_cohomology/rips_persistence_via_boundary_matrix.cpp + * @example Persistent_cohomology/custom_persistence_sort.cpp + * @example Persistent_cohomology/persistence_from_simple_simplex_tree.cpp + * @example Persistent_cohomology/rips_multifield_persistence.cpp + * @example Skeleton_blocker/Skeleton_blocker_from_simplices.cpp + * @example Skeleton_blocker/Skeleton_blocker_iteration.cpp + * @example Skeleton_blocker/Skeleton_blocker_link.cpp + * @example Contraction/Garland_heckbert.cpp + * @example Contraction/Rips_contraction.cpp + * @example Bitmap_cubical_complex/Random_bitmap_cubical_complex.cpp + * @example common/example_CGAL_3D_points_off_reader.cpp + * @example common/example_vector_double_points_off_reader.cpp + * @example common/example_CGAL_points_off_reader.cpp + * @example Rips_complex/example_one_skeleton_rips_from_distance_matrix.cpp + * @example Rips_complex/example_one_skeleton_rips_from_points.cpp + * @example Rips_complex/example_rips_complex_from_csv_distance_matrix_file.cpp + * @example Rips_complex/example_rips_complex_from_off_file.cpp + * @example Persistence_representations/persistence_intervals.cpp + * @example Persistence_representations/persistence_vectors.cpp + * @example Persistence_representations/persistence_heat_maps.cpp + * @example Persistence_representations/persistence_landscape_on_grid.cpp + * @example Persistence_representations/persistence_landscape.cpp + * @example Tangential_complex/example_basic.cpp + * @example Tangential_complex/example_with_perturb.cpp + * @example Subsampling/example_custom_kernel.cpp + * @example Subsampling/example_choose_n_farthest_points.cpp + * @example Subsampling/example_sparsify_point_set.cpp + * @example Subsampling/example_pick_n_random_points.cpp + * @example Nerve_GIC/CoordGIC.cpp + * @example Nerve_GIC/Nerve.cpp + * @example Nerve_GIC/FuncGIC.cpp + * @example Nerve_GIC/VoronoiGIC.cpp + * @example Spatial_searching/example_spatial_searching.cpp + * @example Alpha_complex/alpha_complex_3d_persistence.cpp + * @example Alpha_complex/alpha_complex_persistence.cpp + * @example Alpha_complex/weighted_periodic_alpha_complex_3d_persistence.cpp + * @example Alpha_complex/weighted_alpha_complex_3d_persistence.cpp + * @example Alpha_complex/periodic_alpha_complex_3d_persistence.cpp + * @example Alpha_complex/exact_alpha_complex_3d_persistence.cpp + * @example Bottleneck_distance/bottleneck_distance.cpp + * @example Witness_complex/weak_witness_persistence.cpp + * @example Witness_complex/strong_witness_persistence.cpp + * @example Bitmap_cubical_complex/cubical_complex_persistence.cpp + * @example Bitmap_cubical_complex/periodic_cubical_complex_persistence.cpp + * @example common/off_file_from_shape_generator.cpp + * @example Rips_complex/rips_distance_matrix_persistence.cpp + * @example Rips_complex/rips_persistence.cpp + * @example Persistence_representations/persistence_landscapes_on_grid/create_landscapes_on_grid.cpp + * @example Persistence_representations/persistence_landscapes_on_grid/plot_landscapes_on_grid.cpp + * @example Persistence_representations/persistence_landscapes_on_grid/compute_scalar_product_of_landscapes_on_grid.cpp + * @example Persistence_representations/persistence_landscapes_on_grid/compute_distance_of_landscapes_on_grid.cpp + * @example Persistence_representations/persistence_landscapes_on_grid/average_landscapes_on_grid.cpp + * @example Persistence_representations/persistence_intervals/compute_birth_death_range_in_persistence_diagram.cpp + * @example Persistence_representations/persistence_intervals/compute_number_of_dominant_intervals.cpp + * @example Persistence_representations/persistence_intervals/plot_persistence_Betti_numbers.cpp + * @example Persistence_representations/persistence_intervals/plot_persistence_intervals.cpp + * @example Persistence_representations/persistence_intervals/plot_histogram_of_intervals_lengths.cpp + * @example Persistence_representations/persistence_intervals/compute_bottleneck_distance.cpp + * @example Persistence_representations/persistence_heat_maps/create_pssk.cpp + * @example Persistence_representations/persistence_heat_maps/create_p_h_m_weighted_by_arctan_of_their_persistence.cpp + * @example Persistence_representations/persistence_heat_maps/create_p_h_m_weighted_by_squared_diag_distance.cpp + * @example Persistence_representations/persistence_heat_maps/compute_distance_of_persistence_heat_maps.cpp + * @example Persistence_representations/persistence_heat_maps/compute_scalar_product_of_persistence_heat_maps.cpp + * @example Persistence_representations/persistence_heat_maps/create_p_h_m_weighted_by_distance_from_diagonal.cpp + * @example Persistence_representations/persistence_heat_maps/average_persistence_heat_maps.cpp + * @example Persistence_representations/persistence_heat_maps/plot_persistence_heat_map.cpp + * @example Persistence_representations/persistence_heat_maps/create_persistence_heat_maps.cpp + * @example Persistence_representations/persistence_vectors/plot_persistence_vectors.cpp + * @example Persistence_representations/persistence_vectors/compute_distance_of_persistence_vectors.cpp + * @example Persistence_representations/persistence_vectors/average_persistence_vectors.cpp + * @example Persistence_representations/persistence_vectors/create_persistence_vectors.cpp + * @example Persistence_representations/persistence_vectors/compute_scalar_product_of_persistence_vectors.cpp + * @example Persistence_representations/persistence_landscapes/average_landscapes.cpp + * @example Persistence_representations/persistence_landscapes/compute_scalar_product_of_landscapes.cpp + * @example Persistence_representations/persistence_landscapes/create_landscapes.cpp + * @example Persistence_representations/persistence_landscapes/compute_distance_of_landscapes.cpp + * @example Persistence_representations/persistence_landscapes/plot_landscapes.cpp + */ + diff --git a/doc/common/file_formats.h b/doc/common/file_formats.h index d715aa4d..c60ed15a 100644 --- a/doc/common/file_formats.h +++ b/doc/common/file_formats.h @@ -53,6 +53,72 @@ namespace Gudhi { Such files can be generated with `Gudhi::persistent_cohomology::Persistent_cohomology::output_diagram()` and read with `Gudhi::read_persistence_intervals_and_dimension()`, `Gudhi::read_persistence_intervals_grouped_by_dimension()` or `Gudhi::read_persistence_intervals_in_dimension()`. + + + \section FileFormatsIsoCuboid Iso-cuboid + + Such a file describes an iso-oriented cuboid with diagonal opposite vertices (min_x, min_y, min_z,...) and (max_x, max_y, max_z, ...). The format is:<br> + \verbatim + min_x min_y [min_z ...] + max_x max_y [max_z ...] + \endverbatim + + Here is a simple sample file in the 3D case: + \verbatim + -1. -1. -1. + 1. 1. 1. + \endverbatim + + + \section FileFormatsPerseus Perseus + + This file format is the format used by the Perseus software + (http://www.sas.upenn.edu/~vnanda/perseus/) by Vidit Nanda. + The first line contains a number d begin the dimension of the + bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3 + in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8 + 20 4 7 6 5 in the example below). + + \image html "exampleBitmap.png" "Example of a input data." + + The input file for the following complex is: + \verbatim + 2 + 3 + 3 + 1 + 4 + 6 + 8 + 20 + 4 + 7 + 6 + 5 + \endverbatim + + To indicate periodic boundary conditions in a + given direction, then number of top dimensional cells in this direction have to be multiplied by -1. For instance: + + \verbatim + 2 + -3 + 3 + 1 + 4 + 6 + 8 + 20 + 4 + 7 + 6 + 5 + \endverbatim + + Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y. + + Other sample files can be found in the `data/bitmap` folder. + */ } // namespace Gudhi diff --git a/doc/common/footer.html b/doc/common/footer.html index 7b4cdc5c..a557922b 100644 --- a/doc/common/footer.html +++ b/doc/common/footer.html @@ -6,24 +6,18 @@ <!--BEGIN PROJECT_NAME--> $projectname <!--BEGIN PROJECT_NUMBER--> Version $projectnumber<!--END PROJECT_NUMBER--> <!--BEGIN PROJECT_BRIEF--> - $projectbrief<!--END PROJECT_BRIEF--> +<!--BEGIN PROJECT_BRIEF--> - Copyright : GPL v3<!--END PROJECT_BRIEF--> <!--END PROJECT_NAME--> </td> <td class="network-entypo"> <!--BEGIN GENERATE_TREEVIEW--> $generatedby <a href="http://www.doxygen.org/index.html"> - <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion + Doxygen</a> $doxygenversion <!--END GENERATE_TREEVIEW--> </td> </tr> </table> -<!--BEGIN !GENERATE_TREEVIEW--> -<hr class="footer"/><address class="footer"><small> tralala -$generatedby  <a href="http://www.doxygen.org/index.html"> -<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/> -</a> $doxygenversion -</small></address> -<!--END !GENERATE_TREEVIEW--> </body> </html> diff --git a/doc/common/header.html b/doc/common/header.html index 53b5c0a2..9c514381 100644 --- a/doc/common/header.html +++ b/doc/common/header.html @@ -56,6 +56,8 @@ $extrastylesheet <ul class="dropdown"> <li><a href="http://gudhi.gforge.inria.fr/licensing/">Licensing</a></li> <li><a href="https://gforge.inria.fr/frs/?group_id=3865" target="_blank">Get the sources</a></li> + <li><a href="https://gforge.inria.fr/frs/download.php/file/37113/GUDHI_2.0.0_OSX_UTILS.beta.tar.gz" target="_blank">Utils for Mac OSx</a></li> + <li><a href="https://gforge.inria.fr/frs/download.php/file/37112/GUDHI_2.0.0_WIN64_UTILS.beta.zip" target="_blank">Utils for Win x64</a></li> </ul> </li> <li class="divider"></li> @@ -66,6 +68,8 @@ $extrastylesheet <li><a href="http://gudhi.gforge.inria.fr/doc/latest/installation.html">C++ installation manual</a></li> <li><a href="http://gudhi.gforge.inria.fr/python/latest/">Python documentation</a></li> <li><a href="http://gudhi.gforge.inria.fr/python/latest/installation.html">Python installation manual</a></li> + <li><a href="http://gudhi.gforge.inria.fr/utils/">Utilities</a></li> + <li><a href="http://bertrand.michel.perso.math.cnrs.fr/Enseignements/TDA-Gudhi-Python.html" target="_blank">Tutorial</a></li> </ul> </li> <li class="divider"></li> diff --git a/doc/common/installation.h b/doc/common/installation.h new file mode 100644 index 00000000..25675cc5 --- /dev/null +++ b/doc/common/installation.h @@ -0,0 +1,263 @@ +/*! \page installation GUDHI installation + * \tableofcontents + * As GUDHI is a header only library, there is no need to install the library. + * + * Examples of GUDHI headers inclusion can be found in \ref demos. + * + * \section compiling Compiling + * The library uses c++11 and requires <a target="_blank" href="http://www.boost.org/">Boost</a> with version 1.48.0 or + * more recent. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2015. + * + * \subsection demos Demos and examples + * To build the demos and examples, run the following commands in a terminal: +\verbatim cd /path-to-gudhi/ +mkdir build +cd build/ +cmake .. +make \endverbatim + * A list of examples is available <a href="examples.html">here</a>. + * + * \subsection testsuites Test suites + * To test your build, run the following command in a terminal: + * \verbatim make test \endverbatim + * + * \subsection documentationgeneration Documentation + * To generate the documentation, <a target="_blank" href="http://www.doxygen.org/">Doxygen</a> is required. + * Run the following command in a terminal: +\verbatim +make doxygen +# Documentation will be generated in the folder YYYY-MM-DD-hh-mm-ss_GUDHI_X.Y.Z/doc/html/ +# You can customize the directory name by calling `cmake -DUSER_VERSION_DIR=/my/custom/folder` +\endverbatim + * + * \section optionallibrary Optional third-party library + * \subsection gmp GMP + * The multi-field persistent homology algorithm requires GMP which is a free library for arbitrary-precision + * arithmetic, operating on signed integers, rational numbers, and floating point numbers. + * + * The following example requires the <a target="_blank" href="http://gmplib.org/">GNU Multiple Precision Arithmetic + * Library</a> (GMP) and will not be built if GMP is not installed: + * \li <a href="_persistent_cohomology_2rips_multifield_persistence_8cpp-example.html"> + * Persistent_cohomology/rips_multifield_persistence.cpp</a> + * + * Having GMP version 4.2 or higher installed is recommended. + * + * \subsection cgal CGAL + * The \ref alpha_complex data structure, \ref bottleneck_distance, and few examples requires CGAL, which is a C++ + * library which provides easy access to efficient and reliable geometric algorithms. + * + * \note There is no need to install CGAL, you can just <CODE>cmake . && make</CODE> CGAL (or even + * <CODE>cmake -DCGAL_HEADER_ONLY=ON .</CODE> for CGAL version ≥ 4.8.0), thereafter you will be able to compile + * GUDHI by calling <CODE>cmake -DCGAL_DIR=/your/path/to/CGAL-X.Y .. && make</CODE> + * + * Having CGAL version 4.4.0 or higher installed is recommended. The procedure to install this library according to + * your operating system is detailed here http://doc.cgal.org/latest/Manual/installation.html + * + * The following examples/utilities require the <a target="_blank" href="http://www.cgal.org/">Computational Geometry Algorithms + * Library</a> (CGAL \cite cgal:eb-15b) and will not be built if CGAL is not installed: + * \li <a href="_alpha_complex_2alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/alpha_complex_3d_persistence.cpp</a> + * \li <a href="_alpha_complex_2exact_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/exact_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_alpha_complex_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/weighted_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html"> + * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> + * + * The following examples/utilities require CGAL version ≥ 4.6.0: + * \li <a href="_witness_complex_2strong_witness_persistence_8cpp-example.html"> + * Witness_complex/strong_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2weak_witness_persistence_8cpp-example.html"> + * Witness_complex/weak_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2example_strong_witness_complex_off_8cpp-example.html"> + * Witness_complex/example_strong_witness_complex_off.cpp</a> + * \li <a href="_witness_complex_2example_witness_complex_off_8cpp-example.html"> + * Witness_complex/example_witness_complex_off.cpp</a> + * \li <a href="_witness_complex_2example_witness_complex_sphere_8cpp-example.html"> + * Witness_complex/example_witness_complex_sphere.cpp</a> + * + * The following example requires CGAL version ≥ 4.7.0: + * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_off.cpp</a> + * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_points.cpp</a> + * \li <a href="_alpha_complex_2alpha_complex_persistence_8cpp-example.html"> + * Alpha_complex/alpha_complex_persistence.cpp</a> + * \li <a href="_alpha_complex_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/periodic_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> + * Persistent_cohomology/custom_persistence_sort.cpp</a> + * + * The following example requires CGAL version ≥ 4.8.1: + * \li <a href="_bottleneck_distance_2alpha_rips_persistence_bottleneck_distance_8cpp-example.html"> + * Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp.cpp</a> + * \li <a href="_bottleneck_distance_2bottleneck_basic_example_8cpp-example.html"> + * Bottleneck_distance/bottleneck_basic_example.cpp</a> + * \li <a href="_bottleneck_distance_2bottleneck_read_file_8cpp-example.html"> + * Bottleneck_distance/bottleneck_distance.cpp</a> + * \li <a href="_nerve__g_i_c_2_coord_g_i_c_8cpp-example.html"> + * Nerve_GIC/CoordGIC.cpp</a> + * \li <a href="_nerve__g_i_c_2_func_g_i_c_8cpp-example.html"> + * Nerve_GIC/FuncGIC.cpp</a> + * \li <a href="_nerve__g_i_c_2_nerve_8cpp-example.html"> + * Nerve_GIC/Nerve.cpp</a> + * \li <a href="_nerve__g_i_c_2_voronoi_g_i_c_8cpp-example.html"> + * Nerve_GIC/VoronoiGIC.cpp</a> + * \li <a href="_spatial_searching_2example_spatial_searching_8cpp-example.html"> + * Spatial_searching/example_spatial_searching.cpp</a> + * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html"> + * Subsampling/example_choose_n_farthest_points.cpp</a> + * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html"> + * Subsampling/example_custom_kernel.cpp</a> + * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html"> + * Subsampling/example_pick_n_random_points.cpp</a> + * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html"> + * Subsampling/example_sparsify_point_set.cpp</a> + * \li <a href="_tangential_complex_2example_basic_8cpp-example.html"> + * Tangential_complex/example_basic.cpp</a> + * \li <a href="_tangential_complex_2example_with_perturb_8cpp-example.html"> + * Tangential_complex/example_with_perturb.cpp</a> + * + * \subsection eigen3 Eigen3 + * The \ref alpha_complex data structure and few examples requires + * <a target="_blank" href="http://eigen.tuxfamily.org/">Eigen3</a> is a C++ template library for linear algebra: + * matrices, vectors, numerical solvers, and related algorithms. + * + * The following examples/utilities require the <a target="_blank" href="http://eigen.tuxfamily.org/">Eigen3</a> and will not be + * built if Eigen3 is not installed: + * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_off.cpp</a> + * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_points.cpp</a> + * \li <a href="_alpha_complex_2alpha_complex_persistence_8cpp-example.html"> + * Alpha_complex/alpha_complex_persistence.cpp</a> + * \li <a href="_alpha_complex_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/periodic_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_bottleneck_distance_2alpha_rips_persistence_bottleneck_distance_8cpp-example.html"> + * Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp.cpp</a> + * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> + * Persistent_cohomology/custom_persistence_sort.cpp</a> + * \li <a href="_spatial_searching_2example_spatial_searching_8cpp-example.html"> + * Spatial_searching/example_spatial_searching.cpp</a> + * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html"> + * Subsampling/example_choose_n_farthest_points.cpp</a> + * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html"> + * Subsampling/example_custom_kernel.cpp</a> + * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html"> + * Subsampling/example_pick_n_random_points.cpp</a> + * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html"> + * Subsampling/example_sparsify_point_set.cpp</a> + * \li <a href="_tangential_complex_2example_basic_8cpp-example.html"> + * Tangential_complex/example_basic.cpp</a> + * \li <a href="_tangential_complex_2example_with_perturb_8cpp-example.html"> + * Tangential_complex/example_with_perturb.cpp</a> + * \li <a href="_witness_complex_2strong_witness_persistence_8cpp-example.html"> + * Witness_complex/strong_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2weak_witness_persistence_8cpp-example.html"> + * Witness_complex/weak_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2example_strong_witness_complex_off_8cpp-example.html"> + * Witness_complex/example_strong_witness_complex_off.cpp</a> + * \li <a href="_witness_complex_2example_witness_complex_off_8cpp-example.html"> + * Witness_complex/example_witness_complex_off.cpp</a> + * \li <a href="_witness_complex_2example_witness_complex_sphere_8cpp-example.html"> + * Witness_complex/example_witness_complex_sphere.cpp</a> + * + * \subsection tbb Threading Building Blocks + * <a target="_blank" href="https://www.threadingbuildingblocks.org/">Intel® TBB</a> lets you easily write parallel + * C++ programs that take full advantage of multicore performance, that are portable and composable, and that have + * future-proof scalability. + * + * Having Intel® TBB installed is recommended to parallelize and accelerate some GUDHI computations. + * + * The following examples/utilities are using Intel® TBB if installed: + * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_off.cpp</a> + * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> + * Alpha_complex/Alpha_complex_from_points.cpp</a> + * \li <a href="_alpha_complex_2alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/alpha_complex_3d_persistence.cpp</a> + * \li <a href="_alpha_complex_2alpha_complex_persistence_8cpp-example.html"> + * Alpha_complex/alpha_complex_persistence.cpp</a> + * \li <a href="_alpha_complex_2exact_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/exact_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_alpha_complex_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/periodic_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_alpha_complex_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> + * Alpha_complex/weighted_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_bitmap_cubical_complex_2_bitmap_cubical_complex_8cpp-example.html"> + * Bitmap_cubical_complex/cubical_complex_persistence.cpp</a> + * \li <a href="_bitmap_cubical_complex_2_bitmap_cubical_complex_periodic_boundary_conditions_8cpp-example.html"> + * Bitmap_cubical_complex/periodic_cubical_complex_persistence.cpp</a> + * \li <a href="_bitmap_cubical_complex_2_random_bitmap_cubical_complex_8cpp-example.html"> + * Bitmap_cubical_complex/Random_bitmap_cubical_complex.cpp</a> + * \li <a href="_nerve__g_i_c_2_coord_g_i_c_8cpp-example.html"> + * Nerve_GIC/CoordGIC.cpp</a> + * \li <a href="_nerve__g_i_c_2_func_g_i_c_8cpp-example.html"> + * Nerve_GIC/FuncGIC.cpp</a> + * \li <a href="_nerve__g_i_c_2_nerve_8cpp-example.html"> + * Nerve_GIC/Nerve.cpp</a> + * \li <a href="_nerve__g_i_c_2_voronoi_g_i_c_8cpp-example.html"> + * Nerve_GIC/VoronoiGIC.cpp</a> + * \li <a href="_simplex_tree_2simple_simplex_tree_8cpp-example.html"> + * Simplex_tree/simple_simplex_tree.cpp</a> + * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html"> + * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> + * \li <a href="_simplex_tree_2simplex_tree_from_cliques_of_graph_8cpp-example.html"> + * Simplex_tree/simplex_tree_from_cliques_of_graph.cpp</a> + * \li <a href="_simplex_tree_2graph_expansion_with_blocker_8cpp-example.html"> + * Simplex_tree/graph_expansion_with_blocker.cpp</a> + * \li <a href="_persistent_cohomology_2alpha_complex_3d_persistence_8cpp-example.html"> + * Persistent_cohomology/alpha_complex_3d_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> + * Persistent_cohomology/alpha_complex_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2rips_persistence_via_boundary_matrix_8cpp-example.html"> + * Persistent_cohomology/rips_persistence_via_boundary_matrix.cpp</a> + * \li <a href="_persistent_cohomology_2persistence_from_file_8cpp-example.html"> + * Persistent_cohomology/persistence_from_file.cpp</a> + * \li <a href="_persistent_cohomology_2persistence_from_simple_simplex_tree_8cpp-example.html"> + * Persistent_cohomology/persistence_from_simple_simplex_tree.cpp</a> + * \li <a href="_persistent_cohomology_2plain_homology_8cpp-example.html"> + * Persistent_cohomology/plain_homology.cpp</a> + * \li <a href="_persistent_cohomology_2rips_multifield_persistence_8cpp-example.html"> + * Persistent_cohomology/rips_multifield_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2rips_persistence_step_by_step_8cpp-example.html"> + * Persistent_cohomology/rips_persistence_step_by_step.cpp</a> + * \li <a href="_persistent_cohomology_2exact_alpha_complex_3d_persistence_8cpp-example.html"> + * Persistent_cohomology/exact_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> + * Persistent_cohomology/weighted_alpha_complex_3d_persistence.cpp</a> + * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> + * Persistent_cohomology/custom_persistence_sort.cpp</a> + * \li <a href="_rips_complex_2example_one_skeleton_rips_from_points_8cpp-example.html"> + * Rips_complex/example_one_skeleton_rips_from_points.cpp</a> + * \li <a href="_rips_complex_2example_rips_complex_from_off_file_8cpp-example.html"> + * Rips_complex/example_rips_complex_from_off_file.cpp</a> + * \li <a href="_rips_complex_2rips_distance_matrix_persistence_8cpp-example.html"> + * Rips_complex/rips_distance_matrix_persistence.cpp</a> + * \li <a href="_rips_complex_2rips_persistence_8cpp-example.html"> + * Rips_complex/rips_persistence.cpp</a> + * \li <a href="_witness_complex_2strong_witness_persistence_8cpp-example.html"> + * Witness_complex/strong_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2weak_witness_persistence_8cpp-example.html"> + * Witness_complex/weak_witness_persistence.cpp</a> + * \li <a href="_witness_complex_2example_nearest_landmark_table_8cpp-example.html"> + * Witness_complex/example_nearest_landmark_table.cpp</a> + * + * \section Contributions Bug reports and contributions + * Please help us improving the quality of the GUDHI library. You may report bugs or suggestions to: + * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim + * + * GUDHI is open to external contributions. If you want to join our development team, please contact us. + * +*/ + +/*! \page Citation Acknowledging the GUDHI library + * We kindly ask users to cite the GUDHI library as appropriately as possible in their papers, and to mention the use + * of the GUDHI library on the web pages of their projects using GUDHI and provide us with links to these web pages. + * Feel free to contact us in case you have any question or remark on this topic. + * + * We provide \ref GudhiBibtex entries for the modules of the User and Reference Manual, as well as for publications + * directly related to the GUDHI library. + * \section GudhiBibtex GUDHI bibtex + * \verbinclude biblio/how_to_cite_gudhi.bib +*/ diff --git a/doc/common/main_page.h b/doc/common/main_page.h index 1a7994a5..b3e9ea03 100644 --- a/doc/common/main_page.h +++ b/doc/common/main_page.h @@ -93,6 +93,25 @@ </td> </tr> </table> + \subsection CoverComplexDataStructure Cover Complexes + \image html "gicvisu.jpg" "Graph Induced Complex of a point cloud." +<table border="0"> + <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> + <td width="75%"> + 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> + </tr> +</table> \subsection SkeletonBlockerDataStructure Skeleton blocker \image html "ds_representation.png" "Skeleton blocker representation" <table border="0"> @@ -152,6 +171,7 @@ </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"> @@ -211,276 +231,23 @@ <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"> + <tr> + <td width="25%"> + <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> + <b>User manual:</b> \ref Persistence_representations + </td> + </tr> </table> + */ - -/*! \page installation GUDHI installation - * \tableofcontents - * As GUDHI is a header only library, there is no need to install the library. - * - * Examples of GUDHI headers inclusion can be found in \ref demos. - * - * \section compiling Compiling - * The library uses c++11 and requires <a target="_blank" href="http://www.boost.org/">Boost</a> with version 1.48.0 or - * more recent. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2015. - * - * \subsection demos Demos and examples - * To build the demos and examples, run the following commands in a terminal: -\verbatim cd /path-to-gudhi/ -mkdir build -cd build/ -cmake .. -make \endverbatim - * A list of examples is available <a href="examples.html">here</a>. - * - * \subsection testsuites Test suites - * To test your build, run the following command in a terminal: - * \verbatim make test \endverbatim - * - * \subsection documentationgeneration Documentation - * To generate the documentation, <a target="_blank" href="http://www.doxygen.org/">Doxygen</a> is required. - * Run the following command in a terminal: -\verbatim -make doxygen -# Documentation will be generated in the folder YYYY-MM-DD-hh-mm-ss_GUDHI_X.Y.Z/doc/html/ -# You can customize the directory name by calling `cmake -DUSER_VERSION_DIR=/my/custom/folder` -\endverbatim - * - * \section optionallibrary Optional third-party library - * \subsection gmp GMP - * The multi-field persistent homology algorithm requires GMP which is a free library for arbitrary-precision - * arithmetic, operating on signed integers, rational numbers, and floating point numbers. - * - * The following example requires the <a target="_blank" href="http://gmplib.org/">GNU Multiple Precision Arithmetic - * Library</a> (GMP) and will not be built if GMP is not installed: - * \li <a href="_persistent_cohomology_2rips_multifield_persistence_8cpp-example.html"> - * Persistent_cohomology/rips_multifield_persistence.cpp</a> - * - * Having GMP version 4.2 or higher installed is recommended. - * - * \subsection cgal CGAL - * The \ref alpha_complex data structure, \ref bottleneck_distance, and few examples requires CGAL, which is a C++ - * library which provides easy access to efficient and reliable geometric algorithms. - * - * \note There is no need to install CGAL, you can just <CODE>cmake . && make</CODE> CGAL (or even - * <CODE>cmake -DCGAL_HEADER_ONLY=ON .</CODE> for CGAL version ≥ 4.8.0), thereafter you will be able to compile - * GUDHI by calling <CODE>cmake -DCGAL_DIR=/your/path/to/CGAL-X.Y .. && make</CODE> - * - * Having CGAL version 4.4.0 or higher installed is recommended. The procedure to install this library according to - * your operating system is detailed here http://doc.cgal.org/latest/Manual/installation.html - * - * The following examples require the <a target="_blank" href="http://www.cgal.org/">Computational Geometry Algorithms - * Library</a> (CGAL \cite cgal:eb-15b) and will not be built if CGAL is not installed: - * \li <a href="_persistent_cohomology_2alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2exact_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/exact_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/weighted_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html"> - * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> - * - * The following example requires CGAL version ≥ 4.6.0: - * \li <a href="_witness_complex_2witness_complex_sphere_8cpp-example.html"> - * Witness_complex/witness_complex_sphere.cpp</a> - * - * The following example requires CGAL version ≥ 4.7.0: - * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_off.cpp</a> - * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_points.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/periodic_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> - * Persistent_cohomology/custom_persistence_sort.cpp</a> - * - * The following example requires CGAL version ≥ 4.8.1: - * \li <a href="_bottleneck_distance_2alpha_rips_persistence_bottleneck_distance_8cpp-example.html"> - * Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp.cpp</a> - * \li <a href="_bottleneck_distance_2bottleneck_basic_example_8cpp-example.html"> - * Bottleneck_distance/bottleneck_basic_example.cpp</a> - * \li <a href="_bottleneck_distance_2bottleneck_read_file_example_8cpp-example.html"> - * Bottleneck_distance/bottleneck_read_file_example.cpp</a> - * \li <a href="_spatial_searching_2example_spatial_searching_8cpp-example.html"> - * Spatial_searching/example_spatial_searching.cpp</a> - * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html"> - * Subsampling/example_choose_n_farthest_points.cpp</a> - * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html"> - * Subsampling/example_custom_kernel.cpp</a> - * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html"> - * Subsampling/example_pick_n_random_points.cpp</a> - * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html"> - * Subsampling/example_sparsify_point_set.cpp</a> - * \li <a href="_tangential_complex_2example_basic_8cpp-example.html"> - * Tangential_complex/example_basic.cpp</a> - * \li <a href="_tangential_complex_2example_with_perturb_8cpp-example.html"> - * Tangential_complex/example_with_perturb.cpp</a> - * - * \subsection eigen3 Eigen3 - * The \ref alpha_complex data structure and few examples requires - * <a target="_blank" href="http://eigen.tuxfamily.org/">Eigen3</a> is a C++ template library for linear algebra: - * matrices, vectors, numerical solvers, and related algorithms. - * - * The following example requires the <a target="_blank" href="http://eigen.tuxfamily.org/">Eigen3</a> and will not be - * built if Eigen3 is not installed: - * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_off.cpp</a> - * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_points.cpp</a> - * \li <a href="_bottleneck_distance_2alpha_rips_persistence_bottleneck_distance_8cpp-example.html"> - * Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/periodic_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> - * Persistent_cohomology/custom_persistence_sort.cpp</a> - * \li <a href="_spatial_searching_2example_spatial_searching_8cpp-example.html"> - * Spatial_searching/example_spatial_searching.cpp</a> - * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html"> - * Subsampling/example_choose_n_farthest_points.cpp</a> - * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html"> - * Subsampling/example_custom_kernel.cpp</a> - * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html"> - * Subsampling/example_pick_n_random_points.cpp</a> - * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html"> - * Subsampling/example_sparsify_point_set.cpp</a> - * \li <a href="_tangential_complex_2example_basic_8cpp-example.html"> - * Tangential_complex/example_basic.cpp</a> - * \li <a href="_tangential_complex_2example_with_perturb_8cpp-example.html"> - * Tangential_complex/example_with_perturb.cpp</a> - * - * \subsection tbb Threading Building Blocks - * <a target="_blank" href="https://www.threadingbuildingblocks.org/">Intel® TBB</a> lets you easily write parallel - * C++ programs that take full advantage of multicore performance, that are portable and composable, and that have - * future-proof scalability. - * - * Having Intel® TBB installed is recommended to parallelize and accelerate some GUDHI computations. - * - * The following examples are using Intel® TBB if installed: - * \li <a href="_alpha_complex_2_alpha_complex_from_off_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_off.cpp</a> - * \li <a href="_alpha_complex_2_alpha_complex_from_points_8cpp-example.html"> - * Alpha_complex/Alpha_complex_from_points.cpp</a> - * \li <a href="_bitmap_cubical_complex_2_bitmap_cubical_complex_8cpp-example.html"> - * Bitmap_cubical_complex/Bitmap_cubical_complex.cpp</a> - * \li <a href="_bitmap_cubical_complex_2_bitmap_cubical_complex_periodic_boundary_conditions_8cpp-example.html"> - * Bitmap_cubical_complex/Bitmap_cubical_complex_periodic_boundary_conditions.cpp</a> - * \li <a href="_bitmap_cubical_complex_2_random_bitmap_cubical_complex_8cpp-example.html"> - * Bitmap_cubical_complex/Random_bitmap_cubical_complex.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_persistence.cpp</a> - * \li <a href="_simplex_tree_2simple_simplex_tree_8cpp-example.html"> - * Simplex_tree/simple_simplex_tree.cpp</a> - * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html"> - * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> - * \li <a href="_simplex_tree_2simplex_tree_from_cliques_of_graph_8cpp-example.html"> - * Simplex_tree/simplex_tree_from_cliques_of_graph.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2alpha_complex_persistence_8cpp-example.html"> - * Persistent_cohomology/alpha_complex_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2rips_persistence_via_boundary_matrix_8cpp-example.html"> - * Persistent_cohomology/rips_persistence_via_boundary_matrix.cpp</a> - * \li <a href="_persistent_cohomology_2persistence_from_file_8cpp-example.html"> - * Persistent_cohomology/persistence_from_file.cpp</a> - * \li <a href="_persistent_cohomology_2persistence_from_simple_simplex_tree_8cpp-example.html"> - * Persistent_cohomology/persistence_from_simple_simplex_tree.cpp</a> - * \li <a href="_persistent_cohomology_2plain_homology_8cpp-example.html"> - * Persistent_cohomology/plain_homology.cpp</a> - * \li <a href="_persistent_cohomology_2rips_distance_matrix_persistence_8cpp-example.html"> - * Persistent_cohomology/rips_distance_matrix_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2rips_multifield_persistence_8cpp-example.html"> - * Persistent_cohomology/rips_multifield_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2rips_persistence_8cpp-example.html"> - * Persistent_cohomology/rips_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2rips_persistence_step_by_step_8cpp-example.html"> - * Persistent_cohomology/rips_persistence_step_by_step.cpp</a> - * \li <a href="_persistent_cohomology_2exact_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/exact_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2weighted_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/weighted_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2periodic_alpha_complex_3d_persistence_8cpp-example.html"> - * Persistent_cohomology/periodic_alpha_complex_3d_persistence.cpp</a> - * \li <a href="_persistent_cohomology_2custom_persistence_sort_8cpp-example.html"> - * Persistent_cohomology/custom_persistence_sort.cpp</a> - * \li <a href="_rips_complex_2example_one_skeleton_rips_from_points_8cpp-example.html"> - * Rips_complex/example_one_skeleton_rips_from_points.cpp</a> - * \li <a href="_rips_complex_2example_rips_complex_from_off_file_8cpp-example.html"> - * Rips_complex/example_rips_complex_from_off_file.cpp</a> - * - * \section Contributions Bug reports and contributions - * Please help us improving the quality of the GUDHI library. You may report bugs or suggestions to: - * \verbatim Contact: gudhi-users@lists.gforge.inria.fr \endverbatim - * - * GUDHI is open to external contributions. If you want to join our development team, please contact us. - * -*/ - -/*! \page Citation Acknowledging the GUDHI library - * We kindly ask users to cite the GUDHI library as appropriately as possible in their papers, and to mention the use - * of the GUDHI library on the web pages of their projects using GUDHI and provide us with links to these web pages. - * Feel free to contact us in case you have any question or remark on this topic. - * - * We provide \ref GudhiBibtex entries for the modules of the User and Reference Manual, as well as for publications - * directly related to the GUDHI library. - * \section GudhiBibtex GUDHI bibtex - * \verbinclude biblio/how_to_cite_gudhi.bib -*/ - -// List of GUDHI examples - Doxygen needs at least a file tag to analyse comments -/*! @file Examples - * @example Alpha_complex/Alpha_complex_from_off.cpp - * @example Alpha_complex/Alpha_complex_from_points.cpp - * @example Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp - * @example Bottleneck_distance/bottleneck_basic_example.cpp - * @example Bottleneck_distance/bottleneck_read_file_example.cpp - * @example Bitmap_cubical_complex/Bitmap_cubical_complex.cpp - * @example Bitmap_cubical_complex/Bitmap_cubical_complex_periodic_boundary_conditions.cpp - * @example Bitmap_cubical_complex/Random_bitmap_cubical_complex.cpp - * @example common/example_CGAL_3D_points_off_reader.cpp - * @example common/example_CGAL_points_off_reader.cpp - * @example Contraction/Garland_heckbert.cpp - * @example Contraction/Rips_contraction.cpp - * @example Persistent_cohomology/alpha_complex_3d_persistence.cpp - * @example Persistent_cohomology/alpha_complex_persistence.cpp - * @example Persistent_cohomology/rips_persistence_via_boundary_matrix.cpp - * @example Persistent_cohomology/exact_alpha_complex_3d_persistence.cpp - * @example Persistent_cohomology/weighted_alpha_complex_3d_persistence.cpp - * @example Persistent_cohomology/periodic_alpha_complex_3d_persistence.cpp - * @example Persistent_cohomology/persistence_from_file.cpp - * @example Persistent_cohomology/persistence_from_simple_simplex_tree.cpp - * @example Persistent_cohomology/plain_homology.cpp - * @example Persistent_cohomology/rips_multifield_persistence.cpp - * @example Persistent_cohomology/rips_distance_matrix_persistence.cpp - * @example Persistent_cohomology/rips_persistence.cpp - * @example Persistent_cohomology/custom_persistence_sort.cpp - * @example Persistent_cohomology/rips_persistence_step_by_step.cpp - * @example Rips_complex/example_one_skeleton_rips_from_points.cpp - * @example Rips_complex/example_rips_complex_from_off_file.cpp - * @example Simplex_tree/mini_simplex_tree.cpp - * @example Simplex_tree/simple_simplex_tree.cpp - * @example Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp - * @example Simplex_tree/simplex_tree_from_cliques_of_graph.cpp - * @example Skeleton_blocker/Skeleton_blocker_from_simplices.cpp - * @example Skeleton_blocker/Skeleton_blocker_iteration.cpp - * @example Skeleton_blocker/Skeleton_blocker_link.cpp - * @example Spatial_searching/example_spatial_searching.cpp - * @example Subsampling/example_choose_n_farthest_points.cpp - * @example Subsampling/example_custom_kernel.cpp - * @example Subsampling/example_pick_n_random_points.cpp - * @example Subsampling/example_sparsify_point_set.cpp - * @example Tangential_complex/example_basic.cpp - * @example Tangential_complex/example_with_perturb.cpp - * @example Witness_complex/example_nearest_landmark_table.cpp - * @example Witness_complex/example_strong_witness_complex_off.cpp - * @example Witness_complex/example_strong_witness_persistence.cpp - * @example Witness_complex/example_witness_complex_off.cpp - * @example Witness_complex/example_witness_complex_persistence.cpp - * @example Witness_complex/example_witness_complex_sphere.cpp - */ - |
