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

ConvertUnits v1¶

../_images/ImageNotFound.png — Enable screenshots using DOCS_SCREENSHOTS in CMake¶

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: [‘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.

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]))