-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathRenameAlgorithm.html
322 lines (286 loc) · 14.3 KB
/
RenameAlgorithm.html
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
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Rename Algorithm</title>
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Tools Overview" href="ToolsOverview.html" />
<link rel="prev" title="Generating Code Coverage" href="CodeCoverage.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head><body>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org"><img src="_static/Mantid_Logo_Transparent.png">
</a>
<span class="navbar-text navbar-version pull-left"><b>master</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="http://download.mantidproject.org">Download</a></li>
<li><a href="http://www.mantidproject.org">Wiki</a></li>
<li><a href="http://docs.mantidproject.org">User Documentation</a></li>
<li><a href="http://www.mantidproject.org/Contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<div class="section" id="rename-algorithm">
<span id="renamealgorithm"></span><h1>Rename Algorithm<a class="headerlink" href="#rename-algorithm" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#algorithm-naming-convention" id="id1">Algorithm Naming Convention</a></li>
<li><a class="reference internal" href="#rename-c-algorithm" id="id2">Rename C++ Algorithm</a></li>
<li><a class="reference internal" href="#rename-python-algorithm" id="id3">Rename Python Algorithm</a></li>
</ul>
</div>
<p>Sometime developers will run into situations where the capability of the algorithm grows
beyond its original designated name, therefore a renaming of the algorithm is necessary
to ensure the name of the algorithm faithfully represent the functionality of given algorithm.
This document provides a recommended process to rename the algorithm while avoiding introducing
breaking changes for the general users.</p>
<div class="section" id="algorithm-naming-convention">
<h2><a class="toc-backref" href="#id1">Algorithm Naming Convention</a><a class="headerlink" href="#algorithm-naming-convention" title="Permalink to this headline">¶</a></h2>
<p>As a general purpose data process platform for global users, the names of the Mantid algorithms need
to be as self evident as possible so that users can intuitively understand the functionality and limitations
of the algorithms they are using.
To this end, it is important for Mantid developers to use clear and concise names during the renaming process.
Generally speaking, the name of a algorithm can contain up to <strong>four</strong> sections:</p>
<div class="admonition-mantid-algorithm-naming-convention admonition">
<p class="first admonition-title">Mantid Algorithm Naming Convention</p>
<p class="last">[Technique] [Instrument/Facility] Action Target</p>
</div>
<ul>
<li><p class="first">Technique</p>
<p>If given algorithm is designed for a specific technique, the algorithm name should start with the abbreviation of the
technique.
However, this section can be omitted if the algorithm is not technique specific (such as file loading and data plotting).
Here are some commonly used abbreviations of techniques</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Abbreviations</th>
<th class="head">Full Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>CWPD</strong></td>
<td>Constant Wavelength Powder Diffraction</td>
</tr>
<tr class="row-odd"><td><strong>PD</strong></td>
<td>Powder Diffraction</td>
</tr>
<tr class="row-even"><td><strong>REFL</strong></td>
<td>Reflectometry</td>
</tr>
<tr class="row-odd"><td><strong>SANS</strong></td>
<td>Small Angle Neutron Scattering</td>
</tr>
<tr class="row-even"><td><strong>SCD</strong></td>
<td>Single Crystal Diffraction</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The table above is a work in progress as more abbreviations will be added in the future.</p>
</div>
</li>
<li><p class="first">Instrument/Facility</p>
<p>As Mantid is a collaboration across many different institutes, it is very common to have some algorithms that are specifically
designed for a special instrument or a facility.
For algorithms like these, it is important to have the abbreviations of the corresponding instrument or facility clearly shown
in the name.
On the other hand, this section can be skipped if the algorithm is general enough that its application is no longer tied to a
specific instrument or facility.</p>
<ul class="simple">
<li>Here are some commonly used abbreviations of facilities</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="8%" />
<col width="92%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Abbreviations</th>
<th class="head">Full Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ILL</strong></td>
<td>Institut Laue-Langevin at GRENOBLE,France</td>
</tr>
<tr class="row-odd"><td><strong>ISIS</strong></td>
<td>ISIS Neutron and Muon Source at UK</td>
</tr>
<tr class="row-even"><td><strong>HFIR</strong></td>
<td>High Flux Isotope Reactor at ORNL,USA</td>
</tr>
<tr class="row-odd"><td><strong>SNS</strong></td>
<td>Spallation Neutron Source at ORNL,USA</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The table above is a work in progress as more abbreviations will be added in the future.</p>
</div>
<ul class="simple">
<li>Here are some commonly used abbreviations of instruments</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Abbreviations</th>
<th class="head">Full Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>CORELLI</strong></td>
<td>Elastic Diffuse Scattering Spectrometer at BL-9, SNS</td>
</tr>
<tr class="row-odd"><td><strong>POWGEN</strong></td>
<td>Powder Diffractometer at BL-11A, SNS</td>
</tr>
<tr class="row-even"><td><strong>TOPAZ</strong></td>
<td>Single-Crystal Diffractometer at BL-12, SNS</td>
</tr>
<tr class="row-odd"><td><strong>WAND2</strong></td>
<td>Wide-Angle Neutron Diffractometer at HB-2C, HFIR</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The table above is a work in progress as more abbreviations will be added in the future.</p>
</div>
</li>
<li><p class="first">Action</p>
<p>As data process platform, Mantid perform various action via algorithms, therefore it is crucial to have clear and concise description
of intended action depicted in the algorithm name.</p>
</li>
<li><p class="first">Target</p>
<p>Most of the time the action term above requires a specific receiving end, namely a target.
Depending on the action, sometimes the target can be omitted if it is self evident (such as <code class="docutils literal notranslate"><span class="pre">LoadFiles</span></code> can be simplified into <code class="docutils literal notranslate"><span class="pre">Load</span></code>).</p>
</li>
</ul>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p class="last"><code class="docutils literal notranslate"><span class="pre">SCDCalibratePanels</span></code> indicates this is a algorithm designed for single crystal diffraction technique that is not
tied to a specific instrument or facility.
It performs calibration of panel type detectors.</p>
</div>
</div>
<div class="section" id="rename-c-algorithm">
<h2><a class="toc-backref" href="#id2">Rename C++ Algorithm</a><a class="headerlink" href="#rename-c-algorithm" title="Permalink to this headline">¶</a></h2>
<p>Renaming a C++ algorithm can be achieved via the following steps:</p>
<ul>
<li><p class="first">Do a grep search (or use Github search) to locate files that call this algorithms.</p>
</li>
<li><p class="first">Rename the algorithm (header, source and unit test)</p>
<ul class="simple">
<li>Rename the header and set the original name as alias</li>
</ul>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"MantidAPI/DeprecatedAlias.h"</span><span class="cp"></span>
<span class="p">...</span>
<span class="k">class</span> <span class="nc">DLLExport</span> <span class="nl">NewAlgName</span> <span class="p">:</span> <span class="k">public</span> <span class="n">API</span><span class="o">::</span><span class="n">Algorithm</span><span class="p">,</span> <span class="k">public</span> <span class="n">API</span><span class="o">::</span><span class="n">DeprecatedAlias</span> <span class="p">{</span>
<span class="p">...</span>
<span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">alias</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"OriginalAlgName"</span><span class="p">;</span> <span class="p">};</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<ul class="simple">
<li>Set the deprecation date (the date this algorithm name changed) in the constructor in source file</li>
</ul>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">//-----------------------------------------------------------------------------------</span>
<span class="cm">/** Constructor</span>
<span class="cm">*/</span>
<span class="n">NewAlgName</span><span class="o">::</span><span class="n">NewAlgName</span><span class="p">(){</span>
<span class="n">setDeprecationDate</span><span class="p">(</span><span class="s">"2021-09-14"</span><span class="p">);</span> <span class="c1">// date string formatted like the example here</span>
<span class="p">}</span>
</pre></div>
</div>
<ul>
<li><p class="first">Update tests</p>
<p>Unit test and system tests should be the place to start with the renaming update.</p>
</li>
<li><p class="first">Update documentation page and corresponding examples</p>
</li>
</ul>
</li>
<li><p class="first">Update calls within Mantid to use the new Algorithm name</p>
</li>
<li><p class="first">Make sure list the name change in the release notes</p>
</li>
<li><p class="first">[Optional] Inform the users about the name change once pull request is merged</p>
</li>
</ul>
</div>
<div class="section" id="rename-python-algorithm">
<h2><a class="toc-backref" href="#id3">Rename Python Algorithm</a><a class="headerlink" href="#rename-python-algorithm" title="Permalink to this headline">¶</a></h2>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="CodeCoverage.html" title="Previous Chapter: Generating Code Coverage"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Generating Co...</span>
</a>
</li>
<li>
<a href="ToolsOverview.html" title="Next Chapter: Tools Overview"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Tools Overview »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>