Merge branch 'feature/v4_docs_review' into feature/version4

docs/source/utilities/distances/euclidean_distances.rst

@@ -1,17 +1,23 @@
 Euclidean Distances
 --------------------------------------
 
+Euclidean distances are measures of proximity between points in standard Euclidean spaces.
 
-EuclideanDistance
+EuclideanDistance Class
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-The abstract :class:`UQpy.utilities.distances.baseclass.EuclideanDistance` class is a blueprint for classes in :mod:`.euclidean_distances` module.
-It allows the user to define a set of methods that must be created within any child classes built from this abstract class.
+The abstract :class:`UQpy.utilities.distances.baseclass.EuclideanDistance` class is the base class for all Euclidean
+distances in :py:mod:`UQpy`. It provides a blueprint for classes in the :mod:`.euclidean_distances` module and allows
+the user to define a set of methods that must be created within any child classes built from this abstract class.
 
 .. autoclass:: UQpy.utilities.distances.baseclass.EuclideanDistance
     :members: calculate_distance_matrix
 
+The :class:`.EuclideanDistance` class is imported using the following command:
+
+>>> from UQpy.utilities.distances.baseclass.EuclideanDistance import EuclideanDistance
+
 List of Available Distances
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/source/utilities/distances/grassmann_distances.rst

@@ -1,62 +1,79 @@
 Grassmann Distances
 --------------------------------------
 
-The Grassmannian (or Riemannian) distance is a metric that assigns nonnegative values to each pair of subspaces
-:math:`Y_1, Y_2 \in \mathbb{R}^{n \times p}` on the Grassmann manifold :math:`\mathcal{G}(p, n)`. Formally,
-is defined as the length of the shortest geodesic connecting the two points on :math:`\mathcal{G}(p, n)`.
-:py:mod:`UQpy` introduces various Grassmann distances derived from the principal angles :cite:`Distances_1`.
+The Grassmannian (or Riemannian) distance assigns a nonnegative value to measure distance between a pair of subspaces
+:math:`\mathbf{X}_0, \mathbf{X}_1 \in \mathbb{R}^{n \times p}` on the Grassmann manifold :math:`\mathcal{G}(p, n)`.
+Formally, a Grassmann distance measures the length of the geodesic path connecting the two points on
+:math:`\mathcal{G}(p, n)` where all distances are a function of the principal angles between subspaces. :py:mod:`UQpy`
+introduces various Grassmann distances derived from the principal angles :cite:`Distances_1`.
 
 .. math:: 0 \leq \theta_1 \leq \theta_2 \leq \ldots \leq \theta_p \leq \pi/2,
 
-where the first principal angle :math:`\theta_1` is the smallest angle between all pairs of unit vectors in the
-first and the second subspaces. Practically, the principal angles can be calculated from the singular value
-decomposition (SVD) of :math:`\mathbf{Y}_1'\mathbf{Y}_2`,
+Practically, the principal angles can be calculated from the singular value decomposition (SVD) of
+:math:`\mathbf{X}_0^T\mathbf{X}_1`, as
 
-.. math:: \mathbf{Y}_1'\mathbf{Y}_2 = \mathbf{U}\cos(\Theta)\mathbf{V}'
+.. math:: \mathbf{X}_0^T\mathbf{X}_1 = \mathbf{U}\cos(\Theta)\mathbf{V}'
 
 where :math:`\cos(\Theta)=\text{diag}(\cos\theta_1, \ldots,\cos\theta_p)`. This definition of distance can be extended
-to cases where :math:`\mathbf{Y}_1` and :math:`\mathbf{Y}_2` have different number of columns :math:`p`. More
+to cases where :math:`\mathbf{X}_0` and :math:`\mathbf{X}_1` have different number of columns :math:`p`. More
 information can be found in :cite:`Distances_2`.
 
-GrassmannianDistance
+GrassmannianDistance Class
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :class:`.GrassmannianDistance` class is imported using the following command:
-
->>> from UQpy.utilities.distances.baseclass.GrassmannianDistance import GrassmannianDistance
 
-The abstract :class:`.GrassmannianDistance` class is a blueprint for all classes in :mod:`.grassmannian_distances` module.
-It allows the user to define a set of methods that must be created within any child classes built from this abstract class.
+The abstract :class:`UQpy.utilities.distances.baseclass.GrassmannianDistance` class is the base class for all
+Grassmannian distances in :py:mod:`UQpy`. It provides a blueprint for classes in the :mod:`.grassmannian_distances`
+module and allows the user to define a set of methods that must be created within any child classes built
+from this abstract class.
 
 .. autoclass:: UQpy.utilities.distances.baseclass.GrassmannianDistance
     :members: calculate_distance_matrix
 
+The :class:`.GrassmannianDistance` class is imported using the following command:
 
+>>> from UQpy.utilities.distances.baseclass.GrassmannianDistance import GrassmannianDistance
+
+List of Available Distances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+All the distances classes below are subclasses of the :class:`.GrassmannianDistance` class. New distances can be written
+as subclasses having a :py:meth:`compute_distance` method.
 
-Asimov
+Asimov Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Asimov distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0` and
+:math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_A(\mathbf{X}_0,\mathbf{X}_1) = \cos^{-1}||\mathbf{X}_0^T\mathbf{X}_1||_2 = \max(\Theta)
+
 The :class:`.AsimovDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.AsimovDistance import AsimovDistance
 
-One can use the following command to instantiate the class :class:`.AsimovDistance`
+One can use the following command to instantiate the :class:`.AsimovDistance` class.
 
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.AsimovDistance
     :members:
 
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.AsimovDistance.distance_matrix
 
-Binet-Cauchy
+Binet-Cauchy Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Binet-Cauchy distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0` and
+:math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{BC}(\mathbf{X}_0,\mathbf{X}_1) = \left[1-(\det\mathbf{X}_0^T\mathbf{X}_1)^2\right]^{1/2} = \left[1-\prod_{l}\cos^2(\Theta_l)\right]^{1/2}
+
+
 The :class:`.BinetCauchyDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.BinetCauchyDistance import BinetCauchyDistance
 
-One can use the following command to instantiate the class :class:`.BinetCauchyDistance`
+One can use the following command to instantiate the :class:`.BinetCauchyDistance` class.
 
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.BinetCauchyDistance
@@ -65,14 +82,19 @@ One can use the following command to instantiate the class :class:`.BinetCauchyD
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.BinetCauchyDistance.distance_matrix
 
 
-Fubini-Study
+Fubini-Study Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Fubini-Study distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0` and
+:math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{FS}(\mathbf{X}_0,\mathbf{X}_1) = \cos^{-1}\left(\prod_{l}\cos(\Theta_l)\right)
+
 The :class:`.FubiniStudyDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.FubiniStudyDistance import FubiniStudyDistance
 
-One can use the following command to instantiate the class :class:`.FubiniStudyDistance`
+One can use the following command to instantiate the :class:`.FubiniStudyDistance` class.
 
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.FubiniStudyDistance
@@ -81,9 +103,14 @@ One can use the following command to instantiate the class :class:`.FubiniStudyD
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.FubiniStudyDistance.distance_matrix
 
 
-Geodesic
+Geodesic Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Geodesic (or Arc-length) distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0`
+and :math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{G}(\mathbf{X}_0,\mathbf{X}_1) = ||\boldsymbol\Theta ||_2 = \left(\sum \Theta^2_l\right)^{1/2}
+
 The :class:`.GeodesicDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.GeodesicDistance import GeodesicDistance
@@ -96,14 +123,19 @@ One can use the following command to instantiate the class :class:`.GeodesicDist
 
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.GeodesicDistance.distance_matrix
 
-Martin
+Martin Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Martin distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0`
+and :math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{M}(\mathbf{X}_0,\mathbf{X}_1) = \left[\log\prod_{l}1/\cos^2(\Theta_l)\right]^{1/2}
+
 The :class:`.MartinDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.MartinDistance import MartinDistance
 
-One can use the following command to instantiate the class :class:`.MartinDistance`
+One can use the following command to instantiate the :class:`.MartinDistance` class.
 
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.MartinDistance
@@ -113,43 +145,59 @@ One can use the following command to instantiate the class :class:`.MartinDistan
 
 
 
-Procrustes
+Procrustes Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Procrustes distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0`
+and :math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{P}(\mathbf{X}_0,\mathbf{X}_1) = ||\mathbf{X}_0\mathbf{U}-\mathbf{X}_1\mathbf{V} ||_F = 2\left[\sum_{l}\sin^2(\Theta_l/2)\right]^{1/2}
+
 The :class:`.ProcrustesDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.ProcrustesDistance import ProcrustesDistance
 
-One can use the following command to instantiate the class :class:`.ProcrustesDistance`
+One can use the following command to instantiate the :class:`.ProcrustesDistance` class.
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.ProcrustesDistance
     :members:
 
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.ProcrustesDistance.distance_matrix
 
-Projection
+Projection Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Projection distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0`
+and :math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{Pr}(\mathbf{X}_0,\mathbf{X}_1) = ||\mathbf{X}_0\mathbf{X}_0^T-\mathbf{X}_1\mathbf{X}_1^T ||_2 =  \left(\sum_{l} \sin^2(\Theta_l)\right)^{1/2}
+
 The :class:`.ProjectionDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.ProjectionDistance import ProjectionDistance
 
-One can use the following command to instantiate the class :class:`.ProjectionDistance`
+One can use the following command to instantiate the :class:`.ProjectionDistance` class.
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.ProjectionDistance
     :members:
 
 .. autoattribute:: UQpy.utilities.distances.grassmannian_distances.ProjectionDistance.distance_matrix
 
 
-Spectral
+Spectral Distance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The Spectral distance between two subspaces defined by the orthonormal matrices, :math:`\mathbf{X}_0`
+and :math:`\mathbf{X}_1`, is given by:
+
+.. math:: d_{S}(\mathbf{X}_0,\mathbf{X}_1) = ||\mathbf{X}_0\mathbf{U}-\mathbf{X}_1\mathbf{V} ||_2 = 2\sin( \max(\Theta_l)/2)
+
+
 The :class:`.SpectralDistance` class is imported using the following command:
 
 >>> from UQpy.utilities.distances.grassmannian_distances.SpectralDistance import SpectralDistance
 
-One can use the following command to instantiate the class :class:`.SpectralDistance`
+One can use the following command to instantiate the :class:`.SpectralDistance` class.
 
 .. autoclass:: UQpy.utilities.distances.grassmannian_distances.SpectralDistance
     :members:

src/UQpy/utilities/distances/baseclass/GrassmannianDistance.py

@@ -22,7 +22,7 @@ def calculate_distance_matrix(self,
                                   points: Union[list[Numpy2DFloatArrayOrthonormal],  list[GrassmannPoint]],
                                   p_dim: Union[list, np.ndarray]):
         """
-        Given a list of points that belong on a Grassmann Manifold
+        Given a list of points that belong on a Grassmann Manifold, assemble the distance matrix between all points.
 
         :param points: List of points belonging on the Grassmann Manifold. Either a list of :class:`.GrassmannPoint` or
          a list of orthonormal :class:`.ndarray`.

src/UQpy/utilities/distances/euclidean_distances/L2Distance.py

@@ -8,7 +8,7 @@ class L2Distance(EuclideanDistance):
 
     def compute_distance(self, xi: NumpyFloatArray, xj: NumpyFloatArray) -> float:
         """
-        Given two points, this method calculates the Euclidean distance.
+        Given two points, this method calculates the L2 distance.
 
         :param xi: First point.
         :param xj: Second point.

src/UQpy/utilities/distances/euclidean_distances/MinkowskiDistance.py

@@ -12,7 +12,6 @@ def __init__(self, p: float = 2):
         """
         self.p = p
 
-
     def compute_distance(self, xi: NumpyFloatArray, xj: NumpyFloatArray) -> float:
         """
         Given two points, this method calculates the Minkowski distance.

src/UQpy/utilities/distances/grassmannian_distances/AsimovDistance.py

@@ -9,11 +9,7 @@
 
 class AsimovDistance(GrassmannianDistance):
     """
-    A class to calculate the Asimov distance between two  Grassmann points defined as:
-
-    .. math::
-
-        d_{A}(x_i, x_j) = \max(\Theta)
+    A class to calculate the Asimov distance between two Grassmann points.
 
     """
     @beartype

src/UQpy/utilities/distances/grassmannian_distances/BinetCauchyDistance.py

@@ -8,12 +8,7 @@
 
 class BinetCauchyDistance(GrassmannianDistance):
     """
-    A class to calculate the Binet-Cauchy distance between two  Grassmann points defined as:
-
-    .. math::
-
-        d_{BC}(x_i, x_j) = [1-\prod_{l}\cos^2(\Theta_l)]^{1/2}
-
+    A class to calculate the Binet-Cauchy distance between two Grassmann points.
     """
 
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float:

src/UQpy/utilities/distances/grassmannian_distances/FubiniStudyDistance.py

@@ -8,11 +8,7 @@
 
 class FubiniStudyDistance(GrassmannianDistance):
     """
-    A class to calculate the Fubini-Study distance between two  Grassmann points defined as:
-
-    .. math::
-
-        d_{C}(x_i, x_j) = cos^{-1}(\prod_{l}\cos(\Theta_l))
+    A class to calculate the Fubini-Study distance between two Grassmann points.
 
     """
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float:

src/UQpy/utilities/distances/grassmannian_distances/GeodesicDistance.py

@@ -9,11 +9,7 @@
 
 class GeodesicDistance(GrassmannianDistance):
     """
-    A class to calculate the Geodesic distance between two Grassmann points defined as:
-
-    .. math::
-
-        d_{C}(x_i, x_j) = (\sum \Theta^2_l)^{1/2}
+    A class to calculate the Geodesic distance between two Grassmann points.
 
     """
     @beartype

src/UQpy/utilities/distances/grassmannian_distances/MartinDistance.py

@@ -8,11 +8,7 @@
 
 class MartinDistance(GrassmannianDistance):
     """
-    A class to calculate the Martin distance between two  Grassmann points defined as:
-
-    .. math::
-
-        d_{M}(x_i, x_j) = [\log\prod_{l}1/\cos^2(\Theta_l)]^{1/2}
+    A class to calculate the Martin distance between two Grassmann points.
 
     """
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float:

src/UQpy/utilities/distances/grassmannian_distances/ProcrustesDistance.py

@@ -8,16 +8,12 @@
 
 class ProcrustesDistance(GrassmannianDistance):
     """
-    A class to calculate the Procrustes (chordal) distance between two  Grassmann points defined as:
-
-    .. math::
-
-        d_{C}(x_i, x_j) = 2[\sum_{l}\sin^2(\Theta_l/2)]^{1/2}
+    A class to calculate the Procrustes distance between two Grassmann points.
 
     """
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float:
         """
-        Compute the Procrustes (chordal) distance between two points on the Grassmann manifold.
+        Compute the Procrustes distance between two points on the Grassmann manifold.
 
         :param xi: Orthonormal matrix representing the first point.
         :param xj: Orthonormal matrix representing the second point.

src/UQpy/utilities/distances/grassmannian_distances/ProjectionDistance.py

@@ -8,11 +8,7 @@
 
 class ProjectionDistance(GrassmannianDistance):
     """
-    A class to calculate the Projection distance between two Grassmann points defined as:
-
-    .. math::
-
-        d_{C}(x_i, x_j) =  (\sum_{l} \sin^2(\Theta_l))^{1/2}
+    A class to calculate the Projection distance between two Grassmann points.
 
     """
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float:

src/UQpy/utilities/distances/grassmannian_distances/SpectralDistance.py

@@ -8,11 +8,7 @@
 
 class SpectralDistance(GrassmannianDistance):
     """
-    A class to calculate the Spectral distance between two Grassmann points defined as:
-
-    .. math::
-
-        d_{C}(x_i, x_j) =  2\sin( \max(\Theta_l)/2)
+    A class to calculate the Spectral distance between two Grassmann points.
 
     """
     def compute_distance(self, xi: GrassmannPoint, xj: GrassmannPoint) -> float: