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

ConvertUnits v1

Summary

Performs a unit change on the X values of a workspace

See Also

ConvertAxisByFormula, ConvertAxesToRealSpace, ConvertSpectrumAxis, ConvertToYSpace

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: [‘DeltaE’, ‘DeltaE_inFrequency’, ‘DeltaE_inWavenumber’, ‘dSpacing’, ‘dSpacingPerpendicular’, ‘Energy’, ‘Energy_inWavenumber’, ‘Momentum’, ‘MomentumTransfer’, ‘QSquared’, ‘SpinEchoLength’, ‘SpinEchoTime’, ‘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://docs.mantidproject.org/algorithms/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: AlgorithmIndex | Transforms\Units

Source

C++ header: ConvertUnits.h

C++ source: ConvertUnits.cpp