Add some documentation for Fix #31

Cythonization of Fix #31
Add some tests

7 files changed, 90 insertions, 6 deletions

diff --git a/src/Tangential_complex/include/gudhi/Tangential_complex.h b/src/Tangential_complex/include/gudhi/Tangential_complex.h
index 37cdf1b4..4a78127c 100644
--- a/src/Tangential_complex/include/gudhi/Tangential_complex.h
+++ b/src/Tangential_complex/include/gudhi/Tangential_complex.h
@@ -322,7 +322,11 @@ class Tangential_complex {
     for (std::size_t i = 0; i < m_points.size(); ++i) m_are_tangent_spaces_computed[i] = true;
   }
 
-  /// Computes the tangential complex.
+  /** \brief Computes the tangential complex.
+   *  \exception std::invalid_argument In debug mode, if the computed star dimension is too low. Try to set a bigger
+   *  maximal edge length value with `Tangential_complex::set_max_squared_edge_length` if
+   *  this happens.
+   */
   void compute_tangential_complex() {
 #ifdef GUDHI_TC_PERFORM_EXTRA_CHECKS
     std::cerr << red << "WARNING: GUDHI_TC_PERFORM_EXTRA_CHECKS is defined. "
@@ -1984,6 +1988,13 @@ class Tangential_complex {
     return os;
   }
 
+  /** \brief Sets the maximal possible squared edge length for the edges in the triangulations.
+   *
+   * @param[in] max_squared_edge_length Maximal possible squared edge length.
+   *
+   * If the maximal edge length value is too low `Tangential_complex::compute_tangential_complex` will throw an
+   * exception in debug mode.
+   */
   void set_max_squared_edge_length(FT max_squared_edge_length) { m_max_squared_edge_length = max_squared_edge_length; }
 
  private:
diff --git a/src/Tangential_complex/test/test_tangential_complex.cpp b/src/Tangential_complex/test/test_tangential_complex.cpp
index 4e2d4f65..103b8b30 100644
--- a/src/Tangential_complex/test/test_tangential_complex.cpp
+++ b/src/Tangential_complex/test/test_tangential_complex.cpp
@@ -126,3 +126,33 @@ BOOST_AUTO_TEST_CASE(test_mini_tangential) {
   BOOST_CHECK(stree.num_vertices() == 4);
   BOOST_CHECK(stree.num_simplices() == 6);
 }
+
+#ifdef GUDHI_DEBUG
+BOOST_AUTO_TEST_CASE(test_basic_example_throw) {
+  typedef CGAL::Epick_d<CGAL::Dynamic_dimension_tag> Kernel;
+  typedef Kernel::FT FT;
+  typedef Kernel::Point_d Point;
+  typedef Kernel::Vector_d Vector;
+  typedef tc::Tangential_complex<Kernel, CGAL::Dynamic_dimension_tag,CGAL::Parallel_tag> TC;
+
+  const int INTRINSIC_DIM = 2;
+  const int AMBIENT_DIM = 3;
+  const int NUM_POINTS = 1000;
+
+  Kernel k;
+
+  // Generate points on a 2-sphere
+  CGAL::Random_points_on_sphere_d<Point> generator(AMBIENT_DIM, 3.);
+  std::vector<Point> points;
+  points.reserve(NUM_POINTS);
+  for (int i = 0; i < NUM_POINTS; ++i)
+    points.push_back(*generator++);
+
+  // Compute the TC
+  TC tc(points, INTRINSIC_DIM, k);
+  tc.set_max_squared_edge_length(0.01);
+  std::cout << "test_basic_example_throw - set_max_squared_edge_length(0.01) to make GUDHI_CHECK fail" << std::endl;
+  BOOST_CHECK_THROW(tc.compute_tangential_complex(), std::invalid_argument);
+
+}
+#endif
diff --git a/src/cython/cython/tangential_complex.pyx b/src/cython/cython/tangential_complex.pyx
index 4bb07076..293ef8cb 100644
--- a/src/cython/cython/tangential_complex.pyx
+++ b/src/cython/cython/tangential_complex.pyx
@@ -36,6 +36,7 @@ cdef extern from "Tangential_complex_interface.h" namespace "Gudhi":
         Tangential_complex_interface(int intrisic_dim, vector[vector[double]] points)
         # bool from_file is a workaround for cython to find the correct signature
         Tangential_complex_interface(int intrisic_dim, string off_file, bool from_file)
+        void compute_tangential_complex() except +
         vector[double] get_point(unsigned vertex)
         unsigned number_of_vertices()
         unsigned number_of_simplices()
@@ -43,6 +44,7 @@ cdef extern from "Tangential_complex_interface.h" namespace "Gudhi":
         unsigned number_of_inconsistent_stars()
         void create_simplex_tree(Simplex_tree_interface_full_featured* simplex_tree)
         void fix_inconsistencies_using_perturbation(double max_perturb, double time_limit)
+        void set_max_squared_edge_length(double max_squared_edge_length)
 
 # TangentialComplex python interface
 cdef class TangentialComplex:
@@ -92,6 +94,17 @@ cdef class TangentialComplex:
          """
         return self.thisptr != NULL
 
+    def compute_tangential_complex(self):
+        """This function computes the tangential complex.
+
+        Raises:
+            ValueError: In debug mode, if the computed star dimension is too
+                low. Try to set a bigger maximal edge length value with
+                :func:`~gudhi.Tangential_complex.set_max_squared_edge_length`
+                if this happens.
+        """
+        self.thisptr.compute_tangential_complex()
+
     def get_point(self, vertex):
         """This function returns the point corresponding to a given vertex.
 
@@ -152,3 +165,16 @@ cdef class TangentialComplex:
         """
         self.thisptr.fix_inconsistencies_using_perturbation(max_perturb,
                                                             time_limit)
+
+    def set_max_squared_edge_length(self, max_squared_edge_length):
+        """Sets the maximal possible squared edge length for the edges in the
+        triangulations.
+
+        :param max_squared_edge_length: Maximal possible squared edge length.
+        :type max_squared_edge_length: double
+
+        If the maximal edge length value is too low
+        :func:`~gudhi.Tangential_complex.compute_tangential_complex`
+        will throw an exception in debug mode.
+        """
+        self.thisptr.set_max_squared_edge_length(max_squared_edge_length)
diff --git a/src/cython/doc/tangential_complex_user.rst b/src/cython/doc/tangential_complex_user.rst
index 5ce69e86..97471baf 100644
--- a/src/cython/doc/tangential_complex_user.rst
+++ b/src/cython/doc/tangential_complex_user.rst
@@ -128,6 +128,7 @@ This example builds the Tangential complex of point set read in an OFF file.
     import gudhi
     tc = gudhi.TangentialComplex(intrisic_dim = 1,
         off_file=gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off')
+    tc.compute_tangential_complex()
     result_str = 'Tangential contains ' + repr(tc.num_simplices()) + \
         ' simplices - ' + repr(tc.num_vertices()) + ' vertices.'
     print(result_str)
@@ -175,6 +176,7 @@ simplices.
    import gudhi
    tc = gudhi.TangentialComplex(intrisic_dim = 1,
        points=[[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+   tc.compute_tangential_complex()
    result_str = 'Tangential contains ' + repr(tc.num_vertices()) + ' vertices.'
    print(result_str)
 
diff --git a/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py b/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
index 0f8f5e80..536517d1 100755
--- a/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
+++ b/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
@@ -50,6 +50,7 @@ with open(args.file, 'r') as f:
         print("TangentialComplex creation from points read in a OFF file")
         
         tc = gudhi.TangentialComplex(intrisic_dim = args.intrisic_dim, off_file=args.file)
+        tc.compute_tangential_complex()
         st = tc.create_simplex_tree()
     
         message = "Number of simplices=" + repr(st.num_simplices())
diff --git a/src/cython/include/Tangential_complex_interface.h b/src/cython/include/Tangential_complex_interface.h
index 71418886..c4ddbdbe 100644
--- a/src/cython/include/Tangential_complex_interface.h
+++ b/src/cython/include/Tangential_complex_interface.h
@@ -49,8 +49,6 @@ class Tangential_complex_interface {
     Dynamic_kernel k;
 
     tangential_complex_ = new TC(points, intrisic_dim, k);
-    tangential_complex_->compute_tangential_complex();
-    num_inconsistencies_ = tangential_complex_->number_of_inconsistent_simplices();
   }
 
   Tangential_complex_interface(int intrisic_dim, const std::string& off_file_name, bool from_file = true) {
@@ -60,14 +58,17 @@ class Tangential_complex_interface {
     std::vector<Point_d> points = off_reader.get_point_cloud();
 
     tangential_complex_ = new TC(points, intrisic_dim, k);
-    tangential_complex_->compute_tangential_complex();
-    num_inconsistencies_ = tangential_complex_->number_of_inconsistent_simplices();
   }
 
   ~Tangential_complex_interface() {
     delete tangential_complex_;
   }
 
+  void compute_tangential_complex() {
+    tangential_complex_->compute_tangential_complex();
+    num_inconsistencies_ = tangential_complex_->number_of_inconsistent_simplices();
+  }
+
   std::vector<double> get_point(unsigned vh) {
     std::vector<double> vd;
     if (vh < tangential_complex_->number_of_vertices()) {
@@ -104,7 +105,11 @@ class Tangential_complex_interface {
     simplex_tree->initialize_filtration();
   }
 
- private:
+  void set_max_squared_edge_length(double max_squared_edge_length) {
+    tangential_complex_->set_max_squared_edge_length(max_squared_edge_length);
+  }
+
+private:
   TC* tangential_complex_;
   TC::Num_inconsistencies num_inconsistencies_;
 };
diff --git a/src/cython/test/test_tangential_complex.py b/src/cython/test/test_tangential_complex.py
index 5385a0d3..5c62f278 100755
--- a/src/cython/test/test_tangential_complex.py
+++ b/src/cython/test/test_tangential_complex.py
@@ -32,6 +32,15 @@ def test_tangential():
     tc = TangentialComplex(intrisic_dim = 1, points=point_list)
     assert tc.__is_defined() == True
     assert tc.num_vertices() == 4
+    assert tc.num_simplices() == 0
+    assert tc.num_inconsistent_simplices() == 0
+    assert tc.num_inconsistent_stars() == 0
+
+    tc.compute_tangential_complex()
+    assert tc.num_vertices() == 4
+    assert tc.num_simplices() == 4
+    assert tc.num_inconsistent_simplices() == 0
+    assert tc.num_inconsistent_stars() == 0
 
     st = tc.create_simplex_tree()
     assert st.__is_defined() == True