\(\renewcommand\AA{\unicode{x212B}}\)
ConvertToMD v1¶
Summary¶
Create a MDEventWorkspace with selected dimensions, e.g. the reciprocal space of momentums (Qx, Qy, Qz) or momentums modules mod(Q), energy transfer dE if available and any other user specified log values which can be treated as dimensions.
See Also¶
ConvertToDiffractionMDWorkspace, ConvertToMDMinMaxGlobal, ConvertToMDMinMaxLocal, CreateMDWorkspace, SetSpecialCoordinates
Properties¶
Name 
Direction 
Type 
Default 
Description 

InputWorkspace 
Input 
Mandatory 
An input Matrix Workspace (2DMatrix or Event workspace) 

QDimensions 
InOut 
string 
CopyToMD 
String, describing available analysis modes, registered with MD Transformation factory.There are 3 modes currently available and described in details on MD Transformation factory page.The modes names are CopyToMD, Q and Q3D. Allowed values: [‘CopyToMD’, ‘Q3D’, ‘Q’] 
dEAnalysisMode 
InOut 
string 
Direct 
You can analyze neutron energy transfer in Direct, Indirect or Elastic mode.The analysis mode has to correspond to experimental set up. Selecting inelastic mode increasesthe number of the target workspace dimensions by one. See MD Transformation factory for further details. Allowed values: [‘Elastic’, ‘Direct’, ‘Indirect’] 
Q3DFrames 
Input 
string 
AutoSelect 
Selects Qdimensions of the output workspace in Q3D case. AutoSelect: Choose the target coordinate frame as the function of goniometer and UB matrix values set on the input workspace. Q (lab frame): Wavevector converted into the lab frame. Q (sample frame): Wavevector converted into the frame of the sample (taking out the goniometer rotation). HKL: Use the sample’s UB matrix to convert Wavevector to crystal’s HKL indices.See MD Transformation factory (Q3D) for more details about this. Allowed values: [‘Q_lab’, ‘Q_sample’, ‘HKL’, ‘AutoSelect’] 
QConversionScales 
Input 
string 
Q in A^1 
This property to normalize three momentums obtained in Q3D mode. See MD Transformation factory for description and available scaling modes. The value can be modified depending on the target coordinate system, defined by the property OutputDimensions. Allowed values: [‘Q in A^1’, ‘Q in lattice units’, ‘Orthogonal HKL’, ‘HKL’] 
OtherDimensions 
Input 
str list 
List(comma separated) of additional to Q and DeltaE variables which form additional (orthogonal) to Q dimensions in the target workspace (e.g. Temperature or Magnetic field). These variables had to be logged during experiment and the names of these variables have to coincide with the log names for the records of these variables in the source workspace. 

PreprocDetectorsWS 
Input 
string 
PreprocessedDetectorsWS 
The name of the table workspace where the part of the detectors transformation into reciprocal space, calculated by PreprocessDetectorsToMD v1 algorithm is stored. If the workspace is not found in analysis data service, PreprocessDetectorsToMD v1 used to calculate it. If found, the algorithm uses existing workspace. The field is useful if one expects to analyze number of different experiments obtained on the same instrument… warning:: Dangerous if one uses number of workspaces with modified derived instrument one after another. In this case this property has to be set to “” sting (minus without quotes) or empty (possible from script only) to force the workspace recalculation each time the algorithm is invoked. 
UpdateMasks 
Input 
boolean 
False 
if PreprocessDetectorWS is used to build the workspace with preprocessed detectors at first algorithm call,and the input workspaces instruments are different by just different masked detectors, setting this option to true forces PreprocessDetectorsToMD v1 update only the detectors masks for all subsequent calls to this algorithm… warning:: This is temporary solution necessary until Mantid masks spectra by 0 rather then by NaN. 
LorentzCorrection 
Input 
boolean 
False 
Correct the weights of events or signals and errors transformed into reciprocal space by multiplying them by the Lorentz multiplier: \(sin(\theta)^2/\lambda^4\). Currently works in Q3D Elastic case only and is ignored in any other case. 
IgnoreZeroSignals 
Input 
boolean 
False 
Enabling this property forces the algorithm to ignore bins with zero signal for an input matrix workspace. Input event workspaces are not affected. This violates the data normalization but may substantially accelerate calculations in situations when the normalization is not important (e.g. peak finding). 
Uproj 
Input 
dbl list 
Defines the first projection vector of the target Q coordinate system in Q3D mode  Default (1,0,0) 

Vproj 
Input 
dbl list 
Defines the second projection vector of the target Q coordinate system in Q3D mode  Default (0,1,0). 

Wproj 
Input 
dbl list 
Defines the third projection vector of the target Q coordinate system in Q3D mode.  Default (0,0,1) 

AbsMinQ 
Input 
number 
0 
Do not add events to MD workspace that are closer to the origin in QSample radius than this value. Needed for 3Dviews to remove noise. 
OutputWorkspace 
Output 
Mandatory 
Name of the output MDEventWorkspace. 

OverwriteExisting 
Input 
boolean 
True 
By default (“1”), existing Output Workspace will be replaced. Select false (“0”) if you want to add new events to the workspace, which already exist. Choosing “0” can be very inefficient for filebased workspaces 
MinValues 
Input 
dbl list 
It has to be N comma separated values, where N is the number of dimensions of the target workspace. Values smaller then specified here will not be added to workspace. Number N is defined by properties 4,6 and 7 and described on MD Transformation factory page. See also ConvertToMDMinMaxLocal v1 

MaxValues 
Input 
dbl list 
A list of the same size and the same units as MinValues list. Values higher or equal to the specified by this list will be ignored 

SplitInto 
Input 
int list 
5 
A comma separated list of into how many subgrid elements each dimension should split; or just one to split into the same number for all dimensions. Default 5. 
SplitThreshold 
Input 
number 
1000 
How many events in a box before it should be split. Default 1000. 
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 
1 
Optional. If specified, then all the boxes will be split to this minimum recursion depth. 0 = no splitting, 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 is necessary if one wants to generate multiple file based workspaces in order to merge them later. 
TopLevelSplitting 
Input 
boolean 
False 
This option causes a split of the top level, i.e. level0, of 50 for the first four dimensions. 
Filename 
Input 
string 
The name of the Nexus file to write, as a full or relative path. Only used if FileBackEnd is true. Allowed extensions: [‘.nxs’] 

FileBackEnd 
Input 
boolean 
False 
If true, Filename must also be specified. The algorithm will create the specified file in addition to an output workspace. The workspace will load data from the file on demand in order to reduce memory use. 
ConverterType 
Input 
string 
Default 
[Default, Indexed], indexed is the experimental type that can speedup the conversion processfor the big files using the indexing. Allowed values: [‘Default’, ‘Indexed’] 
Description¶
The algorithm is used transform existing Event or Matrix workspace into Multidimensional workspace.
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.
Using the FileBackEnd and Filename properties the algorithm can produce a filebacked workspace. Note that this will significantly increase the execution time of the algorithm.
Used Subalgorithms¶
The algorithm uses Unit Factory and existing unit conversion procedures from the input Workspace units to the units , necessary for transformation into correspondent MD Event workspace. It also uses PreprocessDetectorsToMD v1 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, ConvertToMDMinMaxLocal v1 is used to estimate missing minmax values. This algorithm is also used to calculate minmax values if specified minmax 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 unit 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 Xvalues 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 unit 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 ConvertToMDMinMaxLocal v1 algorithm.
Indexed mode¶
Setting the ConverterType parameter to Indexed uses an alternative intermediate data format within ConvertToMD which may give significant performance boosts in certain cases.
The performance benefit of this method is dependant on the number of events in the input dataset. Once you have data files containing more than 100 million events and have at least 8 cores this method becomes worth enabling. For large files (>500 million events) performance scales well with the number of available CPU cores (i.e. using 32 cores will be notably faster than 8 cores).
Use of this method comes with the following restrictions:
SplitInto should be the power of two (i.e. 2, 4, 8, 16, etc.)
FileBackEnd and TopLevelSplitting are not applicable and should be disabled
Indexing adds a small numerical error to the event coordinates, the magnitude of this error is listed in the log (Error with using Morton indexes is)
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 Writing a Custom ConvertToMD Transformation.
Usage examples¶
Note
To run these usage examples please first download the usage data, and add these to your path. In Mantid this is done using Manage User Directories.
Example  Convert rebinned MARI 2D workspace to 3D MD workspace for further analysis/merging with data at different temperatures :
# Load Operation (disabled in test code)
# Load(Filename='MAR11001.nxspe',OutputWorkspace='MAR11001')
# Simulates Load of the workspace above #################
redWS = CreateSimulationWorkspace(Instrument='MAR',BinParams=[10,1,10],UnitX='DeltaE',OutputWorkspace='MAR11001')
AddSampleLog(redWS,LogName='Ei',LogText='12.',LogType='Number');
# Do fine rebinning, which accounts for poligon intersections
SofQW3(InputWorkspace='MAR11001',OutputWorkspace='MAR11001Qe2',QAxisBinning='0,0.1,7',EMode='Direct')
AddSampleLog(Workspace='MAR11001Qe2',LogName='T',LogText='100.0',LogType='Number Series')
# copy to new MD workspace
ws=ConvertToMD(InputWorkspace='MAR11001Qe2',OutputWorkspace='MD3',QDimensions='CopyToMD',OtherDimensions='T',\
MinValues='10,0,0',MaxValues='10,6,500',SplitInto='50,50,5')
#Output **MD3** workspace can be viewed in sliceviewer as 3D workspace with Taxis having single value.
#Visualize 3D data using slice viewer:
#plotSlice(ws)
# Look at sample results:
# A way to look at these results as a text:
print("Resulting MD workspace has {0} events and {1} dimensions".format(ws.getNEvents(),ws.getNumDims()))
print("")
Output:
Resulting MD workspace has 802 events and 3 dimensions

Example  Convert Set of Event Workspaces (Horace scan) to 4D MD workspace, direct mode:
Meaningful 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.
import os
# set up target ws name and remove target workspace with the same name which can occasionally exist.
# list of MD files (workspaces) to combine into target MD workspace
MD_FilesList='';
# define convetr to MD parameters
pars = dict();
pars['InputWorkspace']=''
pars['QDimensions']='Q3D'
pars['dEAnalysisMode']='Direct'
pars['Q3DFrames']='HKL'
pars['QConversionScales']='HKL'
pars['PreprocDetectorsWS']='preprDetMantid'
pars['MinValues']='3,3,3.,50.0'
pars['MaxValues']='3.,3.,3.,50.0'
pars['SplitInto']=50
pars['MaxRecursionDepth']=1
pars['MinRecursionDepth']=1
pars['OverwriteExisting']=1 # Change this to false, if the files should/can be added in memory
# test script combines all contributed files in memory
pars['OverwriteExisting']=0 # Change this to false, if the files should/can be added in memory
#
#> Start loop over contributing files
for n in range(0,5,1):
source_file = 'MER19566_22.0meV_one2one125.nxspe'; # redefine source files list as function of loop number
target = 'MDMAP_T1'+str(n)+'.nxs';
# check if the file already been converted to MD and is there
if not(os.path.exists(target )):
print('Converting {}'.format(source_file))
#current_ws=LoadNXSPE(Filename=source)
#### For the sample script, simulate load operation above
current_ws = CreateSimulationWorkspace(Instrument='MAR',BinParams=[3,1,3],UnitX='DeltaE',OutputWorkspace=source_file)
AddSampleLog(Workspace=current_ws,LogName='Ei',LogText='3.0',LogType='Number')
#### Add iformation which is not stored in the nxspe file
# Add UB matrix (lattice and the beam direction)
SetUB(Workspace=current_ws,a='1.4165',b='1.4165',c='1.4165',u='1,0,0',v='0,1,0')
# Add crystal rotation (assume rotation abgle Psi=5*n where n is file number. Define list of angles if this is not correct
AddSampleLog(Workspace=current_ws,LogName='Psi',LogText=str(5*n)+'.',LogType='Number') # correct Psi value may be already in nxspe file. This operation is then unnecessary
# set crystal rotation
SetGoniometer(Workspace=current_ws,Axis0='Psi,0,1,0,1')
# Convert to MD
pars['InputWorkspace']=current_ws;
md_ws=ConvertToMD(**pars)
# save MD for further usage  disabled in test script
#SaveMD(md_ws,Filename=target);
#DeleteWorkspace(md_ws); # delete intermediate workspace to save memory
DeleteWorkspace(current_ws);
# add the file name of the file to combine
if (len(MD_FilesList) == 0):
MD_FilesList = target;
else:
MD_FilesList=MD_FilesList+','+target;
#> End loop
# merge md files into filebased MD workspace
#md_ws = MergeMDFiles(MD_FilesList,OutputFilename='TestSQW_1.nxs',Parallel='0');
# plot results using sliceviewer
#plotSlice(md_ws)
# produce some test output
print("Resulting MD workspace contains {0} events and {1} dimensions".format(md_ws.getNEvents(),md_ws.getNumDims()))
print("")
Output:
Converting MER19566_22.0meV_one2one125.nxspe
Converting MER19566_22.0meV_one2one125.nxspe
Converting MER19566_22.0meV_one2one125.nxspe
Converting MER19566_22.0meV_one2one125.nxspe
Converting MER19566_22.0meV_one2one125.nxspe
Resulting MD workspace contains 27540 events and 4 dimensions

Example  Convert set of inelastic results obtained in Powder mode (direct) as function of temperature to a 3D workspace:
This example produces 3dimensional dataset, with a temperature axis.
# set up target ws name and remove target workspace with the same name which can occasionally exist.
RezWS = 'WS_3D'
try:
DeleteWorkspace(RezWS)
except ValueError:
print("Target ws {} not found in analysis data service\n".format(RezWS))
# define convert to MD parameters
pars = dict();
pars['InputWorkspace']=''
pars['QDimensions']='Q'
pars['dEAnalysisMode']='Direct'
pars['OtherDimensions']='T' # make temperature log to be a dimension
pars['PreprocDetectorsWS']='preprDetMantid'
pars['MinValues']='0,10,0'
pars['MaxValues']='12,10,10'
pars['SplitInto']='100,100,12'
pars['OverwriteExisting']=0 # contributed MD worskpaces are added in memory
# let's assume this is the temperature range obtained in experiments and
# each data file is obtained for particular temperature.
T = [1.0,2.0,3.0,3.5,4.0,5.0,6.0,7.0,8.0,9.0,9.5,10.0]
for i in range(0,len(T),1):
# source = sorurce_file_name[i];
#current_ws=LoadNXSPE(Filename=source)
# EMULATE LOAD OF DIFFERENT results obtained for different temperatures. >
current_ws = CreateSimulationWorkspace(Instrument='MAR',BinParams=[3,0.1,3],UnitX='DeltaE')
AddSampleLog(Workspace=current_ws,LogName='Ei',LogText='3.0',LogType='Number')
# if the file does not have temperature log, add it here.
AddSampleLog(Workspace=current_ws,LogName='T',LogText=str(T[i]),LogType='Number Series')
# simulate changes in scattering with temperature
current_ws = current_ws*T[i];
# END EMULATION 
pars['InputWorkspace']=current_ws;
md_ws=ConvertToMD(**pars)
# delete source workspace from memory;
DeleteWorkspace(current_ws)
# end loop
# produce some test output
print("Resulting MD workspace contains {0} events and {1} dimensions".format(md_ws.getNEvents(),md_ws.getNumDims()))
Output:
Target ws WS_3D not found in analysis data service
Resulting MD workspace contains 605880 events and 3 dimensions
Example  Convert to Qspace, indexed version:
1#.. testcode:: ExConvertToMDQ
2
3# load test workspace
4TOPAZ_3132_event = Load(Filename=r'TOPAZ_3132_event.nxs', ConverterType='Indexed')
5
6# build peak workspace necessary for IntegrateEllipsoids algorithm to work
7TOPAZ_3132_md = ConvertToMD(InputWorkspace=TOPAZ_3132_event,QDimensions='Q3D',dEAnalysisMode='Elastic',Q3DFrames='Q_sample',LorentzCorrection='1',\
8MinValues='25,25,25',MaxValues='25,25,25',SplitInto='4',SplitThreshold='50',MaxRecursionDepth='13',MinRecursionDepth='7')
9
10# produce some test output
11print("Resulting MD workspace contains {0} events and {1} dimensions".format(TOPAZ_3132_md.getNEvents(),TOPAZ_3132_md.getNumDims()))
Output:
Resulting MD workspace contains 15329354 events and 3 dimensions
Categories: AlgorithmIndex  MDAlgorithms\Creation
Source¶
C++ header: ConvertToMD.h
C++ source: ConvertToMD.cpp