Unverified Commit fc4be440 authored by Zhang, Chen's avatar Zhang, Chen Committed by GitHub
Browse files

Merge pull request #32527 from mantidproject/PL95_deprecatedAliasCPP_ornlnext

Pl95 deprecated alias cpp ornlnext
parents 5263efc5 0dcfda28
......@@ -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
......
......@@ -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.
......
// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright &copy; 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
......@@ -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.
......
......@@ -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);
......
// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright &copy; 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
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
......
......@@ -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;
......
......@@ -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);
......
......@@ -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.
......
......@@ -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;
}
......
.. _RenameAlgorithm:
================
Rename 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
###########################
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 **four** sections:
.. admonition:: Mantid Algorithm Naming Convention
[Technique] [Instrument/Facility] Action Target
* Technique
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
============= ===========================================
Abbreviations Full Description
============= ===========================================
**CWPD** Constant Wavelength Powder Diffraction
**PD** Powder Diffraction
**REFL** Reflectometry
**SANS** Small Angle Neutron Scattering
**SCD** Single Crystal Diffraction
============= ===========================================
.. note::
The table above is a work in progress as more abbreviations will be added in the future.
* Instrument/Facility
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.
* Here are some commonly used abbreviations of facilities
============= ===========================================
Abbreviations Full Description
============= ===========================================
**ILL** Institut Laue-Langevin at GRENOBLE,France
**ISIS** ​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​ISIS Neutron and Muon Source at UK
**HFIR** High Flux Isotope Reactor at ORNL,USA
**SNS** Spallation Neutron Source at ORNL,USA
============= ===========================================
.. note::
The table above is a work in progress as more abbreviations will be added in the future.
* Here are some commonly used abbreviations of instruments
============= ====================================================
Abbreviations Full Description
============= ====================================================
**CORELLI** Elastic Diffuse Scattering Spectrometer at BL-9, SNS
**POWGEN** Powder Diffractometer at BL-11A, SNS
**TOPAZ** Single-Crystal Diffractometer at BL-12, SNS
**WAND2** Wide-Angle Neutron Diffractometer at HB-2C, HFIR
============= ====================================================
.. note::
The table above is a work in progress as more abbreviations will be added in the future.
* Action
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.
* Target
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 ``LoadFiles`` can be simplified into ``Load``).
.. admonition:: Example
``SCDCalibratePanels`` 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.
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
Rename Python Algorithm
#######################
......@@ -59,6 +59,8 @@ Development Process
PatchReleaseChecklist
TSC
DesignDocumentGuides
CodeCoverage
RenameAlgorithm
:doc:`DevelopmentAndReleaseCycle`
An overview of the development cycle.
......@@ -93,6 +95,9 @@ Development Process
:doc:`DesignDocumentGuides`
How to write a good design document.
:doc:`RenameAlgorithm`
How to rename an existing algorithm.
=====
Tools
=====
......
......@@ -10,9 +10,10 @@ Description
-----------
This algorithm is intended to append the geometry information into a raw
NeXus file. It is initially for use only at the SNS, as it is needed for
the currently upgrade program. But there is nothing preventing it being
used elsewhere.
NeXus file.
It is initially for use only at the SNS, as it is needed for