Add upper_bound_dimension and associated documentation for automatic dimension set.

prune_above_filtration cythonization


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

Former-commit-id: 12af3c5c2d6012c43d80cc95e1ecc8a2c0df340e

3 files changed, 94 insertions, 9 deletions

diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree.h b/src/Simplex_tree/include/gudhi/Simplex_tree.h
index 7da767cb..eef710e1 100644
--- a/src/Simplex_tree/include/gudhi/Simplex_tree.h
+++ b/src/Simplex_tree/include/gudhi/Simplex_tree.h
@@ -761,8 +761,12 @@ class Simplex_tree {
     return &root_;
   }
 
-  /** Set a dimension for the simplicial complex. */
+  /** \brief Set a dimension for the simplicial complex.
+   *  \details This function must be used with caution because it disables dimension recomputation when required
+   * (this recomputation can be triggered by `remove_maximal_simplex()` or `prune_above_filtration()`).
+   */
   void set_dimension(int dimension) {
+    dimension_to_be_lowered_ = false;
     dimension_ = dimension;
   }
 
diff --git a/src/cython/cython/simplex_tree.pyx b/src/cython/cython/simplex_tree.pyx
index 32b91028..9204d7c6 100644
--- a/src/cython/cython/simplex_tree.pyx
+++ b/src/cython/cython/simplex_tree.pyx
@@ -42,6 +42,7 @@ cdef extern from "Simplex_tree_interface.h" namespace "Gudhi":
         int num_simplices()
         void set_dimension(int dimension)
         int dimension()
+        int upper_bound_dimension()
         bint find_simplex(vector[int] simplex)
         bint insert_simplex_and_subfaces(vector[int] simplex,
                                          double filtration)
@@ -50,8 +51,9 @@ cdef extern from "Simplex_tree_interface.h" namespace "Gudhi":
         vector[pair[vector[int], double]] get_star(vector[int] simplex)
         vector[pair[vector[int], double]] get_cofaces(vector[int] simplex,
                                                           int dimension)
-        void remove_maximal_simplex(vector[int] simplex)
         void expansion(int max_dim)
+        void remove_maximal_simplex(vector[int] simplex)
+        bool prune_above_filtration(double filtration)
 
 cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
     cdef cppclass Simplex_tree_persistence_interface "Gudhi::Persistent_cohomology_interface<Gudhi::Simplex_tree<Gudhi::Simplex_tree_options_full_featured>>":
@@ -148,21 +150,36 @@ cdef class SimplexTree:
 
         :returns:  the simplicial complex dimension.
         :rtype:  int
+
+        .. note::
+
+            This function is not constant time because it can recompute
+            dimension if required (can be triggered by
+            remove_maximal_simplex or prune_above_filtration methods).
         """
         return self.thisptr.dimension()
 
-    def set_dimension(self, dimension):
-        """This function sets the dimension of the simplicial complex.
+    def upper_bound_dimension(self):
+        """This function returns a valid dimension upper bound of the
+        simplicial complex.
 
-        insert and remove_maximal_simplex functions do not update dimension
-        value of the `SimplexTree`.
+        :returns:  an upper bound on the dimension of the simplicial complex.
+        :rtype:  int
+        """
+        return self.thisptr.upper_bound_dimension()
 
-        `AlphaComplex`, `RipsComplex`, `TangentialComplex` and `WitnessComplex`
-        automatically sets the correct dimension in their `create_simplex_tree`
-        functions.
+    def set_dimension(self, dimension):
+        """This function sets the dimension of the simplicial complex.
 
         :param dimension: The new dimension value.
         :type dimension: int.
+
+        .. note::
+
+            This function must be used with caution because it disables
+            dimension recomputation when required
+            (this recomputation can be triggered by remove_maximal_simplex
+            or prune_above_filtration methods.
         """
         self.thisptr.set_dimension(<int>dimension)
 
@@ -286,9 +303,49 @@ cdef class SimplexTree:
 
         :param simplex: The N-simplex, represented by a list of vertex.
         :type simplex: list of int.
+
+        .. note::
+
+            Be aware that removing is shifting data in a flat_map
+            (initialize_filtration to be done).
+
+        .. note::
+
+            The dimension of the simplicial complex may be lower after calling
+            remove_maximal_simplex than it was before. However,
+            upper_bound_dimension method will return the old value, which
+            remains a valid upper bound. If you care, you can call dimension
+            to recompute the exact dimension.
         """
         self.thisptr.remove_maximal_simplex(simplex)
 
+    def prune_above_filtration(self, filtration):
+        """Prune above filtration value given as parameter.
+
+        :param filtration: Maximum threshold value.
+        :type filtration: float.
+        :returns: The filtration modification information.
+        :rtype: bint
+
+
+        .. note::
+
+            Some simplex tree functions require the filtration to be valid.
+            prune_above_filtration function is not launching
+            initialize_filtration but returns the filtration modification
+            information. If the complex has changed , please call
+            initialize_filtration to recompute it.
+
+        .. note::
+
+            Note that the dimension of the simplicial complex may be lower
+            after calling prune_above_filtration than it was before. However,
+            upper_bound_dimension will return the old value, which remains a
+            valid upper bound. If you care, you can call dimension method to
+            recompute the exact dimension.
+        """
+        return self.thisptr.prune_above_filtration(filtration)
+
     def expansion(self, max_dim):
         """Expands the Simplex_tree containing only its one skeleton
         until dimension max_dim.
diff --git a/src/cython/test/test_simplex_tree.py b/src/cython/test/test_simplex_tree.py
index 801d52b7..8af653d2 100755
--- a/src/cython/test/test_simplex_tree.py
+++ b/src/cython/test/test_simplex_tree.py
@@ -134,3 +134,27 @@ def test_expansion():
     ([1, 2], 0.5), ([0, 1, 2], 0.5), ([1, 2, 3], 0.5), ([5], 0.6), ([6], 0.6),
     ([5, 6], 0.6), ([4], 0.7), ([2, 4], 0.7), ([0, 3], 0.8), ([0, 1, 3], 0.8),
     ([0, 2, 3], 0.8), ([0, 1, 2, 3], 0.8), ([4, 6], 0.9), ([3, 6], 1.0)]
+
+def test_automatic_dimension():
+    st = SimplexTree()
+    assert st.__is_defined() == True
+    assert st.__is_persistence_defined() == False
+
+    # insert test
+    assert st.insert([0,1,3], filtration=0.5) == True
+    assert st.insert([0,1,2], filtration=1.) == True
+
+    assert st.num_vertices() == 4
+    assert st.num_simplices() == 11
+
+    assert st.dimension() == 2
+    assert st.upper_bound_dimension() == 2
+
+    assert st.prune_above_filtration(0.6) == True
+    assert st.dimension() == 2
+    assert st.upper_bound_dimension() == 2
+
+    st.remove_maximal_simplex([0, 1, 3])
+    assert st.upper_bound_dimension() == 2
+    assert st.dimension() == 1
+    assert st.upper_bound_dimension() == 1