diff options
author | vrouvrea <vrouvrea@636b058d-ea47-450e-bf9e-a15bfbe3eedb> | 2017-12-06 08:13:32 +0000 |
---|---|---|
committer | vrouvrea <vrouvrea@636b058d-ea47-450e-bf9e-a15bfbe3eedb> | 2017-12-06 08:13:32 +0000 |
commit | 9c0ff374057baf19d3ea1147553b68f5293074ac (patch) | |
tree | 007f17b1fd37ef7f689a63d4ebcaf9fa409d76ee /src | |
parent | 841c4db0448687a61c25bd57729ae0cad1ae2b72 (diff) | |
parent | 86f7c676f094e44d4c06392c452b372f4470099b (diff) |
Merge add_utils_in_gudhi_v2 branch after 2nd round of review
git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/trunk@3041 636b058d-ea47-450e-bf9e-a15bfbe3eedb
Former-commit-id: ad134cc2b6756e20afc8d9db9e40c5af87d09f9d
Diffstat (limited to 'src')
13 files changed, 282 insertions, 266 deletions
diff --git a/src/Alpha_complex/utilities/README b/src/Alpha_complex/utilities/README index c3dd170b..1cd2ca95 100644 --- a/src/Alpha_complex/utilities/README +++ b/src/Alpha_complex/utilities/README @@ -1,172 +1,177 @@ -# Alpha_complex # - -## `alpha_complex_3d_persistence` ## -This program computes the persistent homology with coefficient field Z/pZ of the 3D alpha complex built from a 3D point cloud. The output diagram contains one bar per line, written with the convention: - -`p dim b d` - -where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number). - -**Usage** -`alpha_complex_3d_persistence [options] <OFF input file>` - -**Allowed options** -* `-h [ --help ]` Produce help message -* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output. -* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology. -* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. - -**Example** -`alpha_complex_3d_persistence ../../data/points/tore3D_300.off -p 2 -m 0.45` - -outputs: -``` -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 -``` - -Here we retrieve expected Betti numbers on a tore 3D: -``` -Betti numbers[0] = 1 -Betti numbers[1] = 2 -Betti numbers[2] = 1 -``` - -N.B.: -* `alpha_complex_3d_persistence` only accepts OFF files in dimension 3. -* Filtration values are alpha square values. - - - -## `exact_alpha_complex_3d_persistence` ## -Same as `alpha_complex_3d_persistence`, but using exact computation. It is slower, but it is necessary when points are on a grid for instance. - - - -## `weighted_alpha_complex_3d_persistence` ## -Same as `alpha_complex_3d_persistence`, but using weighted points. - -**Usage** -`weighted_alpha_complex_3d_persistence [options] <OFF input file> <weights input file>` - -**Allowed options** -* `-h [ --help ]` Produce help message -* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output. -* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology. -* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. - -**Example** -`weighted_alpha_complex_3d_persistence ../../data/points/tore3D_300.off ../../data/points/tore3D_300.weights -p 2 -m 0.45` - -outputs: -``` -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 -``` - -N.B.: -* Weights values are explained on CGAL [Alpha shape](https://doc.cgal.org/latest/Alpha_shapes_3/index.html#title0) -and [Regular triangulation](https://doc.cgal.org/latest/Triangulation_3/index.html#Triangulation3secclassRegulartriangulation) documentation. -* Filtration values are alpha square values. - - -## `periodic_alpha_complex_3d_persistence` ## -Same as `alpha_complex_3d_persistence`, but using periodic alpha shape 3d. - -**Usage** -`periodic_alpha_complex_3d_persistence <input OFF file> <cuboid file> <p> <min_persistence>` -where -`<input OFF file>` is the path to the input point cloud in OFF format. -`<cuboid file>` is the path to the file describing the periodic domain. It must be in the format described [here](http://gudhi.gforge.inria.fr/doc/latest/fileformats.html#FileFormatsIsoCuboid). -`<p>` is the characteristic p of the coefficient field *Z/pZ* for computing homology. It must be a stricly positive integer. -`<min_persistence>` is the minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. - -**Usage** -`./periodic_alpha_complex_3d_persistence [options] input-file cuboid-file` - -**Allowed options** -* `-h [ --help ]` Produce help message -* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output. -* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology. -* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals - - -**Example** -`periodic_alpha_complex_3d_persistence ../../data/points/grid_10_10_10_in_0_1.off ../../data/points/iso_cuboid_3_in_0_1.txt -p 3 -m 1.0` - -outputs: -``` -Periodic Delaunay computed. -Simplex_tree dim: 3 -3 0 0 inf -3 1 0.0025 inf -3 1 0.0025 inf -3 1 0.0025 inf -3 2 0.005 inf -3 2 0.005 inf -3 2 0.005 inf -3 3 0.0075 inf -``` - -Here we retrieve expected Betti numbers on an 3D iso-oriented cuboids: -``` -Betti numbers[0] = 1 -Betti numbers[1] = 3 -Betti numbers[2] = 3 -Betti numbers[3] = 1 -``` - -N.B.: -* Cuboid file must be in the format described [here](http://gudhi.gforge.inria.fr/doc/latest/fileformats.html#FileFormatsIsoCuboid). -* Filtration values are alpha square values. - - - - -## `alpha_complex_persistence` ## -This program computes the persistent homology with coefficient field Z/pZ of the dD alpha complex built from a dD point cloud. The output diagram contains one bar per line, written with the convention: - -`p dim b d` - -where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number). - -**Usage** -`alpha_complex_persistence [options] <OFF input file>` - -**Allowed options** - -* `-h [ --help ]` Produce help message -* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output. -* `-r [ --max-alpha-square-value ]` (default = inf) Maximal alpha square value for the Alpha complex construction. -* `-p [ --field-charac ]` (default = 11) Characteristic p of the coefficient field Z/pZ for computing homology. -* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. - -**Example** -`alpha_complex_persistence -r 32 -p 2 -m 0.45 ../../data/points/tore3D_300.off` - -outputs: -``` -Alpha complex is of dimension 3 - 9273 simplices - 300 vertices. -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 -``` - -Here we retrieve expected Betti numbers on a tore 3D: -``` -Betti numbers[0] = 1 -Betti numbers[1] = 2 -Betti numbers[2] = 1 -``` - -N.B.: -* `alpha_complex_persistence` only accepts OFF files in dimension d. -* Filtration values are alpha square values. +# Alpha_complex #
+
+## `alpha_complex_3d_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the 3D alpha complex built from a 3D point cloud. The output diagram contains one bar per line, written with the convention:
+
+`p dim birth death`
+
+where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number).
+
+**Usage**
+`alpha_complex_3d_persistence [options] <input OFF file>`
+where
+`<input OFF file>` is the path to the input point cloud in [nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output.
+* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology.
+* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals.
+
+**Example**
+`alpha_complex_3d_persistence ../../data/points/tore3D_300.off -p 2 -m 0.45`
+
+outputs:
+```
+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
+```
+
+Here we retrieve expected Betti numbers on a tore 3D:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 2
+Betti numbers[2] = 1
+```
+
+N.B.:
+* `alpha_complex_3d_persistence` only accepts OFF files in dimension 3.
+* Filtration values are alpha square values.
+
+
+
+## `exact_alpha_complex_3d_persistence` ##
+Same as `alpha_complex_3d_persistence`, but using exact computation. It is slower, but it is necessary when points are on a grid for instance.
+
+
+
+## `weighted_alpha_complex_3d_persistence` ##
+Same as `alpha_complex_3d_persistence`, but using weighted points.
+
+**Usage**
+`weighted_alpha_complex_3d_persistence [options] <input OFF file> <weights input file>`
+where
+`<input OFF file>` is the path to the input point cloud in [nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+`<input weights file>` is the path to the file containing the weights of the points (one value per line).
+
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output.
+* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology.
+* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals.
+
+**Example**
+`weighted_alpha_complex_3d_persistence ../../data/points/tore3D_300.off ../../data/points/tore3D_300.weights -p 2 -m 0.45`
+
+outputs:
+```
+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
+```
+
+N.B.:
+* Weights values are explained on CGAL [Alpha shape](https://doc.cgal.org/latest/Alpha_shapes_3/index.html#title0)
+and [Regular triangulation](https://doc.cgal.org/latest/Triangulation_3/index.html#Triangulation3secclassRegulartriangulation) documentation.
+* Filtration values are alpha square values.
+
+
+## `periodic_alpha_complex_3d_persistence` ##
+Same as `alpha_complex_3d_persistence`, but using periodic alpha shape 3d.
+Refer to the [CGAL's 3D Periodic Triangulations User Manual](https://doc.cgal.org/latest/Periodic_3_triangulation_3/index.html) for more details.
+
+**Usage**
+`periodic_alpha_complex_3d_persistence [options] <input OFF file> <cuboid file>`
+where
+`<input OFF file>` is the path to the input point cloud in [nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+`<cuboid file>` is the path to the file describing the periodic domain. It must be in the format described [here](http://gudhi.gforge.inria.fr/doc/latest/fileformats.html#FileFormatsIsoCuboid).
+
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output.
+* `-p [ --field-charac ]` (default=11) Characteristic p of the coefficient field Z/pZ for computing homology.
+* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals
+
+
+**Example**
+`periodic_alpha_complex_3d_persistence ../../data/points/grid_10_10_10_in_0_1.off ../../data/points/iso_cuboid_3_in_0_1.txt -p 3 -m 1.0`
+
+outputs:
+```
+Periodic Delaunay computed.
+Simplex_tree dim: 3
+3 0 0 inf
+3 1 0.0025 inf
+3 1 0.0025 inf
+3 1 0.0025 inf
+3 2 0.005 inf
+3 2 0.005 inf
+3 2 0.005 inf
+3 3 0.0075 inf
+```
+
+Here we retrieve expected Betti numbers on an 3D iso-oriented cuboids:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 3
+Betti numbers[2] = 3
+Betti numbers[3] = 1
+```
+
+N.B.:
+* Cuboid file must be in the format described [here](http://gudhi.gforge.inria.fr/doc/latest/fileformats.html#FileFormatsIsoCuboid).
+* Filtration values are alpha square values.
+
+
+
+
+## `alpha_complex_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the dD alpha complex built from a dD point cloud. The output diagram contains one bar per line, written with the convention:
+
+`p dim birth death`
+
+where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number).
+
+**Usage**
+`alpha_complex_persistence [options] <input OFF file>`
+where
+`<input OFF file>` is the path to the input point cloud in [nOFF ASCII format](http://www.geomview.org/docs/html/OFF.html).
+
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. Default print in standard output.
+* `-r [ --max-alpha-square-value ]` (default = inf) Maximal alpha square value for the Alpha complex construction.
+* `-p [ --field-charac ]` (default = 11) Characteristic p of the coefficient field Z/pZ for computing homology.
+* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals.
+
+**Example**
+`alpha_complex_persistence -r 32 -p 2 -m 0.45 ../../data/points/tore3D_300.off`
+
+outputs:
+```
+Alpha complex is of dimension 3 - 9273 simplices - 300 vertices.
+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
+```
+
+Here we retrieve expected Betti numbers on a tore 3D:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 2
+Betti numbers[2] = 1
+```
+
+N.B.:
+* Filtration values are alpha square values.
diff --git a/src/Bitmap_cubical_complex/doc/Gudhi_Cubical_Complex_doc.h b/src/Bitmap_cubical_complex/doc/Gudhi_Cubical_Complex_doc.h index daba15a4..ee84e201 100644 --- a/src/Bitmap_cubical_complex/doc/Gudhi_Cubical_Complex_doc.h +++ b/src/Bitmap_cubical_complex/doc/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,26 +100,8 @@ 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 and utilities/Bitmap_cubical_complex folders. * diff --git a/src/Bitmap_cubical_complex/utilities/CMakeLists.txt b/src/Bitmap_cubical_complex/utilities/CMakeLists.txt index f0f80059..676a730a 100644 --- a/src/Bitmap_cubical_complex/utilities/CMakeLists.txt +++ b/src/Bitmap_cubical_complex/utilities/CMakeLists.txt @@ -1,29 +1,29 @@ cmake_minimum_required(VERSION 2.6) project(Bitmap_cubical_complex_utilities) -add_executable ( Bitmap_cubical_complex Bitmap_cubical_complex.cpp ) +add_executable ( cubical_complex_persistence cubical_complex_persistence.cpp ) if (TBB_FOUND) - target_link_libraries(Bitmap_cubical_complex ${TBB_LIBRARIES}) + target_link_libraries(cubical_complex_persistence ${TBB_LIBRARIES}) endif() -add_test(NAME Bitmap_cubical_complex_utility_persistence_one_sphere COMMAND $<TARGET_FILE:Bitmap_cubical_complex> +add_test(NAME Bitmap_cubical_complex_utility_persistence_one_sphere COMMAND $<TARGET_FILE:cubical_complex_persistence> "${CMAKE_SOURCE_DIR}/data/bitmap/CubicalOneSphere.txt") -add_test(NAME Bitmap_cubical_complex_utility_persistence_two_sphere COMMAND $<TARGET_FILE:Bitmap_cubical_complex> +add_test(NAME Bitmap_cubical_complex_utility_persistence_two_sphere COMMAND $<TARGET_FILE:cubical_complex_persistence> "${CMAKE_SOURCE_DIR}/data/bitmap/CubicalTwoSphere.txt") -add_executable ( Bitmap_cubical_complex_periodic_boundary_conditions Bitmap_cubical_complex_periodic_boundary_conditions.cpp ) +add_executable ( periodic_cubical_complex_persistence periodic_cubical_complex_persistence.cpp ) if (TBB_FOUND) - target_link_libraries(Bitmap_cubical_complex_periodic_boundary_conditions ${TBB_LIBRARIES}) + target_link_libraries(periodic_cubical_complex_persistence ${TBB_LIBRARIES}) endif() add_test(NAME Bitmap_cubical_complex_utility_periodic_boundary_conditions_2d_torus - COMMAND $<TARGET_FILE:Bitmap_cubical_complex_periodic_boundary_conditions> + COMMAND $<TARGET_FILE:periodic_cubical_complex_persistence> "${CMAKE_SOURCE_DIR}/data/bitmap/2d_torus.txt") add_test(NAME Bitmap_cubical_complex_utility_periodic_boundary_conditions_3d_torus - COMMAND $<TARGET_FILE:Bitmap_cubical_complex_periodic_boundary_conditions> + COMMAND $<TARGET_FILE:periodic_cubical_complex_persistence> "${CMAKE_SOURCE_DIR}/data/bitmap/3d_torus.txt") -install(TARGETS Bitmap_cubical_complex DESTINATION bin) -install(TARGETS Bitmap_cubical_complex_periodic_boundary_conditions DESTINATION bin) +install(TARGETS cubical_complex_persistence DESTINATION bin) +install(TARGETS periodic_cubical_complex_persistence DESTINATION bin) diff --git a/src/Bitmap_cubical_complex/utilities/README b/src/Bitmap_cubical_complex/utilities/README index d9085635..ddff7034 100644 --- a/src/Bitmap_cubical_complex/utilities/README +++ b/src/Bitmap_cubical_complex/utilities/README @@ -1,24 +1,18 @@ # Bitmap_cubical_complex #
-## `Bitmap_cubical_complex` ##
-This program computes persistent homology, by using the Bitmap_cubical_complex class, of cubical complexes provided in text files in Perseus style. The only number in the first line is a dimension D of a bitmap. In the lines I between 2 and D+1 there are numbers of top dimensional cells in the direction I. Let N denote product of the numbers in the lines between 2 and D. In the lines D+2 to D+2+N there are filtrations of top dimensional cells. We assume that the cells are in the lexicographical order.
+## `cubical_complex_persistence` ##
+This program computes persistent homology, by using the Bitmap_cubical_complex class, of cubical complexes provided in text files in Perseus style. See [here](http://gudhi.gforge.inria.fr/doc/latest/fileformats.html#FileFormatsPerseus) for a description of the file format.
-Examples:
+Example:
-* Create a Cubical Complex from the Perseus style file CubicalOneSphere.txt, computes Persistence cohomology from it and writes the results in a persistence file:
-`Bitmap_cubical_complex data/bitmap/CubicalOneSphere.txt`
+* Create a Cubical Complex from the Perseus style file `CubicalTwoSphere.txt`, computes Persistence cohomology from it and writes the results in a persistence file `CubicalTwoSphere.txt_persistence`:
+`cubical_complex_persistence data/bitmap/CubicalTwoSphere.txt`
-* Create a Cubical Complex from the Perseus style file CubicalTwoSphere.txt, computes Persistence cohomology from it and writes the results in a persistence file:
-`Bitmap_cubical_complex data/bitmap/CubicalTwoSphere.txt`
-
-## `Bitmap_cubical_complex_periodic_boundary_conditions` ##
+## `periodic_cubical_complex_persistence` ##
Same as above, but with periodic boundary conditions.
-Examples:
-
-* Create a Periodical Cubical Complex from the Perseus style file 2d_torus.txt, computes Persistence cohomology from it and writes the results in a persistence file:
-`Bitmap_cubical_complex_periodic_boundary_conditions.exe data/bitmap/2d_torus.txt`
+Example:
-* Create a Periodical Cubical Complex from the Perseus style file 3d_torus.txt, computes Persistence cohomology from it and writes the results in a persistence file:
-`Bitmap_cubical_complex_periodic_boundary_conditions.exe data/bitmap/3d_torus.txt`
+* Create a Periodical Cubical Complex from the Perseus style file `3d_torus.txt`, computes Persistence cohomology from it and writes the results in a persistence file `3d_torus.txt_persistence`:
+`periodic_cubical_complex_persistence data/bitmap/3d_torus.txt`
diff --git a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp b/src/Bitmap_cubical_complex/utilities/cubical_complex_persistence.cpp index 9d1bc08c..9d1bc08c 100644 --- a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp +++ b/src/Bitmap_cubical_complex/utilities/cubical_complex_persistence.cpp diff --git a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp b/src/Bitmap_cubical_complex/utilities/periodic_cubical_complex_persistence.cpp index c812cb3a..c812cb3a 100644 --- a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp +++ b/src/Bitmap_cubical_complex/utilities/periodic_cubical_complex_persistence.cpp diff --git a/src/Bottleneck_distance/example/README b/src/Bottleneck_distance/example/README index 0e314608..01bcd74a 100644 --- a/src/Bottleneck_distance/example/README +++ b/src/Bottleneck_distance/example/README @@ -3,9 +3,9 @@ ## `alpha_rips_persistence_bottleneck_distance` ##
This program computes the persistent homology with coefficient field Z/pZ of a Rips complex defined on a set of input points. The output diagram contains one bar per line, written with the convention:
-`p dim b d`
+`p dim birth death`
-where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
+where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
Usage:
`alpha_rips_persistence_bottleneck_distance [options] <OFF input file>`
diff --git a/src/Bottleneck_distance/utilities/CMakeLists.txt b/src/Bottleneck_distance/utilities/CMakeLists.txt index 063b6ae3..d19e3b1c 100644 --- a/src/Bottleneck_distance/utilities/CMakeLists.txt +++ b/src/Bottleneck_distance/utilities/CMakeLists.txt @@ -2,15 +2,15 @@ cmake_minimum_required(VERSION 2.6) project(Bottleneck_distance_utilities) if (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.8.1) - add_executable (bottleneck_read_file bottleneck_read_file.cpp) + add_executable (bottleneck_distance bottleneck_distance.cpp) if (TBB_FOUND) - target_link_libraries(bottleneck_read_file ${TBB_LIBRARIES}) + target_link_libraries(bottleneck_distance ${TBB_LIBRARIES}) endif(TBB_FOUND) add_test(NAME Bottleneck_distance_utilities_Bottleneck_read_file - COMMAND $<TARGET_FILE:bottleneck_read_file> + COMMAND $<TARGET_FILE:bottleneck_distance> "${CMAKE_SOURCE_DIR}/data/persistence_diagram/first.pers" "${CMAKE_SOURCE_DIR}/data/persistence_diagram/second.pers") - install(TARGETS bottleneck_read_file DESTINATION bin) + install(TARGETS bottleneck_distance DESTINATION bin) endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.8.1) diff --git a/src/Bottleneck_distance/utilities/bottleneck_read_file.cpp b/src/Bottleneck_distance/utilities/bottleneck_distance.cpp index 9dd52b31..9dd52b31 100644 --- a/src/Bottleneck_distance/utilities/bottleneck_read_file.cpp +++ b/src/Bottleneck_distance/utilities/bottleneck_distance.cpp diff --git a/src/Rips_complex/utilities/README b/src/Rips_complex/utilities/README index ca10424d..4d20c806 100644 --- a/src/Rips_complex/utilities/README +++ b/src/Rips_complex/utilities/README @@ -3,9 +3,9 @@ ## `rips_persistence` ## This program computes the persistent homology with coefficient field *Z/pZ* of a Rips complex defined on a set of input points. The output diagram contains one bar per line, written with the convention: -`p dim b d` +`p dim birth death` -where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number). +where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p` must be a prime number). **Usage** `rips_persistence [options] <OFF input file>` @@ -19,6 +19,8 @@ where `dim` is the dimension of the homological feature, `b` and `d` are respect * `-p [ --field-charac ]` (default = 11) Characteristic p of the coefficient field Z/pZ for computing homology. * `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. +Beware: this program may use a lot of RAM and take a lot of time if `max-edge-length` is set to a large value. + **Example 1 with Z/2Z coefficients** `rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 2` @@ -46,7 +48,12 @@ outputs: ## `rips_distance_matrix_persistence` ## -Same as `rips_persistence` but taking a distance matrix as input. +Same as `rips_persistence` but taking a distance matrix as input.
+
+**Usage** +`rips_persistence [options] <CSV input file>`
+where
+`<CSV input file>` is the path to the file containing a distance matrix. Can be square or lower triangular matrix. Separator is ';'. **Example** `rips_distance_matrix_persistence data/distance_matrix/full_square_distance_matrix.csv -r 15 -d 3 -p 3 -m 0` diff --git a/src/Witness_complex/utilities/README b/src/Witness_complex/utilities/README index d8dc9ca7..1141033e 100644 --- a/src/Witness_complex/utilities/README +++ b/src/Witness_complex/utilities/README @@ -1,11 +1,13 @@ # Witness_complex #
+For more details about the witness complex, please read the [user manual of the package](http://gudhi.gforge.inria.fr/doc/latest/group__witness__complex.html).
+
## `weak_witness_persistence` ##
This program computes the persistent homology with coefficient field *Z/pZ* of a Weak witness complex defined on a set of input points. The output diagram contains one bar per line, written with the convention:
-`p dim b d`
+`p dim birth death`
-where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
+where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
*Usage*
`weak_witness_persistence [options] <OFF input file>`
@@ -39,9 +41,9 @@ N.B.: output is random as the 20 landmarks are chosen randomly. ## `strong_witness_persistence` ##
This program computes the persistent homology with coefficient field *Z/pZ* of a Strong witness complex defined on a set of input points. The output diagram contains one bar per line, written with the convention:
-`p dim b d`
+`p dim birth death`
-where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
+where `dim` is the dimension of the homological feature, `birth` and `death` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients.
*Usage*
`strong_witness_persistence [options] <OFF input file>`
diff --git a/src/common/doc/file_formats.h b/src/common/doc/file_formats.h index 3b3d9248..d06b81f5 100644 --- a/src/common/doc/file_formats.h +++ b/src/common/doc/file_formats.h @@ -57,10 +57,10 @@ namespace Gudhi { \section FileFormatsIsoCuboid Iso-cuboid - Such a file describes an iso-oriented cuboid with diagonal opposite vertices (min_hx, min_hy, min_hz,...) and (max_hx, max_hy, max_hz, ...). The format is:<br> + 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_hx min_hy [min_hz ...] - max_hx max_hy [max_hz ...] + min_x min_y [min_z ...] + max_x max_y [max_z ...] \endverbatim Here is a simple sample file in the 3D case: @@ -68,6 +68,55 @@ namespace Gudhi { -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. + */ } // namespace Gudhi diff --git a/src/common/doc/main_page.h b/src/common/doc/main_page.h index 34d3893d..72ef191d 100644 --- a/src/common/doc/main_page.h +++ b/src/common/doc/main_page.h @@ -328,7 +328,7 @@ make doxygen * \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_read_file.cpp</a> + * Bottleneck_distance/bottleneck_distance.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"> @@ -411,9 +411,9 @@ make doxygen * \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/Bitmap_cubical_complex.cpp</a> + * 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/Bitmap_cubical_complex_periodic_boundary_conditions.cpp</a> + * 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="_simplex_tree_2simple_simplex_tree_8cpp-example.html"> @@ -491,9 +491,9 @@ make doxygen * @example Alpha_complex/weighted_alpha_complex_3d_persistence.cpp * @example Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp * @example Bottleneck_distance/bottleneck_basic_example.cpp - * @example Bottleneck_distance/bottleneck_read_file.cpp - * @example Bitmap_cubical_complex/Bitmap_cubical_complex.cpp - * @example Bitmap_cubical_complex/Bitmap_cubical_complex_periodic_boundary_conditions.cpp + * @example Bottleneck_distance/bottleneck_distance.cpp + * @example Bitmap_cubical_complex/cubical_complex_persistence.cpp + * @example Bitmap_cubical_complex/periodic_cubical_complex_persistence.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 |