DirectILLReduction v1¶

DirectILLReduction dialog.

Table of Contents

Summary
Properties
Description
Usage
Source

Summary ¶

Data reduction workflow for the direct geometry time-of-flight spectrometers at ILL.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	MatrixWorkspace	Mandatory	Input workspace.
OutputWorkspace	Output	Workspace	Mandatory	The output of the algorithm.
Cleanup	Input	string	Cleanup ON	What to do with intermediate workspaces. Allowed values: [‘Cleanup ON’, ‘Cleanup OFF’]
SubalgorithmLogging	Input	string	Logging OFF	Enable or disable subalgorithms to print in the logs. Allowed values: [‘Logging OFF’, ‘Logging ON’]
IntegratedVanadiumWorkspace	Input	MatrixWorkspace		Reduced vanadium workspace.
AbsoluteUnitsNormalisation	Input	string	Absolute Units OFF	Enable or disable normalisation to absolute units. Allowed values: [‘Absolute Units OFF’, ‘Absolute Units ON’]
DiagnosticsWorkspace	Input	MatrixWorkspace		Detector diagnostics workspace obtained from another reduction run.
EnergyRebinningParams	Input	dbl list		Manual energy rebinning parameters.
QBinningParams	Input	dbl list		Manual q rebinning parameters.
Transposing	Input	string	Transposing ON	Enable or disable OutputWorkspace transposing. Allowed values: [‘Transposing ON’, ‘Transposing OFF’]
OutputSofThetaEnergyWorkspace	Output	Workspace		Output workspace for reduced S(theta, DeltaE).

This is the main data reduction algorithm in ILL’s time-of-flight reduction suite. It performs the last steps of the reduction workflow, namely vanadium normalisation and transformation to $S(q,\omega)$ space (optionally $S(2\theta,\omega)$ ). The algorithm’s workflow diagram is shown below:

../_images/DirectILLReduction-v1_wkflw.png

Input workspaces ¶

InputWorkspace should contain data treated by DirectILLCollectData and, optionally, by DirectILLApplySelfShielding.

The mandatory IntegratedVanadiumWorkspace should have gone through DirectILLIntegrateVanadium. This workspace is used for the vanadium normalisation.

DiagnosticsWorkspace should be a product of DirectILLDiagnostics. It is used to mask the spectra of InputWorkspace.

Outputs ¶

The algorithm will transform the time-of-flight and spectrum numbers of InputWorkspace into $S(q,\omega)$ at its output. For $2\theta$ to $q$ transformation, SofQWNormalisedPolygon is used. By default, the output is transposed by Transpose. This behavior can be turned off by the Transpose property.

The optional $S(2\theta,\omega)$ output can be enabled by the OutputSofThetaEnergyWorkspace.

Normalisation to absolute units ¶

Normalisation to absolute units can be enabled by setting AbsoluteUnitsNormalisation to ‘Absolute Units ON’. In this case the data is scaled by a factor

$f = \frac{N_V \sigma_V}{N_S}$

after normalisation to vanadium. In the above, $N_V$ stands for the vanadium number density, $\sigma_V$ for vanadium total scattering cross section and $N_S$ sample number density.

The material properties should be set for InputWorkspace and IntegratedVanadiumWorkspace by SetSample before running this algorithm .

(Re)binning in energy and momentum transfer ¶

After conversion from time-of-flight to energy transfer, the binning may differ from spectrum to spectrum if the sample to detector distances are unequal. The SofQWNormalisedPolygon algorithm cannot work with such ragged workspaces and thus rebinning is necessary. The rebinning can be specified by the EnergyRebinningParams property. This is directly passed to Rebin as the Params property. If EnergyRebinningParams is not specified, an automatic rebinning scheme is used: - Find the spectrum with smallest bin border. Copy binning from this spectrum for negative energy transfers. - For positive energy transfers, use the median bin width at zero energy transfer.

QBinningParams are passed to SofQWNormalisedPolygon and have the same format as EnergyRebinningParamas. If the property is not specified, $q$ is binned to ten times the median $2\theta$ steps between the spectra.

Usage ¶

Example - Fake IN4 workspace reduction

from mantid.kernel import DeltaEModeType, UnitConversion
import numpy
import scipy.stats

# Create a fake IN4 workspace.
# We need an instrument and a template first.
empty_IN4 = LoadEmptyInstrument(InstrumentName='IN4')
nHist = empty_IN4.getNumberHistograms()
# Make TOF bin edges.
xs = numpy.arange(530.0, 2420.0, 4.0)
# Make some Gaussian spectra.
ys = 1000.0 * scipy.stats.norm.pdf(xs[:-1], loc=970, scale=60)
# Repeat data for each histogram.
xs = numpy.tile(xs, nHist)
ys = numpy.tile(ys, nHist)
ws = CreateWorkspace(
    DataX=xs,
    DataY=ys,
    NSpec=nHist,
    UnitX='TOF',
    ParentWorkspace=empty_IN4
)
# Set some histograms to zero for detector diagnostics.
ys = ws.dataY(13)
ys *= 0.0
ys = ws.dataY(101)
ys *= 0.0

# Manually correct monitor spectrum number as LoadEmptyInstrument does
# not know about such details.
SetInstrumentParameter(
    Workspace=ws,
    ParameterName='default-incident-monitor-spectrum',
    ParameterType='Number',
    Value=str(1)
)
# Add incident energy information to sample logs.
AddSampleLog(
    Workspace=ws,
    LogName='Ei',
    LogText=str(57),
    LogType='Number',
    LogUnit='meV',
    NumberType='Double'
)
# Add wavelength to sample logs
wl = UnitConversion.run('Energy', 'Wavelength', 57.0, 0.0, 0.0, 0.0, DeltaEModeType.Direct, 0.0)
AddSampleLog(
    Workspace=ws,
    LogName='wavelength',
    LogText=str(wl),
    LogType='Number',
    LogUnit='Angstrom',
    NumberType='Double'
)
# Elastic channel information is missing in the sample logs.
# It can be given as single valued workspace, as well.
elasticChannelWS = CreateSingleValuedWorkspace(107)

# Create a fake 'vanadium' reference workspace.
V_ws = Scale(
    InputWorkspace=ws,
    Factor=1.3
)

# Process vanadium.
DirectILLCollectData(
    InputWorkspace=V_ws,
    OutputWorkspace='vanadium',
    ElasticChannelWorkspace=elasticChannelWS,
    IncidentEnergyCalibration='Energy Calibration OFF', # Normally we would do this for IN4.
    OutputEPPWorkspace='epps' # Needed for diagnostics and integration.
)

DirectILLDiagnostics(
    InputWorkspace='vanadium',
    OutputWorkspace='diagnostics_mask',
    EPPWorkspace='epps',
    MaskedComponents='rosace', #Exclude small-angle detectors.
)

DirectILLIntegrateVanadium(
    InputWorkspace='vanadium',
    OutputWorkspace='vanadium_factors',
    SubalgorithmLogging='Logging ON',
    EPPWorkspace='epps',
    Temperature=273.0
)

# Process sample.
DirectILLCollectData(
    InputWorkspace=ws,
    OutputWorkspace='preprocessed',
    ElasticChannelWorkspace=elasticChannelWS,
    IncidentEnergyCalibration='Energy Calibration OFF'
)

# Absorption corrections and empty container subtractions could be added here.

DirectILLReduction(
    InputWorkspace='preprocessed',
    OutputWorkspace='SofQW',
    IntegratedVanadiumWorkspace='vanadium_factors',
    DiagnosticsWorkspace='diagnostics_mask'
)

sofqw = mtd['SofQW']
nHist = sofqw.getNumberHistograms()
nBin = sofqw.blocksize()
print('Size of the final S(q,w) workspace: {} histograms, {} bins'.format(nHist, nBin))

Output:

Size of the final S(q,w) workspace: 177 histograms, 234 bins

Categories: Algorithms | Workflow\Inelastic

Source ¶

Python: DirectILLReduction.py