Enable user defined sample and container geometry for abs correction

[Kvieta1990]

Description of work

Summary of work

With this PR, we enable user defined sample and container geometry for absorption correction. Top level changes are in place for SNSPowderReduction and accordingly necessary parameters are introduced for those bottom level algorithms concerning the setup of the absorption correction inputs. The defined sample and container geometry is finally passed to SetSample. This gives users the flexibility to define their own geometry as needed. For example, on POWGEN, some times irregular containers that are not defined in the sample environment XML file will be used for the measurement, e.g., the annular container where the sample is loaded into the hollow cylinder wall.

Also, we implement the definition of beam gauge volume for absorption correction. Without this implementation, the assumption would be that the beam size is the same as the sample size. In practice, this is often not true. In that case, the absorption correction is imperfect in principle. Detailed discussion about this is posted here.

To test:

This is the one for testing the gauge volume definition

from mantid.simpleapi import *

gauge_vol = '''<cuboid id="shape">
     <left-front-bottom-point x="0.01" y="-0.1" z="0.0"  />
     <left-front-top-point  x="0.01" y="-0.1" z="0.02"  />
     <left-back-bottom-point  x="-0.01" y="-0.1" z="0.0"  />
     <right-front-bottom-point  x="0.01" y="0.1" z="0.0"  />
   </cuboid>'''

SNSPowderReduction(
    Filename='/SNS/PG3/IPTS-34523/nexus/PG3_58812.nxs.h5',
    CalibrationFile='/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_OC_d58772_2025-02-12.h5',
    CharacterizationRunsFile='/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_char_2025_2-HighRes_OC.txt,/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_char_2025_2_OC_limit.txt',
    RemovePromptPulseWidth=50,
    Binning='-0.0008',
    BackgroundSmoothParams='5, 2',
    FilterBadPulses=90,
    ScaleData=100,
    TypeOfCorrection='SampleAndContainer',
    SampleFormula='Ba-Nb-Cr-Ru',
    MeasuredMassDensity='6.0',
    SampleGeometry={'Height': 5},
    SampleNumberDensity='0.088',
    ContainerShape='PAC06',
    GaugeVolume=gauge_vol,
    SaveAs='gsas topas and fullprof',
    OutputDirectory='/SNS/NOM/shared/tmp',
    CacheDir='/SNS/NOM/shared/tmp'
)

Here is the one for testing the geometry definition,

from mantid.simpleapi import *

sam_geo = {
    'Shape': 'HollowCylinder', 'Height': 4.0,
    'InnerRadius': 2.0,
    'OuterRadius': 3.0,
    'Center': [0.,0.,0.]
}

c_geo = {
    'Shape': 'HollowCylinderHolder',
    'Height': 4.0,
    'InnerRadius': 1.5,
    'InnerOuterRadius': 2.0,
    'OuterInnerRadius': 3.0,
    'OuterRadius': 4.0,
    'Center': [0.,0.,0.]
}

c_mat = {
    'ChemicalFormula': 'V',
    'NumberDensity': 0.072324
}

gauge_vol = '''<cuboid id="shape">
     <left-front-bottom-point x="0.01" y="-0.1" z="0.0"  />
     <left-front-top-point  x="0.01" y="-0.1" z="0.02"  />
     <left-back-bottom-point  x="-0.01" y="-0.1" z="0.0"  />
     <right-front-bottom-point  x="0.01" y="0.1" z="0.0"  />
   </cuboid>'''

SNSPowderReduction(
    Filename='/SNS/PG3/IPTS-34523/nexus/PG3_58812.nxs.h5',
    CalibrationFile='/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_OC_d58772_2025-02-12.h5',
    CharacterizationRunsFile='/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_char_2025_2-HighRes_OC.txt,/SNS/PG3/shared/CALIBRATION/2025-1_11A_CAL/PG3_char_2025_2_OC_limit.txt',
    RemovePromptPulseWidth=50,
    Binning='-0.0008',
    BackgroundSmoothParams='5, 2',
    FilterBadPulses=90,
    ScaleData=100,
    TypeOfCorrection='SampleAndContainer',
    SampleFormula='Ba-Nb-Cr-Ru',
    MeasuredMassDensity='6.0',
    SampleGeometry=sam_geo,
    SampleNumberDensity='0.088',
    ContainerGeometry=c_geo,
    ContainerMaterial=c_mat,
    GaugeVolume=gauge_vol,
    SaveAs='gsas topas and fullprof',
    OutputDirectory='/SNS/NOM/shared/tmp',
    CacheDir='/SNS/NOM/shared/tmp'
)

---

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?
• Do the release notes conform to the release notes guide?

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.

[peterfpeterson]

This is strange in a way similar to the DefineGaugeVolume user docs. I think it is configured that

• front-back is x-dimension
• left/right is y-dimension (beam height)
• top/bottom is z-dimension

It would be good to also add in the beam width for the dimension that has that

Adding a comment explaining that will help future people who see this.

[Kvieta1990]

The DefineGaugeVolume user docs is indeed a bit confusing in the explanation of how the gauge volume is defined. Here are several comments,

1. For the cuboid volume definition, I created an image to demonstrate the idea,
   

2. Ideally, indeed the gauge volume could be defined as above a a cuboid and Mantid then worries about constructing the intersection area between the sample and the defined gauge volume. However, the construction of the intersection area is not implemented yet. So, we cannot go with this route.

3. However, the gauge volume can be defined as with the same shape as the sample, e.g., cylinder or hollow cylinder and current implementation can meet our need without problems. We do need some further implementation in this PR to define the gauge volume for the sample and container separately.

4. The implementation for SampleOnly and SampleAndContainer method is straightforward -- just define the gauge volume twice here

5. For the PaalmanPingsAbsorptionCorrection method, I am not sure how to do that -- the same principle applies but I am not so familiar with the CPP codes.

[RichardWaiteSTFC]

At ISIS we are also interested in starting to use DefineGaugeVolume with other attenuation algorithms such as MonteCarloAbsoption for use on our engineering beamline ENGIN-X. For us we would need to consider the case of when the gauge volume is not wholly occupied by the sample, both for attenuation correction and normalising by the illuminated sample volume. If you do implement this let us know! Not sure how this fits in with your plans? Happy to discuss!

[Kvieta1990]

sure. I will keep you updated about the implementation. We do plan to do the gauge volume definition for both the absorption correction and normalization purpose. Currently I am working on this and the PR here is part of the work. Maybe we need another PR for working with implementation for PaalmanPingsAbsorptionCorrection which may need the help from @peterfpeterson and his team since I am not so familiar the C++ code and the code architecture there^_^ Anyhow, I will keep you in the loop.

[peterfpeterson]

There is also the algorithm SetBeam which may be appropriate for these calculations. I'm still in progress on understanding the effect of it.

[Kvieta1990]

@peterfpeterson I put in the implementation to define the gauge volume for sample and container separately to account for the beam size. I think you are right -- the way that gauge volume definition works is that the defined gauge volume will just replace the part of the sample shined by the beam. I did the test with a gauge volume larger than the sample size and in that case, as we change the gauge volume, the absorption spectrum is changing accordingly. This indicates that the gauge volume is not working as what I thought it would work, i.e., calculate the intersection region between the sample and the defined gauge volume.

As I put above, I think this is fine. We then just need to define the gauge volume to follow exactly the shape of the sample but with different height and position so only the defined gauge volume region will be taken as the integration volume. When calculating L2 (i.e., the path after the scattering all the way to detectors), still the original sample volume will be used -- I think this is how the codes are currently working but it will be nice to double check to make sure. We also need to do the same thing for the container separately, just like what we did with the sample, and the gauge volume for sure needs to be defined separately for the container to follow its shape (usually, a hollow cylinder).

All these can be done in the absorption util script for SampleOnly and SampleAndContainer types of correction. For PaalmanPingsAbsorptionCorrection, it is buried in the C++ implementation and I kind of lose myself in the code base and I may need your help on this. I will write a story for this. Tried to do that last night but the IBM tool seems to be problematic blocking me from logging in. Will do that later so we can schedule it next week or some time recently. This is a bit urgent as we do rely on a proper absorption correction for reducing samples with strong absorption quite often on both NOMAD and POWGEN. Thank you!

[Kvieta1990]

@peterfpeterson could you please leave this open while I am testing to see whether the currently implementation is doing its job properly? Or should I just change to draft?

[peterfpeterson]

This appears to be right for simple absorption calculations. It is unclear if this would work for Paalman-Pings with the current state of the calculations.

tl;dr use for simple absorption only