Merge pull request #19600 from mantidproject/19599_reflectometry_sum_in_Q_docs

Update docs for new option to sum in Q in RRO

docs/source/algorithms/ReflectometryReductionOne-v2.rst

@@ -9,8 +9,9 @@
 Description
 -----------
 
-This algorithm is not meant to be used directly by users. Please see :ref:`algm-ReflectometryReductionOneAuto`
-which is a facade over this algorithm.
+This algorithm is not meant to be used directly by users. Please see
+:ref:`algm-ReflectometryReductionOneAuto` which is a facade over this
+algorithm.
 
 This algorithm reduces a single reflectometry run into a mod Q vs I/I0 workspace.
 The mandatory input properties, :literal:`WavelengthMin`, :literal:`WavelengthMax`
@@ -31,30 +32,51 @@ steps taking place in the reduction.
 
 .. diagram:: ReflectometryReductionOne_HighLvl-v2_wkflw.dot
 
+First, the algorithm checks the X units of the input workspace. If the input
+workspace is already in wavelength, summation and normalization by monitors and
+direct beam are not performed, as it is considered that the input run was
+already reduced using this algorithm.
+
+If summation is to be done in wavelength, then this is done first. The the
+conversion to wavelength and normalisation by monitors and direct beam is done,
+followed by the transmission correction. Transmission correction is always
+done, even if the input was already in wavelength.
+
+If summation is to be done in Q, this is done after the normalisations, but
+again, only if the original input was not already in wavelength.
+
+Finally, the output workspace in wavelength is converted to momentum transfer
+(Q).
 
 Conversion to Wavelength
 ########################
 
-First, the algorithm checks the X units of
-the input workspace. If the input workspace is already in wavelength, normalization by
-monitors and direct beam are not performed, as it is considered that the input run was
-already reduced using this algorithm. If the input workspace is in TOF, monitors, detectors of
-interest and region of direct beam are extracted by running :ref:`algm-GroupDetectors` with
-``ProcessingInstructions`` as input, :ref:`algm-GroupDetectors` with ``RegionOfDirectBeam`` as input,
-and :ref:`algm-CropWorkspace` with ``I0MonitorIndex`` as input respectively, and each of
-the resulting workspaces is converted to wavelength (note that :literal:`AlignBins` is set
-to :literal:`True` in all the three cases). Note that the normalization by a direct beam
-is optional, and only happens if ``RegionOfDirectBeam`` is provided. In the same way,
-monitor normalization is also optional, and only takes place if ``I0MonitorIndex``,
-``MonitorBackgroundWavelengthMin`` and ``MonitorBackgroundWavelengthMax`` are all
-specified. Detectors can be normalized by integrated monitors by setting
+If the input workspace is in TOF, monitors are extracted using
+:ref:`algm-GroupDetectors` with ``RegionOfDirectBeam`` as input, and region of
+direct beam using :ref:`algm-CropWorkspace` with ``I0MonitorIndex`` as
+input. If summing in wavelength, detectors of interest are extracted and summed
+in TOF using :ref:`algm-GroupDetectors` with ``ProcessingInstructions`` as
+input. If summing in Q, summation is not done yet as it is done in a later step
+after all normalisations have been done.
+
+Each of the resulting workspaces is converted to wavelength (note that
+:literal:`AlignBins` is set to :literal:`True` in all the three cases). Note
+that the normalization by a direct beam is optional, and only happens if
+``RegionOfDirectBeam`` is provided. In the same way, monitor normalization is
+also optional, and only takes place if ``I0MonitorIndex``,
+``MonitorBackgroundWavelengthMin`` and ``MonitorBackgroundWavelengthMax`` are
+all specified.
+
+Detectors can be normalized by integrated monitors by setting
 :literal:`NormalizeByIntegratedMonitors` to true, in which case
-:literal:`MonitorIntegrationWavelengthMin` and :literal:`MonitorIntegrationWavelengthMax` are
-used as the integration range. If monitors are not integrated, detectors are rebinned to
-monitors using :ref:`algm-RebinToWorkspace` so that the normalization by monitors can take place.
-Finally, the resulting workspace is cropped in wavelength according to :literal:`WavelengthMin`
-and :literal:`WavelengthMax`, which are both mandatory properties. A summary of the steps
-is shown in the workflow diagram below. For the sake of clarity, all possible steps are illustrated, even if some of them are optional.
+:literal:`MonitorIntegrationWavelengthMin` and
+:literal:`MonitorIntegrationWavelengthMax` are used as the integration
+range. If monitors are not integrated, detectors are rebinned to monitors using
+:ref:`algm-RebinToWorkspace` so that the normalization by monitors can take
+place.
+
+A summary of the steps is shown in the workflow diagram below. For the sake of
+clarity, all possible steps are illustrated, even if some of them are optional.
 
 .. diagram:: ReflectometryReductionOne_ConvertToWavelength-v2_wkflw.dot
 
@@ -98,12 +120,32 @@ property. If the :literal:`CorrectionAlgorithm` property is set to
 algorithm is used, with *C0* and *C1* taken from the :literal:`C0` and :literal:`C1`
 properties.
 
+Sum in Q and crop
+#################
+
+If summing in Q, the summation is done now, after all normalisations have been
+done. The summation is done using the algorithm proposed by Cubitt et al
+(J. Appl. Crystallogr., 48 (6) (2015)). This involves a projection to an
+arbitrary reference angle, :math:`2\theta_R`, with a "virtual" wavelength,
+:math:`\lambda_v`. This is the wavelength the neutron would have had if it had
+arrived at :math:`2\theta_R` with the same momentum transfer
+(:math:`Q`). Counts are shared out proportionally into the output array in
+:math:`\lambda_v` and the projections from all pixels are summed in
+:math:`\lambda_v`.
+
+In all cases, the 1D array in :math:`\lambda` is then cropped in wavelength
+according to :literal:`WavelengthMin` and :literal:`WavelengthMax`, which are
+both mandatory properties.
+
+.. diagram:: ReflectometryReductionOne_SumInQ-v2_wkflw.dot
+
 Conversion to Momentum Transfer (Q)
 ###################################
 
-Finally, the output workspace in wavelength is converted to momentum transfer (Q) using
-:ref:`algm-ConvertUnits`. Note that the output workspace in Q is therefore a workspace
-with native binning, and no rebin step is applied to it.
+Finally, the output workspace in wavelength is converted to momentum transfer
+(:math:`Q`) using :ref:`algm-ConvertUnits`. Note that the output workspace in Q
+is therefore a workspace with native binning, and no rebin step is applied to
+it.
 
 .. diagram:: ReflectometryReductionOne_ConvertToMomentum-v2_wkflw.dot
 

docs/source/diagrams/ReflectometryReductionOne_ConvertToMomentum-v2_wkflw.dot

@@ -4,8 +4,8 @@ label = "\n"
 
 subgraph params {
  $param_style
-  inputWorkspace    [label="OutputWorkspaceWavelength", group=g1]
-  outputWorkspace   [label="OutputWorkspace"]
+  inputWorkspace     [label="OutputWorkspaceWavelength", group=g1]
+  outputWorkspace    [label="OutputWorkspace"]
 }
 
 subgraph decisions {
@@ -25,6 +25,8 @@ subgraph values {
  $value_style
 }
 
-inputWorkspace    -> convertUnits
-convertUnits      ->  outputWorkspace
+inputWorkspace     -> convertUnits
+convertUnits       ->  outputWorkspace
+
 }
+

docs/source/diagrams/ReflectometryReductionOne_ConvertToWavelength-v2_wkflw.dot

@@ -9,8 +9,6 @@ subgraph params {
   inputWS             [label="InputWorkspace"]
   outputWS            [label="OutputWorkspaceWavelength"]
   procCommands        [label="ProcessingInstructions"]
-  wavMin              [label="WavelengthMin", group=gwav]
-  wavMax              [label="WavelengthMax", group=gwav]
   monitorIndex        [label="I0MonitorIndex"]
   regionOfDirectBeam  [label="RegionOf-\nDirectBeam"]
   monIntWavMax        [label="MonitorIntegration-\nWavelengthMax"]
@@ -21,6 +19,7 @@ subgraph params {
 
 subgraph decisions {
  $decision_style
+  checkSumInLam   [label="Sum in λ?"]
 }
 
 subgraph algorithms {
@@ -35,7 +34,6 @@ subgraph algorithms {
   groupDetRDB   [label="GroupDetectors"]
   divideDetMon  [label="Divide\n(Detectors / Monitors)", group=g1]
   divideDetRDB  [label="Divide\n(Detectors / DirectBeam)", group=g1]
-  cropWav       [label="CropWorkspace", group=g1]
 }
 
 subgraph processes {
@@ -46,21 +44,24 @@ subgraph values {
  $value_style
 }
 
-inputWS				-> groupDet			[label="Detectors"]
-inputWS				-> groupDetRDB		[label="Direct Beam"]
-inputWS				-> cropMonWS		[label="Monitors"]
+inputWS			-> checkSumInLam	[label="Detectors"]
+inputWS			-> groupDetRDB		[label="Direct Beam"]
+inputWS			-> cropMonWS		[label="Monitors"]
+
+checkSumInLam           -> convertDet [label="No"]
+checkSumInLam           -> groupDet   [label="Yes"]
+groupDet		-> convertDet
 
 procCommands		-> groupDet
-groupDet			-> convertDet
 
 regionOfDirectBeam	-> groupDetRDB
-groupDetRDB			-> convertDB
+groupDetRDB		-> convertDB
 
 monitorIndex		-> cropMonWS
-cropMonWS			-> convertMon
+cropMonWS		-> convertMon
 
-convertDet			-> divideDetRDB
-convertDB			-> divideDetRDB
+convertDet		-> divideDetRDB
+convertDB		-> divideDetRDB
 
 convertMon          -> calcFlatBg
 monBackWavMin       -> calcFlatBg
@@ -71,10 +72,8 @@ monIntWavMax        -> intMon
 
 divideDetRDB        -> divideDetMon
 intMon              -> divideDetMon
-wavMin              -> cropWav
-divideDetMon        -> cropWav
-wavMax              -> cropWav
-cropWav             -> outputWS
+
+divideDetMon        -> outputWS
 
 {rank=same; groupDet; groupDetRDB; cropMonWS}
 {rank=same; convertDet; convertDB; convertMon}

docs/source/diagrams/ReflectometryReductionOne_HighLvl-v2_wkflw.dot

@@ -20,8 +20,9 @@ subgraph algorithms {
 
 subgraph processes {
  $process_style
-  convertUnits    [label="Convert to λ and\nnormalize\nby monitors"]
+  convertUnits    [label="Convert to λ,\noptionally sum in λ, and\nnormalize by monitors"]
   applyCorrTrans  [label="Apply transmission\n corrections"]
+  sumInQ          [label="Optionally sum in Q,\nand crop"]
   convertMom      [label="Convert to momentum\ntransfer"]
 }
 
@@ -33,7 +34,9 @@ inputWS         -> checkXUnit
 checkXUnit      -> applyCorrTrans [label="Yes"]
 checkXUnit      -> convertUnits   [label="No"]
 convertUnits    -> applyCorrTrans
-applyCorrTrans  -> outputWSWL
+
+applyCorrTrans  -> sumInQ
+sumInQ          -> outputWSWL
 
 outputWSWL      -> convertMom
 convertMom      -> outputWSFinal

docs/source/diagrams/ReflectometryReductionOne_SumInQ-v2_wkflw.dot

+digraph ReflectometryReductionOne {
+label = "\n"
+ $global_style
+
+subgraph params {
+ $param_style
+  inputWorkspace     [label="OutputWorkspaceWavelength", group=g1]
+  outputWorkspaceWav [label="OutputWorkspaceWavelength"]
+  wavMin             [label="WavelengthMin", group=gwav]
+  wavMax             [label="WavelengthMax", group=gwav]
+}
+
+subgraph decisions {
+ $decision_style
+  checkSumInQ        [label="Sum in Q?"]
+}
+
+subgraph algorithms {
+ $algorithm_style
+  cropWav           [label="CropWorkspace"]
+}
+
+subgraph processes {
+ $process_style
+  projectCounts      [label=<Project input counts to &lambda;<sub>v</sub> at 2&theta;<sub>R</sub>>]
+  sumInQ             [label=<Sum in &lambda;<sub>v</sub>>]
+}
+
+subgraph values {
+ $value_style
+}
+
+inputWorkspace     -> checkSumInQ
+checkSumInQ        -> projectCounts      [label="Yes"]
+checkSumInQ        -> cropWav            [label="No"]
+projectCounts      -> sumInQ
+sumInQ             -> cropWav
+wavMin             -> cropWav
+wavMax             -> cropWav
+cropWav            -> outputWorkspaceWav
+
+}
+