update on python documentation

8 files changed, 163 insertions, 53 deletions

diff --git a/src/python/doc/cubical_complex_sum.inc b/src/python/doc/cubical_complex_sum.inc
index 87db184d..90ec9fc2 100644
--- a/src/python/doc/cubical_complex_sum.inc
+++ b/src/python/doc/cubical_complex_sum.inc
@@ -1,14 +1,17 @@
 .. table::
    :widths: 30 40 30
 
-   +--------------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------+
-   | .. figure::                                                              | The cubical complex represents a grid as a cell complex with         | :Author: Pawel Dlotko       |
-   |      ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | cells of all dimensions.                                             |                             |
-   |      :alt: Cubical complex representation                                |                                                                      | :Since: GUDHI 2.0.0         |
-   |      :figclass: align-center                                             |                                                                      |                             |
-   |                                                                          |                                                                      | :License: MIT               |
-   |                                                                          |                                                                      |                             |
-   +--------------------------------------------------------------------------+----------------------------------------------------------------------+-----------------------------+
-   | * :doc:`cubical_complex_user`                                            | * :doc:`cubical_complex_ref`                                                                       |
-   |                                                                          | * :doc:`periodic_cubical_complex_ref`                                                              |
-   +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+
+   +--------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------------------------------------+
+   | .. figure::                                                              | The cubical complex represents a grid as a cell complex with         | :Author: Pawel Dlotko                                   |
+   |      ../../doc/Bitmap_cubical_complex/Cubical_complex_representation.png | cells of all dimensions.                                             |                                                         |
+   |      :alt: Cubical complex representation                                |                                                                      | :Since: GUDHI 2.0.0                                     |
+   |      :figclass: align-center                                             |                                                                      |                                                         |
+   |                                                                          |                                                                      | :License: MIT                                           |
+   |                                                                          |                                                                      |                                                         |
+   +--------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------------------------------------+
+   | * :doc:`cubical_complex_user`                                            | * :doc:`cubical_complex_ref`                                                                                                   |
+   |                                                                          | * :doc:`periodic_cubical_complex_ref`                                                                                          |
+   +--------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------------------------------------+
+   |                                                                          | * :doc:`cubical_complex_tflow_itf_ref`                               | :requires: `TensorFlow <installation.html#tensorflow>`_ |
+   |                                                                          |                                                                      |                                                         |
+   +--------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------------------------------------+
diff --git a/src/python/doc/cubical_complex_tflow_itf_ref.rst b/src/python/doc/cubical_complex_tflow_itf_ref.rst
new file mode 100644
index 00000000..8991b638
--- /dev/null
+++ b/src/python/doc/cubical_complex_tflow_itf_ref.rst
@@ -0,0 +1,33 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+TensorFlow layer for cubical persistence
+########################################
+
+.. include:: differentiation_sum.inc
+
+Example of gradient computed from cubical persistence
+-----------------------------------------------------
+
+.. code-block:: python
+    from gudhi.tensorflow import *
+    import numpy as np
+    import tensorflow as tf
+
+    Xinit = np.array([[0.,2.,2.],[2.,2.,2.],[2.,2.,1.]], dtype=np.float32)
+    X = tf.Variable(initial_value=Xinit, trainable=True)
+    cl = CubicalLayer(dimension=0)
+
+    with tf.GradientTape() as tape:
+        dgm = cl.call(X)
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+    grads = tape.gradient(loss, [X])
+
+Documentation for CubicalLayer
+------------------------------
+
+.. autoclass:: gudhi.tensorflow.CubicalLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:
diff --git a/src/python/doc/differentiation.rst b/src/python/doc/differentiation.rst
deleted file mode 100644
index 906a9965..00000000
--- a/src/python/doc/differentiation.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-:orphan:
-
-.. To get rid of WARNING: document isn't included in any toctree
-
-======================
-Differentiation manual
-======================
-
-.. include:: differentiation_sum.inc
-
-In this module, we provide neural network models for computing persistent homology. In particular, we provide TensorFlow 2 models that allow to compute persistence diagrams from complexes available in the Gudhi library, including simplex trees, cubical complexes and Vietoris-Rips complexes. These models can be incorporated at each step of a given neural network architecture, and can be used in addition to `PersLay <https://github.com/MathieuCarriere/gudhi/blob/perslay/src/python/gudhi/representations/perslay.py>`_ to produce topological features.
-
-TensorFlow models
------------------
-.. automodule:: gudhi.differentiation
-   :members:
-   :special-members:
-   :show-inheritance:
diff --git a/src/python/doc/differentiation_sum.inc b/src/python/doc/differentiation_sum.inc
index 30188e0b..7340d24d 100644
--- a/src/python/doc/differentiation_sum.inc
+++ b/src/python/doc/differentiation_sum.inc
@@ -1,14 +1,10 @@
-.. table::
-   :widths: 30 40 30
+. list-table::
+   :widths: 40 30 30
+   :header-rows: 0
 
-   +------------------------------------------------------------------+----------------------------------------------------------------+-------------------------------------------------------------+
-   | .. figure::                                                      | Deep learning models for differentiating persistence diagrams. | :Author: Mathieu Carrière                                   |
-   |      img/ripsTF.png                                              |                                                                |                                                             |
-   |                                                                  |                                                                | :Since: GUDHI 3.1.0                                         |
-   |                                                                  |                                                                |                                                             |
-   |                                                                  |                                                                | :License: MIT                                               |
-   |                                                                  |                                                                |                                                             |
-   |                                                                  |                                                                | :Requires: `TensorFlow 2 <installation.html#tensorflow>`_   |
-   +------------------------------------------------------------------+----------------------------------------------------------------+-------------------------------------------------------------+
-   | * :doc:`differentiation`                                                                                                                                                                        |
-   +------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
+   * - :Since: GUDHI 3.5.0
+     - :License: MIT
+     - :Requires: `TensorFlow <installation.html#tensorflow>`_
+
+We provide TensorFlow 2 models that can handle automatic differentiation for the computation of persistence diagrams from complexes available in the Gudhi library. 
+This includes simplex trees, cubical complexes and Vietoris-Rips complexes. 
diff --git a/src/python/doc/ls_simplex_tree_tflow_itf_ref.rst b/src/python/doc/ls_simplex_tree_tflow_itf_ref.rst
new file mode 100644
index 00000000..bb9c61c6
--- /dev/null
+++ b/src/python/doc/ls_simplex_tree_tflow_itf_ref.rst
@@ -0,0 +1,57 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+TensorFlow layer for lower-star persistence on simplex trees
+############################################################
+
+.. include:: differentiation_sum.inc
+
+Example of gradient computed from lower-star filtration of a simplex tree
+-------------------------------------------------------------------------
+
+.. code-block:: python
+    from gudhi.tensorflow import *
+    import numpy as np
+    import tensorflow as tf
+    import gudhi as gd
+
+    st = gd.SimplexTree()
+    st.insert([0])
+    st.insert([1]) 
+    st.insert([2]) 
+    st.insert([3]) 
+    st.insert([4]) 
+    st.insert([5]) 
+    st.insert([6]) 
+    st.insert([7]) 
+    st.insert([8]) 
+    st.insert([9]) 
+    st.insert([10]) 
+    st.insert([0, 1]) 
+    st.insert([1, 2]) 
+    st.insert([2, 3]) 
+    st.insert([3, 4]) 
+    st.insert([4, 5]) 
+    st.insert([5, 6]) 
+    st.insert([6, 7]) 
+    st.insert([7, 8]) 
+    st.insert([8, 9]) 
+    st.insert([9, 10]) 
+
+    Finit = np.array([6.,4.,3.,4.,5.,4.,3.,2.,3.,4.,5.], dtype=np.float32)
+    F = tf.Variable(initial_value=Finit, trainable=True)
+    sl = LowerStarSimplexTreeLayer(simplextree=st, dimension=0)
+
+    with tf.GradientTape() as tape:
+        dgm = sl.call(F)
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+    grads = tape.gradient(loss, [F])
+
+Documentation for LowerStarSimplexTreeLayer
+-------------------------------------------
+
+.. autoclass:: gudhi.tensorflow.LowerStarSimplexTreeLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:
diff --git a/src/python/doc/rips_complex_sum.inc b/src/python/doc/rips_complex_sum.inc
index 2cb24990..6931ebee 100644
--- a/src/python/doc/rips_complex_sum.inc
+++ b/src/python/doc/rips_complex_sum.inc
@@ -11,4 +11,7 @@
    |                                                                |                                                                        |                                                                                  |
    +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------+
    | * :doc:`rips_complex_user`                                     | * :doc:`rips_complex_ref`                                                                                                                                 |
-   +----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
+   +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------+
+   |                                                                | * :doc:`rips_complex_tflow_itf_ref`                                    | :requires: `TensorFlow <installation.html#tensorflow>`_                          |
+   |                                                                |                                                                        |                                                                                  |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------+
diff --git a/src/python/doc/rips_complex_tflow_itf_ref.rst b/src/python/doc/rips_complex_tflow_itf_ref.rst
new file mode 100644
index 00000000..db8c64ff
--- /dev/null
+++ b/src/python/doc/rips_complex_tflow_itf_ref.rst
@@ -0,0 +1,33 @@
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+TensorFlow layer for Vietoris-Rips persistence
+##############################################
+
+.. include:: differentiation_sum.inc
+
+Example of gradient computed from Vietoris-Rips persistence
+-----------------------------------------------------------
+
+.. code-block:: python
+    from gudhi.tensorflow import *
+    import numpy as np
+    import tensorflow as tf
+
+    Xinit = np.array([[1.,1.],[2.,2.]], dtype=np.float32)
+    X = tf.Variable(initial_value=Xinit, trainable=True)
+    rl = RipsLayer(maximum_edge_length=2., dimension=0)
+
+    with tf.GradientTape() as tape:
+        dgm = rl.call(X)
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+    grads = tape.gradient(loss, [X])
+
+Documentation for RipsLayer
+---------------------------
+
+.. autoclass:: gudhi.tensorflow.RipsLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:
diff --git a/src/python/doc/simplex_tree_sum.inc b/src/python/doc/simplex_tree_sum.inc
index a8858f16..3ad1292c 100644
--- a/src/python/doc/simplex_tree_sum.inc
+++ b/src/python/doc/simplex_tree_sum.inc
@@ -1,13 +1,16 @@
 .. table::
    :widths: 30 40 30
 
-   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------+
-   | .. figure::                                                    | The simplex tree is an efficient and flexible data structure for       | :Author: Clément Maria      |
-   |      ../../doc/Simplex_tree/Simplex_tree_representation.png    | representing general (filtered) simplicial complexes.                  |                             |
-   |      :alt: Simplex tree representation                         |                                                                        | :Since: GUDHI 2.0.0         |
-   |      :figclass: align-center                                   | The data structure is described in                                     |                             |
-   |                                                                | :cite:`boissonnatmariasimplextreealgorithmica`                         | :License: MIT               |
-   |                                                                |                                                                        |                             |
-   +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------+
-   | * :doc:`simplex_tree_user`                                     | * :doc:`simplex_tree_ref`                                                                            |
-   +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+   +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------+
+   | .. figure::                                                    | The simplex tree is an efficient and flexible data structure for       | :Author: Clément Maria                                  |
+   |      ../../doc/Simplex_tree/Simplex_tree_representation.png    | representing general (filtered) simplicial complexes.                  |                                                         |
+   |      :alt: Simplex tree representation                         |                                                                        | :Since: GUDHI 2.0.0                                     |
+   |      :figclass: align-center                                   | The data structure is described in                                     |                                                         |
+   |                                                                | :cite:`boissonnatmariasimplextreealgorithmica`                         | :License: MIT                                           |
+   |                                                                |                                                                        |                                                         |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------+
+   | * :doc:`simplex_tree_user`                                     | * :doc:`simplex_tree_ref`                                                                                                        |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------+
+   |                                                                | * :doc:`ls_simplex_tree_tflow_itf_ref`                                 | :requires: `TensorFlow <installation.html#tensorflow>`_ |
+   |                                                                |                                                                        |                                                         |
+   +----------------------------------------------------------------+------------------------------------------------------------------------+---------------------------------------------------------+