ConvertToMD-v1.rst



Description
The algorithm is used transform existing :ref:`Event <EventWorkspace>`
or :ref:`Matrix <MatrixWorkspace>` workspace into
Multidimensional workspace using
MD Transformations Factory.
If  the target workspace does not exist, the algorithm creates MDEventWorkspace
with selected dimensions, e.g. the reciprocal space of momentums (Qx, Qy, Qz) or momentums modules |Q|, energy transfer dE if available
and any other user specified log values which can be treated as dimensions. If the target workspace do exist,
the MD Events are added to this workspace.

Used Subalgorithms
The algorithm uses :ref:`Unit Factory <Unit Factory>` and existing unit
conversion procedures from the input Workspace :ref:`units <Unit Factory>`
to the :ref:`units <Unit Factory>` , necessary
for transformation into correspondent MD Event workspace. It also uses
:ref:`algm-PreprocessDetectorsToMD` algorithm to help
with transformation to reciprocal space.
If min, max or both lists of values (properties 12 and 13) for the
algorithm are not specified,
:ref:`algm-ConvertToMDMinMaxLocal` is used to estimate
missing min-max values. This algorithm is also used to calculate min-max
values if specified min-max values are deemed incorrect (e.g. less
values then dimensions or some min values are bigger then max values)
l = (extents) / (SplitInto^{MaxRecursionDepth}).

Notes

For elastic analysis (dEAnalysisMode=Elastic) the target
:ref:`unit <Unit Factory>` is momentum k.
For no analysis (CopyToMD) mode, the units remain the one, previously
defined along the workspace's axes.
When units of input Matrix 2D workspace (Histogram workspace) are not
Momentums for Elastic or EnergyTransfer for inelastic mode, the
algorithm uses internal unit conversion of input X-values based on
central average of a bin ranges. Namely, value
X_c = 0.5*(X_i+X_{i+1}) is calculated and converted to
Momentum or EnergyTransfer correspondingly. This can give slightly
different result from the case, when input workspace has been
converted into correspondent units before converting to MDEvents.
Confusing message "Error in execution of algorithm ConvertToMD: emode
must be equal to 1 or 2 for energy transfer calculation" is generated
when one tries to process the results of inelastic scattering
experiment in elastic mode. This message is generated by units
conversion routine, which finds out that one of the workspace axis is
in :ref:`unit <Unit Factory>` of DeltaE. These units can not be directly
converted into momentum or energy, necessary for elastic mode. Select
Direct or Indirect mode and integrate over whole energy transfer
range to obtain MD workspace, which would correspond to an Elastic
mode.
A good guess on the limits can be obtained from the
:ref:`algm-ConvertToMDMinMaxLocal` algorithm.


How to write custom ConvertToMD plugin
This information intended for developers who have at least basic
knowledge of C++ and needs to write its own
plugin using custom ConvertTo MD transformation.

Usage examples
The examples below demonstrate the usages of the algorithm in most
common situations. They work with the data files which already used by
Mantid for different testing tasks.
Example - Convert re-binned MARI 2D workspace to 3D MD workspace for further analysis/merging with data at different temperatures :
Output:
Example - Convert Set of Event Workspaces (Horace scan) to 4D MD workspace, direct mode:
Meaningfull results can be obtained on the basis of CNCS_7860_event.nxs file, available in Mantid
test folder. The script below simulates workspace loading but would produce meaningfill result if real experimental data
obtained in an experiment and stored in nxspe files are provided to it.
Output:
Example - Convert set of inelastic results obtained in Powder mode (direct) as function of temperature to a 3D workspace:
This example produces 3-dimensional dataset, with a temperature axis.
Output: