Adding more docs and explanations

Author: theogf

docs/src/create_kernel.md

@@ -2,19 +2,41 @@
 
 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 :
+Here are a few ways depending on how complicated your kernel is :
+
+### SimpleKernel for kernels function depending on a metric
+
+If your kernel function is of the form `k(x, y) = f(d(x, y))` where `d(x, y)` is a `PreMetric`,
+you can construct your custom kernel by defining `kappa` and `metric` for your kernel.
+Here is for example how one can define the `SqExponentialKernel` again :
 
 ```julia
-struct MyKernel <: Kernel end
+struct MyKernel <: KernelFunctions.SimpleKernel 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.
+### Kernel for more complex kernels
+
+If your kernel does not satisfy such a representation, all you need to do is define `(k::MyKernel)(x, y)` and inherit from `Kernel`.
+For example we recreate here the `NeuralNetworkKernel`
+
+```julia
+struct MyKernel <: KernelFunctions.Kernel end
+
+(::MyKernel)(x, y) = asin(dot(x, y) / sqrt((1 + sum(abs2, x)) * (1 + sum(abs2, y))))
+```
+
+Note that `BaseKernel` do not use `Distances.jl` and can therefore be a bit slower.
+
+### Additional Options
 
-Once these functions are defined, you can use all the wrapping functions of KernelFuntions.jl
+Finally there are additional functions you can define to bring in more features :
+ - Define the trainable parameters of your kernel with `KernelFunctions.trainable(k)` which should return a `Tuple` of your parameters.
+This parameters will be then passed to `Flux.params` function
+ - `KernelFunctions.iskroncompatible(k)`, if your kernel factorizes in the dimensions. You can declare your kernel as `iskroncompatible(k) = true`
+ - `KernelFunctions.dim`: by default the dimension of the inputs will only be checked for vectors of `AbstractVector{<:Real}`.
+If you want to check the dimensions of your inputs, dispatch the `dim` function on your kernel. Note that `0` is the default.
+ - You can also redefine the `kernelmatrix(k, x, y)...` functions for your kernel to eventually optimize the computations of your kernel.
+ - `Base.print(io::IO, k::Kernel)`, if you want to specialize the printing of your kernel

docs/src/metrics.md

@@ -3,9 +3,9 @@
 KernelFunctions.jl relies on [Distances.jl](https://github.com/JuliaStats/Distances.jl) for computing the pairwise matrix.
 To do so a distance measure is needed for each kernel. Two very common ones can already be used : `SqEuclidean` and `Euclidean`.
 However all kernels do not rely on distances metrics respecting all the definitions. That's why  additional metrics come with the package such as `DotProduct` (`<x,y>`) and `Delta` (`δ(x,y)`).
-Note that every `BaseKernel` must have a defined metric defined as :
+Note that every `SimpleKernel` must have a defined metric defined as :
 ```julia
-    metric(::CustomKernel) = SqEuclidean()
+    KernelFunctions.metric(::CustomKernel) = SqEuclidean()
 ```
 
 ## Adding a new metric

src/utils.jl

@@ -91,7 +91,7 @@ For a transform return its parameters, for a `ChainTransform` return a vector of
 """
 #params
 
-dim(x) = 0
+dim(x) = 0 # This is the passes-by-default choice. For a proper check, implement `KernelFunctions.dim` for your datatype.
 dim(x::AbstractVector{<:AbstractVector{<:Real}}) = length(first(x))
 dim(x::AbstractVector{<:Real}) = 1
 dim(x::AbstractVector{Tuple{Any,Int}}) = 1