From 06c60f361fe9a96cb73ee2ae32de13f5c324ae16 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Wed, 31 Mar 2021 14:49:21 +0530
Subject: Document usage information in README.

* README.md (Usage): New section.
---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/README.md b/README.md
index c3daf81..53ef9ce 100644
--- a/README.md
+++ b/README.md
@@ -4,3 +4,55 @@ sambal provides functions to
 
 - uniformly sample a sphere
 - uniformly sample a spherical cap of a sphere
+
+# Usage
+
+## Random vector on sphere
+
+Generate a random vector on a 100-dimensional unit sphere.
+```python
+import numpy as np
+from sambal import random_on_sphere
+
+dim = 100
+print(random_on_sphere(dim))
+```
+
+The same as above, but with a random number generator seeded to 0.
+```python
+import numpy as np
+from sambal import random_on_sphere
+
+dim = 100
+rng = np.random.default_rng(0)
+print(random_on_sphere(dim, rng))
+```
+
+## Random vector on spherical cap
+
+Generate a 100-dimensional random vector on a spherical cap whose
+central axis is `[1, 1, 1, ..., 1] / sqrt(100)` and whose maximum
+planar angle is `pi/3`.
+```python
+import numpy as np
+from sambal import random_on_cap
+
+dim = 100
+axis = np.ones(dim)
+axis = axis / np.linalg.norm(axis)
+max_planar_angle = np.pi/3
+print(random_on_cap(axis, max_planar_angle))
+```
+
+The same as above, but with a random number generator seeded to 0.
+```python
+import numpy as np
+from sambal import random_on_cap
+
+rng = np.random.default_rng(0)
+dim = 100
+axis = np.ones(dim)
+axis = axis / np.linalg.norm(axis)
+max_planar_angle = np.pi/3
+print(random_on_cap(axis, max_planar_angle, rng))
+```
-- 
cgit v1.2.3