Rename Kernel to CovarianceFunction (#789)

* Rename `Kernel` -> `CovarianceFunction`

* Renaming in `test_randprocs`

* Renaming in benchmarks

* Pylint fixes

* Bugfix

* Update CODEOWNERS

.github/CODEOWNERS

@@ -40,12 +40,12 @@
 /tests/test_quad/ @mmahsereci @tskarvone
 /tests/test_problems/test_zoo/test_quad/ @mmahsereci @tskarvone
 
-# Random Processes & Kernels
+# Random Processes & Covariance Functions
 /src/probnum/randprocs/ @marvinpfoertner @JonathanWenger
 /tests/test_randprocs/ @marvinpfoertner @JonathanWenger
 
 /benchmarks/randprocs.py @marvinpfoertner @JonathanWenger
-/benchmarks/kernels.py @marvinpfoertner @JonathanWenger
+/benchmarks/covfuncs.py @marvinpfoertner @JonathanWenger
 
 /src/probnum/randprocs/markov/ @pnkraemer @schmidtjonathan
 /tests/test_randprocs/test_markov/ @pnkraemer @schmidtjonathan

benchmarks/covfuncs.py

@@ -0,0 +1,70 @@
+"""Benchmarks for covariance functions."""
+
+import numpy as np
+
+from probnum.randprocs import covfuncs
+
+# Module level variables
+COVFUNC_NAMES = [
+    "white_noise",
+    "linear",
+    "polynomial",
+    "exp_quad",
+    "rat_quad",
+    "matern12",
+    "matern32",
+    "matern52",
+    "matern72",
+]
+
+N_DATAPOINTS = [10, 100, 1000]
+
+
+def get_covfunc(covfunc_name, input_shape):
+    """Return a covariance function for a given name."""
+    if covfunc_name == "white_noise":
+        k = covfuncs.WhiteNoise(input_shape=input_shape)
+    elif covfunc_name == "linear":
+        k = covfuncs.Linear(input_shape=input_shape)
+    elif covfunc_name == "polynomial":
+        k = covfuncs.Polynomial(input_shape=input_shape)
+    elif covfunc_name == "exp_quad":
+        k = covfuncs.ExpQuad(input_shape=input_shape)
+    elif covfunc_name == "rat_quad":
+        k = covfuncs.RatQuad(input_shape=input_shape)
+    elif covfunc_name == "matern12":
+        k = covfuncs.Matern(input_shape=input_shape, nu=0.5)
+    elif covfunc_name == "matern32":
+        k = covfuncs.Matern(input_shape=input_shape, nu=1.5)
+    elif covfunc_name == "matern52":
+        k = covfuncs.Matern(input_shape=input_shape, nu=2.5)
+    elif covfunc_name == "matern72":
+        k = covfuncs.Matern(input_shape=input_shape, nu=3.5)
+    else:
+        raise ValueError(f"Covariance function '{covfunc_name}' not recognized.")
+
+    return k
+
+
+class CovarianceFunctions:
+    """Benchmark evaluation of a covariance function at a set of inputs."""
+
+    param_names = ["covfunc", "n_datapoints"]
+    params = [COVFUNC_NAMES, N_DATAPOINTS]
+
+    def setup(self, covfunc, n_datapoints):
+        rng = np.random.default_rng(42)
+        self.input_dim = 100
+        self.data = rng.normal(size=(n_datapoints, self.input_dim))
+        self.covfunc = get_covfunc(covfunc_name=covfunc, input_shape=self.input_dim)
+
+    def time_covfunc_call(self, covfunc, n_datapoints):
+        self.covfunc(self.data, None)
+
+    def time_covfunc_matrix(self, covfunc, n_datapoints):
+        """Times sampling from this distribution."""
+        self.covfunc.matrix(self.data)
+
+    def peakmem_covfunc_matrix(self, covfunc, n_datapoints):
+        """Peak memory of sampling process."""
+        self.covfunc.matrix(self.data)

docs/source/api/randprocs.rst

@@ -9,5 +9,5 @@ probnum.randprocs
 .. toctree::
     :hidden:
 
+    randprocs/covfuncs
     randprocs/markov
-    randprocs/kernels

docs/source/api/randprocs/covfuncs.rst

@@ -0,0 +1,7 @@
+**************************
+probnum.randprocs.covfuncs
+**************************
+
+.. automodapi:: probnum.randprocs.covfuncs
+    :no-heading:
+    :headings: "="

src/probnum/randprocs/__init__.py

@@ -6,7 +6,7 @@
 functions with stochastic output.
 """
 
-from . import kernels
+from . import covfuncs, kernels, markov
 from ._gaussian_process import GaussianProcess
 from ._random_process import RandomProcess
 
@@ -15,7 +15,6 @@
     "RandomProcess",
     "GaussianProcess",
 ]
-from . import markov
 
 # Set correct module paths. Corrects links and module paths in documentation.
 RandomProcess.__module__ = "probnum.randprocs"

src/probnum/randprocs/_gaussian_process.py

@@ -7,7 +7,7 @@
 from probnum import randvars
 from probnum.typing import ArrayLike
 
-from . import _random_process, kernels
+from . import _random_process, covfuncs
 from .. import functions
 
 
@@ -23,7 +23,7 @@ class GaussianProcess(_random_process.RandomProcess[ArrayLike, np.ndarray]):
     mean
         Mean function.
     cov
-        Covariance function or kernel.
+        Covariance function.
 
     See Also
     --------
@@ -32,14 +32,14 @@ class GaussianProcess(_random_process.RandomProcess[ArrayLike, np.ndarray]):
 
     Examples
     --------
-    Define a Gaussian process with a zero mean function and RBF kernel.
+    Define a Gaussian process with a zero mean function and RBF covariance function.
 
     >>> import numpy as np
     >>> from probnum.functions import Zero
-    >>> from probnum.randprocs.kernels import ExpQuad
+    >>> from probnum.randprocs.covfuncs import ExpQuad
     >>> from probnum.randprocs import GaussianProcess
     >>> mu = Zero(input_shape=())  # zero-mean function
-    >>> k = ExpQuad(input_shape=())  # RBF kernel
+    >>> k = ExpQuad(input_shape=())  # RBF covariance function
     >>> gp = GaussianProcess(mu, k)
 
     Sample from the Gaussian process.
@@ -59,7 +59,7 @@ class GaussianProcess(_random_process.RandomProcess[ArrayLike, np.ndarray]):
     def __init__(
         self,
         mean: functions.Function,
-        cov: kernels.Kernel,
+        cov: covfuncs.CovarianceFunction,
     ):
         if not isinstance(mean, functions.Function):
             raise TypeError("The mean function must have type `probnum.Function`.")

src/probnum/randprocs/_random_process.py

@@ -8,7 +8,7 @@
 import numpy as np
 
 from probnum import functions, randvars, utils as _utils
-from probnum.randprocs import kernels
+from probnum.randprocs import covfuncs
 from probnum.typing import DTypeLike, ShapeLike, ShapeType
 
 InputType = TypeVar("InputType")
@@ -57,7 +57,7 @@ def __init__(
         output_shape: ShapeLike,
         dtype: DTypeLike,
         mean: Optional[functions.Function] = None,
-        cov: Optional[kernels.Kernel] = None,
+        cov: Optional[covfuncs.CovarianceFunction] = None,
     ):
         self._input_shape = _utils.as_shape(input_shape)
         self._input_ndim = len(self._input_shape)
@@ -94,9 +94,10 @@ def __init__(
 
         # Covariance function
         if cov is not None:
-            if not isinstance(cov, kernels.Kernel):
+            if not isinstance(cov, covfuncs.CovarianceFunction):
                 raise TypeError(
-                    "The covariance functions must be implemented as a `Kernel`."
+                    "The covariance functions must be implemented as a "
+                    "`CovarianceFunction`."
                 )
 
             if cov.input_shape != self._input_shape:
@@ -196,7 +197,7 @@ def mean(self) -> functions.Function:
         return self._mean
 
     @property
-    def cov(self) -> kernels.Kernel:
+    def cov(self) -> covfuncs.CovarianceFunction:
         r"""Covariance function :math:`k(x_0, x_1)` of the random process.
 
         .. math::
@@ -222,7 +223,7 @@ def cov(self) -> kernels.Kernel:
     def var(self, args: InputType) -> OutputType:
         """Variance function.
 
-        Returns the variance function which is the value of the covariance or kernel
+        Returns the variance function which is the value of the covariance function
         evaluated elementwise at ``args`` for each output dimension separately.
 
         Parameters

src/probnum/randprocs/covfuncs/__init__.py

@@ -0,0 +1,43 @@
+"""Covariance functions.
+
+Covariance functions describe the spatial or temporal variation of a random process.
+If evaluated at two sets of points, a covariance function computes the covariance of the
+values of the random process at these locations.
+
+Covariance functions support basic algebraic operations, including scaling, addition
+and multiplication.
+"""
+
+from ._covariance_function import CovarianceFunction, IsotropicMixin
+from ._exponentiated_quadratic import ExpQuad
+from ._linear import Linear
+from ._matern import Matern
+from ._polynomial import Polynomial
+from ._product_matern import ProductMatern
+from ._rational_quadratic import RatQuad
+from ._white_noise import WhiteNoise
+
+# Public classes and functions. Order is reflected in documentation.
+__all__ = [
+    "CovarianceFunction",
+    "IsotropicMixin",
+    "WhiteNoise",
+    "Linear",
+    "Polynomial",
+    "ExpQuad",
+    "RatQuad",
+    "Matern",
+    "ProductMatern",
+]
+
+# Set correct module paths. Corrects links and module paths in documentation.
+CovarianceFunction.__module__ = "probnum.randprocs.covfuncs"
+IsotropicMixin.__module__ = "probnum.randprocs.covfuncs"
+
+WhiteNoise.__module__ = "probnum.randprocs.covfuncs"
+Linear.__module__ = "probnum.randprocs.covfuncs"
+Polynomial.__module__ = "probnum.randprocs.covfuncs"
+ExpQuad.__module__ = "probnum.randprocs.covfuncs"
+RatQuad.__module__ = "probnum.randprocs.covfuncs"
+Matern.__module__ = "probnum.randprocs.covfuncs"
+ProductMatern.__module__ = "probnum.randprocs.covfuncs"

src/probnum/randprocs/covfuncs/_arithmetic.py

@@ -0,0 +1,17 @@
+"""Covariance function arithmetic."""
+from ._arithmetic_fallbacks import SumCovarianceFunction, _mul_fallback
+from ._covariance_function import BinaryOperandType, CovarianceFunction
+
+
+# pylint: disable=missing-param-doc
+def add(op1: BinaryOperandType, op2: BinaryOperandType) -> CovarianceFunction:
+    """Covariance function summation."""
+    return SumCovarianceFunction(op1, op2)
+
+
+def mul(op1: BinaryOperandType, op2: BinaryOperandType) -> CovarianceFunction:
+    """Covariance function multiplication."""
+    return _mul_fallback(op1, op2)
+
+
+# pylint: enable=missing-param-doc