PD gradient

src/python/CMakeLists.txt

@@ -70,6 +70,7 @@ if(PYTHONINTERP_FOUND)
     set(GUDHI_PYTHON_MODULES "${GUDHI_PYTHON_MODULES}'euclidean_strong_witness_complex', ")
     # Modules that should not be auto-imported in __init__.py
     set(GUDHI_PYTHON_MODULES_EXTRA "${GUDHI_PYTHON_MODULES_EXTRA}'representations', ")
+    set(GUDHI_PYTHON_MODULES_EXTRA "${GUDHI_PYTHON_MODULES_EXTRA}'tensorflow', ")
     set(GUDHI_PYTHON_MODULES_EXTRA "${GUDHI_PYTHON_MODULES_EXTRA}'wasserstein', ")
     set(GUDHI_PYTHON_MODULES_EXTRA "${GUDHI_PYTHON_MODULES_EXTRA}'point_cloud', ")
     set(GUDHI_PYTHON_MODULES_EXTRA "${GUDHI_PYTHON_MODULES_EXTRA}'weighted_rips_complex', ")
@@ -289,7 +290,8 @@ if(PYTHONINTERP_FOUND)
     # Other .py files
     file(COPY "gudhi/persistence_graphical_tools.py" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")
     file(COPY "gudhi/representations" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi/")
-    file(COPY "gudhi/wasserstein" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")
+    file(COPY "gudhi/wasserstein" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")    
+    file(COPY "gudhi/tensorflow" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")
     file(COPY "gudhi/point_cloud" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")
     file(COPY "gudhi/clustering" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi" FILES_MATCHING PATTERN "*.py")
     file(COPY "gudhi/weighted_rips_complex.py" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/gudhi")
@@ -562,6 +564,11 @@ if(PYTHONINTERP_FOUND)
       add_gudhi_py_test(test_representations)
     endif()
 
+    # Differentiation
+    if(TENSORFLOW_FOUND)
+      add_gudhi_py_test(test_diff)
+    endif()
+
     # Betti curves
     if(SKLEARN_FOUND AND SCIPY_FOUND)
       add_gudhi_py_test(test_betti_curve_representations)

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

src/python/doc/cubical_complex_tflow_itf_ref.rst

@@ -0,0 +1,40 @@
+: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
+-----------------------------------------------------
+
+.. testcode::
+
+    from gudhi.tensorflow import CubicalLayer
+    import tensorflow as tf
+
+    X = tf.Variable([[0.,2.,2.],[2.,2.,2.],[2.,2.,1.]], dtype=tf.float32, trainable=True)
+    cl = CubicalLayer(homology_dimensions=[0])
+
+    with tf.GradientTape() as tape:
+        dgm = cl.call(X)[0][0]
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+
+    grads = tape.gradient(loss, [X])
+    print(grads[0].numpy())
+
+.. testoutput::
+
+    [[ 0.   0.   0. ]
+     [ 0.   0.5  0. ]
+     [ 0.   0.  -0.5]]
+
+Documentation for CubicalLayer
+------------------------------
+
+.. autoclass:: gudhi.tensorflow.CubicalLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:

src/python/doc/differentiation_sum.inc

@@ -0,0 +1,12 @@
+.. list-table::
+   :widths: 40 30 30
+   :header-rows: 0
+
+   * - :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. Detailed example on how to use these layers in practice are available
+in the following `notebook <https://github.com/GUDHI/TDA-tutorial/blob/master/Tuto-GUDHI-optimization.ipynb>`_. Note that even if TensorFlow GPU is enabled, all 
+internal computations using Gudhi will be done on CPU. 

src/python/doc/installation.rst

@@ -396,7 +396,11 @@ mathematics, science, and engineering.
 TensorFlow
 ----------
 
-`TensorFlow <https://www.tensorflow.org>`_ is currently only used in some automatic differentiation tests.
+The :doc:`cubical complex </cubical_complex_tflow_itf_ref>`, :doc:`simplex tree </ls_simplex_tree_tflow_itf_ref>`
+and :doc:`Rips complex </rips_complex_tflow_itf_ref>` modules require `TensorFlow <https://www.tensorflow.org>`_
+for incorporating them in neural nets. 
+
+`TensorFlow <https://www.tensorflow.org>`_ is also used in some automatic differentiation tests.
 
 Bug reports and contributions
 *****************************

src/python/doc/ls_simplex_tree_tflow_itf_ref.rst

@@ -0,0 +1,53 @@
+: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
+-------------------------------------------------------------------------
+
+.. testcode::
+
+    from gudhi.tensorflow import LowerStarSimplexTreeLayer
+    import tensorflow as tf
+    import gudhi as gd
+
+    st = gd.SimplexTree()
+    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]) 
+
+    F = tf.Variable([6.,4.,3.,4.,5.,4.,3.,2.,3.,4.,5.], dtype=tf.float32, trainable=True)
+    sl = LowerStarSimplexTreeLayer(simplextree=st, homology_dimensions=[0])
+
+    with tf.GradientTape() as tape:
+        dgm = sl.call(F)[0][0]
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+
+    grads = tape.gradient(loss, [F])
+    print(grads[0].indices.numpy())
+    print(grads[0].values.numpy())
+
+.. testoutput::
+
+    [2 4]
+    [-1.  1.]
+
+Documentation for LowerStarSimplexTreeLayer
+-------------------------------------------
+
+.. autoclass:: gudhi.tensorflow.LowerStarSimplexTreeLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:

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

src/python/doc/rips_complex_tflow_itf_ref.rst

@@ -0,0 +1,48 @@
+: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
+-----------------------------------------------------------
+
+.. testsetup::
+
+    import numpy
+    numpy.set_printoptions(precision=4)
+
+.. testcode::
+
+    from gudhi.tensorflow import RipsLayer
+    import tensorflow as tf
+
+    X = tf.Variable([[1.,1.],[2.,2.]], dtype=tf.float32, trainable=True)
+    rl = RipsLayer(maximum_edge_length=2., homology_dimensions=[0])
+
+    with tf.GradientTape() as tape:
+        dgm = rl.call(X)[0][0]
+        loss = tf.math.reduce_sum(tf.square(.5*(dgm[:,1]-dgm[:,0])))
+
+    grads = tape.gradient(loss, [X])
+    print(grads[0].numpy())
+
+.. testcleanup::
+
+    numpy.set_printoptions(precision=8)
+
+.. testoutput::
+
+    [[-0.5 -0.5]
+     [ 0.5  0.5]]
+
+Documentation for RipsLayer
+---------------------------
+
+.. autoclass:: gudhi.tensorflow.RipsLayer
+   :members:
+   :special-members: __init__
+   :show-inheritance:

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

src/python/gudhi/tensorflow/__init__.py

@@ -0,0 +1,5 @@
+from .cubical_layer import CubicalLayer
+from .lower_star_simplex_tree_layer import LowerStarSimplexTreeLayer
+from .rips_layer import RipsLayer
+
+__all__ = ["LowerStarSimplexTreeLayer", "RipsLayer", "CubicalLayer"]