Merge last trunk modification

Fix doc issue
Still doc issue


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

Former-commit-id: 0a99345f06e93a3525691699a6fe1505979e8e8e

8 files changed, 133 insertions, 71 deletions

diff --git a/src/Simplex_tree/concept/SimplexKey.h b/src/Simplex_tree/concept/SimplexKey.h
index 7fdbdd84..9fbed401 100644
--- a/src/Simplex_tree/concept/SimplexKey.h
+++ b/src/Simplex_tree/concept/SimplexKey.h
@@ -22,7 +22,7 @@
 
  /** \brief Key type used as simplex identifier.
   *
-  * Must be a signed integer type.
+  * Must be an integer type.
   */
  struct SimplexKey {};
  
diff --git a/src/Simplex_tree/concept/SimplexTreeOptions.h b/src/Simplex_tree/concept/SimplexTreeOptions.h
index d072cf34..89acdc18 100644
--- a/src/Simplex_tree/concept/SimplexTreeOptions.h
+++ b/src/Simplex_tree/concept/SimplexTreeOptions.h
@@ -31,7 +31,7 @@ struct SimplexTreeOptions {
   typedef VertexHandle Vertex_handle;
   /// Must be comparable with operator<.
   typedef FiltrationValue Filtration_value;
-  /// Must be a signed integer type.
+  /// Must be an integer type.
   typedef SimplexKey Simplex_key;
   /// If true, each simplex has extra storage for one `Simplex_key`. Necessary for `Persistent_cohomology`.
   static const bool store_key;
diff --git a/src/Simplex_tree/doc/Intro_simplex_tree.h b/src/Simplex_tree/doc/Intro_simplex_tree.h
new file mode 100644
index 00000000..940dd694
--- /dev/null
+++ b/src/Simplex_tree/doc/Intro_simplex_tree.h
@@ -0,0 +1,85 @@
+/*    This file is part of the Gudhi Library. The Gudhi library
+ *    (Geometric Understanding in Higher Dimensions) is a generic C++
+ *    library for computational topology.
+ *
+ *    Author(s):       Clément Maria
+ *
+ *    Copyright (C) 2014  INRIA Sophia Antipolis-Méditerranée (France)
+ *
+ *    This program is free software: you can redistribute it and/or modify
+ *    it under the terms of the GNU General Public License as published by
+ *    the Free Software Foundation, either version 3 of the License, or
+ *    (at your option) any later version.
+ *
+ *    This program is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU General Public License for more details.
+ *
+ *    You should have received a copy of the GNU General Public License
+ *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef DOC_SIMPLEX_TREE_INTRO_SIMPLEX_TREE_H_
+#define DOC_SIMPLEX_TREE_INTRO_SIMPLEX_TREE_H_
+
+// needs namespace for Doxygen to link on classes
+namespace Gudhi {
+
+
+/** \defgroup simplex_tree Filtered Complexes
+ * @{
+ * \author    Cl&eacute;ment Maria
+ *
+ * A simplicial complex \f$\mathbf{K}\f$ on a set of vertices \f$V = \{1, \cdots ,|V|\}\f$ is a collection of
+ * implices \f$\{\sigma\}\f$, \f$\sigma \subseteq V\f$ such that
+ * \f$\tau \subseteq \sigma \in \mathbf{K} \rightarrow \tau \in \mathbf{K}\f$. The dimension \f$n=|\sigma|-1\f$ of
+ * \f$\sigma\f$ is its number of elements minus \f$1\f$.
+ *
+ * A filtration of a simplicial complex is a function \f$f:\mathbf{K} \rightarrow \mathbb{R}\f$ satisfying
+ * \f$f(\tau)\leq f(\sigma)\f$ whenever \f$\tau \subseteq \sigma\f$. Ordering the simplices by increasing filtration
+ * values (breaking ties so as a simplex appears after its subsimplices of same filtration value) provides an
+ * indexing scheme.
+ *
+ * \section filteredcomplexesimplementation Implementations
+ * \subsection filteredcomplexessimplextree Simplex tree
+ * There are two implementation of complexes. The first on is the Simplex_tree data structure. The simplex tree is an
+ * efficient and flexible data structure for representing general (filtered) simplicial complexes. The data structure
+ * is described in \cite boissonnatmariasimplextreealgorithmica
+ * \image html "Simplex_tree_representation.png" "Simplex tree representation"
+ * 
+ * \subsubsection filteredcomplexessimplextreeexamples Examples
+ * 
+ * Here is a list of simplex tree examples :
+ * \li <a href="_simplex_tree_2simple_simplex_tree_8cpp-example.html">
+ * Simplex_tree/simple_simplex_tree.cpp</a> - Simple simplex tree construction and basic function use.
+ *
+ * \li <a href="_simplex_tree_2simplex_tree_from_cliques_of_graph_8cpp-example.html">
+ * Simplex_tree/simplex_tree_from_cliques_of_graph.cpp</a> - Simplex tree construction from cliques of graph read in
+ * a file.
+ * 
+ * Simplex tree construction with \f$\mathbb{Z}/3\mathbb{Z}\f$ coefficients on weighted graph Klein bottle file:
+ * \code $> ./simplex_tree_from_cliques_of_graph ../../data/points/Klein_bottle_complex.txt 3 \endcode
+ * \code Insert the 1-skeleton in the simplex tree in 0.000404 s. 
+max_dim = 3
+Expand the simplex tree in 3.8e-05 s. 
+Information of the Simplex Tree: 
+Number of vertices = 10   Number of simplices = 98 \endcode
+ * 
+ * \li <a href="_simplex_tree_2example_alpha_shapes_3_simplex_tree_from_off_file_8cpp-example.html">
+ * Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp</a> - Simplex tree is computed and displayed from a 3D alpha
+ * complex (Requires CGAL, GMP and GMPXX to be installed)
+ * 
+ * 
+ * \subsection filteredcomplexeshassecomplex Hasse complex
+ * The second one is the Hasse_complex. The Hasse complex is a data structure representing explicitly all co-dimension
+ * 1 incidence relations in a complex. It is consequently faster when accessing the boundary of a simplex, but is less
+ * compact and harder to construct from scratch.
+ * 
+ * \copyright GNU General Public License v3.
+ * @}
+ */
+
+}  // namespace Gudhi
+
+#endif  // DOC_SIMPLEX_TREE_INTRO_SIMPLEX_TREE_H_
diff --git a/src/Simplex_tree/example/CMakeLists.txt b/src/Simplex_tree/example/CMakeLists.txt
index 9314a805..e5285591 100644
--- a/src/Simplex_tree/example/CMakeLists.txt
+++ b/src/Simplex_tree/example/CMakeLists.txt
@@ -5,8 +5,10 @@ add_executable ( simplex_tree_from_cliques_of_graph simplex_tree_from_cliques_of
 if (TBB_FOUND)
   target_link_libraries(simplex_tree_from_cliques_of_graph ${TBB_LIBRARIES})
 endif()
-add_test(simplex_tree_from_cliques_of_graph_2 ${CMAKE_CURRENT_BINARY_DIR}/simplex_tree_from_cliques_of_graph ${CMAKE_SOURCE_DIR}/data/points/Klein_bottle_complex.txt 2)
-add_test(simplex_tree_from_cliques_of_graph_3 ${CMAKE_CURRENT_BINARY_DIR}/simplex_tree_from_cliques_of_graph ${CMAKE_SOURCE_DIR}/data/points/Klein_bottle_complex.txt 3)
+add_test(simplex_tree_from_cliques_of_graph_2 ${CMAKE_CURRENT_BINARY_DIR}/simplex_tree_from_cliques_of_graph
+         ${CMAKE_SOURCE_DIR}/data/filtered_simplicial_complex/Klein_bottle_complex.fsc 2)
+add_test(simplex_tree_from_cliques_of_graph_3 ${CMAKE_CURRENT_BINARY_DIR}/simplex_tree_from_cliques_of_graph
+         ${CMAKE_SOURCE_DIR}/data/filtered_simplicial_complex/Klein_bottle_complex.fsc 3)
 
 add_executable ( simple_simplex_tree simple_simplex_tree.cpp )
 if (TBB_FOUND)
@@ -20,10 +22,12 @@ add_test(mini_simplex_tree ${CMAKE_CURRENT_BINARY_DIR}/mini_simplex_tree)
 
 # An example with Simplex-tree using CGAL alpha_shapes_3
 if(GMP_FOUND AND CGAL_FOUND)
-  add_executable ( simplex_tree_from_alpha_shapes_3 simplex_tree_from_alpha_shapes_3.cpp )
-  target_link_libraries(simplex_tree_from_alpha_shapes_3 ${GMP_LIBRARIES} ${CGAL_LIBRARY} ${Boost_SYSTEM_LIBRARY})
+  add_executable ( alpha_shapes_3_simplex_tree_from_off_file example_alpha_shapes_3_simplex_tree_from_off_file.cpp )
+  target_link_libraries(alpha_shapes_3_simplex_tree_from_off_file ${GMP_LIBRARIES} ${CGAL_LIBRARY} ${Boost_SYSTEM_LIBRARY})
   if (TBB_FOUND)
-    target_link_libraries(simplex_tree_from_alpha_shapes_3 ${TBB_LIBRARIES})
+    target_link_libraries(alpha_shapes_3_simplex_tree_from_off_file ${TBB_LIBRARIES})
   endif()
-  add_test(simplex_tree_from_alpha_shapes_3 ${CMAKE_CURRENT_BINARY_DIR}/simplex_tree_from_alpha_shapes_3 ${CMAKE_SOURCE_DIR}/data/points/bunny_5000)
+  add_test(alpha_shapes_3_simplex_tree_from_off_file
+           ${CMAKE_CURRENT_BINARY_DIR}/alpha_shapes_3_simplex_tree_from_off_file
+           ${CMAKE_SOURCE_DIR}/data/points/bunny_5000.off)
 endif()
diff --git a/src/Simplex_tree/example/README b/src/Simplex_tree/example/README
index 03c759cb..e37af790 100644
--- a/src/Simplex_tree/example/README
+++ b/src/Simplex_tree/example/README
@@ -52,7 +52,7 @@ EXAMPLE OF SIMPLE INSERTION
 
 *** Simplex tree construction with Z/2Z coefficients on weighted graph Klein bottle file:
 
-./simplex_tree_from_file ../../../data/points/Klein_bottle_complex.txt 2
+./simplex_tree_from_cliques_of_graph ../../../data/points/Klein_bottle_complex.txt 2
 Insert the 1-skeleton in the simplex tree in 0 s. 
 Expand the simplex tree in 0 s. 
 Information of the Simplex Tree: 
@@ -60,7 +60,7 @@ Information of the Simplex Tree:
 
 with Z/3Z coefficients:
 
-./simplex_tree_from_file ../../../data/points/Klein_bottle_complex.txt 3
+./simplex_tree_from_cliques_of_graph ../../../data/points/Klein_bottle_complex.txt 3
 
 Insert the 1-skeleton in the simplex tree in 0 s.
 Expand the simplex tree in 0 s.
diff --git a/src/Simplex_tree/example/simplex_tree_from_alpha_shapes_3.cpp b/src/Simplex_tree/example/example_alpha_shapes_3_simplex_tree_from_off_file.cpp
index 49d358ab..ff2eebcb 100644
--- a/src/Simplex_tree/example/simplex_tree_from_alpha_shapes_3.cpp
+++ b/src/Simplex_tree/example/example_alpha_shapes_3_simplex_tree_from_off_file.cpp
@@ -20,8 +20,9 @@
  *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <gudhi/graph_simplicial_complex.h>
 #include <gudhi/Simplex_tree.h>
+#include <gudhi/Points_3D_off_io.h>
+
 #include <boost/variant.hpp>
 
 #include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
@@ -118,24 +119,21 @@ int main(int argc, char * const argv[]) {
   // program args management
   if (argc != 2) {
     std::cerr << "Usage: " << argv[0]
-        << " path_to_file_graph \n";
+        << " path_to_off_file \n";
     return 0;
   }
 
   // Read points from file
-  std::string filegraph = argv[1];
-  std::list<Point> lp;
-  std::ifstream is(filegraph.c_str());
-  int n;
-  is >> n;
-#ifdef DEBUG_TRACES
-  std::cout << "Reading " << n << " points " << std::endl;
-#endif  // DEBUG_TRACES
-  Point p;
-  for (; n > 0; n--) {
-    is >> p;
-    lp.push_back(p);
+  std::string offInputFile(argv[1]);
+  // Read the OFF file (input file name given as parameter) and triangulate points
+  Gudhi::Points_3D_off_reader<Point> off_reader(offInputFile);
+  // Check the read operation was correct
+  if (!off_reader.is_valid()) {
+    std::cerr << "Unable to read file " << argv[1] << std::endl;
+    return 0;
   }
+  // Retrieve the triangulation
+  std::vector<Point> lp = off_reader.get_point_cloud();
 
   // alpha shape construction from points. CGAL has a strange behavior in REGULARIZED mode.
   Alpha_shape_3 as(lp.begin(), lp.end(), 0, Alpha_shape_3::GENERAL);
diff --git a/src/Simplex_tree/include/gudhi/Simplex_tree.h b/src/Simplex_tree/include/gudhi/Simplex_tree.h
index 65ead001..63e3f0e5 100644
--- a/src/Simplex_tree/include/gudhi/Simplex_tree.h
+++ b/src/Simplex_tree/include/gudhi/Simplex_tree.h
@@ -48,40 +48,9 @@
 #include <limits>  // Inf
 #include <initializer_list>
 #include <algorithm>  // for std::max
+#include <cstdint>  // for std::uint32_t
 
 namespace Gudhi {
-/** \defgroup simplex_tree Filtered Complexes
- * \author    Cl&eacute;ment Maria
- *
- * A simplicial complex \f$\mathbf{K}\f$
- * on a set of vertices \f$V = \{1, \cdots ,|V|\}\f$ is a collection of simplices
- * \f$\{\sigma\}\f$,
- * \f$\sigma \subseteq V\f$ such that \f$\tau \subseteq \sigma \in \mathbf{K} \rightarrow \tau \in
- * \mathbf{K}\f$. The
- * dimension \f$n=|\sigma|-1\f$ of \f$\sigma\f$ is its number of elements minus \f$1\f$.
- *
- * A filtration of a simplicial complex is
- * a function \f$f:\mathbf{K} \rightarrow \mathbb{R}\f$ satisfying \f$f(\tau)\leq f(\sigma)\f$ whenever
- * \f$\tau \subseteq \sigma\f$. Ordering the simplices by increasing filtration values
- * (breaking ties so as a simplex appears after its subsimplices of same filtration value)
- * provides an indexing scheme.
- *
-
- <DT>Implementations:</DT>
- There are two implementation of complexes. The first on is the Simplex_tree data structure.
- The simplex tree is an efficient and flexible
- data structure for representing general (filtered) simplicial complexes. The data structure
- is described in \cite boissonnatmariasimplextreealgorithmica
- \image html "Simplex_tree_representation.png" "Simplex tree representation"
-
- The second one is the Hasse_complex. The Hasse complex is a data structure representing
- explicitly all co-dimension 1 incidence relations in a complex. It is consequently faster
- when accessing the boundary of a simplex, but is less compact and harder to construct from
- scratch.
-
- * \copyright GNU General Public License v3.
- * @{
- */
 
 struct Simplex_tree_options_full_featured;
 
@@ -109,7 +78,7 @@ class Simplex_tree {
   typedef typename Options::Filtration_value Filtration_value;
   /** \brief Key associated to each simplex.
    *
-   * Must be a signed integer type. */
+   * Must be an integer type. */
   typedef typename Options::Simplex_key Simplex_key;
   /** \brief Type for the vertex handle.
    *
@@ -1297,25 +1266,31 @@ std::istream& operator>>(std::istream & is, Simplex_tree<T...> & st) {
   return is;
 }
 
-/// Model of SimplexTreeOptions.
+/** Model of SimplexTreeOptions.
+ * 
+ * Maximum number of simplices to compute persistence is <CODE>std::numeric_limits<std::uint32_t>::max()</CODE>
+ * (about 4 billions of simplices). */
 struct Simplex_tree_options_full_featured {
   typedef linear_indexing_tag Indexing_tag;
   typedef int Vertex_handle;
   typedef double Filtration_value;
-  typedef int Simplex_key;
+  typedef std::uint32_t Simplex_key;
   static const bool store_key = true;
   static const bool store_filtration = true;
   static const bool contiguous_vertices = false;
 };
 
-/** Model of SimplexTreeOptions, faster than
-  `Simplex_tree_options_full_featured` but note the unsafe
-  `contiguous_vertices` option. */
+/** Model of SimplexTreeOptions, faster than `Simplex_tree_options_full_featured` but note the unsafe
+ * `contiguous_vertices` option.
+ * 
+ * Maximum number of simplices to compute persistence is <CODE>std::numeric_limits<std::uint32_t>::max()</CODE>
+ * (about 4 billions of simplices). */
+
 struct Simplex_tree_options_fast_persistence {
   typedef linear_indexing_tag Indexing_tag;
   typedef int Vertex_handle;
   typedef float Filtration_value;
-  typedef int Simplex_key;
+  typedef std::uint32_t Simplex_key;
   static const bool store_key = true;
   static const bool store_filtration = true;
   static const bool contiguous_vertices = true;
diff --git a/src/Simplex_tree/test/simplex_tree_unit_test.cpp b/src/Simplex_tree/test/simplex_tree_unit_test.cpp
index b1bb23b1..28bf202b 100644
--- a/src/Simplex_tree/test/simplex_tree_unit_test.cpp
+++ b/src/Simplex_tree/test/simplex_tree_unit_test.cpp
@@ -806,14 +806,14 @@ BOOST_AUTO_TEST_CASE(make_filtration_non_decreasing) {
   st.insert_simplex_and_subfaces({3, 0}, 2.0);
   st.insert_simplex_and_subfaces({3, 4, 5}, 2.0);
   
-  // Inserted simplex:
-  //    1
-  //    o
-  //   /X\
-  //  o---o---o---o
-  //  2   0   3\X/4
-  //            o
-  //            5
+  /* Inserted simplex:     */
+  /*    1                  */
+  /*    o                  */
+  /*   /X\                 */
+  /*  o---o---o---o        */
+  /*  2   0   3\X/4        */
+  /*            o          */
+  /*            5          */
 
   std::cout << "Check default insertion ensures the filtration values are non decreasing" << std::endl;
   BOOST_CHECK(!st.make_filtration_non_decreasing());