Units#

What are units?#

Units are a set of small classes in Mantid that define a unit of measure, and the conversions between various units.

The Unit Factory is a Dynamic Factory that creates and hands out instances of Mantid Unit objects.

Available TOF Convertible units#

The following units are available in the default Mantid distribution. These units are TOF convertible.

Name	ID (as known by Unit Factory)	Unit	Relevant equation
Time of flight	TOF	\(\mu s\)	TOF
Wavelength	Wavelength	\(\mathrm{\AA}\)	\(\lambda = \frac{h}{p} = \frac{h \times \mathrm{tof}}{m_N \times L_{tot}}\) (see below)
Energy	Energy	\(meV\)	\(E = \frac{1}{2} mv^2 = \frac{m_N}{2} \left ( \frac{L_{tot}}{\mathrm{tof}} \right )^2\)
Energy in wavenumber	Energy_inWavenumber	\(cm^{-1}\)	\(8.06554465 \times E\)
Momentum (k)	Momentum	\(\mathrm{\AA}^{-1}\)	\(k = \frac{2 \pi }{\lambda}=\frac{2 \pi \times m_N \times L_{tot}}{h \times \mathrm{tof}}\)
d-spacing	dSpacing	\(\mathrm{\AA}\)	\(TOF = DIFA \, d^2 + DIFC d + TZERO\) (see below)
Momentum transfer (Q)	MomentumTransfer	\(\mathrm{\AA}^{-1}\)	\(Q = 2 \, k \, sin \, \theta = \frac{4 \pi sin \theta}{\lambda}\)
Momentum transfer squared (\(Q^2\))	QSquared	\(\mathrm{\AA}^{-2}\)	\(Q^2 \frac{}{}\)
Energy transfer	DeltaE	\(meV\)	\(\Delta E = E_{i}-\frac{1}{2}m_N \left ( \frac{L_2}{\mathrm{tof}-L_1\sqrt{\frac{m_N}{2E_i}}} \right )^2\)
Energy transfer in wavenumber	DeltaE_inWavenumber	\(cm^{-1}\)	\(8.06554465 \times \Delta E\)
Spin Echo Length	SpinEchoLength	\(nm\)	\(constant \times \lambda^2\) The constant is supplied in eFixed
Spin Echo Time	SpinEchoTime	\(ns\)	\(constant \times \lambda^3\) The constant is supplied in eFixed
d-spacingPerpendicular	dSpacingPerpendicular	\(\mathrm{\AA}\)	\(d_{\perp} = \sqrt{\lambda^2 - 2\log\cos\theta}\)

Where \(L_1\) and \(L_2\) are sample to the source and sample to detector distances respectively, \(L_{tot} = L_1+L_2\) and \(E_i\) is the energy of neutrons leaving the source. \(\theta\) here is the Bragg scattering angle (e.g. half of the \(\theta\)-angle used in spherical coordinate system directed along Mantid z-axis)

Note on Wavelength: If the emode property in ConvertUnits is specified as inelastic Direct/Indirect (inelastic) then the conversion to wavelength will take into account the fixed initial/final energy respectively. Units conversion into elastic momentum transfer (MomentumTransfer) will throw in elastic mode (emode=0) on inelastic workspace (when energy transfer is specified along x-axis)

Note on d-spacing: The coefficients DIFA, DIFC and TZERO may be obtained via calibration of a TOF diffraction instrument. In the absence of a calibration, DIFA=TZERO=0 and the default value of DIFC is:

\(DIFC = 10^{-4} \frac{m_N}{h} (L_1 + L_2) 2 \sin(\theta)\)

where the scaling factor adjusts for the fact that DIFC is required in units of \(\mu s\) per \(\mathrm{\AA}\).

d-spacingPerpendicular is a unit invented in J. Appl. Cryst. (2015) 48, pp. 1627–1636 for 2D Rietveld refinement of angular and wavelength-dispersive neutron time-of-flight powder diffraction data. Together with the d-Spacing \(d\), d-SpacingPerpendicular \(d_{\perp}\) forms a new orthogonal coordinate system.

Note on converting time-of-flight to dSpacing using GSAS The equation in GSAS converts from d-spacing (\(d\)) to time-of-flight (\(TOF\)) by the equation:

\[TOF = DIFC * d + DIFA * d^2 + TZERO\]

The manual describes these terms in more detail. Roughly, \(TZERO\) is related to the difference between the measured and actual time-of-flight base on emission time from the moderator, \(DIFA\) is an empirical term (ideally zero), and \(DIFC\) is

\[DIFC = \frac{2m_N}{h} L_{tot} sin \theta\]

Measuring peak positions using a crystal with a very well known lattice constant will give a good value for converting the data. The d-spacing of the data will be calculated using whichever equation below is appropriate for solving the quadratic.

When \(DIFA = 0\) then the solution is just for a line and

\[d = \frac{TOF - TZERO}{DIFC}\]

For the case of needing to solve the actual quadratic equation

\[d = \frac{-DIFC}{2 DIFA} \pm \sqrt{\frac{TOF}{DIFA} + \left(\frac{DIFC}{2 DIFA}\right)^2 - \frac{TZERO}{DIFA}}\]

Here the positive root is used when \(DIFA > 0\) and the negative when \(DIFA < 0\).

Available non-TOF Convertible units#

The following units are available in the default Mantid distribution. These units cannot be converted to or from TOF.

Name	ID (as known by Unit Factory)	Unit	Description
	Empty	No unit	An empty label
t	Time	\(s\)	An independent unit of time not related to energy or TOF
Scattering angle	Degrees	\(degrees\)	Degrees is a measurement of angular position
Temperature	Temperature	\(K\)	Temperature in Kelvin

Working with Units in Python#

Accessing units on workspaces#

Units on MatrixWorkspaces are accessed via the Axis.

ws = CreateSampleWorkspace()
for i in range(ws.axes()):
    axis = ws.getAxis(i)
    print("Axis {0} is a {1}{2}{3}".format(i,
                                           "Spectrum Axis" if axis.isSpectra() else "",
                                           "Text Axis" if axis.isText() else "",
                                           "Numeric Axis" if axis.isNumeric() else ""))

    unit = axis.getUnit()
    print("\t caption:{0}".format(unit.caption()))
    print("\t symbol:{0}".format(unit.symbol()))

Output:

Axis 0 is a Numeric Axis
   caption:Time-of-flight
   symbol:microsecond
Axis 1 is a Spectrum Axis
   caption:Spectrum
   symbol:

Setting the axisLabel to a Label of your choice#

ws = CreateSampleWorkspace()
axis = ws.getAxis(1)
# Create a new axis
axis.setUnit("Label").setLabel('Temperature', 'K')

unit = axis.getUnit()
print("New caption:{0}".format(unit.caption()))
print("New symbol:{0}".format(unit.symbol()))

Output:

New caption:Temperature
New symbol:K

Adding new units#

Writing and adding a new unit is relatively straightforward. Instructions will appear here in due course. In the meantime if a unit that you require is missing, then please contact the development team and we will add it to the default Mantid library.

Category: Concepts