Merge branch 'feature/v4_docs_review' of https://github.com/SURGroup/…

…UQpy into feature/v4_docs_review

docs/source/utilities/kernels/euclidean_kernels.rst

@@ -1,30 +1,35 @@
 Euclidean Kernels
 -----------------------------------
 
-Euclidean Kernel
+Euclidean Kernel Class
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :class:`.EuclideanKernel` class is imported using the following command:
+The :class:`.EuclideanKernel` class is the parent class for all Euclidean kernels. It is imported using the following
+command:
 
 >>> from UQpy.utilities.kernels.baseclass.EuclideanKernel import EuclideanKernel
 
 .. autoclass:: UQpy.utilities.kernels.baseclass.EuclideanKernel
     :members: calculate_kernel_matrix
 
-Gaussian
+Gaussian Kernel
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Gaussian kernel is defined by:
+
+.. math:: k(\mathbf{x}_i,\mathbf{x}_j) = \exp\left(\dfrac{||\mathbf{x}_i-\mathbf{x}_j||^2}{2\epsilon^2}\right)
+
 The :class:`.GaussianKernel` class is imported using the following command:
 
 >>> from UQpy.utilities.kernels.GaussianKernel import GaussianKernel
 
-One can use the following command to instantiate the class :class:`.GaussianKernel`
+One can use the following to instantiate the class :class:`.GaussianKernel`
 
 Methods
 ~~~~~~~~~
 
 .. autoclass:: UQpy.utilities.kernels.GaussianKernel
-    :members: optimize_parameters
+    :members: kernel_entry, optimize_parameters
 
 Attributes
 ~~~~~~~~~~

docs/source/utilities/kernels/index.rst

@@ -17,9 +17,13 @@ The :class:`UQpy.utilities.kernels.baseclass.Kernel` class is imported using the
 .. autoclass:: UQpy.utilities.kernels.baseclass.Kernel
     :members: kernel_entry, optimize_parameters, calculate_kernel_matrix
 
+Types of Kernels
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`Kernel` class has subclasses for the following types of kernels:
 
 .. toctree::
    :maxdepth: 1
 
-    Grassmannian Kernels <grassmann_kernels>
     Euclidean Kernels <euclidean_kernels>
+    Grassmannian Kernels <grassmann_kernels>

src/UQpy/dimension_reduction/grassmann_manifold/projections/SVDProjection.py

@@ -77,12 +77,12 @@ def __init__(
             psi.append(GrassmannPoint(v))
 
         self.input_points = data
-        self.u:list[GrassmannPoint] = phi
+        self.u: list[GrassmannPoint] = phi
         """Left singular vectors from the SVD of each sample in `data` representing a point on the Grassmann 
         manifold. """
-        self.sigma:np.ndarray = sigma
+        self.sigma: np.ndarray = sigma
         """Singular values from the SVD of each sample in `data`."""
-        self.v:list[GrassmannPoint] = psi
+        self.v: list[GrassmannPoint] = psi
         """Right singular vectors from the SVD of each sample in `data` representing a point on the Grassmann 
         manifold."""
 

src/UQpy/utilities/kernels/GaussianKernel.py

@@ -2,7 +2,7 @@
 import scipy
 import scipy.spatial.distance as sd
 
-from UQpy.utilities.ValidationTypes import RandomStateType
+from UQpy.utilities.ValidationTypes import RandomStateType, Numpy2DFloatArray
 from UQpy.utilities.kernels import EuclideanKernel
 from scipy.spatial.distance import pdist
 
@@ -22,10 +22,9 @@ def __init__(self, epsilon: float = 1.0):
         super().__init__()
         self.epsilon = epsilon
 
-    def kernel_entry(self, xi, xj):
+    def kernel_entry(self, xi: Numpy2DFloatArray, xj: Numpy2DFloatArray):
         """
-        Given two points, this method calculates the respective kernel entry. Each concrete kernel implementation must
-        override this method and provide its own implementation.
+        Given two points, this method computes the Gaussian kernel value between those two points
 
         :param xi: First point.
         :param xj: Second point.
@@ -40,8 +39,8 @@ def optimize_parameters(self, data: np.ndarray, tolerance: float,
                             random_state: RandomStateType):
         """
 
-        :param data: Cloud of data points.
-        :param tolerance: Tolerance below which the Gaussian kernels is assumed to be zero.
+        :param data: Set of data points.
+        :param tolerance: Tolerance below which the Gaussian kernel is assumed to be zero.
         :param n_nearest_neighbors: Number of neighbors to use for cut-off estimation.
         :param n_cutoff_samples: Number of samples to use for cut-off estimation.
         :param random_state: Random seed used to initialize the pseudo-random number generator. If an :any:`int` is

src/UQpy/utilities/kernels/baseclass/EuclideanKernel.py

@@ -4,7 +4,8 @@
 import scipy.spatial.distance as sd
 import numpy as np
 
-from UQpy.utilities.ValidationTypes import NumpyFloatArray
+from UQpy.utilities import GrassmannPoint
+from UQpy.utilities.ValidationTypes import NumpyFloatArray, Numpy2DFloatArray
 from UQpy.utilities.kernels.baseclass.Kernel import Kernel
 
 
@@ -14,11 +15,11 @@ class EuclideanKernel(Kernel, ABC):
     def __init__(self):
         super().__init__()
 
-    def calculate_kernel_matrix(self, points: Union[list, NumpyFloatArray]):
+    def calculate_kernel_matrix(self, points: Numpy2DFloatArray):
         """
-        Compute the Gaussian kernel matrix given a list of points on the Euclidean space.
+        Using the kernel-specific :py:meth:`.kernel_entry` method, this function assembles the kernel matrix.
 
-        :param points: Coordinates of the points in the Euclidean space
+        :param points: Set of data points in the Euclidean space
 
         """
         nargs = len(points)

src/UQpy/utilities/kernels/baseclass/Kernel.py

@@ -15,23 +15,26 @@ class Kernel(ABC):
     This serves a blueprint to show the methods for kernels implemented in the :py:mod:`.kernels` module .
     """
     def __init__(self):
-        self.kernel_matrix = None
+        self.kernel_matrix: np.ndarray = None
         """Kernel matrix defining the similarity between the points"""
 
-    def calculate_kernel_matrix(self, points: Union[list, NumpyFloatArray]):
+    def calculate_kernel_matrix(self, points: Union[Numpy2DFloatArray, list[GrassmannPoint]]):
         """
         Using the kernel-specific :py:meth:`.kernel_entry` method, this function assembles the kernel matrix.
+
+        :param points: Set of data points. Depending on the type of kernel these should be either :class:`numpy.ndarray`
+            or of type :class:`.GrassmannPoint`.
         """
         pass
 
-    def optimize_parameters(self, data, **kwargs_optimization):
+    def optimize_parameters(self, data: Union[Numpy2DFloatArray, list[GrassmannPoint]], **kwargs_optimization):
         """
         This serves as a blueprint function in case a kernel provides the ability to optimize its parameters. In that
-        case, the kernel will override of this method, and store the optimized parameters in the kernel's attributes.
+        case, the kernel will override this method, and store the optimized parameters in the kernel's attributes.
 
         :param data: Set of data points.
         :param kwargs_optimization: Keyword arguments containing any extra parameters needed to perform the
-            optimization.
+            optimization. These will be unique to the specific kernel.
         """
         pass