Add docstring to kernelkronmat and small corrections (#377)

* Gives a docstring to kernelkronmat

* Add elements to the `Conditional Utilities` parts

* Reformulation of the docstring

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Formatting

* Fix typo and error uniformisation

* Formatting

* Change to ArugmentError

* Adapt tests

* Splitted docstring and corrected type output

* Included comments

* Update src/matrix/kernelkroneckermat.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Patch bump

* Update src/matrix/kernelkroneckermat.jl

Co-authored-by: st-- <[email protected]>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: st-- <[email protected]>

Author: 3 people

Project.toml

@@ -1,6 +1,6 @@
 name = "KernelFunctions"
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
-version = "0.10.25"
+version = "0.10.26"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

docs/src/api.md

@@ -84,7 +84,6 @@ To find out more about the background, read this [review of kernels for vector-v
 
 KernelFunctions also provides miscellaneous utility functions.
 ```@docs
-kernelpdmat
 nystrom
 NystromFact
 ```
@@ -96,4 +95,11 @@ To keep the dependencies of KernelFunctions lean, some functionality is only ava
 [*https://github.com/MichielStock/Kronecker.jl*](https://github.com/MichielStock/Kronecker.jl)
 ```@docs
 kronecker_kernelmatrix
+kernelkronmat
 ```
+
+### PDMats.jl
+[*https://github.com/JuliaStats/PDMats.jl*](https://github.com/JuliaStats/PDMats.jl)
+```@docs
+kernelpdmat
+```

src/matrix/kernelkroneckermat.jl

@@ -6,27 +6,58 @@ using .Kronecker: Kronecker
 export kernelkronmat
 export kronecker_kernelmatrix
 
-function kernelkronmat(κ::Kernel, X::AbstractVector, dims::Int)
-    @assert iskroncompatible(κ) "The chosen kernel is not compatible for kroenecker matrices (see [`iskroncompatible`](@ref))"
-    k = kernelmatrix(κ, X)
-    return Kronecker.kronecker(k, dims)
+@doc raw"""
+    kernelkronmat(κ::Kernel, X::AbstractVector{<:Real}, dims::Int) -> KroneckerPower
+
+Return a `KroneckerPower` matrix on the `D`-dimensional input grid constructed by ``\otimes_{i=1}^D X``,
+where `D` is given by `dims`.
+
+!!! warning
+
+    Require `Kronecker.jl` and for `iskroncompatible(κ)` to return `true`.
+"""
+function kernelkronmat(κ::Kernel, X::AbstractVector{<:Real}, dims::Int)
+    checkkroncompatible(κ)
+    K = kernelmatrix(κ, X)
+    return Kronecker.kronecker(K, dims)
 end
 
-function kernelkronmat(
-    κ::Kernel, X::AbstractVector{<:AbstractVector}; obsdim::Int=defaultobs
-)
-    @assert iskroncompatible(κ) "The chosen kernel is not compatible for Kronecker matrices"
+@doc raw"""
+
+    kernelkronmat(κ::Kernel, X::AbstractVector{<:AbstractVector}) -> KroneckerProduct
+
+Returns a `KroneckerProduct` matrix on the grid built with the collection of vectors ``\{X_i\}_{i=1}^D``: ``\otimes_{i=1}^D X_i``.
+
+!!! warning
+
+    Requires `Kronecker.jl` and for `iskroncompatible(κ)` to return `true`.
+"""
+function kernelkronmat(κ::Kernel, X::AbstractVector{<:AbstractVector})
+    checkkroncompatible(κ)
     Ks = kernelmatrix.(κ, X)
-    return K = reduce(Kronecker.:⊗, Ks)
+    return reduce(Kronecker.:⊗, Ks)
 end
 
-"""
-    To be compatible with kroenecker constructions the kernel must satisfy
-    the property : for x,x' ∈ ℜᴰ
-    k(x,x') = ∏ᵢᴰ k(xᵢ,x'ᵢ)
+@doc raw"""
+    iskroncompatible(k::Kernel)
+
+Determine whether kernel `k` is compatible with Kronecker constructions such as [`kernelkronmat`](@ref)
+
+The function returns `false` by default. If `k` is compatible it must satisfy for all ``x, x' \in \mathbb{R}^D`:
+```math
+k(x, x') = \prod_{i=1}^D k(x_i, x'_i).
+```
 """
 @inline iskroncompatible(κ::Kernel) = false # Default return for kernels
 
+function checkkroncompatible(κ::Kernel)
+    return iskroncompatible(κ) || throw(
+        ArgumentError(
+            "The chosen kernel is not compatible for Kronecker matrices (see [`iskroncompatible`](@ref))",
+        ),
+    )
+end
+
 function _kernelmatrix_kroneckerjl_helper(
     ::Type{<:MOInputIsotopicByFeatures}, Kfeatures, Koutputs
 )

test/matrix/kernelkroneckermat.jl

@@ -6,7 +6,7 @@
 
     @test all(collect(kernelkronmat(k, collect(x), 2)) .≈ kernelmatrix(k, X; obsdim=1))
     @test all(collect(kernelkronmat(k, [x, x])) .≈ kernelmatrix(k, X; obsdim=1))
-    @test_throws AssertionError kernelkronmat(LinearKernel(), collect(x), 2)
+    @test_throws ArgumentError kernelkronmat(LinearKernel(), collect(x), 2)
 
     @testset "lazy kernelmatrix" begin
         rng = MersenneTwister(123)