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

ConvertToDiffractionMDWorkspace v1¶

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

Summary ¶

Create a MDEventWorkspace with events in reciprocal space (Qx, Qy, Qz) for an elastic diffraction experiment.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	MatrixWorkspace	Mandatory	An input workspace in time-of-flight. If you specify a Workspace2D, it gets converted to an EventWorkspace using ConvertToEventWorkspace.
OutputWorkspace	Output	MDEventWorkspace	Mandatory	Name of the output MDEventWorkspace. If the workspace already exists, then the events will be added to it.
Append	Input	boolean	False	Append events to the output workspace. The workspace is replaced if unchecked.
ClearInputWorkspace	Input	boolean	False	Clear the events from the input workspace during conversion, to save memory.
OneEventPerBin	Input	boolean	False	Use the histogram representation (event for event workspaces). One MDEvent will be created for each histogram bin (even empty ones). Warning! This can use significantly more memory!
OutputDimensions	Input	string	Q (lab frame)	What will be the dimensions of the output workspace? Q (lab frame): Wave-vector change of the lattice in the lab frame. Q (sample frame): Wave-vector change of the lattice in the frame of the sample (taking out goniometer rotation). HKL: Use the sample’s UB matrix to convert to crystal’s HKL indices. Allowed values: [‘Q (lab frame)’, ‘Q (sample frame)’, ‘HKL’]
LorentzCorrection	Input	boolean	False	Correct the weights of events by multiplying by the Lorentz formula: sin(theta)^2 / lambda^4
SplitInto	Input	int list	2	A comma separated list of into how many sub-grid elements each dimension should split; or just one to split into the same number for all dimensions. Default 2.
SplitThreshold	Input	number	1500	How many events in a box before it should be split. Default 1500.
MaxRecursionDepth	Input	number	20	How many levels of box splitting recursion are allowed. The smallest box will have each side length \(l = (extents) / (SplitInto^{MaxRecursionDepth}).\) Default 20.
MinRecursionDepth	Input	number	0	Optional. If specified, then all the boxes will be split to this minimum recursion depth. 1 = one level of splitting, etc. Be careful using this since it can quickly create a huge number of \(boxes = SplitInto^{MinRercursionDepth \times NumDimensions}\). But setting this property equal to MaxRecursionDepth property is necessary if one wants to generate multiple file based workspaces in order to merge them later
Extents	Input	dbl list	-50,50	A comma separated list of min, max for each dimension, specifying the extents of each dimension. Optional, default +-50 in each dimension.

Description ¶

This algorithm converts from a MatrixWorkspace (in detector/time-of-flight space) to a MDEventWorkspace containing events in reciprocal space.

The calculations apply only to elastic diffraction experiments. The conversion can be done either to Q-space in the lab or sample frame, or to HKL of the crystal.

If the OutputWorkspace does NOT already exist, a default one is created. In order to define more precisely the parameters of the MDEventWorkspace, use the CreateMDWorkspace v1 algorithm first.

Types of Conversion ¶

Q (lab frame): this calculates the momentum transfer (ki-kf) for each event is calculated in the experimental lab frame.
Q (sample frame): the goniometer rotation of the sample is taken out, to give Q in the frame of the sample. See SetGoniometer v1 to specify the goniometer used in the experiment.
HKL: uses the UB matrix (see SetUB v1, FindUBUsingFFT v1 and others) to calculate the HKL Miller indices of each event.

Lorentz Correction ¶

If selected, the following Lorentz correction factor is applied on each event by multiplying its weight by L:

\(L = \frac{ sin(\theta)^2 } { \lambda^{4} }\)

Where \(\theta\) is half of the neutron scattering angle (conventionally called \(2\theta\)). \(\lambda\) is the neutron wavelength in Angstroms.

This correction is also done by the AnvredCorrection v1 algorithm, and will be set to false if that algorithm has been run on the input workspace.

OneEventPerBin option ¶

If you specify OneEventPerBin, then the histogram representation of the input workspace is used, with one MDEvent generated for each bin of the workspace, including zeros.

This can be useful in cases where the experimental coverage needs to be tracked. With one MDEvent for each bin, you can count which regions in Q-space have been measured. The Sliceviewer has an option to view normalized by number of events. This means that, for example, areas with overlap from two runs will appear scaled down.

A significant drawback to this is that the output MDEventWorkspace will be significantly larger than the events alone would be. It currently must be created in physical memory (it cannot yet be cached to disk). One way to limit the memory used is to limit the OutputExtents to a smaller region and only convert part of the space.

Also, the FindPeaksMD v1 algorithm may not work optimally because it depends partly on higher density of events causing more finely split boxes.

If your input is a Workspace2D and you do NOT check OneEventPerBin, then the workspace is converted to an EventWorkspace but with no events for empty bins.

Performance Notes ¶

8-core Intel Xeon 3.2 GHz computer: measured between 4 and 5.5 million events per second (100-200 million event workspace).
32-core AMD Opteron 2.7 GHz computer: measured between 8 and 9 million events per second (400-1000 million event workspaces).

Usage

Example - Convert re-binned MARI 2D workspace to 3D MD workspace for further analysis/merging with data at different temperatures :

# create or load event workspace
events = CreateSampleWorkspace(OutputWorkspace='events', WorkspaceType='Event', Function='Multiple Peaks')
# convert to  MD workspace
md = ConvertToDiffractionMDWorkspace(InputWorkspace=events, OutputWorkspace='md', OneEventPerBin=False, LorentzCorrection=True, SplitThreshold=150, Version=1)

# A way to look at these results as a text:
print("Resulting MD workspace has {0} events and {1} dimensions".format(md.getNEvents(),md.getNumDims()))
print("Workspace Type is:  {}".format(md.id()))

Output:

Resulting MD workspace has 194... events and 3 dimensions
Workspace Type is:  MDEventWorkspace<MDLeanEvent,3>

Categories: AlgorithmIndex | MDAlgorithms\Creation

Source ¶

C++ header: ConvertToDiffractionMDWorkspace.h

C++ source: ConvertToDiffractionMDWorkspace.cpp