\(\renewcommand\AA{\unicode{x212B}}\)

CorrectTOFAxis v1

../_images/ImageNotFound.png

Enable screenshots using DOCS_SCREENSHOTS in CMake

Summary

Corrects the time-of-flight axis with regards to the incident energy and the L1+L2 distance or a reference workspace.

See Also

ConvertToConstantL2

Properties

Name

Direction

Type

Default

Description

InputWorkspace

Input

MatrixWorkspace

Mandatory

An input workspace.

OutputWorkspace

Output

MatrixWorkspace

Mandatory

An output workspace.

ReferenceWorkspace

Input

MatrixWorkspace

A reference workspace from which to copy the TOF axis as well as the ‘Ei’ and ‘wavelength’ sample logs.

EPPTable

Input

TableWorkspace

An input EPP table.

IndexType

Input

string

Detector ID

The type of indices used in ReferenceSpectra or ElasticBinIndex (default: ‘Detector ID’). Allowed values: [‘Detector ID’, ‘Spectrum Number’, ‘Workspace Index’]

ReferenceSpectra

Input

int list

A list of reference spectra.

ElasticBinIndex

Input

number

Optional

Bin index of the nominal elastic TOF channel.

EFixed

Input

number

Optional

Incident energy if the ‘EI’ sample log is not present/incorrect.

L2

Input

number

Optional

Sample to detector distance, in meters.

Description

This algorithm is meant to adjust the time-of-flight axis so that the elastic peak is at zero energy transfer after unit conversion from ‘TOF’ to ‘DeltaE’. The algorithm has two modes: either it uses a given ReferenceWorkspace, or it calculates a constant time-of-flight shift using the L1 + L2 distances of the InputWorkspace and incident energy.

Using a reference workspace

If ReferenceWorkspace is set, this algorithm copies the X axis as well as the ‘Ei’ and ‘wavelength’ sample logs, if present, to OutputWorkspace. The rest of the input properties are discarded.

Calculating new TOF axis

If no ReferenceWorkspace is given, the algorithm takes the source-to-sample distance \(l_1\) from the instrument attached to InputWorkspace. The source-to-detector distance \(l_2\) can either be given directly by the L2 property, or it is calculated as the mean L2 distance from the histograms specified by ReferenceSpectra. The algorithm also needs to know the TOF \(t_{elastic}\) corresponding to the zero-energy transfer. This is either taken from the first spectrum in InputWorkspace as the bin centre of the bin specified by ElasticBinIndex, or calculated from the elastic peak positions given in EPPTable. EPPTable should be in the format returned by the FindEPP v2 algorithm. In this case the algorithm averages the PeakCentre column for histograms listed in ReferenceSpectra. Finally, the algorithm needs the incident energy \(E_i\) which can be either specified by EFixed or is taken from the sample logs of InputWorkspace. In case EFixed is specified, the ‘Ei’ and ‘wavelength’ sample logs of OutputWorkspace are updated accordingly.

The TOF shift \(\Delta t\) is calculated by

\(\Delta t = t_{elastic} - (l_1 + l_2) / \sqrt{2 E_i / m_n}\),

where \(m_n\) is the neutron mass. The shift \(\Delta t\) is then added to all X values of OutputWorkspace.

The algorithm assumes micro seconds as units of time and meV as units of energy.

Whether the ReferenceSpectra input property refers to workspace indices, spectrum numbers or detector IDs is specified by IndexType.

Usage

Example - CorrectTOFAxis by specifying the elastic bin and L2

from mantid.kernel import DeltaEModeType, UnitConversion

L1 = 2.0 # in metres.
L2 = 2.0
Ei = 55.0 # in meV
elasticTOF = UnitConversion.run(src='Energy', dest='TOF',
                                srcValue=Ei,
                                l1=L1, l2=L2,
                                theta=0, emode=DeltaEModeType.Direct, efixed=Ei)

# Make a workspace with wrong TOF axis.
TOFMin = 0.0
TOFMax = 100.0
binWidth = 0.5
# Lets say the elastic bin is in the centre of the spectrum.
elasticBinIndex = int(((TOFMax - TOFMin) / binWidth) / 2.0)
# Build a Gaussian elastic peak in the workspace.
peakCentre = TOFMin + elasticBinIndex * binWidth
spectrumDescription = '''name=Gaussian, PeakCentre={0},
Height=100, Sigma={1}'''.format(peakCentre, 0.03 * peakCentre)
ws = CreateSampleWorkspace(WorkspaceType='Histogram',
    NumBanks=1,
    BankPixelWidth=1,
    Function='User Defined',
    UserDefinedFunction=spectrumDescription,
    BankDistanceFromSample=L2,
    SourceDistanceFromSample=L1,
    XMin=TOFMin,
    XMax=TOFMax,
    BinWidth=binWidth)

# Do the correction.
correctedWs = CorrectTOFAxis(ws,
    IndexType='Workspace Index',
    ElasticBinIndex=elasticBinIndex,
    EFixed=Ei,
    L2=L2)

# Convert TOF to energy transfer.
convertedWs = ConvertUnits(correctedWs,
    Target='DeltaE',
    EMode='Direct')

# Check results
# Zero energy transfer should be around elasticBinIndex.
for index in range(elasticBinIndex-1, elasticBinIndex+2):
    binCentre = (convertedWs.readX(0)[index+1] + convertedWs.readX(0)[index]) / 2
    print('DeltaE at the centre of bin {0}: {1:0.4f}'.format(index,binCentre))

Output:

DeltaE at the centre of bin 99: -0.0893
DeltaE at the centre of bin 100: -0.0000
DeltaE at the centre of bin 101: 0.0891

Example - CorrectTOFAxis by specifying the elastic bin and taking L2 from reference spectra

from mantid.kernel import DeltaEModeType, UnitConversion

L1 = 2.0 # in metres.
L2 = 2.0
Ei = 55.0 # in meV
elasticTOF = UnitConversion.run(src='Energy', dest='TOF',
                                srcValue=Ei,
                                l1=L1, l2=L2,
                                theta=0, emode=DeltaEModeType.Direct, efixed=Ei)

# Make a workspace with wrong TOF axis.
TOFMin = 0.0
TOFMax = 100.0
binWidth = 0.5
# Lets say the elastic bin is in the centre of the spectrum.
elasticBinIndex = int(((TOFMax - TOFMin) / binWidth) / 2.0)
# Build a Gaussian elastic peak in the workspace.
peakCentre = TOFMin + elasticBinIndex * binWidth
spectrumDescription = '''name=Gaussian, PeakCentre={0},
Height=100, Sigma={1}'''.format(peakCentre, 0.03 * peakCentre)
ws = CreateSampleWorkspace(WorkspaceType='Histogram',
    NumBanks=1,
    BankPixelWidth=1,
    Function='User Defined',
    UserDefinedFunction=spectrumDescription,
    BankDistanceFromSample=L2,
    SourceDistanceFromSample=L1,
    XMin=TOFMin,
    XMax=TOFMax,
    BinWidth=binWidth)

# Do the correction.
correctedWs = CorrectTOFAxis(ws,
    IndexType='Workspace Index',
    ReferenceSpectra='0',
    ElasticBinIndex=elasticBinIndex,
    EFixed=Ei)

# Convert TOF to energy transfer.
convertedWs = ConvertUnits(correctedWs,
    Target='DeltaE',
    EMode='Direct')

# Check results
# Zero energy transfer should be around elasticBinIndex.
for index in range(elasticBinIndex-1, elasticBinIndex+2):
    binCentre = (convertedWs.readX(0)[index+1] + convertedWs.readX(0)[index]) / 2
    print('DeltaE at the centre of bin {0}: {1:0.4f}'.format(index,binCentre))

Output:

DeltaE at the centre of bin 99: -0.0893
DeltaE at the centre of bin 100: -0.0000
DeltaE at the centre of bin 101: 0.0891

Example - CorrectTOFAxis using EPP table

from mantid.kernel import DeltaEModeType, UnitConversion
import numpy

L1 = 2.0 # in metres
L2 = 2.0
Ei = 55.0 # in meV
elasticTOF = UnitConversion.run(src='Energy', dest='TOF',
                                srcValue=Ei,
                                l1=L1, l2=L2,
                                theta=0, emode=DeltaEModeType.Direct, efixed=Ei)

# Make a workspace with wrong TOF axis.
TOFMin = 0.0
TOFMax = 100.0
# Build a Gaussian elastic peak in the workspace.
peakCentre = TOFMin + 2.0 * (TOFMax - TOFMin) / 3.0
spectrumDescription = '''name=Gaussian, PeakCentre={0},
Height=100, Sigma={1}'''.format(peakCentre, 0.03 * peakCentre)
ws = CreateSampleWorkspace(WorkspaceType='Histogram',
       NumBanks=1,
       BankPixelWidth=1,
       Function='User Defined',
       UserDefinedFunction=spectrumDescription,
       BankDistanceFromSample=L2,
       SourceDistanceFromSample=L1,
       XMin=TOFMin,
       XMax=TOFMax,
       BinWidth=0.5)

# Prepare for the correction.
EPPTable = FindEPP(ws)

# Do the correction.
correctedWs = CorrectTOFAxis(ws,
    EPPTable=EPPTable,
    IndexType='Workspace Index',
    ReferenceSpectra='0',
    EFixed=Ei)

# Check results.
print('Original TOF for the elastic peak: {0:0.1f}'.format(
    ws.readX(0)[numpy.argmax(ws.readY(0))]))
print('Corrected TOF for the elastic peak: {0:0.1f}'.format(
    correctedWs.readX(0)[numpy.argmax(correctedWs.readY(0))]))
print('Actual elastic TOF: {0:0.1f}'.format(elasticTOF))

Output:

Original TOF for the elastic peak: 66.5
Corrected TOF for the elastic peak: 1233.0
Actual elastic TOF: 1233.1

Example - CorrectTOFAxis using a reference workspace

from mantid.kernel import DeltaEModeType, UnitConversion
import numpy

L1 = 2.0
L2 = 2.0
Ei = 55.0 # in meV
elasticTOF = UnitConversion.run(src='Energy', dest='TOF',
                                srcValue=Ei,
                                l1=L1, l2=L2,
                                theta=0, emode=DeltaEModeType.Direct, efixed=Ei)

# Make two workspaces with wrong TOF axis.
TOFMin = 0.0
TOFMax = 100.0
peakCentre = TOFMin + 2.0 * (TOFMax - TOFMin) / 3.0
# Build a Gaussian elastic peak in the first workspace.
spectrumDescription = '''name=Gaussian, PeakCentre={0},
Height=100, Sigma={1}'''.format(peakCentre, 0.03 * peakCentre)
ws1 = CreateSampleWorkspace(WorkspaceType='Histogram',
    NumBanks=1,
    BankPixelWidth=1,
    Function='User Defined',
    UserDefinedFunction=spectrumDescription,
    BankDistanceFromSample=L2,
    SourceDistanceFromSample=L1,
    XMin=TOFMin,
    XMax=TOFMax,
    BinWidth=0.5)
# Build a second workspace with slightly different Gaussian.
spectrumDescription = '''name=Gaussian, PeakCentre={0},
Height=100, Sigma={1}'''.format(peakCentre, 0.06 * peakCentre)
ws2 = CreateSampleWorkspace(WorkspaceType='Histogram',
NumBanks=1,
BankPixelWidth=1,
Function='User Defined',
UserDefinedFunction=spectrumDescription,
BankDistanceFromSample=L2,
SourceDistanceFromSample=L1,
XMin=TOFMin,
XMax=TOFMax,
BinWidth=0.5)

# Correct the first workspace using the EPP table method.
EPPTable = FindEPP(ws1)

# Do the correction.
correctedWs1 = CorrectTOFAxis(ws1,
    EPPTable=EPPTable,
    IndexType='Workspace Index',
    ReferenceSpectra='0',
    EFixed=Ei)

# Correct the second workspace by using the first as a reference.
correctedWs2 = CorrectTOFAxis(ws2,
    ReferenceWorkspace=correctedWs1)

# Check results
print('First workspace original TOF for the elastic peak: {0:0.1f}'.format(
    ws1.readX(0)[numpy.argmax(ws1.readY(0))]))
print('EPP table corrected TOF for the elastic peak: {0:0.1f}'.format(
    correctedWs1.readX(0)[numpy.argmax(correctedWs1.readY(0))]))
print('Elastic TOF for the corrected second workspace: {0:0.1f}'.format(
    correctedWs2.readX(0)[numpy.argmax(correctedWs2.readY(0))]))

Output:

First workspace original TOF for the elastic peak: 66.5
EPP table corrected TOF for the elastic peak: ...
Elastic TOF for the corrected second workspace: ...

Categories: AlgorithmIndex | Inelastic\Corrections

Source

C++ header: CorrectTOFAxis.h

C++ source: CorrectTOFAxis.cpp