Add RationalKernel and rename GammaRationalQuadraticKernel

Author: devmotion

docs/src/kernels.md

@@ -88,11 +88,12 @@ LinearKernel
 PolynomialKernel
 ```
 
-### Rational Quadratic Kernels
+### Rational Kernels
 
 ```@docs
+RationalKernel
 RationalQuadraticKernel
-GammaRationalQuadraticKernel
+GammaRationalKernel
 ```
 
 ### Spectral Mixture Kernels

src/KernelFunctions.jl

@@ -26,7 +26,8 @@ export ExponentiatedKernel
 export FBMKernel
 export MaternKernel, Matern12Kernel, Matern32Kernel, Matern52Kernel
 export LinearKernel, PolynomialKernel
-export RationalQuadraticKernel, GammaRationalQuadraticKernel
+export RationalKernel, RationalQuadraticKernel
+export GammaRationalKernel, GammaRationalQuadraticKernel
 export GaborKernel, PiecewisePolynomialKernel
 export PeriodicKernel, NeuralNetworkKernel
 export KernelSum, KernelProduct

src/basekernels/rationalquad.jl

@@ -1,3 +1,40 @@
+"""
+    RationalKernel(; α::Real=2.0)
+
+Rational kernel with shape parameter `α`.
+
+# Definition
+
+For inputs ``x, x' \\in \\mathbb{R}^d``, the rational kernel with shape parameter
+``\\alpha > 0`` is defined as
+```math
+k(x, x'; \\alpha) = \\bigg(1 + \\frac{\\|x - x'\\|_2}{\\alpha}\\bigg)^{-\\alpha}.
+```
+
+The [`ExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
+
+See also: [`GammaRationalKernel`](@ref)
+"""
+struct RationalKernel{Tα<:Real} <: SimpleKernel
+    α::Vector{Tα}
+    function RationalKernel(; alpha::T=2.0, α::T=alpha) where {T}
+        @check_args(RationalKernel, α, α > zero(T), "α > 0")
+        return new{T}([α])
+    end
+end
+
+@functor RationalKernel
+
+function kappa(κ::RationalKernel, d::Real)
+    return (one(d) + d / first(κ.α))^(-first(κ.α))
+end
+
+metric(::RationalKernel) = Euclidean()
+
+function Base.show(io::IO, κ::RationalKernel)
+    return print(io, "Rational Kernel (α = $(first(κ.α)))")
+end
+
 """
     RationalQuadraticKernel(; α::Real=2.0)
 
@@ -13,7 +50,7 @@ k(x, x'; \\alpha) = \\bigg(1 + \\frac{\\|x - x'\\|_2^2}{2\\alpha}\\bigg)^{-\\alp
 
 The [`SqExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
 
-See also: [`GammaRationalQuadraticKernel`](@ref)
+See also: [`GammaRationalKernel`](@ref)
 """
 struct RationalQuadraticKernel{Tα<:Real} <: SimpleKernel
     α::Vector{Tα}
@@ -36,44 +73,42 @@ function Base.show(io::IO, κ::RationalQuadraticKernel)
 end
 
 """
-    GammaRationalQuadraticKernel(; α::Real=2.0, γ::Real=2.0)
+    GammaRationalKernel(; α::Real=2.0, γ::Real=2.0)
 
-γ-rational-quadratic kernel with shape parameters `α` and `γ`.
+γ-rational kernel with shape parameters `α` and `γ`.
 
 # Definition
 
-For inputs ``x, x' \\in \\mathbb{R}^d``, the γ-rational-quadratic kernel with shape
+For inputs ``x, x' \\in \\mathbb{R}^d``, the γ-rational kernel with shape
 parameters ``\\alpha > 0`` and ``\\gamma \\in (0, 2]`` is defined as
 ```math
 k(x, x'; \\alpha, \\gamma) = \\bigg(1 + \\frac{\\|x - x'\\|_2^{\\gamma}}{\\alpha}\\bigg)^{-\\alpha}.
 ```
 
 The [`GammaExponentialKernel`](@ref) is recovered in the limit as ``\\alpha \\to \\infty``.
 
-See also: [`RationalQuadraticKernel`](@ref)
+See also: [`RationalKernel`](@ref), [`RationalQuadraticKernel`](@ref)
 """
-struct GammaRationalQuadraticKernel{Tα<:Real,Tγ<:Real} <: SimpleKernel
+struct GammaRationalKernel{Tα<:Real,Tγ<:Real} <: SimpleKernel
     α::Vector{Tα}
     γ::Vector{Tγ}
-    function GammaRationalQuadraticKernel(;
+    function GammaRationalKernel(;
         alpha::Real=2.0, gamma::Real=2.0, α::Real=alpha, γ::Real=gamma
     )
-        @check_args(GammaRationalQuadraticKernel, α, α > zero(α), "α > 0")
-        @check_args(GammaRationalQuadraticKernel, γ, zero(γ) < γ ≤ 2, "γ ∈ (0, 2]")
+        @check_args(GammaRationalKernel, α, α > zero(α), "α > 0")
+        @check_args(GammaRationalKernel, γ, zero(γ) < γ ≤ 2, "γ ∈ (0, 2]")
         return new{typeof(α),typeof(γ)}([α], [γ])
     end
 end
 
-@functor GammaRationalQuadraticKernel
+@functor GammaRationalKernel
 
-function kappa(κ::GammaRationalQuadraticKernel, d::Real)
+function kappa(κ::GammaRationalKernel, d::Real)
     return (one(d) + d^first(κ.γ) / first(κ.α))^(-first(κ.α))
 end
 
-metric(::GammaRationalQuadraticKernel) = Euclidean()
+metric(::GammaRationalKernel) = Euclidean()
 
-function Base.show(io::IO, κ::GammaRationalQuadraticKernel)
-    return print(
-        io, "Gamma Rational Quadratic Kernel (α = $(first(κ.α)), γ = $(first(κ.γ)))"
-    )
+function Base.show(io::IO, κ::GammaRationalKernel)
+    return print(io, "Gamma Rational Kernel (α = $(first(κ.α)), γ = $(first(κ.γ)))")
 end

src/deprecated.jl

@@ -7,3 +7,6 @@
 @deprecate PiecewisePolynomialKernel{V}(A::AbstractMatrix{<:Real}) where {V} transform(
     PiecewisePolynomialKernel{V}(size(A, 1)), LinearTransform(cholesky(A).U)
 )
+
+# TODO: remove in next breaking release
+const GammaRationalQuadraticKernel = GammaRationalKernel

test/basekernels/rationalquad.jl

@@ -4,8 +4,31 @@
     v1 = rand(rng, 3)
     v2 = rand(rng, 3)
 
+    @testset "RationalKernel" begin
+        α = rand()
+        k = RationalKernel(; α=α)
+
+        @testset "RationalKernel ≈ Exponential for large α" begin
+            @test isapprox(
+                RationalKernel(; α=1e9)(v1, v2),
+                ExponentialKernel()(v1, v2);
+                atol=1e-6,
+                rtol=1e-6,
+            )
+        end
+
+        @test metric(RationalKernel()) == Euclidean()
+        @test metric(RationalKernel(; α=α)) == Euclidean()
+        @test repr(k) == "Rational Kernel (α = $(α))"
+
+        # Standardised tests.
+        TestUtils.test_interface(k, Float64)
+        test_ADs(x -> RationalKernel(; alpha=exp(x[1])), [α])
+        test_params(k, ([α],))
+    end
+
     @testset "RationalQuadraticKernel" begin
-        α = 2.0
+        α = rand()
         k = RationalQuadraticKernel(; α=α)
 
         @testset "RQ ≈ EQ for large α" begin
@@ -18,74 +41,91 @@
         end
 
         @test metric(RationalQuadraticKernel()) == SqEuclidean()
-        @test metric(RationalQuadraticKernel(; α=2.0)) == SqEuclidean()
+        @test metric(RationalQuadraticKernel(; α=α)) == SqEuclidean()
         @test repr(k) == "Rational Quadratic Kernel (α = $(α))"
 
         # Standardised tests.
         TestUtils.test_interface(k, Float64)
-        test_ADs(x -> RationalQuadraticKernel(; alpha=x[1]), [α])
+        test_ADs(x -> RationalQuadraticKernel(; alpha=exp(x[1])), [α])
         test_params(k, ([α],))
     end
 
-    @testset "GammaRationalQuadraticKernel" begin
-        k = GammaRationalQuadraticKernel()
+    @testset "GammaRationalKernel" begin
+        k = GammaRationalKernel()
 
-        @test repr(k) == "Gamma Rational Quadratic Kernel (α = 2.0, γ = 2.0)"
+        @test repr(k) == "Gamma Rational Kernel (α = 2.0, γ = 2.0)"
 
-        @testset "Default GammaRQ ≈ RQ with rescaled inputs" begin
+        @testset "Default GammaRational ≈ RQ with rescaled inputs" begin
             @test isapprox(
-                GammaRationalQuadraticKernel()(v1 ./ sqrt(2), v2 ./ sqrt(2)),
+                GammaRationalKernel()(v1 ./ sqrt(2), v2 ./ sqrt(2)),
                 RationalQuadraticKernel()(v1, v2),
             )
-            a = 1.0 + rand()
+            a = 1 + rand()
             @test isapprox(
-                GammaRationalQuadraticKernel(; α=a)(v1 ./ sqrt(2), v2 ./ sqrt(2)),
+                GammaRationalKernel(; α=a)(v1 ./ sqrt(2), v2 ./ sqrt(2)),
                 RationalQuadraticKernel(; α=a)(v1, v2),
             )
         end
 
-        @testset "GammaRQ ≈ EQ for large α with rescaled inputs" begin
+        @testset "Default GammaRational ≈ EQ for large α with rescaled inputs" begin
             v1 = randn(2)
             v2 = randn(2)
             @test isapprox(
-                GammaRationalQuadraticKernel(; α=1e9)(v1 ./ sqrt(2), v2 ./ sqrt(2)),
+                GammaRationalKernel(; α=1e9)(v1 ./ sqrt(2), v2 ./ sqrt(2)),
                 SqExponentialKernel()(v1, v2);
                 atol=1e-6,
                 rtol=1e-6,
             )
         end
 
-        @testset "GammaRQ(γ=1) ≈ Exponential with rescaled inputs for large α" begin
+        @testset "GammaRational(γ=1) ≈ Rational" begin
+            @test isapprox(GammaRationalKernel(; γ=1.0)(v1, v2), RationalKernel()(v1, v2))
+            a = 1 + rand()
+            @test isapprox(
+                GammaRationalKernel(; γ=1.0, α=a)(v1, v2), RationalKernel(; α=a)(v1, v2)
+            )
+        end
+
+        @testset "GammaRational(γ=1) ≈ Exponential with rescaled inputs for large α" begin
             v1 = randn(4)
             v2 = randn(4)
             @test isapprox(
-                GammaRationalQuadraticKernel(; α=1e9, γ=1.0)(v1, v2),
+                GammaRationalKernel(; α=1e9, γ=1.0)(v1, v2),
                 ExponentialKernel()(v1, v2);
                 atol=1e-6,
                 rtol=1e-6,
             )
         end
 
-        @testset "GammaRQ ≈ GammaExponential for same γ and large α" begin
+        @testset "GammaRational ≈ GammaExponential for same γ and large α" begin
             v1 = randn(3)
             v2 = randn(3)
             γ = rand() + 0.5
             @test isapprox(
-                GammaRationalQuadraticKernel(; α=1e9, γ=γ)(v1, v2),
+                GammaRationalKernel(; α=1e9, γ=γ)(v1, v2),
                 GammaExponentialKernel(; γ=γ)(v1, v2);
                 atol=1e-6,
                 rtol=1e-6,
             )
         end
 
-        @test metric(GammaRationalQuadraticKernel()) == Euclidean()
-        @test metric(GammaRationalQuadraticKernel(; γ=2.0)) == Euclidean()
-        @test metric(GammaRationalQuadraticKernel(; γ=2.0, α=3.0)) == Euclidean()
+        @test metric(GammaRationalKernel()) == Euclidean()
+        @test metric(GammaRationalKernel(; γ=2.0)) == Euclidean()
+        @test metric(GammaRationalKernel(; γ=2.0, α=3.0)) == Euclidean()
+
+        # Deprecations.
+        a = rand()
+        g = 2 * rand()
+        @test GammaRationalQuadraticKernel()(v1, v2) == GammaRationalKernel()(v1, v2)
+        @test GammaRationalQuadraticKernel(; γ=g)(v1, v2) ==
+              GammaRationalKernel(; γ=g)(v1, v2)
+        @test GammaRationalQuadraticKernel(; γ=g, α=a)(v1, v2) ==
+              GammaRationalKernel(; γ=g, α=a)(v1, v2)
 
         # Standardised tests.
         TestUtils.test_interface(k, Float64)
         a = 1.0 + rand()
-        test_ADs(x -> GammaRationalQuadraticKernel(; α=x[1], γ=x[2]), [a, 1 + 0.5 * rand()])
-        test_params(GammaRationalQuadraticKernel(; α=a, γ=x), ([a], [x]))
+        test_ADs(x -> GammaRationalKernel(; α=x[1], γ=x[2]), [a, 1 + 0.5 * rand()])
+        test_params(GammaRationalKernel(; α=a, γ=x), ([a], [x]))
     end
 end

test/runtests.jl

@@ -51,6 +51,10 @@ using KernelFunctions.TestUtils: test_interface
 @info "Packages Loaded"
 
 include("test_utils.jl")
+include(joinpath("basekernels", "exponential.jl"))
+include(joinpath("basekernels", "rationalquad.jl"))
+include(joinpath("basekernels", "wiener.jl"))
+exit(0)
 
 @testset "KernelFunctions" begin
     include("utils.jl")