CFSimpleIndexer.md

@@ -20,7 +20,7 @@ The signature of the `CFSimpleIterator` constructor is the following
     const axis_desc_t& frequency,
     unsigned mueller);
 ```
-The arguments of the constructor correspond (largely) to dimensions in the space of `CFStore2 x CFBuffer`. Each of the arguments (except the last) is a value of type `CFSimpleIndexer::axis_desc_t`, which combines the size of the axis and a flag to indicate whether the convolution function support sizes may be variable along that axis. Note that  each axis is assumed to be densely occupied, and any conversion of an index on these axes to or from an index in `CFStore2 x CFBuffer` is unspecified. The "variable-size CF" flag **must** be set if the support size of the convolution functions is not constant as the index on that axis changes while the remaining indexes stay fixed.
+The arguments of the constructor correspond (largely) to dimensions in the space of `CFStore2 x CFBuffer`. Each of the arguments (except the last) is a value of type `CFSimpleIndexer::axis_desc_t`, which combines the size of the axis and a flag to indicate whether the convolution function support sizes may be variable along that axis. A boolean element is "true" if and only if the CF size (in X and Y) can change when the associated index varies while all other indexes remain fixed.  Note that  each axis is assumed to be densely occupied, and any conversion of an index on these axes to or from an index in `CFStore2 x CFBuffer` is unspecified. The "variable-size CF" flag **must** be set if the support size of the convolution functions is not constant as the index on that axis changes while the remaining indexes stay fixed.
 
 The index type that is related to `hpg::CFArray` is `CFSimpleIndexer::cf_index_t`, which comprises three elements that correspond to the `mueller` `cube` and `group` arguments of the `CFArray` indexing operator. The `CFSimpleIndexer` method that converts from a CASA-like index to a `CFArray` index is then
 ```c++
@@ -68,4 +68,17 @@ and the `CFSimpleIndexer` method that converts from a `CFArray` index to a CASA
   CFCellIndex
   cell_index(cf_index_t index) const;
 ```
-Note that a `CFCellIndex` value only provides indexes within the range of each dimension as defined by the `CFSimpleIndexer` constructor! Global index transformations to and from `CFCellIndex` and `CFStore2 x CFBuffer` are the responsibility of the user.
+Note that a `CFCellIndex` value only provides indexes within the range of each dimension as defined by the `CFSimpleIndexer` constructor! In other words, `CFSimpleIndexer` values are always defined on a dense space (note that X/Y element indexes are a part of neither `CFCellIndex` nor `CFSimpleIndexer`). Global index transformations to and from `CFCellIndex` and `CFStore2 x CFBuffer` are the responsibility of the user. Conditions under which such global index transformations are necessary may be a consequence of using a subset of indexes in `CFStore2 x CFBuffer` to define a `CFArray` instance, which may be useful in many cases to limit the memory needed by the `CFArray` instance (in particular when a `CFArray` instance needs to be copied to device memory, such as a GPU).
\ No newline at end of file
+
+## Example
+
+Let `store` be a `CFStore2` instance, with a single baseline type and ten elements on the "PA/Time" axis. Let each `CFBuffer` element have four frequencies, eight "W" values, and sixteen Mueller elements. Furthermore, assume that the CF support size varies with "W", and no other index values. To define a `CFSimpleIndexer` value for the *entire* `CFStore2 x CFBuffer`, the following is correct
+```c++
+CFSimpleIndexer
+  indexer(
+    {1, false}, // 1 baseline type with no CF support variability
+    {10, false}, // 10 times with no CF support variability
+    {8, true}, // 8 W planes with CF support variability
+    {4, false}, // 4 frequencies with no CF support variability
+    16); // 16 Mueller elements
+```