Added the random_points_on_spheroid function to generate points on a …

…minimum-volume spheroid

src/tcutility/geometry.py

@@ -420,3 +420,35 @@ def random_points_in_anular_sphere(shape: Tuple[int], min_radius: float = 0, max
     """
     random_radii = np.random.rand(shape[0]) * (max_radius - min_radius) + min_radius
     return random_points_on_sphere(shape, random_radii)
+
+
+def random_points_on_spheroid(coordinates: np.ndarray, Nsamples: int = 1, margin: float = 0):
+    """
+    Generate random points on a spheroid generated by a set of coordinates.
+
+    Args:
+        coordinates: The (n x dim) set of coordinates that is used to generate the minimum-volume spheroid.
+        Nsamples: The number of samples to return.
+        margin: the spacing between the sampling spheroid and the minimum-volume spheroid.
+
+    Returns:
+        Array of coordinates on a spheroid.
+    """
+    # for this to work we should first get the centroid of our molecule
+    centroid = np.mean(coordinates, axis=0)
+    # and get the centered coordiantes
+    Xc = coordinates - centroid
+
+    # we then do a singular-value decomposition to obtain
+    # the three principle components (Vh) with their eigenvalues (s)
+    _, s, Vh = scipy.linalg.svd(Xc)
+
+    # then compute a transformation matrix for generating the correct spheroid
+    transform = Transform()
+    transform.translate(centroid)
+    transform.rotate((np.diag(s/2 + margin) @ Vh).T)
+
+    # to sample the spheroid we generate points on a 
+    # sphere and transform them to our spheroid
+    p = random_points_on_sphere((Nsamples, Xc.shape[1]))
+    return transform(p)