Merge set_dimension_mechanism_precision branch

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

Former-commit-id: b308c3c49a541175f4c70e7e28575ac503552514

4 files changed, 146 insertions, 19 deletions

diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree.h b/src/Simplex_tree/include/gudhi/Simplex_tree.h
index 5d8a90ee..96e6007c 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..8a436619 100644
--- a/src/cython/cython/simplex_tree.pyx
+++ b/src/cython/cython/simplex_tree.pyx
@@ -37,11 +37,13 @@ cdef extern from "Simplex_tree_interface.h" namespace "Gudhi":
     cdef cppclass Simplex_tree_interface_full_featured "Gudhi::Simplex_tree_interface<Gudhi::Simplex_tree_options_full_featured>":
         Simplex_tree()
         double simplex_filtration(vector[int] simplex)
+        void assign_simplex_filtration(vector[int] simplex, double filtration)
         void initialize_filtration()
         int num_vertices()
         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 +52,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>>":
@@ -113,15 +116,31 @@ cdef class SimplexTree:
         """
         return self.thisptr.simplex_filtration(simplex)
 
+    def assign_filtration(self, simplex, filtration):
+        """This function assigns the simplicial complex filtration value for a
+        given N-simplex.
+
+        :param simplex: The N-simplex, represented by a list of vertex.
+        :type simplex: list of int.
+        :param filtration:  The simplicial complex filtration value.
+        :type filtration:  float
+        """
+        self.thisptr.assign_simplex_filtration(simplex, filtration)
+
     def initialize_filtration(self):
         """This function initializes and sorts the simplicial complex
         filtration vector.
 
         .. note::
 
-            This function must be launched before persistence, betti_numbers,
-            persistent_betti_numbers or get_filtration after inserting or
-            removing simplices.
+            This function must be launched before
+            :func:`persistence()<gudhi.SimplexTree.persistence>`,
+            :func:`betti_numbers()<gudhi.SimplexTree.betti_numbers>`,
+            :func:`persistent_betti_numbers()<gudhi.SimplexTree.persistent_betti_numbers>`,
+            or :func:`get_filtration()<gudhi.SimplexTree.get_filtration>`
+            after :func:`inserting<gudhi.SimplexTree.insert>` or
+            :func:`removing<gudhi.SimplexTree.remove_maximal_simplex>`
+            simplices.
         """
         self.thisptr.initialize_filtration()
 
@@ -148,21 +167,42 @@ 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
+            :func:`remove_maximal_simplex()<gudhi.SimplexTree.remove_maximal_simplex>`
+            or
+            :func:`prune_above_filtration()<gudhi.SimplexTree.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
+            :func:`remove_maximal_simplex()<gudhi.SimplexTree.remove_maximal_simplex>`
+            or
+            :func:`prune_above_filtration()<gudhi.SimplexTree.prune_above_filtration>`
+            ).
         """
         self.thisptr.set_dimension(<int>dimension)
 
@@ -286,9 +326,57 @@ 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
+            (:func:`initialize_filtration()<gudhi.SimplexTree.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,
+            :func:`upper_bound_dimension()<gudhi.SimplexTree.upper_bound_dimension>`
+            method will return the old value, which
+            remains a valid upper bound. If you care, you can call
+            :func:`dimension()<gudhi.SimplexTree.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
+            :func:`initialize_filtration()<gudhi.SimplexTree.initialize_filtration>`
+            but returns the filtration modification
+            information. If the complex has changed , please call
+            :func:`initialize_filtration()<gudhi.SimplexTree.initialize_filtration>`
+            to recompute it.
+
+        .. note::
+
+            Note that the dimension of the simplicial complex may be lower
+            after calling
+            :func:`prune_above_filtration()<gudhi.SimplexTree.prune_above_filtration>`
+            than it was before. However,
+            :func:`upper_bound_dimension()<gudhi.SimplexTree.upper_bound_dimension>`
+            will return the old value, which remains a
+            valid upper bound. If you care, you can call
+            :func:`dimension()<gudhi.SimplexTree.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.
@@ -336,8 +424,9 @@ cdef class SimplexTree:
         :returns: The Betti numbers ([B0, B1, ..., Bn]).
         :rtype:  list of int
 
-        :note: betti_numbers function requires persistence function to be
-            launched first.
+        :note: betti_numbers function requires
+            :func:`persistence()<gudhi.SimplexTree.persistence>`
+            function to be launched first.
         """
         cdef vector[int] bn_result
         if self.pcohptr != NULL:
@@ -361,7 +450,8 @@ cdef class SimplexTree:
         :returns: The persistent Betti numbers ([B0, B1, ..., Bn]).
         :rtype:  list of int
 
-        :note: persistent_betti_numbers function requires persistence
+        :note: persistent_betti_numbers function requires
+            :func:`persistence()<gudhi.SimplexTree.persistence>`
             function to be launched first.
         """
         cdef vector[int] pbn_result
@@ -381,8 +471,9 @@ cdef class SimplexTree:
         :returns: The persistence intervals.
         :rtype:  list of pair of float
 
-        :note: intervals_in_dim function requires persistence function to be
-            launched first.
+        :note: intervals_in_dim function requires
+            :func:`persistence()<gudhi.SimplexTree.persistence>`
+            function to be launched first.
         """
         cdef vector[pair[double,double]] intervals_result
         if self.pcohptr != NULL:
@@ -399,8 +490,9 @@ cdef class SimplexTree:
         :param persistence_file: The specific dimension.
         :type persistence_file: string.
 
-        :note: intervals_in_dim function requires persistence function to be
-            launched first.
+        :note: intervals_in_dim function requires
+            :func:`persistence()<gudhi.SimplexTree.persistence>`
+            function to be launched first.
         """
         if self.pcohptr != NULL:
             if persistence_file != '':
diff --git a/src/cython/include/Simplex_tree_interface.h b/src/cython/include/Simplex_tree_interface.h
index 09e7e992..54a4f824 100644
--- a/src/cython/include/Simplex_tree_interface.h
+++ b/src/cython/include/Simplex_tree_interface.h
@@ -52,6 +52,10 @@ class Simplex_tree_interface : public Simplex_tree<SimplexTreeOptions> {
     return (Base::find(vh) != Base::null_simplex());
   }
 
+  void assign_simplex_filtration(const Simplex& vh, Filtration_value filtration) {
+    Base::assign_filtration(Base::find(vh), filtration);
+  }
+
   bool insert(const Simplex& simplex, Filtration_value filtration = 0) {
     Insertion_result result = Base::insert_simplex_and_subfaces(simplex, filtration);
     return (result.second);
diff --git a/src/cython/test/test_simplex_tree.py b/src/cython/test/test_simplex_tree.py
index 801d52b7..6dec5d94 100755
--- a/src/cython/test/test_simplex_tree.py
+++ b/src/cython/test/test_simplex_tree.py
@@ -134,3 +134,30 @@ 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.assign_filtration([0, 1, 3], 0.7)
+    assert st.filtration([0, 1, 3]) == 0.7
+
+    st.remove_maximal_simplex([0, 1, 3])
+    assert st.upper_bound_dimension() == 2
+    assert st.dimension() == 1
+    assert st.upper_bound_dimension() == 1