Merge remote-tracking branch 'origin/master' into syntacticsugarallkernels

Author: theogf

docs/make.jl

@@ -12,6 +12,7 @@ makedocs(
              "Transform"=>"transform.md",
              "Metrics"=>"metrics.md",
              "Theory"=>"theory.md",
+             "Custom Kernels"=>"create_kernel.md"
              "API"=>"api.md"]
 )
 

docs/src/create_kernel.md

@@ -0,0 +1,20 @@
+## Creating your own kernel
+
+KernelFunctions.jl contains the most popular kernels already but you might want to make your own!
+
+Here is for example how one can define the Squared Exponential Kernel again :
+
+```julia
+struct MyKernel <: Kernel end
+
+KernelFunctions.kappa(::MyKernel, d2::Real) = exp(-d2)
+KernelFunctions.metric(::MyKernel) = SqEuclidean()
+```
+
+For a "Base" kernel, where the kernel function is simply a function applied on some metric between two vectors of real, you only need to:
+ - Define your struct inheriting from `Kernel`.
+ - Define a `kappa` function.
+ - Define the metric used `SqEuclidean`, `DotProduct` etc. Note that the term "metric" is here overabused.
+ - Optional : Define any parameter of your kernel as `trainable` by Flux.jl if you want to perform optimization on the parameters. We recommend wrapping all parameters in arrays to allow them to be mutable.
+
+Once these functions are defined, you can use all the wrapping functions of KernelFuntions.jl

src/KernelFunctions.jl

@@ -14,6 +14,7 @@ export ExponentiatedKernel
 export MaternKernel, Matern32Kernel, Matern52Kernel
 export LinearKernel, PolynomialKernel
 export RationalQuadraticKernel, GammaRationalQuadraticKernel
+export MahalanobisKernel
 export KernelSum, KernelProduct
 export TransformedKernel, ScaledKernel
 
@@ -44,7 +45,7 @@ include("distances/dotproduct.jl")
 include("distances/delta.jl")
 include("transform/transform.jl")
 
-for k in ["exponential","matern","polynomial","constant","rationalquad","exponentiated","cosine"]
+for k in ["exponential","matern","polynomial","constant","rationalquad","exponentiated","cosine","maha"]
     include(joinpath("kernels",k*".jl"))
 end
 include("kernels/transformedkernel.jl")

src/kernels/maha.jl

@@ -0,0 +1,21 @@
+"""
+    MahalanobisKernel(P::AbstractMatrix)
+
+    Mahalanobis distance-based kernel given by
+```math
+    κ(x,y) =  exp(-r^2), r^2 = maha(x,P,y) = (x-y)'*inv(P)*(x-y)
+```
+where the matrix P is the metric.
+
+"""
+struct MahalanobisKernel{T<:Real, A<:AbstractMatrix{T}} <: BaseKernel
+    P::A
+    function MahalanobisKernel(P::AbstractMatrix{T}) where {T<:Real}
+        LinearAlgebra.checksquare(P)
+        new{T,typeof(P)}(P)
+    end
+end
+
+kappa(κ::MahalanobisKernel, d::T) where {T<:Real} = exp(-d) 
+
+metric(κ::MahalanobisKernel) = SqMahalanobis(κ.P)

src/trainable.jl

@@ -16,6 +16,8 @@ trainable(k::PolynomialKernel) = (k.d, k.c)
 
 trainable(k::RationalQuadraticKernel) = (k.α,)
 
+trainable(k::MahalanobisKernel) = (k.P,)
+
 #### Composite kernels
 
 trainable(κ::KernelProduct) = κ.kernels

test/test_kernels.jl

@@ -113,6 +113,13 @@ x = rand()*2; v1 = rand(3); v2 = rand(3); id = IdentityTransform()
             @test kappa(PolynomialKernel(d=1.0,c=c),x) ≈ kappa(LinearKernel(c=c),x)
         end
     end
+    @testset "Mahalanobis" begin
+        P = rand(3,3)
+        k = MahalanobisKernel(P)
+        @test kappa(k,x) == exp(-x)
+        @test k(v1,v2) ≈ exp(-sqmahalanobis(v1,v2, k.P))
+        @test kappa(ExponentialKernel(),x) == kappa(k,x)
+    end
     @testset "RationalQuadratic" begin
         @testset "RationalQuadraticKernel" begin
             α = 2.0