Merge pull request #3712 from rcurtin/kernels-doc

Document all of kernels/ directory.

src/mlpack/core/kernels/cauchy_kernel.hpp

@@ -76,6 +76,11 @@ class CauchyKernel
     ar(CEREAL_NVP(bandwidth));
   }
 
+  // Get the kernel bandwidth.
+  const double Bandwidth() const { return bandwidth; }
+  // Modify the kernel bandwidth.
+  void Bandwidth(const double bw) { this->bandwidth = bw; }
+
  private:
   //! Kernel bandwidth.
   double bandwidth;

src/mlpack/core/kernels/cosine_distance.hpp → src/mlpack/core/kernels/cosine_similarity.hpp

@@ -1,17 +1,17 @@
 /**
- * @file core/kernels/cosine_distance.hpp
+ * @file core/kernels/cosine_similarity.hpp
  * @author Ryan Curtin
  *
- * This implements the cosine distance (or cosine similarity) between two
- * vectors, which is a measure of the angle between the two vectors.
+ * This implements the cosine similarity between two vectors, which is a measure
+ * of the angle between the two vectors.
  *
  * mlpack is free software; you may redistribute it and/or modify it under the
  * terms of the 3-clause BSD license.  You should have received a copy of the
  * 3-clause BSD license along with mlpack.  If not, see
  * http://www.opensource.org/licenses/BSD-3-Clause for more information.
  */
-#ifndef MLPACK_CORE_KERNELS_COSINE_DISTANCE_HPP
-#define MLPACK_CORE_KERNELS_COSINE_DISTANCE_HPP
+#ifndef MLPACK_CORE_KERNELS_COSINE_SIMILARITY_HPP
+#define MLPACK_CORE_KERNELS_COSINE_SIMILARITY_HPP
 
 #include <mlpack/prereqs.hpp>
 #include <mlpack/core/kernels/kernel_traits.hpp>
@@ -27,7 +27,7 @@ namespace mlpack {
  *
  * and this class assumes the standard L2 inner product.
  */
-class CosineDistance
+class CosineSimilarity
 {
  public:
   /**
@@ -47,7 +47,7 @@ class CosineDistance
 
 //! Kernel traits for the cosine distance.
 template<>
-class KernelTraits<CosineDistance>
+class KernelTraits<CosineSimilarity>
 {
  public:
   //! The cosine kernel is normalized: K(x, x) = 1 for all x.
@@ -57,9 +57,12 @@ class KernelTraits<CosineDistance>
   static const bool UsesSquaredDistance = false;
 };
 
+// This name is deprecated and can be removed in mlpack 5.0.0.
+typedef CosineSimilarity CosineDistance;
+
 } // namespace mlpack
 
 // Include implementation.
-#include "cosine_distance_impl.hpp"
+#include "cosine_similarity_impl.hpp"
 
 #endif

src/mlpack/core/kernels/cosine_distance_impl.hpp → src/mlpack/core/kernels/cosine_similarity_impl.hpp

@@ -1,23 +1,23 @@
 /**
- * @file core/kernels/cosine_distance_impl.hpp
+ * @file core/kernels/cosine_similarity_impl.hpp
  * @author Ryan Curtin
  *
- * This implements the cosine distance.
+ * This implements the cosine similarity.
  *
  * mlpack is free software; you may redistribute it and/or modify it under the
  * terms of the 3-clause BSD license.  You should have received a copy of the
  * 3-clause BSD license along with mlpack.  If not, see
  * http://www.opensource.org/licenses/BSD-3-Clause for more information.
  */
-#ifndef MLPACK_CORE_KERNELS_COSINE_DISTANCE_IMPL_HPP
-#define MLPACK_CORE_KERNELS_COSINE_DISTANCE_IMPL_HPP
+#ifndef MLPACK_CORE_KERNELS_COSINE_SIMILARITY_IMPL_HPP
+#define MLPACK_CORE_KERNELS_COSINE_SIMILARITY_IMPL_HPP
 
-#include "cosine_distance.hpp"
+#include "cosine_similarity.hpp"
 
 namespace mlpack {
 
 template<typename VecTypeA, typename VecTypeB>
-double CosineDistance::Evaluate(const VecTypeA& a, const VecTypeB& b)
+double CosineSimilarity::Evaluate(const VecTypeA& a, const VecTypeB& b)
 {
   // Since we are using the L2 inner product, this is easy.  But we have to make
   // sure we aren't dividing by zero (if we are, then the cosine similarity is

src/mlpack/core/kernels/epanechnikov_kernel.hpp

@@ -70,6 +70,15 @@ class EpanechnikovKernel
    */
   inline double Normalizer(const size_t dimension);
 
+  // Get the bandwidth of the kernel.
+  const double Bandwidth() const { return bandwidth; }
+  // Modify the bandwidth of the kernel.
+  void Bandwidth(const double bandwidth)
+  {
+    this->bandwidth = bandwidth;
+    this->inverseBandwidthSquared = 1.0 / (bandwidth * bandwidth);
+  }
+
   /**
    * Serialize the kernel.
    */

src/mlpack/core/kernels/hyperbolic_tangent_kernel.hpp

@@ -64,12 +64,12 @@ class HyperbolicTangentKernel
   //! Get scale factor.
   double Scale() const { return scale; }
   //! Modify scale factor.
-  double& Scale() { return scale; }
+  void Scale(const double scale) { this->scale = scale; }
 
   //! Get offset for the kernel.
   double Offset() const { return offset; }
   //! Modify offset for the kernel.
-  double& Offset() { return offset; }
+  void Offset(const double offset) { this->offset = offset; }
 
   //! Serialize the kernel.
   template<typename Archive>

src/mlpack/core/kernels/kernels.hpp

@@ -15,7 +15,7 @@
 #include "kernel_traits.hpp"
 
 #include "cauchy_kernel.hpp"
-#include "cosine_distance.hpp"
+#include "cosine_similarity.hpp"
 #include "epanechnikov_kernel.hpp"
 #include "example_kernel.hpp"
 #include "gaussian_kernel.hpp"

src/mlpack/core/kernels/laplacian_kernel.hpp

@@ -30,19 +30,11 @@ class LaplacianKernel
 {
  public:
   /**
-   * Default constructor; sets bandwidth to 1.0.
-   */
-  LaplacianKernel() : bandwidth(1.0)
-  { }
-
-  /**
-   * Construct the Laplacian kernel with a custom bandwidth.
+   * Construct the Laplacian kernel with the given bandwidth.
    *
    * @param bandwidth The bandwidth of the kernel (@f$\mu@f$).
    */
-  LaplacianKernel(double bandwidth) :
-      bandwidth(bandwidth)
-  { }
+  LaplacianKernel(const double bandwidth = 1.0) : bandwidth(bandwidth) { }
 
   /**
    * Evaluation of the Laplacian kernel.  This could be generalized to use any
@@ -93,7 +85,7 @@ class LaplacianKernel
   //! Get the bandwidth.
   double Bandwidth() const { return bandwidth; }
   //! Modify the bandwidth.
-  double& Bandwidth() { return bandwidth; }
+  void Bandwidth(const double bandwidth) { this->bandwidth = bandwidth; }
 
   //! Serialize the kernel.
   template<typename Archive>

src/mlpack/core/kernels/polynomial_kernel.hpp

@@ -59,12 +59,12 @@ class PolynomialKernel
   //! Get the degree of the polynomial.
   const double& Degree() const { return degree; }
   //! Modify the degree of the polynomial.
-  double& Degree() { return degree; }
+  void Degree(const double degree) { this->degree = degree; }
 
   //! Get the offset of the dot product of the arguments.
   const double& Offset() const { return offset; }
   //! Modify the offset of the dot product of the arguments.
-  double& Offset() { return offset; }
+  void Offset(const double offset) { this->offset = offset; }
 
   //! Serialize the kernel.
   template<typename Archive>

src/mlpack/core/kernels/pspectrum_string_kernel_impl.hpp

@@ -25,6 +25,12 @@ inline PSpectrumStringKernel::PSpectrumStringKernel(
     const std::vector<std::vector<std::string> >& datasets,
     const size_t p) : p(p)
 {
+  if (p == 0)
+  {
+    throw std::invalid_argument(
+        "PSpectrumStringKernel::PSpectrumStringKernel(): p must be positive");
+  }
+
   // We have to assemble the counts of substrings.  This is not a particularly
   // fast operation, unfortunately, but it only needs to be done once.
   Log::Info << "Assembling counts of substrings of length " << p << "."

src/mlpack/core/kernels/spherical_kernel.hpp

@@ -29,6 +29,15 @@ class SphericalKernel
     bandwidthSquared(std::pow(bandwidth, 2.0))
   { /* Nothing to do. */ }
 
+  // Get the bandwidth.
+  const double Bandwidth() const { return bandwidth; }
+  // Modify the bandwidth.
+  void Bandwidth(const double bandwidth)
+  {
+    this->bandwidth = bandwidth;
+    this->bandwidthSquared = bandwidth * bandwidth;
+  }
+
   /**
    * Evaluate the spherical kernel with the given two vectors.
    *

src/mlpack/core/kernels/triangular_kernel.hpp

@@ -87,7 +87,7 @@ class TriangularKernel
   //! Get the bandwidth of the kernel.
   double Bandwidth() const { return bandwidth; }
   //! Modify the bandwidth of the kernel.
-  double& Bandwidth() { return bandwidth; }
+  void Bandwidth(const double bandwidth) { this->bandwidth = bandwidth; }
 
   //! Serialize the kernel.
   template<typename Archive>

src/mlpack/methods/fastmks/fastmks_main.cpp

@@ -186,7 +186,7 @@ void BINDING_FUNCTION(util::Params& params, util::Timers& timers)
     else if (kernelType == "cosine")
     {
       CosineDistance cd;
-      model->KernelType() = FastMKSModel::COSINE_DISTANCE;
+      model->KernelType() = FastMKSModel::COSINE_SIMILARITY;
       model->BuildModel(timers, std::move(referenceData), cd, single, naive,
           base);
     }

src/mlpack/methods/fastmks/fastmks_model.hpp

@@ -17,7 +17,7 @@
 #include <mlpack/core/kernels/kernel_traits.hpp>
 #include <mlpack/core/kernels/linear_kernel.hpp>
 #include <mlpack/core/kernels/polynomial_kernel.hpp>
-#include <mlpack/core/kernels/cosine_distance.hpp>
+#include <mlpack/core/kernels/cosine_similarity.hpp>
 #include <mlpack/core/kernels/gaussian_kernel.hpp>
 #include <mlpack/core/kernels/epanechnikov_kernel.hpp>
 #include <mlpack/core/kernels/hyperbolic_tangent_kernel.hpp>
@@ -38,7 +38,7 @@ class FastMKSModel
   {
     LINEAR_KERNEL,
     POLYNOMIAL_KERNEL,
-    COSINE_DISTANCE,
+    COSINE_SIMILARITY,
     GAUSSIAN_KERNEL,
     EPANECHNIKOV_KERNEL,
     TRIANGULAR_KERNEL,
@@ -142,7 +142,7 @@ class FastMKSModel
   //! This will only be non-NULL if this is the type of kernel we are using.
   FastMKS<PolynomialKernel>* polynomial;
   //! This will only be non-NULL if this is the type of kernel we are using.
-  FastMKS<CosineDistance>* cosine;
+  FastMKS<CosineSimilarity>* cosine;
   //! This will only be non-NULL if this is the type of kernel we are using.
   FastMKS<GaussianKernel>* gaussian;
   //! This will only be non-NULL if this is the type of kernel we are using.

src/mlpack/methods/fastmks/fastmks_model_impl.hpp

@@ -36,7 +36,7 @@ inline FastMKSModel::FastMKSModel(const FastMKSModel& other) :
     polynomial(other.polynomial == NULL ? NULL :
         new FastMKS<PolynomialKernel>(*other.polynomial)),
     cosine(other.cosine == NULL ? NULL :
-        new FastMKS<CosineDistance>(*other.cosine)),
+        new FastMKS<CosineSimilarity>(*other.cosine)),
     gaussian(other.gaussian == NULL ? NULL :
         new FastMKS<GaussianKernel>(*other.gaussian)),
     epan(other.epan == NULL ? NULL :
@@ -98,7 +98,7 @@ inline FastMKSModel& FastMKSModel::operator=(const FastMKSModel& other)
     if (other.polynomial)
       polynomial = new FastMKS<PolynomialKernel>(*other.polynomial);
     if (other.cosine)
-      cosine = new FastMKS<CosineDistance>(*other.cosine);
+      cosine = new FastMKS<CosineSimilarity>(*other.cosine);
     if (other.gaussian)
       gaussian = new FastMKS<GaussianKernel>(*other.gaussian);
     if (other.epan)
@@ -164,7 +164,7 @@ inline bool FastMKSModel::Naive() const
       return linear->Naive();
     case POLYNOMIAL_KERNEL:
       return polynomial->Naive();
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       return cosine->Naive();
     case GAUSSIAN_KERNEL:
       return gaussian->Naive();
@@ -187,7 +187,7 @@ inline bool& FastMKSModel::Naive()
       return linear->Naive();
     case POLYNOMIAL_KERNEL:
       return polynomial->Naive();
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       return cosine->Naive();
     case GAUSSIAN_KERNEL:
       return gaussian->Naive();
@@ -210,7 +210,7 @@ inline bool FastMKSModel::SingleMode() const
       return linear->SingleMode();
     case POLYNOMIAL_KERNEL:
       return polynomial->SingleMode();
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       return cosine->SingleMode();
     case GAUSSIAN_KERNEL:
       return gaussian->SingleMode();
@@ -233,7 +233,7 @@ inline bool& FastMKSModel::SingleMode()
       return linear->SingleMode();
     case POLYNOMIAL_KERNEL:
       return polynomial->SingleMode();
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       return cosine->SingleMode();
     case GAUSSIAN_KERNEL:
       return gaussian->SingleMode();
@@ -339,8 +339,8 @@ void FastMKSModel::BuildModel(util::Timers& timers,
           base);
       break;
 
-    case COSINE_DISTANCE:
-      cosine = new FastMKS<CosineDistance>(singleMode, naive);
+    case COSINE_SIMILARITY:
+      cosine = new FastMKS<CosineSimilarity>(singleMode, naive);
       BuildFastMKSModel(timers, *cosine, kernel, std::move(referenceData), base);
       break;
 
@@ -411,7 +411,7 @@ void FastMKSModel::serialize(Archive& ar, const uint32_t /* version */)
       ar(CEREAL_POINTER(polynomial));
       break;
 
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       ar(CEREAL_POINTER(cosine));
       break;
 
@@ -476,7 +476,7 @@ inline void FastMKSModel::Search(
     case POLYNOMIAL_KERNEL:
       Search(timers, *polynomial, querySet, k, indices, kernels, base);
       break;
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       Search(timers, *cosine, querySet, k, indices, kernels, base);
       break;
     case GAUSSIAN_KERNEL:
@@ -511,7 +511,7 @@ inline void FastMKSModel::Search(
     case POLYNOMIAL_KERNEL:
       polynomial->Search(k, indices, kernels);
       break;
-    case COSINE_DISTANCE:
+    case COSINE_SIMILARITY:
       cosine->Search(k, indices, kernels);
       break;
     case GAUSSIAN_KERNEL:

src/mlpack/tests/fastmks_test.cpp

@@ -592,9 +592,9 @@ TEST_CASE("FastMKSModelCosineTest", "[FastMKSTest]")
 
   FastMKS<CosineDistance> f(referenceData, ck);
 
-  FastMKSModel m(FastMKSModel::COSINE_DISTANCE);
-  FastMKSModel mNaive(FastMKSModel::COSINE_DISTANCE);
-  FastMKSModel mSingle(FastMKSModel::COSINE_DISTANCE);
+  FastMKSModel m(FastMKSModel::COSINE_SIMILARITY);
+  FastMKSModel mNaive(FastMKSModel::COSINE_SIMILARITY);
+  FastMKSModel mSingle(FastMKSModel::COSINE_SIMILARITY);
   util::Timers timers;
 
   m.BuildModel(timers, std::move(referenceCopy1), ck, false, false, 2.0);