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

Former-commit-id: d0f6606d7afde132a4d86203eeff80e97f35adce

3 files changed, 89 insertions, 0 deletions

diff --git a/src/Kernels/doc/COPYRIGHT b/src/Kernels/doc/COPYRIGHT
new file mode 100644
index 00000000..0c36a526
--- /dev/null
+++ b/src/Kernels/doc/COPYRIGHT
@@ -0,0 +1,19 @@
+The files of this directory are part of the Gudhi Library. The Gudhi library
+(Geometric Understanding in Higher Dimensions) is a generic C++ library for
+computational topology.
+
+Author(s):       Mathieu Carrière
+
+Copyright (C) 2017  INRIA
+
+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/>.
diff --git a/src/Kernels/doc/Intro_kernels.h b/src/Kernels/doc/Intro_kernels.h
new file mode 100644
index 00000000..be97a6cf
--- /dev/null
+++ b/src/Kernels/doc/Intro_kernels.h
@@ -0,0 +1,61 @@
+/*    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):       Mathieu Carriere
+ *
+ *    Copyright (C) 2017  INRIA
+ *
+ *    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_KERNEL_INTRO_KERNEL_H_
+#define DOC_KERNEL_INTRO_KERNEL_H_
+
+namespace Gudhi {
+
+namespace kernel {
+
+/**  \defgroup kernel Kernels
+ * 
+ * \author    Mathieu Carrière
+ * 
+ * @{
+ * 
+ * Kernels are generalized scalar products. They take the form of functions whose evaluations on pairs of persistence diagrams are equal
+ * to the scalar products of the images of the diagrams under some feature map into a (generally unknown and infinite dimensional)
+ * Hilbert space. Kernels are
+ * very useful to handle any type of data for algorithms that require at least a Hilbert structure, such as Principal Component Analysis
+ * or Support Vector Machines. In this package, we implement three kernels for persistence diagrams: the Persistence Scale Space kernel,
+ * the Persistence Weighted Gaussian kernel and the Sliced Wasserstein kernel.
+ *
+ *
+ * When launching:
+ *
+ * \code $> ./BasicEx
+ * \endcode
+ *
+ * the program output is:
+ *
+ *
+ * \copyright GNU General Public License v3.                         
+ * \verbatim  Contact: gudhi-users@lists.gforge.inria.fr \endverbatim
+ */
+/** @} */  // end defgroup kernel
+
+}  // namespace kernel
+
+}  // namespace Gudhi
+
+#endif  // DOC_KERNEL_INTRO_KERNEL_H_
diff --git a/src/Kernels/include/gudhi/kernel.h b/src/Kernels/include/gudhi/kernel.h
index c4120d7a..6429efed 100644
--- a/src/Kernels/include/gudhi/kernel.h
+++ b/src/Kernels/include/gudhi/kernel.h
@@ -72,6 +72,7 @@ double pss_weight(std::pair<double,double> P){
 // ********************************************************************
 
 /** \brief Computes the Linear Persistence Weighted Gaussian Kernel between two persistence diagrams.
+ *  \ingroup kernel
  *
  * @param[in] PD1      first persistence diagram.
  * @param[in] PD2      second persistence diagram.
@@ -88,6 +89,7 @@ double lpwg(PD PD1, PD PD2, double sigma, double (*weight)(std::pair<double,doub
 }
 
 /** \brief Computes the Persistence Scale Space Kernel between two persistence diagrams.
+ * \ingroup kernel
  *
  * @param[in] PD1      first persistence diagram.
  * @param[in] PD2      second persistence diagram.
@@ -101,6 +103,7 @@ double pss(PD PD1, PD PD2, double sigma){
 }
 
 /** \brief Computes the Gaussian Persistence Weighted Gaussian Kernel between two persistence diagrams.
+ * \ingroup kernel
  *
  * @param[in] PD1      first persistence diagram.
  * @param[in] PD2      second persistence diagram.
@@ -117,6 +120,7 @@ double gpwg(PD PD1, PD PD2, double sigma, double tau, double (*weight)(std::pair
 }
 
 /** \brief Computes the RKHS distance induced by the Gaussian Kernel Embedding between two persistence diagrams.
+ * \ingroup kernel
  *
  * @param[in] PD1      first persistence diagram.
  * @param[in] PD2      second persistence diagram.
@@ -214,6 +218,7 @@ double compute_sw(const std::vector<std::vector<std::pair<int,double> > > & V1,
 }
 
 /** \brief Computes the Sliced Wasserstein distance between two persistence diagrams.
+ * \ingroup kernel
  *
  * @param[in] PD1 first persistence diagram.
  * @param[in] PD2 second persistence diagram.
@@ -356,6 +361,7 @@ std::vector<std::pair<double,double> > random_Fourier(double sigma, int M = 1000
 
 
 /** \brief Computes an approximation of the Linear Persistence Weighted Gaussian Kernel between two persistence diagrams with random Fourier features.
+ * \ingroup kernel
  *
  * @param[in] PD1       first persistence diagram.
  * @param[in] PD2       second persistence diagram.
@@ -372,6 +378,7 @@ double approx_lpwg(PD PD1, PD PD2, double sigma, double (*weight)(std::pair<doub
 }
 
 /** \brief Computes an approximation of the Persistence Scale Space Kernel between two persistence diagrams with random Fourier features.
+ * \ingroup kernel
  *
  * @param[in] PD1       first persistence diagram.
  * @param[in] PD2       second persistence diagram.
@@ -387,6 +394,7 @@ double approx_pss(PD PD1, PD PD2, double sigma, int M = 1000){
 
 
 /** \brief Computes an approximation of the Gaussian Persistence Weighted Gaussian Kernel between two persistence diagrams with random Fourier features.
+ * \ingroup kernel
  *
  * @param[in] PD1       first persistence diagram.
  * @param[in] PD2       second persistence diagram.
@@ -405,6 +413,7 @@ double approx_gpwg(PD PD1, PD PD2, double sigma, double tau, double (*weight)(st
 
 
 /** \brief Computes an approximation of the Sliced Wasserstein distance between two persistence diagrams.
+ * \ingroup kernel
  *
  * @param[in] PD1       first persistence diagram.
  * @param[in] PD2       second persistence diagram.