Merge pull request #1 from tkphd/docs

document Andahl's law with ASCII speedup curve

README.md

@@ -6,3 +6,53 @@ communication, so can easily be overloaded.
 
 The application is installed as a python module with a shell
 script wrapper. The only requirement is MPI4PY.
+
+## Background
+
+Amdahl's law posits that some unit of work comprises a proportion *p* that
+benefits from parallel resources, and a proportion *s* that is constrained to
+execute in serial. The theoretical maximum speedup achievable for such a
+workload is
+
+```output
+           1
+    S = -------
+        s + p/N
+```
+
+where *S* is the speedup relative to performing all of the work in serial and
+*N* is the number of parallel workers. A plot of *S* vs. *N* ought to look like
+this, for *p*=0.8:
+
+```output
+  5┬─────────────────────────────────────·──────────────────┐
+   │                                   ·                    │
+   │                                 ·                      │
+   │                               ·                        │
+  4┤                             ·                          │
+   │                           ·                            │
+S  │                         ·                              *
+p  │                       ·                   *      *     │
+e  │                     ·               *                  │
+e 3┤                   ·           *                        │
+d  │                 ·      *                               │
+u  │               ·  *                                     │
+p  │             ·                                          │
+   │           ·*                                           |
+  2┤         ·                                              │
+   │     * ·                                                │
+   │     ·                                                  │
+   │   ·                                                    │
+   │ ·                                                      │
+  1*─────┬──────┬─────┬─────┬──────┬─────┬─────┬──────┬─────┤
+   1     2      3     4     5      6     7     8      9     10
+                             Workers
+```
+
+"Ideal scaling" (*p*=1) is would be the line *y* = *x* (or *S* = *N*),
+represented here by the dotted line.
+
+This graph shows there is a speed limit for every workload, and diminishing
+returns on throwing more parallel processors at a problem. It is worth running
+a "scaling study" to assess how far away that speed limit might be for the
+given task.

amdahl/amdahl.py

@@ -4,6 +4,17 @@
 
 from mpi4py import MPI
 
+"""
+Gather timing data in order to plot speedup *S* vs. number of cores *N*,
+which should follow Amdahl's Law:
+
+           1
+    S = -------
+        s + p/N
+
+where *s* is the serial proportion of the total work and *p* the
+parallelizable proportion.
+"""
 
 def do_work(work_time=30, parallel_proportion=0.8, comm=MPI.COMM_WORLD):
     # How many MPI ranks (cores) are we?