From c50fc913662a88995f5e338764dbf4efcfa71f45 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Mon, 15 Mar 2021 15:25:48 +0530
Subject: Add function docstrings.

* contrib/cone-vector.py (random_vector_on_sphere,
planar_angle2solid_angle_fraction, solid_angle_fraction2planar_angle,
rotate_from_nth_canonical, random_vector_on_spherical_cap): Add
docstrings.
---
 contrib/cone-vector.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/contrib/cone-vector.py b/contrib/cone-vector.py
index 9501464..676750f 100644
--- a/contrib/cone-vector.py
+++ b/contrib/cone-vector.py
@@ -22,10 +22,12 @@ from numpy.linalg import norm
 from scipy.special import betainc, betaincinv, gamma
 
 def random_vector_on_sphere(dim):
+    """Return a random vector uniformly distributed on the unit sphere."""
     x = randn(dim)
     return x / norm(x)
 
 def planar_angle2solid_angle_fraction(planar_angle, dim):
+    """Return the solid angle fraction for a given planar angle."""
     alpha = (dim - 1) / 2
     beta = 1/2
     return where(planar_angle < pi/2,
@@ -33,6 +35,7 @@ def planar_angle2solid_angle_fraction(planar_angle, dim):
                  1 - 0.5*betainc(alpha, beta, sin(planar_angle)**2))
 
 def solid_angle_fraction2planar_angle(solid_angle_fraction, dim):
+    """Return the planar angle for a given solid angle fraction."""
     alpha = (dim - 1) / 2
     beta = 1/2
     return where(solid_angle_fraction < 1/2,
@@ -40,6 +43,8 @@ def solid_angle_fraction2planar_angle(solid_angle_fraction, dim):
                  pi - arcsin(sqrt(betaincinv(alpha, beta, 2*(1-solid_angle_fraction)))))
 
 def rotate_from_nth_canonical(x, axis):
+    """Rotate vector from around the nth canonical axis to the given axis.
+    """
     xn = x[-1]
     axisn = axis[-1]
     if axisn != 1:
@@ -52,6 +57,7 @@ def rotate_from_nth_canonical(x, axis):
     return x
 
 def random_vector_on_spherical_cap(axis, maximum_planar_angle):
+    """Return a random vector uniformly distributed on a spherical cap."""
     dim = axis.size
     maximum_solid_angle_fraction = planar_angle2solid_angle_fraction(maximum_planar_angle, dim)
     solid_angle_fraction = maximum_solid_angle_fraction*random()
-- 
cgit v1.2.3