Polarised SANS workflow

[gemmaguest]

Initial investigaton done, requirements still need to be fully specified. See comments below.

[smk78]

Dirk (@dehoni) comments via email (09/03/2021 to @DavidFair, @smk78, & Diego):

As a discussion starter for a project to implement polarised SANS in Mantid, here is also a document https://stfc365-my.sharepoint.com/:w:/g/personal/dirk_honecker_stfc_ac_uk/Eb5G595cOwVKqvJJByUpL2EBu-PUyZhuMXt2rf5YTiXs9Q
With a further description. It should summarize the requirements and steps that a polarisation correction for SANS might involve. It covers different polarised mode like SANSPOL (only polarised incoming beam no analysis after sample), full longitudinal polarisation analysis (PA) with a 3He gas analyser and a simplified PA for certain sample systems. The document might be overly detailed and based on first principles potentially reproducing what already exists in Mantid. There is certainly comparable work on other techniques, to simplify the task and not reinvent the wheel.

[smk78]

TO NOTE: The above document does not explicitly consider SESANS. Since this is also a polarised SANS technique, it might be prudent to include this in any project scoping.

[smk78]

Where this discussion leads us is towards a (near) future where there will be at least 3 SANS reduction workflows:

• SANS; this is what already exists in Mantid
• SESANS
• Pol-SANS

SESANS is currently reduced using scripts devised by @rprospero , but it is desirable for Users to be able to use an interface as they do for SANS. The functionality of this interface is not so different to that of the current ISIS SANS interface, as in, there are still sample and can runs and there are still transmission runs. What changes is how you process those runs. The existing scripts, however, may need unpicking to incorporate them into the Mantid codebase.

Pol-SANS will require a greater degree of functionality conferred on the existing SANS interface to support the more involved reduction workflow outlined in the document above.

Talking to @rmdalgliesh there would seem to be a preference to have a single SANS interface - rather than a separate SANS interface, a SESANS interface, and a Pol-SANS interface - but with functionality included/removed as befits the type of measurement. Talking to @DavidFair a logical and extensible way of accomplishing this would be to introduce a new key in the new TOML User Files, for example:

[instrument]
reduction_type = string  #where string = "SANS" / "SESANS" / "POLSANS"

This approach could, in the (further) future, then be extended to Focussing-SANS (which is outside the scope of this issue).

[DavidFair]

On the reduction side it looks fairly simple the workflow would need to be adapted like so:

• Normalise by incident beam
• Normalise by transmission
• Convert to wavelength (for both cases)
• Normalise by supermirror / H3 cell.
• Rest of the reduction

For the super mirror we simply need to use a calibration run
For the H3 cell we fit the measured polarisation (which is captured multiple times), using ExpDecay for the function pHe(t) = pHe(t0) * exp(-t+t0/y), where y the relaxation time of the gas (this might need to be a user input, or an inst parameter depending how constant it is).
We then normalise by the value at t/2 and our wavelength data.

From a UX point of view it might be worth having the multiple runs encapsulated in a separate page, rather than cluttering the main table.
But I like Steve's idea to toggle between "Normal" SANS, Half polarised and Full Polarisation modes in the main interface above the runs table since it makes it trivial to see which mode were operating in without adding clutter.

[stale]

This issue has been automatically marked as stale because it has not had activity in 6 months. It will be closed in 7 days if no further activity occurs.
Allowing issues to close as stale helps us filter out issues which can wait for future development time. All issues closed by stale bot act like normal issues; they can be searched for, commented on or reopened at any point.
If you'd like a closed stale issue to be considered, feel free to either re-open the issue directly or contact a developer.
To extend the lifetime of an issue please comment below, it helps us see that this is still affecting you and you want it fixed in the near-future. Extending the lifetime of an issue may cause the development team to prioritise it over other issues, which may be closed as stale instead.

[dehoni]

The attached file 3HeMantidDataReduction_BetaVersion1D+2D_ZOOM+Larmor_combined_normalised.py.txt is a python script that contains two main parts: 1) polarisation_parameter(), which extract the polarisation parameters of the beamline (flipper, and polariser) and of the analyser cell and calc_3He_parameters() fitting the time dependence of the analysing power in case, one uses a 3He analyser for polarisation analysis.
2) Creating wavelength slices, performing (wavelength dependent) polarisation corrections of the 4 spin-resolved states with reduction matrixes, and merging data back together.
The reduction is set up for Larmor and Zoom, and one can choose either correction of the 2D detector images or 1D scattering cross section. For the beamtime on Larmor-as the instrument does not have a beamstop monitor unlike ZOOM- we measured the attenuated, direct beam on the detector. The user only has to set up the correct list for transmission measurements through the 3He cell over the time, depolarised 3He cell to obtain the opaqueness of the 3He cell, empty direct beam and transmission/absorption of sample for normalisation, and -of course- scattering measurements.
Parameters like which monitor to use, and usable wavelength range should be ideally extracted from the user file, but I could not quite figure out how MANTID is doing it behind the scenes.
In general the code needs further cleanup and generalisation, a lot of the comments are related to me puzzling how MANTID works. There are several comments in the code where issues or future features are mentioned. I am sure there are more elegant ways than this crude patchy script, but it is a stumbling start.
ISISCommandInterface_tweaked.py.txt
Half-polarised SANS (with only incoming polarised beam) would use a similiar reduction without the additional calculations and matrixes for the 3He analyser appended.

[stale]

This issue has been automatically marked as stale because it has not had activity in 6 months. It will be closed in 7 days if no further activity occurs.
Allowing issues to close as stale helps us filter out issues which can wait for future development time. All issues closed by stale bot act like normal issues; they can be searched for, commented on or reopened at any point.
If you'd like a closed stale issue to be considered, feel free to either re-open the issue directly or contact a developer.
To extend the lifetime of an issue please comment below, it helps us see that this is still affecting you and you want it fixed in the near-future. Extending the lifetime of an issue may cause the development team to prioritise it over other issues, which may be closed as stale instead.

[dehoni]

The updated overview document for Polarization Analysis of TOF SANS contains now a basic workflow, with detailed function descriptions and some code examples in https://stfc365-my.sharepoint.com/:w:/g/personal/dirk_honecker_stfc_ac_uk/Eb5G595cOwVKqvJJByUpL2EBu-PUyZhuMXt2rf5YTiXs9Q?e=hii03t
The general workflow scheme consists of two separate parts: Part A:calibration of the instrument polarisation (polariser, flipper, 3He gas polarisation, and automatic finding and assigning in which order the spin states were measured), and Part B: Polarisation correction on spin-resolved scattering data from a sample.
The code is a first start needing some more work. The goal would be to have a code documentation with nicely isolated testable functions with expected input and output and finally to transform the hacked script into sustainable algorithms in Mantid.

[rbauststfc]

The epic for implementing a Polarised SANS reduction has now been approved. The following are individual issues to capture the steps described in the epic. We will need to add details to these as part of requirements gathering and it may be that some issues are combined or removed as implementation decisions take shape:

• New math functions required for hyperbolic trigonometry #36137
• Algorithm required for labelling spin states of run periods #36138
• Algorithm required for calculating efficiency of ISIS SANS polariser #36139
• Algorithm required for calculating ISIS SANS analyser efficiencies #36140
• Algorithm required for calculating transmission of the analyser #36383
• Add algorithm to extract time dependency of analyser polarised efficiency algorithm #36142
• Algorithm required for interpolating the efficiency wavelength dependence #36143
• Algorithm required to calculate the efficiency of the ISIS SANS spin flipper #36144
• Algorithm required to calculate the position-dependent efficiency on the detector #36145
• Extend PolarizationCorrectionWildes to support Polarised SANS reduction at ISIS #36146
• Alter WavRangeReduction algorithm to take a Mantid workspace #35875
• Modify existing output save formats to include Polarised SANS reduction outputs #36147
• Create wrapper algorithm for Polarised SANS reduction at ISIS #36148

[github-actions]

This issue has been automatically marked as stale because it has not had activity in 6 months. It will be closed in 7 days if no further activity occurs.
Allowing issues to close as stale helps us filter out issues which can wait for future development time. All issues closed by stale bot act like normal issues; they can be searched for, commented on or reopened at any point.
If you'd like a closed stale issue to be considered, feel free to either re-open the issue directly or contact a developer.
To extend the lifetime of an issue please comment below, it helps us see that this is still affecting you and you want it fixed in the near-future. Extending the lifetime of an issue may cause the development team to prioritise it over other issues, which may be closed as stale instead.