4.0

ConvertUnits v1

../_images/ConvertUnits-v1_dlg.png

ConvertUnits dialog.

Summary

Performs a unit change on the X values of a workspace

Properties

Name Direction Type Default Description
InputWorkspace Input MatrixWorkspace Mandatory Name of the input workspace
OutputWorkspace Output MatrixWorkspace Mandatory Name of the output workspace, can be the same as the input
Target Input string Mandatory The name of the units to convert to (must be one of those registered in the Unit Factory). Allowed values: [‘Degrees’, ‘DeltaE’, ‘DeltaE_inFrequency’, ‘DeltaE_inWavenumber’, ‘dSpacing’, ‘dSpacingPerpendicular’, ‘Empty’, ‘Energy’, ‘Energy_inWavenumber’, ‘Label’, ‘Momentum’, ‘MomentumTransfer’, ‘QSquared’, ‘SpinEchoLength’, ‘SpinEchoTime’, ‘Temperature’, ‘Time’, ‘TOF’, ‘Wavelength’]
EMode Input string Elastic The energy mode (default: elastic). Allowed values: [‘Elastic’, ‘Direct’, ‘Indirect’]
EFixed Input number Optional Value of fixed energy in meV : EI (EMode=Direct) or EF (EMode=Indirect) . Must be set if the target unit requires it (e.g. DeltaE)
AlignBins Input boolean False If true (default is false), rebins after conversion to ensure that all spectra in the output workspace have identical bin boundaries. This option is not recommended (see http://www.mantidproject.org/ConvertUnits).
ConvertFromPointData Input boolean True When checked, if the Input Workspace contains Points the algorithm ConvertToHistogram will be run to convert the Points to Bins. The Output Workspace will contains Bins.

Description

Changes the units in which the X values of a workspace are represented. The available units are those registered with the Unit Factory. If the Y data is ‘dimensioned’ (i.e. has been divided by the bin width), then this will be correctly handled, but at present nothing else is done to the Y data. If the sample-detector distance cannot be calculated then the affected spectrum will be zeroed, and a warning message will be output on the logging service.

If AlignBins is false or left at the default the output workspace may be a ragged workspace. If it is set to true then the data is automatically rebinned to a regular grid so that the maximum and minimum X values will be maintained. It uses the same number of bins as the input data, and divides them linearly equally between the minimum and maximum values.

If converting to \Delta E any bins which correspond to a physically inaccessible will be removed, leading to an output workspace than is smaller than the input one. If the geometry is indirect then the value of EFixed will be taken, if available, from the instrument definition file.

If ConvertFromPointData is true, an input workspace contains Point data will be converted using ConvertToHistogram and then the algorithm will be run on the converted workspace.

Restrictions on the input workspace

  • Naturally, the X values must have a unit set, and that unit must be known to the Unit Factory.
  • Histograms and Point data can be handled.
  • The algorithm will also fail if the source-sample distance cannot be calculated (i.e. the instrument has not been properly defined).

Available units

The units currently available to this algorithm are listed here, along with equations specifying exactly how the conversions are done.

Usage

Example: Convert to wavelength

ws = CreateSampleWorkspace("Histogram",NumBanks=1,BankPixelWidth=1)
wsOut = ConvertUnits(ws,Target="Wavelength")

print("Input {}".format(ws.readX(0)[ws.blocksize()-1]))
print("Output {:.11f}".format(wsOut.readX(0)[wsOut.blocksize()-1]))

Output:

Input 19800.0
Output 5.22196485301

Categories: Algorithm Index | Transforms\Units

Source

C++ source: ConvertUnits.cpp (last modified: 2019-01-07)

C++ header: ConvertUnits.h (last modified: 2018-10-05)