-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathWritingCustomConvertToMDTransformation.html
More file actions
640 lines (491 loc) · 41 KB
/
Copy pathWritingCustomConvertToMDTransformation.html
File metadata and controls
640 lines (491 loc) · 41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
<!DOCTYPE html>
<html lang="en" data-content_root="./" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Writing a Custom ConvertToMD Transformation — MantidProject main documentation</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
</script>
<!--
this give us a css class that will be invisible only if js is disabled
-->
<noscript>
<style>
.pst-js-only { display: none !important; }
</style>
</noscript>
<!-- Loaded before other Sphinx assets -->
<link href="_static/styles/theme.css?digest=0790524f97105ba85085" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=0790524f97105ba85085" rel="stylesheet" />
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="_static/css/style.css?v=562d7d41" />
<!-- So that users can add custom icons -->
<script defer src="_static/scripts/fontawesome.js?digest=0790524f97105ba85085"></script>
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=0790524f97105ba85085" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=0790524f97105ba85085" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'WritingCustomConvertToMDTransformation';</script>
<script>DOCUMENTATION_OPTIONS.search_as_you_type = false;</script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="ISIS Energy Transfer Tab" href="ISISEnergyTransferTab.html" />
<link rel="prev" title="Dynamic dialog properties" href="DynamicProperties.html" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="docsearch:language" content="en">
<link rel="icon" sizes="32x32" href="_static/images/favicon.ico">
</head>
<body data-default-mode="">
<div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>Back to top</button>
<dialog id="pst-search-dialog">
<form class="bd-search d-flex align-items-center"
action="search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
</dialog>
<div class="pst-async-banner-revealer d-none">
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>
<header id="pst-header" class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
<button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
<span class="fa-solid fa-bars"></span>
</button>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="index.html">
<img src="_static/images/mantid_logo_light.png" class="logo__image only-light" alt="Logo image">
<img src="_static/images/mantid_logo_dark.png" class="logo__image only-dark" alt="Logo image">
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item"><ul id="navbar-main-elements" class="navbar-nav">
<li class="nav-item">
<a class="reference internal nav-link" href="https://download.mantidproject.org">Downloads</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/nightly/tutorials/">Tutorials</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org">User Docs</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://developer.mantidproject.org">Develop</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/release/">Release notes</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://www.mantidproject.org/contact">Contact Us</a>
</li>
</ul></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<div class="navbar-item">
<div class="theme-switch-container dropdown pst-js-only" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Color mode">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button dropdown-toggle" aria-label="Color mode" data-bs-toggle="dropdown">
<i class="theme-switch fa-solid fa-sun fa-lg fa-fw" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg fa-fw" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg fa-fw" data-mode="auto" title="System Settings"></i>
</button>
<ul class="dropdown-menu dropdown-menu-end">
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg fa-fw me-1"></i>System Settings</button></li>
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="light"><i class="fa-solid fa-sun fa-lg fa-fw me-1"></i>Light</button></li>
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="dark"><i class="fa-solid fa-moon fa-lg fa-fw me-1"></i>Dark</button></li>
</ul>
</div></div>
<div class="navbar-item"><ul id="navbar-icon-links" class="navbar-nav" aria-label="Icon Links">
<li class="nav-item">
<a class="nav-link" href="https://github.com/mantidproject/mantid" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
<span class="fa-solid fa-outdent"></span>
</button>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<dialog id="pst-primary-sidebar-modal"></dialog>
<div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item"><ul id="navbar-main-elements" class="navbar-nav">
<li class="nav-item">
<a class="reference internal nav-link" href="https://download.mantidproject.org">Downloads</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/nightly/tutorials/">Tutorials</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org">User Docs</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://developer.mantidproject.org">Develop</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/release/">Release notes</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://www.mantidproject.org/contact">Contact Us</a>
</li>
</ul></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<div class="theme-switch-container dropdown pst-js-only" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Color mode">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button dropdown-toggle" aria-label="Color mode" data-bs-toggle="dropdown">
<i class="theme-switch fa-solid fa-sun fa-lg fa-fw" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg fa-fw" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg fa-fw" data-mode="auto" title="System Settings"></i>
</button>
<ul class="dropdown-menu dropdown-menu-end">
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg fa-fw me-1"></i>System Settings</button></li>
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="light"><i class="fa-solid fa-sun fa-lg fa-fw me-1"></i>Light</button></li>
<li><button class="dropdown-item d-flex align-items-center theme-change-button" data-mode="dark"><i class="fa-solid fa-moon fa-lg fa-fw me-1"></i>Dark</button></li>
</ul>
</div></div>
<div class="navbar-item"><ul id="navbar-icon-links" class="navbar-nav" aria-label="Icon Links">
<li class="nav-item">
<a class="nav-link" href="https://github.com/mantidproject/mantid" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item pst-sidebar-collapse"><button id="pst-collapse-sidebar-button" aria-expanded="true" aria-controls="pst-primary-sidebar"><svg class="pst-icon svg-inline--fa" role="img" aria-hidden="true" focusable="false" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
<path fill="currentColor" d="M3 15.5C2.36232 15.5 1.74874 15.2564 1.28478 14.8189C0.820828 14.3815 0.541576 13.7832 0.504167 13.1467L0.5 13L0.5 3C0.499965 2.36232 0.743605 1.74874 1.18107 1.28478C1.61854 0.820828 2.21676 0.541576 2.85333 0.504167L3 0.5L13 0.5C13.6377 0.499965 14.2513 0.743605 14.7152 1.18107C15.1792 1.61854 15.4584 2.21676 15.4958 2.85333L15.5 3L15.5 13C15.5 13.6377 15.2564 14.2513 14.8189 14.7152C14.3815 15.1792 13.7832 15.4584 13.1467 15.4958L13 15.5L3 15.5ZM3 13.8333L10.5 13.8333L10.5 2.16667L3 2.16667C2.79589 2.16669 2.59889 2.24163 2.44636 2.37726C2.29383 2.5129 2.19638 2.69979 2.1725 2.9025L2.16667 3L2.16667 13C2.16669 13.2041 2.24163 13.4011 2.37726 13.5536C2.5129 13.7062 2.69979 13.8036 2.9025 13.8275L3 13.8333ZM6.65583 10.325L6.5775 10.2558L4.91083 8.58917C4.76735 8.44567 4.68116 8.25476 4.66843 8.05223C4.65569 7.84971 4.71729 7.6495 4.84167 7.48917L4.91083 7.41083L6.5775 5.74417C6.72747 5.59471 6.9287 5.50794 7.14032 5.50148C7.35194 5.49502 7.55809 5.56935 7.7169 5.70937C7.8757 5.8494 7.97525 6.04463 7.99533 6.25539C8.01541 6.46616 7.95451 6.67667 7.825 6.84417L7.75583 6.9225L6.67917 8L7.75583 9.0775C7.89931 9.22099 7.98551 9.41191 7.99824 9.61443C8.01097 9.81695 7.94938 10.0172 7.825 10.1775L7.75583 10.2558C7.61234 10.3993 7.42142 10.4855 7.2189 10.4982C7.01638 10.511 6.81617 10.4494 6.65583 10.325Z"/>
</svg>
<span class="pst-collapse-sidebar-label">Collapse Sidebar</span>
<span class="pst-expand-sidebar-label">Expand Sidebar</span>
</button></div>
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"></div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
<div class="sidebar-primary-item">
<div id="ethical-ad-placement"
class="flat"
data-ea-publisher="readthedocs"
data-ea-type="readthedocs-sidebar"
data-ea-manual="true">
</div></div>
</div>
</div>
<main id="main-content" class="bd-main" role="main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb" class="d-print-none">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">Writing a Custom ConvertToMD Transformation</span></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="writing-a-custom-converttomd-transformation">
<span id="writingcustomconverttomdtransformation"></span><h1>Writing a Custom ConvertToMD Transformation<a class="headerlink" href="#writing-a-custom-converttomd-transformation" title="Link to this heading">#</a></h1>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">#</a></h2>
<p>This information is intended for a developer who needs to write a customized
<a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/ConvertToMD-v1.html#algm-converttomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">ConvertToMD class</span></a> (plugin). The
plugin then becomes automatically available to use in the
<a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/ConvertToMD-v1.html#algm-converttomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">ConvertToMD</span></a> algorithm.</p>
<p>As the MD transformation factory is similar to the <a class="reference external" href="https://docs.mantidproject.org/nightly/concepts/DynamicFactory.html#dynamic-factory" title="(in MantidProject v6.15)"><span class="xref std std-ref">Dynamic Factory</span></a>
used for converting <a class="reference external" href="https://docs.mantidproject.org/nightly/api/python/mantid/kernel/UnitFactoryImpl.html#mantid.kernel.UnitFactoryImpl" title="(in MantidProject v6.15)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Units</span></code></a>, the
procedure of writing a custom <code class="docutils literal notranslate"><span class="pre">ConvertToMD</span></code> transformation is very similar to adding a new unit to use
with <a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/ConvertUnits-v1.html#algm-convertunits-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">ConvertUnits</span></a> algorithm
or writing a new algorithm to use with Mantid.</p>
<p>The plugin interface deals with the task of converting a generic n-dimensional point of a <code class="docutils literal notranslate"><span class="pre">MatrixWorkspace</span></code>
into a generic m-dimensional point of an <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code> using the necessary parameters.</p>
<p>Examples of such transformations could be a conversion of signal and error at detector num
at specific time of flight plus log values for temperature and pressure (<strong>The instrument’s
space</strong>: 4 numbers + information about the detector) into 6-D point in the <strong>Physical space
qx,qy,qz,dE,T,P</strong> (qx,qy,qz – the components of momentum transfer) or into 3-D point in
<strong>Physical space |Q|,dE,Fugacity</strong> (|Q| - modulus of momentum transfer).</p>
</section>
<section id="writing-a-simple-custom-plugin">
<h2>Writing a simple custom plugin<a class="headerlink" href="#writing-a-simple-custom-plugin" title="Link to this heading">#</a></h2>
<section id="summary">
<h3>Summary<a class="headerlink" href="#summary" title="Link to this heading">#</a></h3>
<p>If a single point of a <code class="docutils literal notranslate"><span class="pre">MatrixWorkspace</span></code> together with correspondent log files can be converted into a single
<code class="docutils literal notranslate"><span class="pre">MDEvent</span></code> (multidimensional point of MD workspace), a simple custom plugin can be written to do this transformation.
The existing framework in this case deals with all other tasks, namely the iterations over source workspace,
conversion of the workspace units into the units of the conversion formula, defining the target workspace,
constructing <code class="docutils literal notranslate"><span class="pre">MDEvent</span></code> instances and adding these events to the <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code>.</p>
<p>A <code class="docutils literal notranslate"><span class="pre">ConvertToMD</span></code> plugin implements <code class="docutils literal notranslate"><span class="pre">MDTransfInterface</span></code>, so to write a plugin you must write a class
which inherits from this interface and register this class with <code class="docutils literal notranslate"><span class="pre">MDTransfFactory</span></code>. The macro to
register the class with the factory is similar to the macro used to register an algorithm with
Mantid or a <code class="docutils literal notranslate"><span class="pre">Unit</span></code> class with the Unit conversion factory. The macro is located in <code class="docutils literal notranslate"><span class="pre">MDTransfFactory.h</span></code>.</p>
<p>The class inheriting from <code class="docutils literal notranslate"><span class="pre">MDTransfInterface</span></code> performs two tasks:</p>
<ul class="simple">
<li><p>Define the target <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code> and its dimensions (both the number of dimensions and the dimension units).</p></li>
<li><p>Initialize the transformation and define a formula to transform a single point of input data into output data.</p></li>
</ul>
<p>These two tasks are mainly independent, but implemented within a single class to be handled by the single dynamic factory.
<strong>Note that the functions which define the target MDWorkspace are called before the MDTransfFactory initialize function.</strong>
The <code class="docutils literal notranslate"><span class="pre">initialize</span></code> function accepts the <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code> description and is expected to fully define all class variables used during
the transformation from a point of a <code class="docutils literal notranslate"><span class="pre">MatrixWorkspace</span></code> into an MD point of a target <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code>.</p>
</section>
<section id="workflow">
<h3>Workflow<a class="headerlink" href="#workflow" title="Link to this heading">#</a></h3>
<p>This workflow is implemented in the <code class="docutils literal notranslate"><span class="pre">ConvertToMD</span></code> algorithm’s <code class="docutils literal notranslate"><span class="pre">exec()</span></code> function.</p>
<ol class="arabic simple">
<li><p>Select a conversion and obtain additional algorithm parameters from the algorithm interface.</p></li>
<li><p>Build <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code> description (call <code class="docutils literal notranslate"><span class="pre">MDTransfFactory</span></code> and ask for the conversion plugin parameters).</p></li>
<li><p>Build new <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code> on the basis of its description (if new workspace is requested or check if existing workspace is suitable).</p></li>
<li><p>Initialize the conversion plugin (using <code class="docutils literal notranslate"><span class="pre">MDWSDescription</span></code>).</p></li>
<li><p>Run the conversion itself by looping over detectors and their values (use <code class="docutils literal notranslate"><span class="pre">MDTransfFactory</span></code> and selected conversion plugin to convert
each input point into output MD point).</p></li>
</ol>
<p>The <code class="docutils literal notranslate"><span class="pre">MDTransformationFactory</span></code> is deployed twice during the conversion. The methods used during each conversion stage are clearly
specified in <code class="docutils literal notranslate"><span class="pre">MDTransformationInterface.h</span></code>.</p>
</section>
<section id="defining-the-target-workspace">
<h3>Defining the target workspace<a class="headerlink" href="#defining-the-target-workspace" title="Link to this heading">#</a></h3>
<p>This describes steps 1-3 of the workflow.</p>
<p>The input data at this stage are the name of the plugin and the outputs – the information necessary for the transformation to work
including the number of output dimensions, units for the selected physical transformation formula, units of the target workspace, etc.</p>
<p>The methods used while defining the workspace should not access or change anything accessed through this pointer of
the custom plugin. The result of the first stage is a <code class="docutils literal notranslate"><span class="pre">MDWSDescription</span></code> class, which can be considered
as a large XML string that provides a common interface to different data obtained from the algorithm’s parameters.
Any data users want to transfer to the custom plugin can be added to this class, as long as this does not lead to
excessive memory usage or overhead.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">MDWSDescription</span></code> class is copy constructable and assignable and if these operators fail due to the changes
to the class, custom copy constructor and assignment operators have to be defined.</p>
</section>
<section id="doing-the-transformation">
<h3>Doing the transformation<a class="headerlink" href="#doing-the-transformation" title="Link to this heading">#</a></h3>
<p>This describes steps 4-5 of the workflow.</p>
<p>The input data at this stage are points of the “Experimental Space”, e.g. coordinates of points in the input workspace and
additional information about these points, e.g. detectors coordinates and log files for values of interest. The output values
are the vectors of the coordinates of the selected points in the space of interest and (possibly) modified/corrected values of
the signal and error at this point.</p>
<p>During the second stage of the transformation, the algorithm calculates the multidimensional coordinates of MD points in the
target workspace, places these coordinates into an MD vector of coordinates and modifies the neutron signal/error if necessary
(e.g. Lorentz corrections). This stage can be best described by the pseudo-code below. It describes performing the conversion
over the whole workspace:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cm">/** initialize all internal variables used for transformation of workspace into MD workspace</span>
<span class="cm"> WorkspaceDescription -- the workspace description obtained on the first stage of the transformation */</span>
<span class="n">plugin</span><span class="o">-></span><span class="n">initialize</span><span class="p">(</span><span class="n">WorkspaceDescription</span><span class="p">);</span>
<span class="cm">/** calculate generic variables, which are usually placed in logs and do not depend on detectors positions</span>
<span class="cm"> or neutron counts (e.g. temperature) and place these values into proper position in the coordinates vector. */</span>
<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">plugin</span><span class="o">-></span><span class="n">calcGenericVariables</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">coord_t</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">Coord</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">N_Dimensions</span><span class="p">))</span>
<span class="w"> </span><span class="k">return</span><span class="p">;</span><span class="w"> </span><span class="c1">// finish if these data are out of range requested</span>
<span class="k">for</span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="n">in</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">detectors</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="cm">/** Here we calculate all MD coordinates which depend on detectors position only. The plugin also</span>
<span class="cm"> changes the internal plugin values which depend on detector's position e.g. sets up the unit conversion */</span>
<span class="w"> </span><span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">plugin</span><span class="o">-></span><span class="n">calcYDepCoordinates</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">coord_t</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">Coord</span><span class="p">,</span><span class="kt">size_t</span><span class="w"> </span><span class="n">i</span><span class="p">))</span>
<span class="w"> </span><span class="k">continue</span><span class="p">;</span><span class="w"> </span><span class="c1">// skip detector if these data are out of range requested</span>
<span class="w"> </span><span class="cm">/** obtain signal and error, array, corresponding to the i-th detector */</span>
<span class="w"> </span><span class="n">spectra</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">InputWorkspace</span><span class="o">-></span><span class="n">getSpectraCorrespondingToTheDetector</span><span class="p">(</span><span class="kt">size_t</span><span class="w"> </span><span class="n">i</span><span class="p">);</span>
<span class="w"> </span><span class="cm">/**Convert units into the units, requested by the plugin */</span>
<span class="w"> </span><span class="n">MantidVector</span><span class="w"> </span><span class="n">X</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">convertUnits</span><span class="p">(</span><span class="n">spectra</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">X_coordinates</span><span class="p">);</span>
<span class="w"> </span><span class="k">for</span><span class="p">(</span><span class="n">j</span><span class="w"> </span><span class="n">in</span><span class="w"> </span><span class="n">spectra</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">Signal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spectra</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">Signal</span><span class="p">[</span><span class="n">j</span><span class="p">];</span>
<span class="w"> </span><span class="n">Error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spectra</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">Error</span><span class="p">[</span><span class="n">j</span><span class="p">];</span>
<span class="w"> </span><span class="cm">/**Calculate remaining MD coordinates and put them into vector of coordinates.</span>
<span class="cm"> Modify Signal and error if the signal and error depends on Coord */</span>
<span class="w"> </span><span class="n">plugin</span><span class="o">-></span><span class="n">calcMatrixCoordinates</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">MantidVec</span><span class="o">&</span><span class="w"> </span><span class="n">X</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">j</span><span class="p">,</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">coord_t</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">Coord</span><span class="p">,</span><span class="w"> </span><span class="n">Signal</span><span class="p">,</span><span class="w"> </span><span class="n">Error</span><span class="p">);</span>
<span class="w"> </span><span class="cm">/**Convert Coord signal and error to MD event with coordinate Coord and add the MDEvent to MD workspace*/</span>
<span class="w"> </span><span class="n">AddPointToMDWorkspace</span><span class="p">(</span><span class="n">Coord</span><span class="p">,</span><span class="n">Signal</span><span class="p">,</span><span class="n">Error</span><span class="p">);</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="preprocessdetectorstomd-with-custom-plugins">
<h3>PreprocessDetectorsToMD with custom plugins<a class="headerlink" href="#preprocessdetectorstomd-with-custom-plugins" title="Link to this heading">#</a></h3>
<p>Unit conversion uses the angular positions and sample-detector distances.
This information is usually expensive to calculate so it is calculated separately by the
<a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/PreprocessDetectorsToMD-v1.html#algm-preprocessdetectorstomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">PreprocessDetectorsToMD</span></a> algorithm.
The detector information can be extracted directly from the input workspace, but consider checking the table workspace
returned by <a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/PreprocessDetectorsToMD-v1.html#algm-preprocessdetectorstomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">PreprocessDetectorsToMD</span></a>
and check if the information is already provided there.</p>
<p><a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/PreprocessDetectorsToMD-v1.html#algm-preprocessdetectorstomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">PreprocessDetectorsToMD</span></a> can also
be modified to add some additional detector information. This information can then be added to the resulting table workspace
and used in the custom plugin.
All currently existing plugins use the information about the detector’s positions calculated by
<a class="reference external" href="https://docs.mantidproject.org/nightly/algorithms/PreprocessDetectorsToMD-v1.html#algm-preprocessdetectorstomd-v1" title="(in MantidProject v6.15)"><span class="xref std std-ref">PreprocessDetectorsToMD</span></a>.</p>
</section>
</section>
<section id="complex-transformations">
<h2>Complex Transformations<a class="headerlink" href="#complex-transformations" title="Link to this heading">#</a></h2>
<p>It is possible that the approach of converting a single point of a <code class="docutils literal notranslate"><span class="pre">MatrixWorkspace</span></code> into a single <code class="docutils literal notranslate"><span class="pre">MDEvent</span></code> is
incorrect or inefficient for what is required. In this situation, more complex changes to the conversion framework
have to be implemented.
To make the changes one needs to understand the interaction between different classes involved in the conversion.</p>
<p>The class diagram with all main classes involved in the conversion is presented below:</p>
<figure class="align-default">
<img alt="ConvertToMDClassDiagram.gif" src="_images/ConvertToMDClassDiagram.gif" />
</figure>
<p>Two factories are involved into the conversion. <code class="docutils literal notranslate"><span class="pre">MDTransfFactory</span></code> deals with different formulae to
transform a single matrix point into an MD point. The other factory (<code class="docutils literal notranslate"><span class="pre">ConvToMDSelector</span></code> and the algorithm inheriting
from <code class="docutils literal notranslate"><span class="pre">ConvToMDBase</span></code>) deal with different kinds of workspaces. There are currently two workspaces that can be transformed
into an <code class="docutils literal notranslate"><span class="pre">MDWorkspace</span></code>, namely <code class="docutils literal notranslate"><span class="pre">EventWorkspace</span></code> and <code class="docutils literal notranslate"><span class="pre">MatrixWorkspace</span></code>. <code class="docutils literal notranslate"><span class="pre">ConvToMDSelector</span></code> identifies which algorithm to
deploy based on the input workspace.</p>
<p>If the input workspace has some special properties (e.g. a workspace obtained for an experiment with a rotating crystal,
which has special units of time of flight with a special time series attached which describe a crystal position),
the <code class="docutils literal notranslate"><span class="pre">ConvToMDSelector</span></code> should be modified to identify such a workspace and an additional class inheriting from
<code class="docutils literal notranslate"><span class="pre">ConvToMDBase</span></code> to deal with such workspaces has to be written.</p>
<p>There are two other important classes in the diagram. The first one is <code class="docutils literal notranslate"><span class="pre">MDWSDescription</span></code>, briefly mentioned above.
The purpose of this class is to collect all input information from the algorithm interface and transfer this information
through the common interface in a way convenient for a plugin to use. The user who is writing his own plugin is expected to
add all the information necessary for the plugin to work to this class.</p>
<p>Another is the <code class="docutils literal notranslate"><span class="pre">MDEventWSWrapper</span></code>. This class interfaces <code class="docutils literal notranslate"><span class="pre">MDEventWorkspace</span></code>. The <code class="docutils literal notranslate"><span class="pre">MDEventWorkspace</span></code> is templated by number
of dimensions and the purpose of <code class="docutils literal notranslate"><span class="pre">MDEventWSWrapper</span></code> is to provide a unified interface to this workspace regardless of the
number of workspace dimensions calculated during the run. It uses <code class="docutils literal notranslate"><span class="pre">MDEventWorkspace</span></code> methods for which the
<code class="docutils literal notranslate"><span class="pre">IMDWorkspace</span></code> interface to the <code class="docutils literal notranslate"><span class="pre">MDEventWorkspace</span></code> is not efficient. You do not usually need to modify this class unless
you are modifying <code class="docutils literal notranslate"><span class="pre">MDEventWorkspace</span></code> code.</p>
</section>
</section>
</article>
<footer class="prev-next-footer d-print-none">
<div class="prev-next-area">
<a class="left-prev"
href="DynamicProperties.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">Dynamic dialog properties</p>
</div>
</a>
<a class="right-next"
href="ISISEnergyTransferTab.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">ISIS Energy Transfer Tab</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<dialog id="pst-secondary-sidebar-modal"></dialog>
<div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav id="pst-page-toc-nav" class="page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="pst-show_toc_level nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#introduction">Introduction</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#writing-a-simple-custom-plugin">Writing a simple custom plugin</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#summary">Summary</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#workflow">Workflow</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#defining-the-target-workspace">Defining the target workspace</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#doing-the-transformation">Doing the transformation</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#preprocessdetectorstomd-with-custom-plugins">PreprocessDetectorsToMD with custom plugins</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#complex-transformations">Complex Transformations</a></li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection sourcelink">
<a href="_sources/WritingCustomConvertToMDTransformation.rst.txt">
<i class="fa-solid fa-file-lines"></i> Show Source
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script defer src="_static/scripts/bootstrap.js?digest=0790524f97105ba85085"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=0790524f97105ba85085"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 2007-2026, Mantid.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
<br/>
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
<!-- # L10n: Setting the PST URL as an argument as this does not need to be localized -->
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.18.0.
</p></div>
</div>
</div>
</footer>
</body>
</html>