Add documentation for platform coverage

- Mention "platform coverage" in README and home page.
- Add a description of "platform coverage" to the specialization page.

Signed-off-by: John Pennycook <[email protected]>

Author: Pennycook

README.md

@@ -6,9 +6,9 @@
 Code Base Investigator (CBI) is an analysis tool that provides insight into the
 portability and maintainability of an application's source code.
 
-- Measure [code divergence](http://doi.org/10.1109/P3HPC.2018.00006) to
-  understand how much code is specialized for different compilers, operating
-  systems, hardware micro-architectures and more.
+- Measure [code divergence](http://doi.org/10.1109/P3HPC.2018.00006) and
+  platform coverage to understand how much code is specialized for different
+  compilers, operating systems, hardware micro-architectures and more.
 
 - Visualize the distance between the code paths used to support different
   compilation targets.

docs/source/features.rst

@@ -42,7 +42,8 @@ are shared between different platform sets.
     {FPGA, CPU 1, GPU 2, GPU 1, CPU 2}   9 21.95
     ---------------------------------------------
     Code Divergence: 0.55
-    Unused Code (%): 4.88
+    Coverage (%): 95.12
+    Avg. Coverage (%): 42.44
     Total SLOC: 41
 
 Future releases of CBI will provide additional ways to visualize the results of

docs/source/index.rst

@@ -41,9 +41,9 @@ Code Base Investigator
 Code Base Investigator (CBI) is an analysis tool that provides insight into the
 portability and maintainability of an application's source code.
 
-- Measure ":doc:`code divergence <specialization>`" to understand how much code
-  is *specialized* for different compilers, operating systems, hardware
-  micro-architectures and more.
+- Measure "code divergence" and "platform coverage" to understand how much code
+  is :doc:`specialized <specialization>` for different compilers, operating
+  systems, hardware micro-architectures and more.
 
 - Visualize the distance between the code paths used to support different
   compilation targets.

docs/source/specialization.rst

@@ -81,3 +81,56 @@ two platforms, whereas a distance of 1 means that no code is shared.
 
 .. _Effective Performance Portability:
     https://doi.org/10.1109/P3HPC.2018.00006
+
+Platform Coverage
+#################
+
+Platform coverage builds on the well-established concept of "test coverage",
+and measures the amount of code in a code base that is utilized by a set of
+platforms. Computing platform coverage is straightforward: it is simply the
+number of lines of code used by one or more platforms expressed as a percentage
+of the number of lines of code in the code base.
+
+.. important::
+    CBI often uses "coverage" as a shorthand for "platform coverage"!
+
+Formally, for a given set of platforms, :math:`H`, the coverage for an
+application :math:`a` solving problem :math:`p` is:
+
+.. math::
+    \textrm{Coverage}(a, p, H) = \frac{\left|\bigcup_{i \in H} c_i(a,p)\right|}
+                                      {\left|\bigcup_{i \in H} c_i(a,p)\right| + \left|\bigcap_{i \in H} c_i'(a,p)\right|} \times 100
+
+where :math:`c_i` is the set of lines of code required to compile application
+:math:`a` and solve problem :math:`p` using platform :math:`i`, and
+:math:`c_i'` is the complement of that set (i.e., the set of lines of code
+*not* required). A coverage of 0% means that none of the code is used by any
+platform, whereas a coverage of 100% means that all of the code is used by at
+least one platform.
+
+Measuring coverage can also help us to reason about differences between
+platforms. The *average* coverage (over platforms) allows us to reason about
+the amount of code covered by *all* platforms.
+
+Formally, the average coverage is:
+
+.. math::
+    \textrm{Average Coverage}(a, p, H) = \frac{\sum_{h \in H} \textrm{Coverage}(a, p, h)}
+                                              {\left|H\right|}
+
+An average coverage of 0% means that none of the code is used by any platform,
+whereas an average coverage of 100% means that all of the code is used by all
+platforms.
+
+.. tip::
+    Low average coverage does not always mean the platforms in :math:`H` share
+    little code; low average coverage can result from a high amount of unused
+    code. Presenting coverage alongside average coverage provides the most insight.
+
+The straightforward nature of coverage and average coverage has several
+advantages. First, it is very easy to intuit the impact of a code change upon
+coverage. Second, it is simple to use and understand in hierarchical contexts
+(e.g., the number of used lines for a directory is the sum of the used lines
+over all files in the directory). For these reasons, CBI functionality focused
+on understanding potential improvements to code structure tend to use coverage
+instead of divergence.