Re #20599 - added release notes and updated documentation

docs/source/algorithms/SofQWNormalisedPolygon-v1.rst

@@ -12,13 +12,55 @@ Description
 Converts a 2D workspace from :ref:`units <Unit Factory>` 
 of spectrum number/**energy transfer** 
 to the intensity as a function of **momentum transfer** :math:`Q` 
-and **energy transfer** :math:`\Delta E`. The rebinning is done as a 
-weighted sum of overlapping polygons with
-fractional area tracking. The result is stored in a new workspace type:
-**RebinnedOutput**. The new workspace presents the data as the
-fractional counts divided by the fractional area. The biggest
-consequence of this method is that in places where there are no counts
-and no acceptance (no fractional areas), **nan**\ -s will result.
+and **energy transfer** :math:`\Delta E`. 
+
+.. figure:: /images/RebinnedOutputStep1.png
+   :align: center
+
+As shown in the figure, the input grid (pink-shaded parallelopiped,
+aligned in scattering angle and energy transfer) is not parallel to the
+output grid (square grid, aligned in :math:`Q` and energy). This means
+that the output bins will only ever partially overlap the input data. To
+account for this, the signal :math:`Y` and errors :math:`E` in the new
+bins are calculated as:
+
+.. math:: Y^{\mathrm{new}} = \sum_i Y^{\mathrm{old}}_i F_i
+.. math:: E^{\mathrm{new}} = \sqrt{\sum_i (E^{\mathrm{old}}_i)^2 F_i}
+
+In addition to weighting the signal and error values, the total
+fractional weights:
+
+.. math:: F^{\mathrm{new}} = \sum_i F_i
+
+are also stored in the output of this algorithm which is a new workspace
+type: **RebinnedOutput**. To see why this is needed, consider rebinning
+the output on a larger grid:
+
+.. figure:: /images/RebinnedOutputStep2.png
+   :align: center
+
+If the fractional weights are not chained as shown, then the area
+shaded in a lighter blue under :math:`A_1` (where originally there was
+no data) would be included in the weights, which would be an
+overestimate of the actual weights, leading to an overestimate of the
+signal and error.
+
+Finally, if there is a bin in the output grid which only has a very
+small overlap with the input grid (for example at the edges of the
+detector coverage), the fractional weight :math:`F` of this bin, and
+hence its signal :math:`Y` and error :math:`E` would be very small
+compared to its neighbours. Thus, for display purposes, the actual
+signal and errors stored in a RebinnedOutput are renomalised by the
+weights:
+
+.. math:: Y^{\mathrm{display}} = Y^{\mathrm{new}} / F^{\mathrm{new}}
+.. math:: E^{\mathrm{display}} = E^{\mathrm{new}} / F^{\mathrm{new}}
+
+at the end of the algorithm. The biggest consequence of this method is
+that in places where there are no counts (:math:`Y=0`) and no acceptance
+(no fractional areas, :math:`F=0`), :math:`Y/F=`\ **nan**\ -s will
+result.
+
 
 The algorithm operates in non-PSD mode by default. This means that all
 azimuthal angles and widths are forced to zero. PSD mode will determine
@@ -26,11 +68,21 @@ the azimuthal angles and widths from the instrument geometry. This mode
 is activated by placing the following named parameter in a Parameter
 file: *detector-neighbour-offset*. The integer value of this parameter
 should be the number of pixels that separates two pixels at the same
-vertical position in adjacent tubes.
-
-
-See  :ref:`algm-SofQWCentre` for centre-point binning  or :ref:`algm-SofQWPolygon`
-for simpler and less precise but faster binning strategies.
+vertical position in adjacent tubes. Note that in both non-PSD and PSD
+modes, the scattering angle widths are determined from the detector
+geometry and may vary from detector to detector as defined by the
+instrument definition files.
+
+
+See :ref:`algm-SofQWCentre` for centre-point binning or :ref:`algm-SofQWPolygon`
+for simpler and less precise but faster binning strategies. The speed-up
+is from ignoring the azimuthal positions of the detectors (as for the non-PSD
+mode in this algorithm) but in addition, :ref:`algm-SofQWPolygon` treats 
+all detectors as being the same, and characterised by a single width in
+scattering angle. Thereafter, it weights the signal and error by the fractional
+overlap, similarly to that shown in the first figure above, but then discards
+the summed weights, producing a **Workspace2D** rather than a
+**RebinnedOutput** workspace.
 
 Usage
 -----

docs/source/algorithms/SofQWPolygon-v1.rst

@@ -14,9 +14,21 @@ of spectrum number/**energy transfer** to
 the intensity as a function of momentum transfer 
 :math:`Q` and energy transfer :math:`\Delta E`. 
 
-The rebinning is done as a weighted sum of overlapping polygons. See 
-:ref:`algm-SofQWCentre` for centre-point binning  or :ref:`algm-SofQWNormalisedPolygon` for
-more complex and precise (but slower) binning strategy.
+The rebinning is done as a weighted sum of overlapping polygons.
+The polygon in :math:`Q-\Delta E` space is calculated from the
+energy bin boundaries and the detector scattering angle :math:`2\theta`.
+The detectors (pixels) are assumed to be uniform, and characterised
+by a single angular width :math:`\Delta2\theta`. The signal and error
+of the rebinned data (in :math:`Q-\Delta E` space) is then the
+sum of the contributing pixels in each bin weighted by their fractional
+overlap area. Unlike the more precise :ref:`algm-SofQWNormalisedPolygon`
+algorithm, these fractional weights are not thereafter retained in the
+workspace produced by this algorithm.
+
+See :ref:`algm-SofQWCentre` for centre-point binning.
+Alternatively, see :ref:`algm-SofQWNormalisedPolygon` for a
+more complex and precise (but slower) binning strategy, where the actual
+detector shape is calculated to obtain the input polygon.
 
 Usage
 -----

docs/source/concepts/Workspace2D.rst

@@ -22,6 +22,24 @@ histogram (with X,Y,E values) but preserves the underlying event data.
 For more information on what a Workspace2D contains, see 
 :ref:`MatrixWorkspace <MatrixWorkspace>`.
 
+There is also a specialised form of Workspace2D, called a RebinnedOutput
+which is produced by :ref:`algm-SofQWNormalisedPolygon`. In addition
+to the signal Y and error E values for each bin, it also carries the
+fractional weight F of the signal in the bin. This is needed to keep
+track of the portions of counts from bins in the original grid which has
+been put into the new (rebinned) grid. A more detailed explanation is
+given in the description of :ref:`algm-SofQWNormalisedPolygon`. 
+For correct handling of the fractional weights in rebinning, the user
+is recommended to use the :ref:`algm-Rebin2D` algorithm in preference
+to :ref:`algm-Integration` or :ref:`algm-SumSpectra` although the other
+algorithms do account for the fractional weights.
+
+.. warning:: Note, however, that all binary and unary operations on
+   workspaces will ignore the fractional weights. Thus it is important
+   to handle all background subtractions and scaling in the original
+   reduced dataset(s) **before** conversion using
+   :ref:`algm-SofQWNormalisedPolygon`.
+
 Working with Workspace2Ds in Python
 -----------------------------------
 

docs/source/release/v3.12.0/framework.rst

@@ -25,6 +25,8 @@ Algorithms
 Data Objects
 ------------
 
+A `bug <https://github.com/mantidproject/mantid/pull/20953>`_ in the handling of fractional bin weights in a specialised form (`RebinnedOutput <http://doxygen.mantidproject.org/nightly/d4/d31/classMantid_1_1DataObjects_1_1RebinnedOutput.html>`_) of :ref:`Workspace2D <Workspace2D>` has been fixed. This mainly affects the algorithms :ref:`algm-SofQWNormalisedPolygon` and :ref:`algm-Rebin2D`, which underlies the `SliceViewer <http://www.mantidproject.org/MantidPlot:_SliceViewer>`_.
+
 Python
 ------
 

docs/source/release/v3.12.0/spectroscopy.rst

@@ -12,7 +12,9 @@ Spectroscopy Changes
 Direct Geometry
 ---------------
 
+A `bug <https://github.com/mantidproject/mantid/pull/20953>`_ in the handling of workspaces with fractional bin weights (generated by :ref:`algm-SofQWNormalisedPolygon`) has been fixed.
+
 Indirect Geometry
 -----------------
 
-:ref:`Release 3.12.0 <v3.12.0>`
+:ref:`Release 3.12.0 <v3.12.0>`
\ No newline at end of file