Add algorithm for creating POLREF polarisation correction workspaces

POLREF need to apply a polarisation correction as part of their reduction. One way they do this is by producing a workspace with the required efficiency factors. At the moment only Andrew and Christy know how to produce this workspace, so the group is keen for us to provide an algorithm in Mantid that can do this.

The documentation for this algorithm should make it transparent to users what the algorithm is doing.

This is part of the Polarised Reflectivity epic.

Requirements:

Calibration runs

The efficiency factors are calculated as per the Wildes 2006 paper (calibrating an instrument with flippers). Two calibration runs are taken with four periods each:

non-magnetic, where the corrected ++ counts and corrected -- counts will be the same.
magnetic, where the corrected ++ counts and corrected -- counts will not be equal.

These runs need to go through the following initial steps before they can be used to calculate the efficiencies:

1) Usually, multiple transmission runs will be taken (because POLREF save out data every hour to avoid needing to start a measurement from scratch in case of any issues) and these need to be summed (all the spectra and the monitors) as part of the loading step. It's rare for the transmission measurement to be taken as a single run. This means the algorithm will need to take a list of mag and non-mag calibration run numbers. 1) Optional flood correction (same as the correction performed in the existing ISIS Reflectometry reduction). See #38393 for details of a bug with the ApplyFloodWorkspace algorithm that is worth being aware of because POLREF have previously saved their flood files with multiple bins. Following discussion with Andrew, we agreed that the pre-processing step should take the flood workspace as an input and just pass it straight through to ApplyFloodWorkspace without doing anything to it. This would have the advantage that once we fix #38393 then there is the option of passing in a flood workspace with any number of bins. Andrew will create their flood workspaces with the Mantid CreateFloodWorkspace algorithm going forward to create single bin flood files as standard. 1) Optional background subtraction, using ReflectometryBackgroundSubtraction with the PerDetectorAverage method (should be the same as the correction performed in the existing ISIS Reflectometry reduction). 1) Create the transmission workspace using CreateTransmissionWorkspaceAuto.

These steps can be seen in Andrew's code in function transmission in POLREF_Red/WrappedReduction.py. Note that there is a step that moves instrument components that Andrew does not believe is required. We should implement without this initially, but test carefully to ensure it really is not making a difference to the calculated values.

Calculating the efficiencies:

Once the non-magnetic and magnetic transmission workspaces have been created, they can be used to calculate the efficiencies as follows (see Wildes paper for exact details):

Calculate $\phi$, $f_p$ (polarizing flipper efficiency) and $f_a$ (analysing flipper efficiency) using the non-magnetic transmission intensities (eqtn.s 11 in the paper).
Use these calculated values and the magnetic transmission intensities to calculate $(2p-1)^2$ (eqtn. 12 in the paper). Then, from this, solve for $p$, the polarizer efficiency.
Given $\phi$ and $p$, we can solve for the analyser efficiency as follows: $a =$ ($\phi/(2p-1)+1)/2$
We can also calculate two other relationships: $\rho=2f_p - 1$ and $\alpha=2f_a - 1$.

The relevant calculations are implemented in Andrew's code in POLREF_Red/polarisation_module.py. Note that he includes a step that multiples through by a workspace of ones, which was a workaround he found was needed at the time for adding and subtracting Mantid workspaces, but is not required for the maths itself.

Input parameters:

We need to expose all the parameters required for pre-processing of the transmission run(s). See transmission function in POLREF_Red/WrappedReduction.py in Andrew's private repo, but only the run numbers, ROI and flood parameters from that function are relevant. We will also need to include an ROI parameter for the background subtraction.

The non-magnetic transmission run is the only mandatory input for the efficiency calculation. There are certain circumstances where efficiencies may already have been calculated from a previous magnetic run and so re-calculating these can be skipped. All existing flexibility that exists in Andrew's code (see POLREF_Red/polarisation_module.py in his private repo) should be retained. This should include making the magnetic transmission run optional.

Required outputs:

The efficiency factors required to pass into PolarizationCorrectionWildes are $p$, $a$, $f_p$ and $f_a$. These need to be passed in as an efficiencies workspace, which can be created using the JoinISISPolarizationEfficiencies algorithm. Values $\phi$, $\rho$, $\alpha$, $(2p-1)$ (check if this is Fredrikze $P_p$) and $(2a-1)$ (check if this is Fredrikze $A_p$) are not required for the Wildes correction, but can be useful for experienced instrument scientists to plot for diagnostic purposes. The values $\rho$, $\alpha$ (and possibly $(2p-1)$ and $(2a-1)$ ) may also be useful for those who want to perform, or are more familiar with, the Fredrikze correction.

So the following output options are required:

Output the four required efficiency factors, with a choice over outputting as individual workspaces or as a single combined workspace. This will give instrument scientists more flexibility, particularly for performing diagnostics, while providing a straightforward method of producing the efficiency workspace required for the NR GUI reduction (useful for less advanced users of the algorithm).
Optionally output $\phi$, $\rho$, $\alpha$, $(2p-1)$ and $(2a-1)$ as single workspaces so that advanced users can access this information.

POLREF instrument scientists are intending to use the algorithm in Mantid only periodically, as they prefer to stick with their own implementation. The algorithm would therefore mainly be for use by instrument scientists that are less experienced with POLREF.

Error calculations:

At the moment the errors in Andrew's code are being calculated automatically using the default approach within Mantid, which is expected to over-estimate them. The scientists are not yet in a position to supply the correct error calculations, so for this first version of the algorithm we have agreed that we will continue to use the default Mantid errors. This will make validation against Andrew's existing code a little easier. A separate issue should be opened to improve the error calculation as a future task.

Testing and validation:

Andrew will provide some calibration run numbers and some example output calculated efficiencies for us to test against during development. When the first/draft version of the algorithm is ready, Andrew will be able to validate the outputs against his code.

mantidproject / mantid

Add algorithm for creating POLREF polarisation correction workspaces #35682

Requirements: