Document usage information in README.

* README.md (Usage): New section.

1 files changed, 52 insertions, 0 deletions

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))
+```