Merge pull request #195 from VincentRouvreau/alpha_complex_documentation_improvements

Fix #105: Alpha-complex document parameter for the picture

6 files changed, 24 insertions, 25 deletions

diff --git a/src/Alpha_complex/doc/Intro_alpha_complex.h b/src/Alpha_complex/doc/Intro_alpha_complex.h
index 3c32a1e6..a8b1a106 100644
--- a/src/Alpha_complex/doc/Intro_alpha_complex.h
+++ b/src/Alpha_complex/doc/Intro_alpha_complex.h
@@ -31,8 +31,8 @@ namespace alpha_complex {
  * circumsphere is empty (the simplex is then said to be Gabriel), and as the minimum of the filtration
  * values of the codimension 1 cofaces that make it not Gabriel otherwise.
  *
- * All simplices that have a filtration value strictly greater than a given alpha squared value are not inserted into
- * the complex.
+ * All simplices that have a filtration value \f$ > \alpha^2 \f$ are removed from the Delaunay complex
+ * when creating the simplicial complex if it is specified.
  *
  * \image html "alpha_complex_representation.png" "Alpha-complex representation"
  *
@@ -46,8 +46,8 @@ namespace alpha_complex {
  * \cite cgal:s-gkd-19b from CGAL as template parameter.
  *
  * \remark
- * - When the simplicial complex is constructed with an infinite value of alpha, the complex is a Delaunay
- * complex.
+ * - When an \f$\alpha\f$-complex is constructed with an infinite value of \f$ \alpha^2 \f$, the complex is a Delaunay
+ * complex (with special filtration values).
  * - For people only interested in the topology of the \ref alpha_complex (for instance persistence),
  * \ref alpha_complex is equivalent to the \ref cech_complex and much smaller if you do not bound the radii.
  * \ref cech_complex can still make sense in higher dimension precisely because you can bound the radii.
@@ -135,13 +135,13 @@ namespace alpha_complex {
  *
  * \subsubsection nondecreasing Non decreasing filtration values
  *
- * As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not
- * quite define a proper filtration (i.e. non-decreasing with respect to inclusion).
+ * As the squared radii computed by CGAL are an approximation, it might happen that these \f$ \alpha^2 \f$ values do
+ * not quite define a proper filtration (i.e. non-decreasing with respect to inclusion).
  * We fix that up by calling `SimplicialComplexForAlpha::make_filtration_non_decreasing()`.
  *
  * \subsubsection pruneabove Prune above given filtration value
  *
- * The simplex tree is pruned from the given maximum alpha squared value (cf.
+ * The simplex tree is pruned from the given maximum \f$ \alpha^2 \f$ value (cf.
  * `SimplicialComplexForAlpha::prune_above_filtration()`).
  * In the following example, the value is given by the user as argument of the program.
  *
diff --git a/src/Alpha_complex/doc/alpha_complex_representation.ipe b/src/Alpha_complex/doc/alpha_complex_representation.ipe
index e8096b93..40ff1d0f 100644
--- a/src/Alpha_complex/doc/alpha_complex_representation.ipe
+++ b/src/Alpha_complex/doc/alpha_complex_representation.ipe
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE ipe SYSTEM "ipe.dtd">
-<ipe version="70107" creator="Ipe 7.1.10">
-<info created="D:20150603143945" modified="D:20160404172133"/>
+<ipe version="70206" creator="Ipe 7.2.7">
+<info created="D:20150603143945" modified="D:20200110100102"/>
 <ipestyle name="basic">
 <symbol name="arrow/arc(spx)">
 <path stroke="sym-stroke" fill="sym-stroke" pen="sym-pen">
@@ -305,7 +305,7 @@ h
 108.275 743.531 m
 166.45 743.531 l
 </path>
-<text matrix="1 0 0 1 142.618 -109.867" transformations="translations" pos="127.397 746.763" stroke="darkgray" type="label" width="6.41" height="4.289" depth="0" valign="baseline">$\alpha$</text>
+<text matrix="1 0 0 1 126.618 -109.867" transformations="translations" pos="127.397 746.763" stroke="darkgray" type="label" width="45.707" height="9.041" depth="1.32" valign="baseline" style="math">\alpha = \sqrt{32.0}</text>
 <use matrix="1 0 0 1 -209.478 12.0238" name="mark/fdisk(sfx)" pos="300 720" size="normal" stroke="black" fill="white"/>
 <use matrix="1 0 0 1 -210.178 22.1775" name="mark/fdisk(sfx)" pos="280 660" size="normal" stroke="black" fill="white"/>
 <use matrix="1 0 0 1 -210.178 22.1775" name="mark/fdisk(sfx)" pos="370 690" size="normal" stroke="black" fill="white"/>
diff --git a/src/Alpha_complex/doc/alpha_complex_representation.png b/src/Alpha_complex/doc/alpha_complex_representation.png
index 7b81cd69..5ebb1e75 100644
--- a/src/Alpha_complex/doc/alpha_complex_representation.png
+++ b/src/Alpha_complex/doc/alpha_complex_representation.png
diff --git a/src/common/doc/main_page.md b/src/common/doc/main_page.md
index e8d11fdf..0b4bfb7a 100644
--- a/src/common/doc/main_page.md
+++ b/src/common/doc/main_page.md
@@ -43,8 +43,8 @@
     The filtration value of each simplex is computed as the square of the circumradius of the simplex if the
     circumsphere is empty (the simplex is then said to be Gabriel), and as the minimum of the filtration
     values of the codimension 1 cofaces that make it not Gabriel otherwise.
-    All simplices that have a filtration value strictly greater than a given alpha squared value are not inserted into
-    the complex.<br>
+    All simplices that have a filtration value \f$ > \alpha^2 \f$ are removed from the Delaunay complex
+    when creating the simplicial complex if it is specified.<br>
     For performances reasons, it is advised to use \ref cgal &ge; 5.0.0.
     </td>
     <td width="15%">
diff --git a/src/python/doc/alpha_complex_sum.inc b/src/python/doc/alpha_complex_sum.inc
index c5ba9dc7..a1184663 100644
--- a/src/python/doc/alpha_complex_sum.inc
+++ b/src/python/doc/alpha_complex_sum.inc
@@ -9,9 +9,9 @@
    |                                                                | circumradius of the simplex if the circumsphere is empty (the simplex  | :Copyright: MIT (`GPL v3 </licensing/>`_)                                                                                   |
    |                                                                | is then said to be Gabriel), and as the minimum of the filtration      |                                                                                                                             |
    |                                                                | values of the codimension 1 cofaces that make it not Gabriel           | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 |
-   |                                                                | otherwise. All simplices that have a filtration value strictly         |                                                                                                                             |
-   |                                                                | greater than a given alpha squared value are not inserted into the     |                                                                                                                             |
-   |                                                                | complex.                                                               |                                                                                                                             |
+   |                                                                | otherwise. All simplices that have a filtration value                  |                                                                                                                             |
+   |                                                                | :math:`> \alpha^2` are removed from the Delaunay complex               |                                                                                                                             |
+   |                                                                | when creating the simplicial complex if it is specified.               |                                                                                                                             |
    |                                                                |                                                                        |                                                                                                                             |
    |                                                                | This package requires having CGAL version 4.7 or higher (4.8.1 is      |                                                                                                                             |
    |                                                                | advised for better performance).                                       |                                                                                                                             |
diff --git a/src/python/doc/alpha_complex_user.rst b/src/python/doc/alpha_complex_user.rst
index b7e69e12..60319e84 100644
--- a/src/python/doc/alpha_complex_user.rst
+++ b/src/python/doc/alpha_complex_user.rst
@@ -16,7 +16,8 @@ Definition
 
 Remarks
 ^^^^^^^
-When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex (with special filtration values).
+When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha^2`,
+the complex is a Delaunay complex (with special filtration values).
 
 Example from points
 -------------------
@@ -137,19 +138,20 @@ sets the filtration value (0 in case of a vertex - propagation will have no effe
 Non decreasing filtration values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not
-quite define a proper filtration (i.e. non-decreasing with respect to inclusion).
+As the squared radii computed by CGAL are an approximation, it might happen that these
+:math:`\alpha^2` values do not quite define a proper filtration (i.e. non-decreasing with
+respect to inclusion).
 We fix that up by calling :func:`~gudhi.SimplexTree.make_filtration_non_decreasing` (cf.
 `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_).
 
 Prune above given filtration value
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The simplex tree is pruned from the given maximum alpha squared value (cf.
+The simplex tree is pruned from the given maximum :math:`\alpha^2` value (cf.
 :func:`~gudhi.SimplexTree.prune_above_filtration`). Note that this does not provide any kind
 of speed-up, since we always first build the full filtered complex, so it is recommended not to use
 :paramref:`~gudhi.AlphaComplex.create_simplex_tree.max_alpha_square`.
-In the following example, a threshold of 59 is used.
+In the following example, a threshold of :math:`\alpha^2 = 32.0` is used.
 
 
 Example from OFF file
@@ -166,7 +168,7 @@ Then, it is asked to display information about the alpha complex:
     import gudhi
     alpha_complex = gudhi.AlphaComplex(off_file=gudhi.__root_source_dir__ + \
         '/data/points/alphacomplexdoc.off')
-    simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=59.0)
+    simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=32.0)
     result_str = 'Alpha complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \
         repr(simplex_tree.num_simplices()) + ' simplices - ' + \
         repr(simplex_tree.num_vertices()) + ' vertices.'
@@ -179,7 +181,7 @@ the program output is:
 
 .. testoutput::
 
-   Alpha complex is of dimension 2 - 23 simplices - 7 vertices.
+   Alpha complex is of dimension 2 - 20 simplices - 7 vertices.
    [0] -> 0.00
    [1] -> 0.00
    [2] -> 0.00
@@ -200,9 +202,6 @@ the program output is:
    [4, 6] -> 22.74
    [4, 5, 6] -> 22.74
    [3, 6] -> 30.25
-   [2, 6] -> 36.50
-   [2, 3, 6] -> 36.50
-   [2, 4, 6] -> 37.24
 
 CGAL citations
 ==============