Add algorithm for creating POLREF polarisation correction workspaces

[rbauststfc]

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.
2. Optional flood correction (same as the correction performed in the existing ISIS Reflectometry reduction). See ApplyFloodWorkspace does not always preserve values in missing spectra #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 ApplyFloodWorkspace does not always preserve values in missing spectra #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.
3. Optional background subtraction, using ReflectometryBackgroundSubtraction with the PerDetectorAverage method (should be the same as the correction performed in the existing ISIS Reflectometry reduction).
4. 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.

[rbauststfc]

I suggest that we create three new algorithms as follows:

• An algorithm that implements the Wildes calculations only, doing no pre or post-processing around that. This algorithm would output all of the values from the calculation as separate workspaces. Additional optional workspaces that are aimed at advanced users would be output if requested. This algorithm would be implemented in C++. Pulling these calculations into their own algorithm will break up the code and aid testing, as well as giving advanced users the flexibility to make use of the Wildes efficiency calculations as part of other workflows (if ever necessary).

• An algorithm that performs the optional pre-processing steps, so that this could be used in a bespoke script with the main calculation algorithm if necessary for testing new workflows.

• A wrapper workflow algorithm that calls the algorithm that performs the optional pre-processing steps for the mag and non-mag inputs, calls the calculation algorithm and then will join the efficiencies into a single workspace. This algorithm would also allow the diagnostic values to be output on request. I have opened issue Add wrapper algorithm for creating POLREF correction workspaces #38470 specifically to cover this. This workflow algorithm would be primarily designed to provide easy use for instrument scientists who are not familiar with working on POLREF. This would be written in Python and would expose the following properties:

For transmission workspace creation
NonMagInputRuns
MagInputRuns
ProcessingInstructions
MagProcessingInstructions (optional, only if different to non-mag)
I0MonitorIndex
MonitorIntegrationWavelengthMin
MonitorIntegrationWavelengthMax
FloodWorkspace
BackgroundProcessingInstructions
MagBackgroundProcessingInstructions (optional, only if different to non-mag)

Efficiency calculation inputs
Flippers
InputPolarizerEfficiency
InputAnalyserEfficiency

Output from JoinISISPolarizationEfficiencies
OutputWorkspace

Efficiency calculation diagnostic outputs
IncludeDiagnosticOutputs
OutputPhi
OutputRho
OutputAlpha
OutputTwoPMinusOne
OutputTwoAMinusOne