Grouping Workspace Fine Points
------------------------------

A `GroupingWorkspace` represents a one-to-many mapping between integer subgroup-IDs, and corresponding sets of pixel-IDs.  As implemented in the Mantid codebase, `GroupingWorkspace` s can be more complex than they initially seem.  Most of the subtlety relates to the fact that there are *multiple* ways to represent any specific subgroup-id to pixel-ids grouping.

A `GroupingWorkspace` is a subclass of `SpecialWorkspace2D`, which is a
workspace where each spectrum consists of a single-value.  The single-value in this case
is the subgroup-ID.  Note that each subgroup-ID may have multiple spectra associated with it.
The subgroup-ID *zero* has a special meaning: which is usually that the associated pixel-IDs should be ignored (e.g. for *masked* pixels).

Accessing the grouping-workspace's spectrum-to-detector map, e.g. using `getDetectorIDs(wi)`, a set of pixel-IDs associated with
the spectrum at each workspace-index can be determined.  Assembling the complete set of pixel-IDs corresponding to a subgroup requires assembling
the spectrum-to-detector map contributions from *all* of the spectra that have that subgroup-ID as a value.
The *possible* number of such spectra ranges from only *one*, to as many spectra as there are pixel-IDs.
That is, there are many alternative *correct* ways to represent the subgroup, and no specific representation
should be depended upon without additional validation.

In general, it is recommended to use the `GroupingWorkspace`-specific methods `getGroupIDs()` and `getDetectorIDsOfGroup()`,
and to *avoid* iterating over the grouping-workspace's spectra.  When for any reason this is not sufficient,
the spectrum-to-detector map must be used and interpreted correctly,
and one needs to be very careful to ensure that the most-general format of the `GroupingWorkspace` is taken into account.

The order of the subgroup-IDs in the grouping workspace cannot be depended upon. It will be emphasized that the subgroup-ID is at `readY(wi)[0]`.  It's important to *validate* any assumption made about the workspace-order at each point-of-use.  Several algorithms in `Mantid`, such as `DiffractionFocussing`, for convenience encode the subgroup-ID
into the spectrum-number (not the workspace-index) of the spectra in the output workspace. In general,
this behavior should be verified in each case that it is used.  For example, after `DiffractionFocussing`
is applied in `FocusSpectraAlgorithm`: the correspondance between the order of the subgroup-IDs
as used by `PixelGroup`, and the workspace-index order of the spectrum-numbers of the output workspace is verified.
As an alternative implementation, it would have been straightforward to use a map to
represent these types.  If this were the case, this ordering ambiguity would no longer be an issue.  However, there still remain several sections in the SNAPRed code-base that do not take this
approach.

Regarding pixel-IDs: it is not required that all of the pixel-IDs have a corresponding subgroup.  In some cases the unused pixels may be placed in subgroup *zero*. At the opposite extreme, it isn't even required that a pixel-ID participate in only *one* subgroup, although this latter assumption
*would* be a correct in many use cases.

To summarize the important points:

  -- Grouping-workspaces are essentially a sequence of subgroup-IDs;

  -- The subgroup-IDs may be repeated: this is why it's important to use `getDetectorIDsOfGroup`;

  -- The ordering of subgroup-IDs is arbitrary: that is, don't depend on workspace-index specifics;

  -- It isn't necessary that the subgroups include *all* pixel-IDs; unused pixels may be grouped into subgroup *zero*, but if this fact were to be used during implementation, it must be verified;

  -- It isn't necessary that a pixel-ID be included in only one subgroup, although usually this will be the case;

  -- Grouping-workspace specific methods should be used wherever possible.  By using these methods,
     most of these representation details will be supported *transparently* by the Mantid codebase itself.