[mlpack-git] master: Document the KernelTraits struct. (fab25ea)

[gitdub at big.cc.gt.atl.ga.us]

Repository : https://github.com/mlpack/mlpack

On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/fbb25be12114b2b216c813b388018cefcd019139...fab25eaf7b9630076fd3b980e43a25363a936d28

>---------------------------------------------------------------

commit fab25eaf7b9630076fd3b980e43a25363a936d28
Author: ryan <ryan at ratml.org>
Date:   Sat Aug 29 17:34:37 2015 -0400

    Document the KernelTraits struct.


>---------------------------------------------------------------

fab25eaf7b9630076fd3b980e43a25363a936d28
 doc/policies/kernels.hpp | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/policies/kernels.hpp b/doc/policies/kernels.hpp
index be7921d..b02d598 100644
--- a/doc/policies/kernels.hpp
+++ b/doc/policies/kernels.hpp
@@ -1,5 +1,13 @@
 /*! @page kernels The KernelType policy in mlpack
 
+ at section kerneltoc Table of Contents
+
+ - \ref kerneltype
+ - \ref kerneltraits
+ - \ref kernellist
+
+ at section kerneltype Introduction to the KernelType policy
+
 `Kernel methods' make up a large class of machine learning techniques.  Each of
 these methods is characterized by its dependence on a \b kernel \b function.  In
 rough terms, a kernel function is a general notion of similarity between two
@@ -100,6 +108,39 @@ int main()
 }
 @endcode
 
+ at section kerneltraits The KernelTraits struct
+
+Some algorithms that use kernels can specialize if the kernel fulfills some
+certain conditions.  An example of a condition might be that the kernel is
+shift-invariant or that the kernel is normalized.  In the case of fast
+max-kernel search (mlpack::fastmks::FastMKS), the computation can be accelerated
+if the kernel is normalized.  For this reason, the \c KernelTraits struct
+exists.  This allows a kernel to specify via a \c const \c static \c bool when
+these types of conditions are satisfied.  **Note that a KernelTraits class
+is not required,** but may be helpful.
+
+The \c KernelTraits struct is a template struct that takes a \c KernelType as a
+parameter, and exposes \c const \c static \c bool values that depend on the
+kernel.  Setting these values is achieved by specialization.  The code below
+provides an example, specializing \c KernelTraits for the \c ExampleKernel from
+earlier:
+
+ at code
+template<>
+struct KernelTraits<ExampleKernel>
+{
+  //! The example kernel is normalized (K(x, x) = 1 for all x).
+  const static bool IsNormalized = true;
+};
+ at endcode
+
+At this time, there is only one kernel trait that is used in mlpack code:
+
+ - \c IsNormalized (defaults to \c false): if \f$ K(x, x) = 1 \; \forall x \f$,
+   then the kernel is normalized and this should be set to true.
+
+ at section kernellist List of kernels and classes that use a \c KernelType
+
 mlpack comes with a number of pre-written kernels that satisfy the \c KernelType
 policy: