RenameAlgorithm.rst 4.87 KB
Newer Older
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
.. _RenameAlgorithm:

=====================
Renaming an Algorithm
=====================

.. contents::
  :local:

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.


Algorithm Naming Convention
###########################

Rename C++ Algorithm
####################

Renaming a C++ algorithm can be achieved via the following steps:

* Do a grep search (or use Github search) to locate files that call this algorithms.
* Rename the algorithm (header, source and unit test)

  * Rename the header and set the original name as alias

  .. code-block:: c++

    #include "MantidAPI/DeprecatedAlias.h"
    ...
    class DLLExport NewAlgName : public API::Algorithm, public API::DeprecatedAlias {
        ...
        const std::string alias() const override { return "OriginalAlgName"; };
        ...
    }

  * Set the deprecation date (the date this algorithm name changed) in the constructor in source file

  .. code-block:: c++

    //-----------------------------------------------------------------------------------
    /** Constructor
    */
    NewAlgName::NewAlgName(){
        setDeprecationDate("2021-09-14"); // date string formatted like the example here
    }

  * Update tests

    Unit test and system tests should be the place to start with the renaming update.

  * Update documentation page and corresponding examples

* Update calls within Mantid to use the new Algorithm name

* Make sure list the name change in the release notes

* [Optional] Inform the users about the name change once pull request is merged

  .. note::

    Script ``buildconfig/move_class.py`` can help facilitate the file renaming process
    of an existing c++ algorithm. More specifically, this script will rename the header,
    source and unit test files, as well as taking care of the renaming within the
    corresponding CMake file. Still, the developer needs to dive into the source files
    to search and replace the class name manually.

    Assumming our algorithm ``OldAlgName`` resides in the ``DataHandling`` namespace,
    we would write:

  .. code-block:: bash

    python2.7 move_class.py DataHandling OldAlgName DataHandling NewAlgName


Rename Python Algorithm
#######################

Goal: given existing algorithm `AlgOldName`, we want to rename it to `AlgNewName`, and `AlgOldName` will
become a deprecated alias of `AlgNewName`.

* Replace

Replace all occurrences of `AlgOldName` with `AlgNewName` in all files. In Linux or Mac:

  .. code-block:: bash

    grep -rl AlgOldName . | xargs sed -i 's/AlgOldName/AlgNewName/g'

The names of some files will need to be replaced. Typically these will be the algorithm file, test file, and documentation

  - `algOldName.py`  (becomes "algNewName.py")
  - `algOldNameTest.py` (becomes "algNewNameTest.py")
  - `algOldName-v1.rst` (becomes "algNewName-v1.rst")

* Edit

Edit `algNewName.py`. We need to add and alias method and mark the algorithm with the alias deprecator

Below are the relevant statements to deprecate the alias on Christmas day of the year 2025

  .. code-block:: python

    from mantid.utils.deprecator import alias_deprecated

    @deprecated_alias('2025-12-25')
    class AlgNewName(PythonAlgorithm):

        def alias(self):
            r"""Alternative name to this algorithm"""
            return 'algOldName'


Configuration
=============

Upon using a deprecated alias to invoke an algorithm, a message will be printed in the log at the `error`
level. For instance, when using deprecated alias `algOldName` in place of the algorithm's name `algNewName`,
the following error message is printed:

  .. code-block:: bash

    Algorithm alias algOldName is deprecated. Use algNewName instead

If so desired, the user can raise a ``RuntimeError`` by setting property ``algorithms.alias.deprecated`` to
``Raise`` in the user properties file `$HOME/.mantid/Mantid.user.properties` or in a script:

  .. code-block:: python

    from mantid.kernel import ConfigService
    config = ConfigService.Instance()
    config['algorithms.alias.deprecated'] = 'Raise'

Coming to our previous example, a ``RuntimeError`` is printed:

  .. code-block:: bash

    RuntimeError: Use of algorithm alias algOldName not allowed. Use algNewName instead
    File "/home/username/my_script.py", line 9, in <module>
        def alias(self):
    File "/path/to/mantid/Framework/PythonInterface/mantid/simpleapi.py", line 1032, in __call__
        raise RuntimeError(f'Use of algorithm alias {self._alias.name} not allowed. Use {name} instead')

To prevent the ``RuntimeError`` and instead print a log error message, the property can be left unset or set to
"``Log``"