Document utilies in README files using Markdown + move/rename some utilities

Only missing doc for now: Garland_heckbert

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/add_utils_in_gudhi_v2@2752 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: 7ba0113762b6622130835dc9e372acfae29c2db8

19 files changed, 374 insertions, 173 deletions

diff --git a/src/Alpha_complex/utilities/CMakeLists.txt b/src/Alpha_complex/utilities/CMakeLists.txt
new file mode 100644
index 00000000..69dbc28a
--- /dev/null
+++ b/src/Alpha_complex/utilities/CMakeLists.txt
@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 2.6)
+project(Alpha_complex_utilities)
+
+if(CGAL_FOUND)
+  add_executable(alpha_complex_3d_persistence alpha_complex_3d_persistence.cpp)
+  target_link_libraries(alpha_complex_3d_persistence ${CGAL_LIBRARY})
+
+  if (TBB_FOUND)
+    target_link_libraries(alpha_complex_3d_persistence ${TBB_LIBRARIES})
+  endif(TBB_FOUND)
+  add_test(NAME Alpha_complex_utilities_alpha_complex_3d_persistence COMMAND $<TARGET_FILE:alpha_complex_3d_persistence>
+      "${CMAKE_SOURCE_DIR}/data/points/tore3D_300.off" "2" "0.45")
+
+  install(TARGETS alpha_complex_3d_persistence DESTINATION bin)
+
+  if (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.7.0)
+    add_executable (alpha_complex_persistence alpha_complex_persistence.cpp)
+    target_link_libraries(alpha_complex_persistence
+        ${CGAL_LIBRARY} ${Boost_PROGRAM_OPTIONS_LIBRARY})
+
+    add_executable(periodic_alpha_complex_3d_persistence periodic_alpha_complex_3d_persistence.cpp)
+    target_link_libraries(periodic_alpha_complex_3d_persistence ${CGAL_LIBRARY})
+
+    if (TBB_FOUND)
+      target_link_libraries(alpha_complex_persistence ${TBB_LIBRARIES})
+      target_link_libraries(periodic_alpha_complex_3d_persistence ${TBB_LIBRARIES})
+    endif(TBB_FOUND)
+    add_test(NAME Alpha_complex_utilities_alpha_complex_persistence COMMAND $<TARGET_FILE:alpha_complex_persistence>
+        "${CMAKE_SOURCE_DIR}/data/points/tore3D_300.off" "-p" "2" "-m" "0.45")
+    add_test(NAME Alpha_complex_utilities_periodic_alpha_complex_3d_persistence COMMAND $<TARGET_FILE:periodic_alpha_complex_3d_persistence>
+        "${CMAKE_SOURCE_DIR}/data/points/grid_10_10_10_in_0_1.off" "${CMAKE_SOURCE_DIR}/data/points/iso_cuboid_3_in_0_1.txt" "2" "0")
+
+    install(TARGETS alpha_complex_persistence DESTINATION bin)
+    install(TARGETS periodic_alpha_complex_3d_persistence DESTINATION bin)
+
+  endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.7.0)
+endif(CGAL_FOUND)
diff --git a/src/Alpha_complex/utilities/README b/src/Alpha_complex/utilities/README
new file mode 100644
index 00000000..30e1b187
--- /dev/null
+++ b/src/Alpha_complex/utilities/README
@@ -0,0 +1,131 @@
+# 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 = p1*...*pr` is the product of prime numbers *pi* such that the homology feature exists in homology with *Z/piZ* coefficients).
+
+**Usage**
+`alpha_complex_3d_persistence <input OFF file> <p> <min_persistence>` 
+where
+`<input OFF file>` is the path to the input point cloud in OFF format.
+`<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. It must be a floating-point number >= -1.
+
+**Example**
+`alpha_complex_3d_persistence ../../data/points/tore3D_300.off 2 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.
+
+
+
+
+## `periodic_alpha_complex_3d_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the 3D periodic 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 = p1*...*pr` is the product of prime numbers *pi* such that the homology feature exists in homology with *Z/piZ* coefficients).
+
+**Usage**
+`periodic_alpha_complex_3d_persistence <input OFF file> <p> <min_persistence>`
+where
+`<input OFF file>` is the path to the input point cloud in OFF format.
+`<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. It must be a floating-point number >= -1.
+
+**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 3 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.: 
+* `periodic_alpha_complex_3d_persistence` only accepts OFF files in dimension 3.
+* In this example, the periodic cube is hard coded to { x = [0,1]; y = [0,1]; z = [0,1] }
+* 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 = p1*...*pr` is the product of prime numbers pi such that the homology feature exists in homology with Z/piZ coefficients).
+
+**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. By default, print in std::cout.
+* `-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.
diff --git a/src/Persistent_cohomology/utilities/alpha_complex_3d_helper.h b/src/Alpha_complex/utilities/alpha_complex_3d_helper.h
index 7865e4ec..7865e4ec 100644
--- a/src/Persistent_cohomology/utilities/alpha_complex_3d_helper.h
+++ b/src/Alpha_complex/utilities/alpha_complex_3d_helper.h
diff --git a/src/Persistent_cohomology/utilities/alpha_complex_3d_persistence.cpp b/src/Alpha_complex/utilities/alpha_complex_3d_persistence.cpp
index f63ff0f6..f63ff0f6 100644
--- a/src/Persistent_cohomology/utilities/alpha_complex_3d_persistence.cpp
+++ b/src/Alpha_complex/utilities/alpha_complex_3d_persistence.cpp
diff --git a/src/Persistent_cohomology/utilities/alpha_complex_persistence.cpp b/src/Alpha_complex/utilities/alpha_complex_persistence.cpp
index 9e84e91f..9e84e91f 100644
--- a/src/Persistent_cohomology/utilities/alpha_complex_persistence.cpp
+++ b/src/Alpha_complex/utilities/alpha_complex_persistence.cpp
diff --git a/src/Persistent_cohomology/utilities/periodic_alpha_complex_3d_persistence.cpp b/src/Alpha_complex/utilities/periodic_alpha_complex_3d_persistence.cpp
index 8140a3c5..8140a3c5 100644
--- a/src/Persistent_cohomology/utilities/periodic_alpha_complex_3d_persistence.cpp
+++ b/src/Alpha_complex/utilities/periodic_alpha_complex_3d_persistence.cpp
diff --git a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp b/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp
index 67735ba1..e126caea 100644
--- a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp
+++ b/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex.cpp
@@ -32,8 +32,8 @@
 #include <cstddef>
 
 int main(int argc, char** argv) {
-  std::cout << "This program computes persistent homology, by using bitmap_cubical_complex class, of cubical " <<
-      "complexes provided in text files in Perseus style (the only numbered in the first line is a dimension D of a" <<
+  std::cout << "This program computes persistent homology, by using the Bitmap_cubical_complex_base 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. See " <<
diff --git a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp b/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp
index 122160a2..7f9296a6 100644
--- a/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp
+++ b/src/Bitmap_cubical_complex/utilities/Bitmap_cubical_complex_periodic_boundary_conditions.cpp
@@ -33,9 +33,9 @@
 #include <string>
 
 int main(int argc, char** argv) {
-  std::cout << "This program computes persistent homology, by using " <<
+  std::cout << "This program computes persistent homology, by using the " <<
       "Bitmap_cubical_complex_periodic_boundary_conditions class, of cubical complexes provided in text files in " <<
-      "Perseus style (the only numbered in the first line is a dimension D of a bitmap. In the lines I between 2 " <<
+      "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. See CubicalOneSphere.txt or CubicalTwoSphere.txt for" <<
diff --git a/src/Bitmap_cubical_complex/utilities/README b/src/Bitmap_cubical_complex/utilities/README
new file mode 100644
index 00000000..d9085635
--- /dev/null
+++ b/src/Bitmap_cubical_complex/utilities/README
@@ -0,0 +1,24 @@
+# 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.

+

+Examples:

+

+* 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:

+`Bitmap_cubical_complex data/bitmap/CubicalTwoSphere.txt`

+

+## `Bitmap_cubical_complex_periodic_boundary_conditions` ##

+

+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`

+

+* 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`

diff --git a/src/Bottleneck_distance/utilities/README b/src/Bottleneck_distance/utilities/README
new file mode 100644
index 00000000..4c9b0735
--- /dev/null
+++ b/src/Bottleneck_distance/utilities/README
@@ -0,0 +1,19 @@
+# Bottleneck_distance #

+

+## `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`

+

+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.

+

+Usage:

+`alpha_rips_persistence_bottleneck_distance [options] <OFF input file>`

+

+Allowed options:

+

+* `-h [ --help ]` Produce help message

+* `-r [ --max-edge-length ]` (default = inf) Maximal length of an edge for the Rips complex construction.`

+* `-d [ --cpx-dimension ]` (default = 1) Maximal dimension of the Rips complex we want to compute.`

+* `-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.
\ No newline at end of file
diff --git a/src/Persistent_cohomology/utilities/CMakeLists.txt b/src/Persistent_cohomology/utilities/CMakeLists.txt
index c2f00da2..5b315801 100644
--- a/src/Persistent_cohomology/utilities/CMakeLists.txt
+++ b/src/Persistent_cohomology/utilities/CMakeLists.txt
@@ -20,37 +20,4 @@ add_test(NAME Persistent_cohomology_example_from_rips_on_tore_3D COMMAND $<TARGE
 install(TARGETS rips_distance_matrix_persistence DESTINATION bin)
 install(TARGETS rips_persistence DESTINATION bin)
 
-if(CGAL_FOUND)
-  add_executable(alpha_complex_3d_persistence alpha_complex_3d_persistence.cpp)
-  target_link_libraries(alpha_complex_3d_persistence ${CGAL_LIBRARY})
-
-  if (TBB_FOUND)
-    target_link_libraries(alpha_complex_3d_persistence ${TBB_LIBRARIES})
-  endif(TBB_FOUND)
-  add_test(NAME Persistent_cohomology_example_alpha_complex_3d COMMAND $<TARGET_FILE:alpha_complex_3d_persistence>
-      "${CMAKE_SOURCE_DIR}/data/points/tore3D_300.off" "2" "0.45")
-
-  install(TARGETS alpha_complex_3d_persistence DESTINATION bin)
-
-  if (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.7.0)
-    add_executable (alpha_complex_persistence alpha_complex_persistence.cpp)
-    target_link_libraries(alpha_complex_persistence
-        ${CGAL_LIBRARY} ${Boost_PROGRAM_OPTIONS_LIBRARY})
-
-    add_executable(periodic_alpha_complex_3d_persistence periodic_alpha_complex_3d_persistence.cpp)
-    target_link_libraries(periodic_alpha_complex_3d_persistence ${CGAL_LIBRARY})
-
-    if (TBB_FOUND)
-      target_link_libraries(alpha_complex_persistence ${TBB_LIBRARIES})
-      target_link_libraries(periodic_alpha_complex_3d_persistence ${TBB_LIBRARIES})
-    endif(TBB_FOUND)
-    add_test(NAME Persistent_cohomology_example_alpha_complex COMMAND $<TARGET_FILE:alpha_complex_persistence>
-        "${CMAKE_SOURCE_DIR}/data/points/tore3D_300.off" "-p" "2" "-m" "0.45")
-    add_test(NAME Persistent_cohomology_example_periodic_alpha_complex_3d COMMAND $<TARGET_FILE:periodic_alpha_complex_3d_persistence>
-        "${CMAKE_SOURCE_DIR}/data/points/grid_10_10_10_in_0_1.off" "${CMAKE_SOURCE_DIR}/data/points/iso_cuboid_3_in_0_1.txt" "2" "0")
-
-    install(TARGETS alpha_complex_persistence DESTINATION bin)
-    install(TARGETS periodic_alpha_complex_3d_persistence DESTINATION bin)
-
-  endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.7.0)
 endif(CGAL_FOUND)
diff --git a/src/Persistent_cohomology/utilities/README b/src/Persistent_cohomology/utilities/README
index 76e960da..eecee7ee 100644
--- a/src/Persistent_cohomology/utilities/README
+++ b/src/Persistent_cohomology/utilities/README
@@ -1,114 +1,66 @@
-To build the utilities, run in a Terminal:
+# Persistent_cohomology #
 
-cd /path-to-utilities/
-cmake .
-make
+## `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:
 
-***********************************************************************************************************************
-Example of use of RIPS:
+`p dim b d`
 
-Computation of the persistent homology with Z/2Z coefficients of the Rips complex on points 
-sampling a 3D torus:
+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 = p1*...*pr` is the product of prime numbers *pi* such that the homology feature exists in homology with *Z/piZ* coefficients).
 
-./rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 2
+**Usage**
+`rips_persistence [options] <OFF input file>`
 
-output:
-2  0 0 inf 
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-r [ --max-edge-length ]` (default = inf) Maximal length of an edge for the Rips complex construction.
+* `-d [ --cpx-dimension ]` (default = 1) Maximal dimension of the Rips complex we want to compute.
+* `-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 1 with Z/2Z coefficients**
+`rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 2`
+
+outputs:
+```
+2  0 0 inf
 2  1 0.0983494 inf 
 2  1 0.104347 inf 
 2  2 0.138335 inf 
+```
 
+**Example 2 with Z/3Z coefficients**
 
-Every line is of this format: p1*...*pr   dim b d
-where
- 	p1*...*pr is the product of prime numbers pi such that the homology feature exists in homology with Z/piZ coefficients. 
-	dim is the dimension of the homological feature,
-    b and d are respectively the birth and death of the feature and
-   
+rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 3
 
+outputs:
+```
+3  0 0 inf
+3  1 0.0983494 inf
+3  1 0.104347 inf
+3  2 0.138335 inf
+```
 
-with Z/3Z coefficients:
 
-./rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 3
 
-output:
-3  0 0 inf 
-3  1 0.0983494 inf 
-3  1 0.104347 inf 
-3  2 0.138335 inf 
-
-***********************************************************************************************************************
-Example of use of ALPHA:
-
-For a more verbose mode, please run cmake with option "DEBUG_TRACES=TRUE" and recompile the programs.
-
-1) 3D special case
-------------------
-Computation of the persistent homology with Z/2Z coefficients of the alpha complex on points 
-sampling a torus 3D:
-
-./alpha_complex_3d_persistence ../../data/points/tore3D_300.off 2 0.45
-
-output:
-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 accepts only OFF files in 3D dimension.
-      - filtration values are alpha square values
-
-2) d-Dimension case
--------------------
-Computation of the persistent homology with Z/2Z coefficients of the alpha complex on points 
-sampling a torus 3D:
-
-./alpha_complex_persistence -r 32 -p 2 -m 0.45 ../../data/points/tore3D_300.off
-
-output:
-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 accepts OFF files in d-Dimension.
-      - filtration values are alpha square values
-
-3) 3D periodic special case
----------------------------
-./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
-
-output:
-Periodic Delaunay computed.
-Simplex_tree dim: 3
+
+## `rips_distance_matrix_persistence` ##
+Same as `rips_persistence` but taking an distance matrix as input.
+
+**Example**
+`rips_distance_matrix_persistence data/distance_matrix/full_square_distance_matrix.csv -r 15 -d 3 -p 3 -m 0`
+
+outputs:
+```
+The complex contains 46 simplices 
+   and has dimension 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 a tore 3D:
-Betti numbers[0] = 1
-Betti numbers[1] = 3
-Betti numbers[2] = 3
-Betti numbers[3] = 1
-
-N.B.: - periodic_alpha_complex_3d_persistence accepts only OFF files in 3D dimension. In this example, the periodic cube
-is hard coded to { x = [0,1]; y = [0,1]; z = [0,1] }
-      - filtration values are alpha square values
+3  0 0 8.94427 
+3  0 0 7.28011 
+3  0 0 6.08276 
+3  0 0 5.83095 
+3  0 0 5.38516 
+3  0 0 5 
+3  1 11 12.0416 
+3  1 6.32456 6.7082 
+```
diff --git a/src/Witness_complex/example/CMakeLists.txt b/src/Witness_complex/example/CMakeLists.txt
index f8527e0f..a8231392 100644
--- a/src/Witness_complex/example/CMakeLists.txt
+++ b/src/Witness_complex/example/CMakeLists.txt
@@ -14,25 +14,22 @@ install(TARGETS Witness_complex_example_nearest_landmark_table DESTINATION bin)
 if (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.6.0)
   add_executable( Witness_complex_example_off example_witness_complex_off.cpp )
   add_executable ( Witness_complex_example_sphere example_witness_complex_sphere.cpp )
-
-  add_executable ( Witness_complex_example_witness_persistence example_witness_complex_persistence.cpp )
-  target_link_libraries(Witness_complex_example_witness_persistence ${Boost_PROGRAM_OPTIONS_LIBRARY})
-
-  if (TBB_FOUND)
-    target_link_libraries(Witness_complex_example_witness_persistence ${TBB_LIBRARIES})
-  endif()
+  
+  add_executable( Witness_complex_example_strong_off example_strong_witness_complex_off.cpp )
+  target_link_libraries(Witness_complex_example_strong_off)
 
   add_test(NAME Witness_complex_example_off_test_torus
       COMMAND $<TARGET_FILE:Witness_complex_example_off>
       "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "20" "1.0" "3")
   add_test(NAME Witness_complex_example_test_sphere_10
       COMMAND $<TARGET_FILE:Witness_complex_example_sphere> "10")
-  add_test(NAME Witness_complex_example_test_torus_persistence
-      COMMAND $<TARGET_FILE:Witness_complex_example_witness_persistence>
-      "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "-l" "20" "-a" "0.5")
-
+  add_test(NAME Witness_complex_example_strong_off_test_torus
+      COMMAND $<TARGET_FILE:Witness_complex_example_strong_off>
+      "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "20" "1.0" "3")
+      
   install(TARGETS Witness_complex_example_off DESTINATION bin)
   install(TARGETS Witness_complex_example_sphere DESTINATION bin)
-  install(TARGETS Witness_complex_example_witness_persistence DESTINATION bin)
+  install(TARGETS Witness_complex_example_strong_off DESTINATION bin)
+
 
 endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.6.0)
diff --git a/src/Witness_complex/utilities/example_strong_witness_complex_off.cpp b/src/Witness_complex/example/example_strong_witness_complex_off.cpp
index 0ee9ee90..0ee9ee90 100644
--- a/src/Witness_complex/utilities/example_strong_witness_complex_off.cpp
+++ b/src/Witness_complex/example/example_strong_witness_complex_off.cpp
diff --git a/src/Witness_complex/utilities/CMakeLists.txt b/src/Witness_complex/utilities/CMakeLists.txt
index 918ab864..125a41ff 100644
--- a/src/Witness_complex/utilities/CMakeLists.txt
+++ b/src/Witness_complex/utilities/CMakeLists.txt
@@ -3,24 +3,26 @@ project(Witness_complex_utilities)
 
 # CGAL and Eigen3 are required for Euclidean version of Witness
 if (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.6.0)
-  add_executable( Witness_complex_example_strong_off example_strong_witness_complex_off.cpp )
-  target_link_libraries(Witness_complex_example_strong_off)
+  
+  add_executable ( Witness_complex_strong_witness_persistence strong_witness_persistence.cpp )
+  target_link_libraries(Witness_complex_strong_witness_persistence ${Boost_PROGRAM_OPTIONS_LIBRARY})
 
-  add_executable ( Witness_complex_example_strong_witness_persistence example_strong_witness_persistence.cpp )
-  target_link_libraries(Witness_complex_example_strong_witness_persistence ${Boost_PROGRAM_OPTIONS_LIBRARY})
+  add_executable ( Witness_complex_weak_witness_persistence weak_witness_persistence.cpp )
+  target_link_libraries(Witness_complex_weak_witness_persistence ${Boost_PROGRAM_OPTIONS_LIBRARY})
 
   if (TBB_FOUND)
-    target_link_libraries(Witness_complex_example_strong_witness_persistence ${TBB_LIBRARIES})
+    target_link_libraries(Witness_complex_strong_witness_persistence ${TBB_LIBRARIES})
+    target_link_libraries(Witness_complex_weak_witness_persistence ${TBB_LIBRARIES})
   endif()
 
-  add_test(NAME Witness_complex_example_strong_off_test_torus
-      COMMAND $<TARGET_FILE:Witness_complex_example_strong_off>
-      "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "20" "1.0" "3")
-  add_test(NAME Witness_complex_example_strong_test_torus_persistence
-      COMMAND $<TARGET_FILE:Witness_complex_example_strong_witness_persistence>
+  add_test(NAME Witness_complex_strong_test_torus_persistence
+      COMMAND $<TARGET_FILE:Witness_complex_strong_witness_persistence>
+      "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "-l" "20" "-a" "0.5")
+  add_test(NAME Witness_complex_weak_test_torus_persistence
+      COMMAND $<TARGET_FILE:Witness_complex_weak_witness_persistence>
       "${CMAKE_SOURCE_DIR}/data/points/tore3D_1307.off" "-l" "20" "-a" "0.5")
 
-  install(TARGETS Witness_complex_example_strong_off DESTINATION bin)
-  install(TARGETS Witness_complex_example_strong_witness_persistence DESTINATION bin)
+  install(TARGETS Witness_complex_strong_witness_persistence DESTINATION bin)
+  install(TARGETS Witness_complex_weak_witness_persistence DESTINATION bin)
 
 endif (NOT CGAL_WITH_EIGEN3_VERSION VERSION_LESS 4.6.0)
diff --git a/src/Witness_complex/utilities/README b/src/Witness_complex/utilities/README
new file mode 100644
index 00000000..d8dc9ca7
--- /dev/null
+++ b/src/Witness_complex/utilities/README
@@ -0,0 +1,72 @@
+# Witness_complex #

+

+## `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`

+

+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.

+

+*Usage*

+`weak_witness_persistence [options] <OFF input file>`

+

+*Allowed options*

+

+* `-h [ --help ]` Produce help message

+* `-l [ --landmarks ]` Number of landmarks to choose from the point cloud.

+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. By default, print in std::cout.

+* `-a [ --max-sq-alpha ]` (default = inf) Maximal squared relaxation parameter.

+* `-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.

+* `-d [ --cpx-dimension ]` (default = 2147483647) Maximal dimension of the weak witness complex we want to compute.

+

+*Example*

+`weak_witness_persistence data/points/tore3D_1307.off -l 20 -a 0.5 -m 0.006`

+

+outputs:

+```

+Successfully read 1307 points.

+Ambient dimension is 3.

+The complex contains 732 simplices and has dimension 8 

+11  0 0 inf 

+11  1 0 inf 

+11  2 0.0275251 0.0534586 

+11  1 0 0.0239952 

+```

+

+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`

+

+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.

+

+*Usage*

+`strong_witness_persistence [options] <OFF input file>`

+

+*Allowed options*

+

+* `-h [ --help ]` Produce help message

+* `-l [ --landmarks ]` Number of landmarks to choose from the point cloud.

+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. By default, print in std::cout.

+* `-a [ --max-sq-alpha ]` (default = inf) Maximal squared relaxation parameter.

+* `-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.

+* `-d [ --cpx-dimension ]` (default = 2147483647) Maximal dimension of the weak witness complex we want to compute.

+

+*Example*

+`strong_witness_persistence data/points/tore3D_1307.off -l 20 -a 0.5 -m 0.06`

+

+outputs:

+```

+Successfully read 1307 points.

+Ambient dimension is 3.

+The complex contains 1836 simplices and has dimension 8 

+11  0 0 inf 

+11  1 0.00674748 inf 

+11  2 0.0937751 0.235354 

+```

+

+N.B.: output is random as the 20 landmarks are chosen randomly.

diff --git a/src/Witness_complex/utilities/example_strong_witness_persistence.cpp b/src/Witness_complex/utilities/strong_witness_persistence.cpp
index f786fe7b..f786fe7b 100644
--- a/src/Witness_complex/utilities/example_strong_witness_persistence.cpp
+++ b/src/Witness_complex/utilities/strong_witness_persistence.cpp
diff --git a/src/Witness_complex/example/example_witness_complex_persistence.cpp b/src/Witness_complex/utilities/weak_witness_persistence.cpp
index a1146922..a1146922 100644
--- a/src/Witness_complex/example/example_witness_complex_persistence.cpp
+++ b/src/Witness_complex/utilities/weak_witness_persistence.cpp
diff --git a/src/common/utilities/README b/src/common/utilities/README
index dc841521..18fa8cc4 100644
--- a/src/common/utilities/README
+++ b/src/common/utilities/README
@@ -1,19 +1,19 @@
-======================= off_file_from_shape_generator ==================================
+# Pointset generator #
 
-Example of use :
+## `off_file_from_shape_generator` ##
 
-*** on|in sphere|cube|curve|torus|klein generator
+Generates a pointset and save it in an OFF file. Command-line is:
+`off_file_from_shape_generator on|in sphere|cube|curve|torus|klein <filename> <num_points> <dimension> <parameter1> <parameter2>...`
 
-./off_file_from_shape_generator on sphere onSphere.off 1000 3 15.2
+Warning: "on cube" generator is not available!
 
- => generates a onSphere.off file with 1000 points randomized on a sphere of dimension 3 and radius 15.2
+Examples:
 
-./off_file_from_shape_generator in sphere inSphere.off 100 2
+* Generate an onSphere.off file with 1000 points randomized on a sphere of dimension 3 and radius 15.2:
+`off_file_from_shape_generator on sphere onSphere.off 1000 3 15.2`
+ 
+* Generate an inSphere.off file with 100 points randomized in a sphere of dimension 2 (circle) and radius 1.0 (default):
+`off_file_from_shape_generator in sphere inSphere.off 100 2`
 
- => generates a inSphere.off file with 100 points randomized in a sphere of dimension 2 (circle) and radius 1.0 (default)
-
-./off_file_from_shape_generator in cube inCube.off 10000 3 5.8
-
- => generates a inCube.off file with 10000 points randomized in a cube of dimension 3 and side 5.8
-
-!! Warning: hypegenerator on cube is not available !!
+* Generates a inCube.off file with 10000 points randomized in a cube of dimension 3 and side 5.8:
+`off_file_from_shape_generator in cube inCube.off 10000 3 5.8`