Merge pull request #32527 from mantidproject/PL95_deprecatedAliasCPP_ornlnext

Pl95 deprecated alias cpp ornlnext

Framework/API/CMakeLists.txt

@@ -30,6 +30,7 @@ set(SRC_FILES
     src/CostFunctionFactory.cpp
     src/DataProcessorAlgorithm.cpp
     src/DeprecatedAlgorithm.cpp
+    src/DeprecatedAlias.cpp
     src/DetectorSearcher.cpp
     src/DistributedAlgorithm.cpp
     src/DomainCreatorFactory.cpp
@@ -202,6 +203,7 @@ set(INC_FILES
     inc/MantidAPI/DataProcessorAlgorithm.h
     inc/MantidAPI/DeclareUserAlg.h
     inc/MantidAPI/DeprecatedAlgorithm.h
+    inc/MantidAPI/DeprecatedAlias.h
     inc/MantidAPI/DetectorSearcher.h
     inc/MantidAPI/DistributedAlgorithm.h
     inc/MantidAPI/DomainCreatorFactory.h

Framework/API/inc/MantidAPI/Algorithm.h

@@ -168,8 +168,11 @@ public:
   /// Function to return all of the seeAlso (these are not validated) algorithms
   /// related to this algorithm.A default implementation is provided.
   const std::vector<std::string> seeAlso() const override { return {}; };
-  /// function to return any aliases to the algorithm;  A default implementation is provided
+  /// Function to return any aliases to the algorithm;  A default implementation
+  /// is provided
   const std::string alias() const override { return ""; }
+  /// Flag to indicate if the algorithm is called by its alias.
+  bool calledByAlias = false;
 
   /// function to return URL for algorithm documentation; A default
   /// implementation is provided.

Framework/API/inc/MantidAPI/DeprecatedAlias.h

+// Mantid Repository : https://github.com/mantidproject/mantid
+//
+// Copyright © 2021 ISIS Rutherford Appleton Laboratory UKRI,
+//   NScD Oak Ridge National Laboratory, European Spallation Source,
+//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
+// SPDX - License - Identifier: GPL - 3.0 +
+#pragma once
+
+#include "MantidAPI/Algorithm.h"
+#include "MantidAPI/DllConfig.h"
+#include "MantidAPI/IAlgorithm.h"
+#include <string>
+
+namespace Mantid {
+namespace API {
+
+/** DeprecatedAlias :
+ * Class for making algorithm with deprecated names (aliases).
+ *
+ * This class will ensure that if an algorithm is invoke with a deprecated name,
+ * - a warning will be throw to inform the users that
+ *   - the algorithm name is deprecated
+ *   - the deprecation date
+ *   - the new algorithm name the user is recommended to use instead
+ *
+ * All algorithms with deprecated alias need to inherit from this class.
+ *
+ * The recommended algorithm naming pattern should be
+ * [Technique][Facility/Instrument]ActionTarget
+ * For example: the calibration routine of panel detector for single crystal diffraction
+ *              beamline can be named as SCDCalibratePanels
+ */
+class MANTID_API_DLL DeprecatedAlias {
+public:
+  DeprecatedAlias();
+  virtual ~DeprecatedAlias();
+  std::string deprecationMessage(const IAlgorithm *);
+  void setDeprecationDate(const std::string &date);
+
+private:
+  /// Deprecation date
+  std::string m_deprecationDate;
+};
+
+} // namespace API
+} // namespace Mantid

Framework/API/src/Algorithm.cpp

@@ -10,6 +10,7 @@
 #include "MantidAPI/AlgorithmManager.h"
 #include "MantidAPI/AnalysisDataService.h"
 #include "MantidAPI/DeprecatedAlgorithm.h"
+#include "MantidAPI/DeprecatedAlias.h"
 #include "MantidAPI/IWorkspaceProperty.h"
 #include "MantidAPI/WorkspaceGroup.h"
 #include "MantidAPI/WorkspaceHistory.h"
@@ -511,12 +512,21 @@ bool Algorithm::executeInternal() {
   Timer timer;
   bool algIsExecuted = false;
   AlgorithmManager::Instance().notifyAlgorithmStarting(this->getAlgorithmID());
+
+  // runtime check for deprecation warning
   {
     auto *depo = dynamic_cast<DeprecatedAlgorithm *>(this);
     if (depo != nullptr)
       getLogger().error(depo->deprecationMsg(this));
   }
 
+  // runtime check for deprecated alias warning
+  {
+    auto *da_alg = dynamic_cast<DeprecatedAlias *>(this);
+    if ((da_alg != nullptr) && (this->calledByAlias))
+      getLogger().warning(da_alg->deprecationMessage(this));
+  }
+
   // Register clean up tasks that should happen regardless of the route
   // out of the algorithm. These tasks will get run after this method
   // finishes.

Framework/API/src/AlgorithmFactory.cpp

@@ -35,8 +35,8 @@ AlgorithmFactoryImpl::AlgorithmFactoryImpl() : Kernel::DynamicFactory<Algorithm>
 AlgorithmFactoryImpl::~AlgorithmFactoryImpl() = default;
 
 /** Creates an instance of an algorithm
- * @param name :: the name of the Algrorithm to create
- * @param version :: the version of the algroithm to create
+ * @param name :: the name of the Algorithm to create
+ * @param version :: the version of the algorithm to create
  * @returns a shared pointer to the created algorithm
  */
 std::shared_ptr<Algorithm> AlgorithmFactoryImpl::create(const std::string &name, const int &version) const {
@@ -58,7 +58,9 @@ std::shared_ptr<Algorithm> AlgorithmFactoryImpl::create(const std::string &name,
   if (realName) {
     // Try create algorithm again with real name
     try {
-      return this->createAlgorithm(realName.get(), local_version);
+      auto alg = this->createAlgorithm(realName.get(), local_version);
+      alg->calledByAlias = true;
+      return alg;
     } catch (Kernel::Exception::NotFoundError &) {
       // Get highest registered version
       const auto hVersion = highestVersion(realName.get()); // Throws if not found
@@ -210,7 +212,7 @@ const std::vector<std::string> AlgorithmFactoryImpl::getKeys(bool includeHidden)
 
 /**
  * @param alias The name of the algorithm to look up in the alias map
- * @return Real name of algroithm if found
+ * @return Real name of algorithm if found
  */
 boost::optional<std::string> AlgorithmFactoryImpl::getRealNameFromAlias(const std::string &alias) const noexcept {
   auto a_it = m_amap.find(alias);

Framework/API/src/DeprecatedAlias.cpp

+// Mantid Repository : https://github.com/mantidproject/mantid
+//
+// Copyright © 2021 ISIS Rutherford Appleton Laboratory UKRI,
+//   NScD Oak Ridge National Laboratory, European Spallation Source,
+//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
+// SPDX - License - Identifier: GPL - 3.0 +
+
+#include "MantidAPI/DeprecatedAlias.h"
+#include "MantidAPI/AlgorithmFactory.h"
+#include "MantidKernel/Logger.h"
+#include "MantidTypes/Core/DateAndTimeHelpers.h"
+
+namespace Mantid {
+namespace API {
+
+namespace {
+Kernel::Logger g_log("DeprecatedAlias");
+} // namespace
+
+/// Constructor to ensure the compiler is happy
+DeprecatedAlias::DeprecatedAlias() : m_deprecationDate() {}
+
+/// Destructor to ensure the compiler is happy
+DeprecatedAlias::~DeprecatedAlias() = default;
+
+/**
+ * @brief Set the deprecation date which will be used to inform the users
+ *
+ * @param date : deprecation date in ISO8601 format
+ */
+void DeprecatedAlias::setDeprecationDate(const std::string &date) {
+  m_deprecationDate = "";
+  if ((!date.empty()) && (Types::Core::DateAndTimeHelpers::stringIsISO8601(date))) {
+    m_deprecationDate = date;
+  } else {
+    throw std::invalid_argument("DeprecatedAlias::DeprecationDate(): deprecation date must follow ISO8601.");
+  }
+}
+
+/**
+ * @brief Construct and return a full deprecation message
+ *
+ * @param algo
+ * @return std::string
+ */
+std::string DeprecatedAlias::deprecationMessage(const IAlgorithm *algo) {
+  std::stringstream msg;
+
+  auto alias = algo->alias();
+
+  if (alias.empty()) {
+    throw std::runtime_error("Cannot find the deprecated alias for this algorithm.");
+  } else {
+    msg << "The algorithm '" << alias << "' is deprecated on " << m_deprecationDate << "."
+        << "Please use '" << algo->name() << "' instead.";
+  }
+
+  return msg.str();
+}
+
+} // namespace API
+} // namespace Mantid

Framework/DataHandling/CMakeLists.txt

 set(SRC_FILES
-    src/AppendGeometryToSNSNexus.cpp
     src/ApplyDiffCal.cpp
     src/BankPulseTimes.cpp
     src/CheckMantidVersion.cpp
@@ -206,13 +205,13 @@ set(SRC_FILES
     src/SetSample.cpp
     src/SetSampleMaterial.cpp
     src/SetScalingPSD.cpp
+    src/SNSAppendGeometryToNexus.cpp
     src/SortTableWorkspace.cpp
     src/StartAndEndTimeFromNexusFileExtractor.cpp
     src/UpdateInstrumentFromFile.cpp
     src/XmlHandler.cpp)
 
 set(INC_FILES
-    inc/MantidDataHandling/AppendGeometryToSNSNexus.h
     inc/MantidDataHandling/ApplyDiffCal.h
     inc/MantidDataHandling/BankPulseTimes.h
     inc/MantidDataHandling/CheckMantidVersion.h
@@ -417,6 +416,7 @@ set(INC_FILES
     inc/MantidDataHandling/SetSample.h
     inc/MantidDataHandling/SetSampleMaterial.h
     inc/MantidDataHandling/SetScalingPSD.h
+    inc/MantidDataHandling/SNSAppendGeometryToNexus.h
     inc/MantidDataHandling/SortTableWorkspace.h
     inc/MantidDataHandling/StartAndEndTimeFromNexusFileExtractor.h
     inc/MantidDataHandling/UpdateInstrumentFromFile.h
@@ -428,7 +428,6 @@ set(INC_FILES
     src/LoadRaw/vms_convert.h)
 
 set(TEST_FILES
-    AppendGeometryToSNSNexusTest.h
     ApplyDiffCalTest.h
     CheckMantidVersionTest.h
     CompressEventsTest.h
@@ -610,6 +609,7 @@ set(TEST_FILES
     SetSampleMaterialTest.h
     SetSampleTest.h
     SetScalingPSDTest.h
+    SNSAppendGeometryToNexusTest.h
     SortTableWorkspaceTest.h
     StartAndEndTimeFromNexusFileExtractorTest.h
     UpdateInstrumentFromFileTest.h

Framework/DataHandling/inc/MantidDataHandling/AppendGeometryToSNSNexus.h → Framework/DataHandling/inc/MantidDataHandling/SNSAppendGeometryToNexus.h

@@ -7,19 +7,20 @@
 #pragma once
 
 #include "MantidAPI/Algorithm.h"
+#include "MantidAPI/DeprecatedAlias.h"
 #include "MantidKernel/System.h"
 
 namespace Mantid {
 namespace DataHandling {
 
-/** AppendGeometryToSNSNexus : Appends geometry information to a NeXus file.
+/** SNSAppendGeometryToNexus : Appends geometry information to a NeXus file.
 
   @date 2012-06-01
 */
-class DLLExport AppendGeometryToSNSNexus : public API::Algorithm {
+class DLLExport SNSAppendGeometryToNexus : public API::Algorithm, public API::DeprecatedAlias {
 public:
-  AppendGeometryToSNSNexus();
-  ~AppendGeometryToSNSNexus() override;
+  SNSAppendGeometryToNexus();
+  ~SNSAppendGeometryToNexus() override;
 
   const std::string name() const override;
   /// Summary of algorithms purpose
@@ -30,6 +31,7 @@ public:
 
   int version() const override;
   const std::string category() const override;
+  const std::string alias() const override { return "AppendGeometryToSNSNexus"; };
 
 private:
   void init() override;

Framework/DataHandling/src/AppendGeometryToSNSNexus.cpp → Framework/DataHandling/src/SNSAppendGeometryToNexus.cpp

@@ -4,7 +4,7 @@
 //   NScD Oak Ridge National Laboratory, European Spallation Source,
 //   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
 // SPDX - License - Identifier: GPL - 3.0 +
-#include "MantidDataHandling/AppendGeometryToSNSNexus.h"
+#include "MantidDataHandling/SNSAppendGeometryToNexus.h"
 #include "MantidAPI/FileProperty.h"
 #include "MantidAPI/InstrumentFileFinder.h"
 #include "MantidAPI/WorkspaceFactory.h"
@@ -30,37 +30,40 @@ namespace Mantid {
 namespace DataHandling {
 
 // Register the algorithm into the AlgorithmFactory
-DECLARE_ALGORITHM(AppendGeometryToSNSNexus)
+DECLARE_ALGORITHM(SNSAppendGeometryToNexus)
 
 //----------------------------------------------------------------------------------------------
 /** Constructor
  */
-AppendGeometryToSNSNexus::AppendGeometryToSNSNexus()
-    : m_makeNexusCopy(false), m_instrumentLoadedCorrectly(false), m_logsLoadedCorrectly(false) {}
+SNSAppendGeometryToNexus::SNSAppendGeometryToNexus()
+    : m_makeNexusCopy(false), m_instrumentLoadedCorrectly(false), m_logsLoadedCorrectly(false) {
+  // inform deprecation alias status
+  setDeprecationDate("2021-09-14");
+}
 
 //----------------------------------------------------------------------------------------------
 /** Destructor
  */
-AppendGeometryToSNSNexus::~AppendGeometryToSNSNexus() {
+SNSAppendGeometryToNexus::~SNSAppendGeometryToNexus() {
   // delete workspace
 }
 
 //----------------------------------------------------------------------------------------------
 /// Algorithm's name for identification. @see Algorithm::name
-const std::string AppendGeometryToSNSNexus::name() const { return "AppendGeometryToSNSNexus"; }
+const std::string SNSAppendGeometryToNexus::name() const { return "SNSAppendGeometryToNexus"; }
 
 /// Algorithm's version for identification. @see Algorithm::version
-int AppendGeometryToSNSNexus::version() const { return 1; }
+int SNSAppendGeometryToNexus::version() const { return 1; }
 
 /// Algorithm's category for identification. @see Algorithm::category
-const std::string AppendGeometryToSNSNexus::category() const { return "DataHandling\\DataAcquisition"; }
+const std::string SNSAppendGeometryToNexus::category() const { return "DataHandling\\DataAcquisition"; }
 
 //----------------------------------------------------------------------------------------------
 
 //----------------------------------------------------------------------------------------------
 /** Initialize the algorithm's properties.
  */
-void AppendGeometryToSNSNexus::init() {
+void SNSAppendGeometryToNexus::init() {
   // Declare potential extensions for input NeXus file
   std::vector<std::string> extensions{".nxs", ".h5"};
 
@@ -76,7 +79,7 @@ void AppendGeometryToSNSNexus::init() {
 //----------------------------------------------------------------------------------------------
 /** Execute the algorithm.
  */
-void AppendGeometryToSNSNexus::exec() {
+void SNSAppendGeometryToNexus::exec() {
   // TODO: rename the created arrays before moving to production
   g_log.warning() << "This is intended as a proof of principle and not a long "
                      "term implementation.\n";
@@ -293,7 +296,7 @@ void AppendGeometryToSNSNexus::exec() {
  * @param nxfilename :: Input NeXus file.
  * @return the instrument name, empty string if failed.
  */
-std::string AppendGeometryToSNSNexus::getInstrumentName(const std::string &nxfilename) {
+std::string SNSAppendGeometryToNexus::getInstrumentName(const std::string &nxfilename) {
   std::string instrument;
 
   // Open the NeXus file
@@ -331,7 +334,7 @@ std::string AppendGeometryToSNSNexus::getInstrumentName(const std::string &nxfil
  * @return true if successful
  */
 
-bool AppendGeometryToSNSNexus::runLoadInstrument(const std::string &idf_filename,
+bool SNSAppendGeometryToNexus::runLoadInstrument(const std::string &idf_filename,
                                                  const API::MatrixWorkspace_sptr &localWorkspace, Algorithm *alg) {
   IAlgorithm_sptr loadInst = createChildAlgorithm("LoadInstrument", 0, 1, true);
 
@@ -367,7 +370,7 @@ bool AppendGeometryToSNSNexus::runLoadInstrument(const std::string &idf_filename
  * @param alg :: Handle of an algorithm for logging access.
  * @return true if successful.
  */
-bool AppendGeometryToSNSNexus::runLoadNexusLogs(const std::string &nexusFileName,
+bool SNSAppendGeometryToNexus::runLoadNexusLogs(const std::string &nexusFileName,
                                                 const API::MatrixWorkspace_sptr &localWorkspace, Algorithm *alg) {
   IAlgorithm_sptr loadLogs = alg->createChildAlgorithm("LoadNexusLogs", 0, 1, true);
 

Framework/DataHandling/test/AppendGeometryToSNSNexusTest.h → Framework/DataHandling/test/SNSAppendGeometryToNexusTest.h

@@ -12,7 +12,7 @@
 #include <Poco/Path.h>
 #include <cxxtest/TestSuite.h>
 
-#include "MantidDataHandling/AppendGeometryToSNSNexus.h"
+#include "MantidDataHandling/SNSAppendGeometryToNexus.h"
 
 using namespace Mantid;
 using namespace Mantid::DataHandling;
@@ -22,24 +22,24 @@ namespace {
 constexpr auto NXS_FILENAME = "HYS_11092_event.nxs";
 }
 
-class AppendGeometryToSNSNexusTest : public CxxTest::TestSuite {
+class SNSAppendGeometryToNexusTest : public CxxTest::TestSuite {
 public:
   // This pair of boilerplate methods prevent the suite being created statically
   // This means the constructor isn't called when running other tests
-  static AppendGeometryToSNSNexusTest *createSuite() { return new AppendGeometryToSNSNexusTest(); }
-  static void destroySuite(AppendGeometryToSNSNexusTest *suite) { delete suite; }
+  static SNSAppendGeometryToNexusTest *createSuite() { return new SNSAppendGeometryToNexusTest(); }
+  static void destroySuite(SNSAppendGeometryToNexusTest *suite) { delete suite; }
 
   void test_Init() {
-    AppendGeometryToSNSNexus alg;
+    SNSAppendGeometryToNexus alg;
     TS_ASSERT_THROWS_NOTHING(alg.initialize())
     TS_ASSERT(alg.isInitialized())
   }
 
   void test_exec() {
     //    // Name of the output workspace.
-    //    std::string outWSName("AppendGeometryToSNSNexusTest_OutputWS");
+    //    std::string outWSName("SNSAppendGeometryToNexusTest_OutputWS");
 
-    AppendGeometryToSNSNexus alg;
+    SNSAppendGeometryToNexus alg;
     TS_ASSERT_THROWS_NOTHING(alg.initialize())
     TS_ASSERT(alg.isInitialized())
     // TODO: Get a better test file.

Framework/PythonInterface/mantid/api/src/Exports/DeprecatedAlgorithmChecker.cpp

@@ -6,10 +6,12 @@
 // SPDX - License - Identifier: GPL - 3.0 +
 #include "MantidAPI/AlgorithmManager.h"
 #include "MantidAPI/DeprecatedAlgorithm.h"
+#include "MantidAPI/DeprecatedAlias.h"
 #include <boost/python/class.hpp>
 
 using Mantid::API::AlgorithmManager;
 using Mantid::API::DeprecatedAlgorithm;
+using Mantid::API::DeprecatedAlias;
 using Mantid::API::IAlgorithm_sptr;
 
 using namespace boost::python;
@@ -43,8 +45,13 @@ public:
   const std::string isDeprecated() const {
     std::string deprecMessage;
     auto *depr = dynamic_cast<DeprecatedAlgorithm *>(m_alg.get());
+    auto *deprecatedAliasAlg = dynamic_cast<DeprecatedAlias *>(m_alg.get());
+
     if (depr)
       deprecMessage = depr->deprecationMsg(m_alg.get());
+    else if (deprecatedAliasAlg)
+      deprecMessage = deprecatedAliasAlg->deprecationMessage(m_alg.get());
+
     return deprecMessage;
   }
 

dev-docs/source/RenameAlgorithm.rst

+.. _RenameAlgorithm:
+
+================