Add multiple scattering correction to OSIRIS script

[MohamedAlmaki]

Description of work
This PR adds multiple scattering corrections to the OSIRIS Diffraction script.
Purpose of work

The aim of the work is to improve the current script's functionality.

Summary of work

Multiple scattering has been added to the OSIRIS script.

Further detail of work

DiscusMultipleScatteringCorrection has been added to the OSIRIS script. To enable it you need to set the multiple_scattering parameter to True. In addition, algorithm parameters NeutronPathsSingle and NeutronPathsMultiple has been added to the script. An example of how to use the multiple scattering scattering

osiris_focus.create_vanadium(run_number="120033")

osiris_focus.focus(run_number="120033",
    merge_drange=True,
    vanadium_normalisation=True,
    absorb_corrections=True,
    empty_can_subtraction_method="Simple",
    multiple_scattering=True
)

To test:
Make sure the following script works fine:

from mantid.simpleapi import *
import matplotlib.pyplot as plt
import numpy as np
from isis_powder.osiris import Osiris
from isis_powder import SampleDetails

osiris_focus = Osiris(user_name="Calib",
                  output_directory=r"\osiris\OsirisCalibrationFiles\output",
                  config_file=r"\osiris\OsirisCalibrationFiles\Config.yaml",
                  calibration_directory=r"\osiris\OsirisCalibrationFiles\Calibration_files",
                  calibration_mapping_file=r"\osiris\OsirisCalibrationFiles\Calibration_files\osiris_run_mapping.yaml"
)

sample_details = SampleDetails(radius=1.1, height=8, center=[0, 0, 0], shape='cylinder')
sample_details.set_material(chemical_formula='Cr2-Ga-N', number_density=10.0)
sample_details.set_container(
    chemical_formula='Al',
    mass_density=2.7,
    radius=1.2
)

osiris_focus.set_sample_details(sample=sample_details)

osiris_focus.create_vanadium(run_number="120033")

osiris_focus.focus(run_number="120033",
    absorb_corrections=True,
    empty_can_subtraction_method="Simple",
    paalman_pings_events_per_point=1000,
    sample_details=sample_details,
    multiple_scattering=True,
    simple_events_per_point=100,
    neutron_paths_single=5,
    neutron_paths_multiple=5,
)

Contact me for configuration files. Also, make sure you update the directories in the script with paths in your local machine.

Fixes #35430.

---

Reviewer

Please comment on the points listed below (full description).
Your comments will be used as part of the gatekeeper process, so please comment clearly on what you have checked during your review. If changes are made to the PR during the review process then your final comment will be the most important for gatekeepers. In this comment you should make it clear why any earlier review is still valid, or confirm that all requested changes have been addressed.

Code Review

• Is the code of an acceptable quality?
• Does the code conform to the coding standards?
• Are the unit tests small and test the class in isolation?
• If there is GUI work does it follow the GUI standards?
• If there are changes in the release notes then do they describe the changes appropriately?
• Are the release notes saved in a separate file, using Issue or PR number for file name and in the correct location?

Functional Tests

• Do changes function as described? Add comments below that describe the tests performed?
• Do the changes handle unexpected situations, e.g. bad input?
• Has the relevant (user and developer) documentation been added/updated?

Does everything look good? Mark the review as Approve. A member of @mantidproject/gatekeepers will take care of it.

Gatekeeper

If you need to request changes to a PR then please add a comment and set the review status to "Request changes". This will stop the PR from showing up in the list for other gatekeepers.

[AnthonyLim23]

I got the following error:

Known keys are:
----------------------------------
absorb_corrections, calibration_directory, calibration_mapping_file, config_file, dat_files_directory, dspacing_xye_filename, empty_can_subtraction_method, file_ext, grouping_filename, gss_filename, keep_raw_workspace, mayers_mult_scat_events, merge_drange, multiple_scattering, neutron_paths_multiple, neutron_paths_single, nxs_filename, output_directory, paalman_pings_events_per_point, run_number, sample_empty_scale, simple_events_per_point, subtract_empty_can, suffix, tof_xye_filename, user_name, vanadium_normalisation, xye_filename, 
----------------------------------
ValueError: Unknown configuration key: sample_details

[AnthonyLim23]

@MialLewis feel free to approve this once you are happy with it

[AnthonyLim23]

@RichardWaiteSTFC if I remove the sample_details=sample_details, from the example script this runs fine, is that expected? The corrections look to be a bunch of straight lines, is this what we expect?

[RichardWaiteSTFC]

@RichardWaiteSTFC if I remove the sample_details=sample_details, from the example script this runs fine, is that expected? The corrections look to be a bunch of straight lines, is this what we expect?

Probably, so without the sample details it cannot actually perform the attenuation corrections - even though you have set absorb_corrections=True - I would like it to at least print something to the log as a warning to let users know the corrections haven't been performed, but I wouldn't be surprised if it didn't...
it's worth checking in the workspace history that the absorption correction algorithm (in this case PaalmanPingsMonteCarloAbsorption I think?) hasn't been run.
I've noticed that in these scripts the user can supply arguments that are not relevant or unused without warning or error. I think long-term it needs addressing but it's a wider issue than this PR I think!

[AnthonyLim23]

@RichardWaiteSTFC if I remove the sample_details=sample_details, from the example script this runs fine, is that expected? The corrections look to be a bunch of straight lines, is this what we expect?

Probably, so without the sample details it cannot actually perform the attenuation corrections - even though you have set absorb_corrections=True - I would like it to at least print something to the log as a warning to let users know the corrections haven't been performed, but I wouldn't be surprised if it didn't... it's worth checking in the workspace history that the absorption correction algorithm (in this case PaalmanPingsMonteCarloAbsorption I think?) hasn't been run. I've noticed that in these scripts the user can supply arguments that are not relevant or unused without warning or error. I think long-term it needs addressing but it's a wider issue than this PR I think!

I cannot see any reference to absorption in the history. So thats good.

How would I change the script to run the correction? If I add the sample_details=sample_details, arg it just gives me an error

Known keys are:
----------------------------------
absorb_corrections, calibration_directory, calibration_mapping_file, config_file, dat_files_directory, dspacing_xye_filename, empty_can_subtraction_method, file_ext, grouping_filename, gss_filename, keep_raw_workspace, mayers_mult_scat_events, merge_drange, multiple_scattering, neutron_paths_multiple, neutron_paths_single, nxs_filename, output_directory, paalman_pings_events_per_point, run_number, sample_empty_scale, simple_events_per_point, subtract_empty_can, suffix, tof_xye_filename, user_name, vanadium_normalisation, xye_filename, 
----------------------------------
ValueError: Unknown configuration key: sample_details

[RichardWaiteSTFC]

Ah I see, I think you need to call instrument.set_sample_details - for example for POLARIS

sample_details = SampleDetails(height=4.0, radius=0.2985, center=[0, 0, 0], shape='cylinder')
sample_details.set_material(chemical_formula='Si', packing_fraction=0.6)
polaris.set_sample_details(sample=sample_details)

[AnthonyLim23]

the script already has that

from mantid.simpleapi import *
import matplotlib.pyplot as plt
import numpy as np
from isis_powder.osiris import Osiris
from isis_powder import SampleDetails

osiris_focus = Osiris(user_name="Calib",
                  output_directory=r"C:\Users\BTR75544\Downloads\OsirisCalibrationFiles (3)\OsirisCalibrationFiles\output",
                  config_file=r"C:\Users\BTR75544\Downloads\OsirisCalibrationFiles (3)\OsirisCalibrationFiles\Config.yaml",
                  calibration_directory=r"C:\Users\BTR75544\Downloads\OsirisCalibrationFiles (3)\OsirisCalibrationFiles\Calibration_files",
                  calibration_mapping_file=r"C:\Users\BTR75544\Downloads\OsirisCalibrationFiles (3)\OsirisCalibrationFiles\Calibration_files\osiris_run_mapping.yaml"
)

sample_details = SampleDetails(radius=1.1, height=8, center=[0, 0, 0], shape='cylinder')
sample_details.set_material(chemical_formula='Cr2-Ga-N', number_density=10.0)
sample_details.set_container(
    chemical_formula='Al',
    number_density=2.7,
    radius=1.2
)

osiris_focus.set_sample_details(sample=sample_details)

osiris_focus.create_vanadium(run_number="120033")
osiris_focus.focus(run_number="120033",
    absorb_corrections=True,
    empty_can_subtraction_method="Simple",
    paalman_pings_events_per_point=1000,
    multiple_scattering=True,
    simple_events_per_point=100,
    neutron_paths_single=5,
    neutron_paths_multiple=5,
)

It does seem to be calculating something with 100 scattering points. How do I know it did the correction?

[RichardWaiteSTFC]

Was testing with @AnthonyLim23 - he found this error thrown when focusing with absorb_corrections=True - but no sample set.

AttributeError: 'NoneType' object has no attribute 'generate_container_geometry'
  File "<string>", line 30, in <module>
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\osiris.py", line 86, in focus
    processed = self._focus(
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\osiris.py", line 140, in _focus
    return focus.focus(
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\routines\focus.py", line 40, in focus
    return _batched_run_focusing(
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\routines\focus.py", line 291, in _batched_run_focusing
    focused_ws = _focus_one_ws(
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\routines\focus.py", line 85, in _focus_one_ws
    input_workspace = _absorb_and_empty_corrections(
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\routines\focus.py", line 183, in _absorb_and_empty_corrections
    input_workspace = instrument._apply_absorb_corrections(run_details=run_details, ws_to_correct=input_workspace)
  File "C:\Users\BTR75544\work\conda\mantid\scripts\Diffraction\isis_powder\osiris.py", line 192, in _apply_absorb_corrections
    container_geometry = self._sample_details.generate_container_geometry()

It looks like an issue with this bit of code

mantid/scripts/Diffraction/isis_powder/routines/focus.py

Lines 182 to 191 in 28d9c3c

	if absorb:
	input_workspace = instrument._apply_absorb_corrections(run_details=run_details, ws_to_correct=input_workspace)
	else:
	# Set sample material if specified by the user
	if sample_details is not None:
	mantid.SetSample(
	InputWorkspace=input_workspace,
	Geometry=sample_details.generate_sample_geometry(),
	Material=sample_details.generate_sample_material(),
	)

There needs to be a check here (or higher up) that the sample is set if when absorb is True

Also the attenuation looks pretty high because the number densities are very high! Remember that sample number density is in units number of formula units per cubic angstrom. So for example Al is an FCC crystal so has 4 atoms in a cubic unit cell with length a=4.04 Ang so the number density is 4/(4.04^3) = 0.0607 ish. Check the numbers, but you see it's a few orders of magnitude less than the numbers in your script!

[MohamedAlmaki]

Also the attenuation looks pretty high because the number densities are very high! Remember that sample number density is in units number of formula units per cubic angstrom. So for example Al is an FCC crystal so has 4 atoms in a cubic unit cell with length a=4.04 Ang so the number density is 4/(4.04^3) = 0.0607 ish. Check the numbers, but you see it's a few orders of magnitude less than the numbers in your script!

Thanks, I wasn't aware of that. Some parts of the script were written by Spencer. What do you think? @SpencerHowells
What are the reasonable values for the number densities?

[SpencerHowells]

@MohamedAlmaki In your test instructions, for Al you have number_density=2.71 You should have mass_density=2.71 I assume that the same applies for the sample.

[AnthonyLim23]

Looks good to me

[RichardWaiteSTFC]

Sorry bit late to this, but why is the check on the sample being defined only done on OSIRIS?

[MohamedAlmaki]

It has been agreed to open an issue for the check as it is not a regression issue. issue raised here #36017