CFSimpleIndexer.md

+# `HGP` convolution function indexing
+
+Indexing of elements of convolution functions that are used for gridding by `HPG` has been designed to optimize performance of the gridding kernel, and also to support a wide range of uses. To that end, the indexing of convolution function elements has been reduced to the essentials that are needed by the gridding kernel, and consequently some of the context of convolution functions as used for imaging has been lost. However, there is sufficient generality in the indexing scheme to allow all the usual gridding algorithms used for imaging to be realized using the generic indexing scheme. Nevertheless, because of the apparent lack of context, it can be difficult to map the normal schemes used for indexing convolution functions needed for imaging to the scheme implemented by `HPG`. To support use of index schemes used by CASA with `HPG`, various index transformation classes are implemented.
+
+## `CFSimpleIndexer`
+
+The `CFSimpleIndexer` is a widely applicable index transformation class (and the only one implemented at this time.) It can be used to transform indexes between indexes in `CFStore2 x CFBuffer` that name a `CFCell` and indexes in `hpg::CFArray`. Note that the `CFSimpleIndexer` class indexes planes and points in a plane, just as the `CFCell` identifies a plane. Once a `CFSimpleIndexer` instance has been created, it can be used to convert between the two index schemes. However, note that no bounds checking is performed by the class methods, and it is the user's responsibility to ensure that valid index arguments are provided to these methods. Because the `hpg::GridderState` class maintains the convolution function values in dense arrays, it is necessary to partition the set of convolution functions provided by a `CFArray`instance according to the size of the convolution function support. While it is acceptable to over-partition the set of convolution functions, limitations in the current implementation of `HPG` set a hard upper limit on the number of partitions that can be used, and therefore it is recommended to reduce the number of partitions as far as is practicable.
+
+The class is defined in the file `hpg_indexing.hpp`.
+
+The signature of the constructor of `CFSimpleIterator` is the following
+```c++
+  // pair elements: (axis length, allows variable-size CF)
+  using axis_desc_t = std::pair<unsigned, bool>;
+
+  CFSimpleIndexer(
+    const axis_desc_t& baseline_class,
+    const axis_desc_t& time,
+    const axis_desc_t& w_plane,
+    const axis_desc_t& frequency,
+    const axis_desc_t& mcol,
+    const axis_desc_t& mrow);
+```
+The arguments of the constructor correspond (largely) to dimensions in the space of `CFStore2 x CFBuffer`. Each of the arguments is a value of type `CFSimpleIndexer::axis_desc_t`, which defines the size of the axis, and a flag to indicate whether the convolution function support sizes may be variable on that axis.
+
+The index type that is related to `hpg::CFArray` is `CFSimpleIndexer::cf_index_t`, which comprises three elements that correspond to the `mrow`, `cube` and `group` arguments of the `CFArray` indexing operator. The `CFSimpleIndexer` method that converts from a CASA index to a `CFArray` index is then
+```c++
+  // array elements: (mrow, cube, grp)
+  using cf_index_t = std::array<unsigned, 3>;
+
+  cf_index_t
+  cf_index(const CFCellIndex& index) const;
+```
+
+The index type that is related to the CASA indexing of convolution functions is `hpg::CFCellIndex`.
+```c++
+  CFCellIndex(
+    unsigned baseline_class,
+    unsigned time,
+    unsigned w_plane,
+    unsigned frequency,
+    unsigned mcol,
+    unsigned mrow);
+```
+and the `CFSimpleIndexer` method that converts from a `CFArray` index to a CASA index is
+```c++
+  CFCellIndex
+  cell_index(cf_index_t index) const;
+```
+
+TODO: describe `mrow` and `mcol`, and how the relate to CASA and `hpg` indexing.
\ No newline at end of file