Algorithm.h

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2007 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 <atomic>
#include <memory>
 
#include "MantidAPI/DllConfig.h"
#include "MantidAPI/IAlgorithm.h"
#include "MantidAPI/IndexTypeProperty.h"
#include "MantidKernel/DateAndTime.h"
#include "MantidKernel/IValidator.h"
#include "MantidKernel/PropertyManagerOwner.h"
 
// -- These headers will (most-likely) be used by every inheriting algorithm
#include "MantidAPI/AlgorithmFactory.h" //for the factory macro
#include "MantidAPI/Progress.h"
#include "MantidAPI/WorkspaceOpOverloads.h"
#include "MantidAPI/WorkspaceProperty.h"
#include "MantidKernel/EmptyValues.h"
#include "MantidKernel/MultiThreaded.h"
 
#include "MantidParallel/ExecutionMode.h"
#include "MantidParallel/StorageMode.h"
 
namespace Poco {
template <class R, class A, class O, class S> class ActiveMethod;
template <class O> class ActiveStarter;
class NotificationCenter;
template <class C, class N> class NObserver;
class Void;
} // namespace Poco
 
namespace Json {
class Value;
}
 
namespace Mantid {
namespace Kernel {
// this is declared in MantidKernel/Timer.h
using time_point_ns = std::chrono::time_point<std::chrono::high_resolution_clock>;
} // namespace Kernel
namespace Indexing {
class SpectrumIndexSet;
}
namespace Parallel {
class Communicator;
}
namespace API {
//----------------------------------------------------------------------
// Forward Declaration
//----------------------------------------------------------------------
class AlgorithmHistory;
class WorkspaceHistory;
 
using Algorithm_sptr = std::shared_ptr<Algorithm>;
 
class MANTID_API_DLL Algorithm : public IAlgorithm {
public:
  class MANTID_API_DLL AlgorithmNotification : public Poco::Notification {
  public:
    AlgorithmNotification(const Algorithm *const alg);
    const IAlgorithm *algorithm() const;
 
  private:
    const IAlgorithm *const m_algorithm; 
  };
 
  class MANTID_API_DLL StartedNotification : public AlgorithmNotification {
  public:
    StartedNotification(const Algorithm *const alg);
    std::string name() const override;
  };
 
  class MANTID_API_DLL FinishedNotification : public AlgorithmNotification {
  public:
    FinishedNotification(const Algorithm *const alg, bool res);
    std::string name() const override;
    bool success; 
  };
 
  class MANTID_API_DLL ProgressNotification : public AlgorithmNotification {
  public:
    ProgressNotification(const Algorithm *const alg, double p, std::string msg, double estimatedTime,
                         int progressPrecision);
    std::string name() const override;
    double progress;       
    std::string message;   
    double estimatedTime;  
    int progressPrecision; 
  };
 
  class MANTID_API_DLL ErrorNotification : public AlgorithmNotification {
  public:
    ErrorNotification(const Algorithm *const alg, std::string str);
    std::string name() const override;
    std::string what; 
  };
 
  class MANTID_API_DLL CancelException : public std::exception {
  public:
    const char *what() const noexcept override;
  };
 
  //============================================================================
  Algorithm();
  Algorithm(const Algorithm &) = delete;
  Algorithm &operator=(const Algorithm &) = delete;
  ~Algorithm() override;
 
  const std::string name() const override = 0;
  int version() const override = 0;
  const std::string summary() const override = 0;
  const std::string category() const override { return "Misc"; }
  const std::vector<std::string> categories() const override;
  const std::string categorySeparator() const override { return ";"; }
  const std::vector<std::string> seeAlso() const override { return {}; };
  const std::string alias() const override { return ""; }
  bool calledByAlias = false;
 
  const std::string aliasDeprecated() const override { return ""; }
 
  const std::string helpURL() const override { return ""; }
 
  template <typename T, typename = typename std::enable_if<std::is_convertible<T *, MatrixWorkspace *>::value>::type>
  std::tuple<std::shared_ptr<T>, Indexing::SpectrumIndexSet> getWorkspaceAndIndices(const std::string &name) const;
 
  template <typename T1, typename T2,
            typename = typename std::enable_if<std::is_convertible<T1 *, MatrixWorkspace *>::value>::type,
            typename = typename std::enable_if<std::is_convertible<T2 *, std::string *>::value ||
                                               std::is_convertible<T2 *, std::vector<int64_t> *>::value>::type>
  void setWorkspaceInputProperties(const std::string &name, const std::shared_ptr<T1> &wksp, IndexType type,
                                   const T2 &list);
 
  template <typename T1, typename T2,
            typename = typename std::enable_if<std::is_convertible<T1 *, MatrixWorkspace *>::value>::type,
            typename = typename std::enable_if<std::is_convertible<T2 *, std::string *>::value ||
                                               std::is_convertible<T2 *, std::vector<int64_t> *>::value>::type>
  void setWorkspaceInputProperties(const std::string &name, const std::string &wsName, IndexType type, const T2 &list);
 
  const std::string workspaceMethodName() const override;
  const std::vector<std::string> workspaceMethodOn() const override;
  const std::string workspaceMethodInputProperty() const override;
 
  AlgorithmID getAlgorithmID() const override { return m_algorithmID; }
 
  void initialize() override;
  bool execute() override final;
  void addTimer(const std::string &name, const Kernel::time_point_ns &begin, const Kernel::time_point_ns &end);
  void executeAsChildAlg() override;
  std::map<std::string, std::string> validateInputs() override;
 
  ExecutionState executionState() const override;
  ResultState resultState() const override;
  bool isInitialized() const override;
  bool isExecuted() const override;
  bool isRunning() const override;
  bool isReadyForGarbageCollection() const override;
 
  bool isChild() const override;
  void setChild(const bool isChild) override;
  void enableHistoryRecordingForChild(const bool on) override;
  bool isRecordingHistoryForChild() { return m_recordHistoryForChild; }
  void setAlwaysStoreInADS(const bool doStore) override;
  bool getAlwaysStoreInADS() const override;
  void setRethrows(const bool rethrow) override;
 
  Poco::ActiveResult<bool> executeAsync() override;
 
  void addObserver(const Poco::AbstractObserver &observer) const override;
 
  void removeObserver(const Poco::AbstractObserver &observer) const override;
 
  void cancel() override;
  bool getCancel() const;
 
  Kernel::Logger &getLogger() const;
  void setLogging(const bool value) override;
  bool isLogging() const override;
  void setLoggingOffset(const int value) override;
  int getLoggingOffset() const override;
  void setAlgStartupLogging(const bool enabled) override;
  bool getAlgStartupLogging() const override;
 
  void setChildStartProgress(const double startProgress) const override { m_startChildProgress = startProgress; }
  void setChildEndProgress(const double endProgress) const override { m_endChildProgress = endProgress; }
 
  std::string toString() const override;
  ::Json::Value toJson() const override;
  static IAlgorithm_sptr fromString(const std::string &input);
  static IAlgorithm_sptr fromJson(const Json::Value &input);
  static IAlgorithm_sptr fromHistory(const AlgorithmHistory &history);
 
  virtual std::shared_ptr<Algorithm> createChildAlgorithm(const std::string &name, const double startProgress = -1.,
                                                          const double endProgress = -1.,
                                                          const bool enableLogging = true, const int &version = -1);
  void setupAsChildAlgorithm(const Algorithm_sptr &algorithm, const double startProgress = -1.,
                             const double endProgress = -1., const bool enableLogging = true);
 
  void trackAlgorithmHistory(std::shared_ptr<AlgorithmHistory> parentHist);
 
  using WorkspaceVector = std::vector<std::shared_ptr<Workspace>>;
 
  void findWorkspaces(WorkspaceVector &workspaces, unsigned int direction, bool checkADS = false) const;
 
  // ------------------ For WorkspaceGroups ------------------------------------
  virtual bool checkGroups();
 
  virtual bool processGroups();
 
  void copyNonWorkspaceProperties(IAlgorithm *alg, int periodNum);
 
  const Parallel::Communicator &communicator() const;
  void setCommunicator(const Parallel::Communicator &communicator);
 
  // Function to declare properties (i.e. store them)
  void declareProperty(std::unique_ptr<Kernel::Property> p, const std::string &doc = "") override;
 
  // Function to declare properties (i.e. store them)
  void declareOrReplaceProperty(std::unique_ptr<Kernel::Property> p, const std::string &doc = "") override;
  void resetProperties() override;
  using IPropertyManager::declareProperty;
  // Sets all the declared properties from
  void setProperties(const std::string &propertiesJson,
                     const std::unordered_set<std::string> &ignoreProperties = std::unordered_set<std::string>(),
                     bool createMissing = false) override;
 
  // Sets all the declared properties from a json object
  void setProperties(const ::Json::Value &jsonValue,
                     const std::unordered_set<std::string> &ignoreProperties = std::unordered_set<std::string>(),
                     bool createMissing = false) override;
 
  // sets all the declared properties using a simple string format
  void setPropertiesWithString(
      const std::string &propertiesString,
      const std::unordered_set<std::string> &ignoreProperties = std::unordered_set<std::string>()) override;
 
  void setPropertyValue(const std::string &name, const std::string &value) override;
  void setPropertyValueFromJson(const std::string &name, const Json::Value &value) override;
  void setPropertyOrdinal(const int &index, const std::string &value) override;
 
  virtual void copyPropertiesFrom(const Algorithm &alg) { m_properties.copyPropertiesFrom(alg.m_properties); }
 
  bool existsProperty(const std::string &name) const override;
  bool validateProperties() const override;
  size_t propertyCount() const override;
 
  std::string getPropertyValue(const std::string &name) const override;
  const std::vector<Kernel::Property *> &getProperties() const override;
  std::vector<std::string> getDeclaredPropertyNames() const noexcept override;
 
  TypedValue getProperty(const std::string &name) const override;
 
  std::string asString(bool withDefaultValues = false) const override;
 
  ::Json::Value asJson(bool withDefaultValues = false) const override;
 
  bool isDefault(const std::string &name) const;
 
  void removeProperty(const std::string &name, const bool delproperty = true) override;
  std::unique_ptr<Kernel::Property> takeProperty(const size_t index) override;
 
  void clear() override;
  void afterPropertySet(const std::string &) override;
 
  void filterByTime(const Types::Core::DateAndTime & /*start*/, const Types::Core::DateAndTime & /*stop*/) override {
    throw(std::runtime_error("Not yet implmented"));
  }
  void splitByTime(std::vector<Kernel::SplittingInterval> & /*splitter*/,
                   std::vector<Kernel::PropertyManager *> /* outputs*/) const override {
    throw(std::runtime_error("Not yet implmented"));
  }
 
  void filterByProperty(const Kernel::TimeSeriesProperty<bool> & /*filter*/, const std::vector<std::string> &
                        /* excludedFromFiltering */) override {
    throw(std::runtime_error("Not yet implmented"));
  }
  Kernel::Property *getPointerToProperty(const std::string &name) const override;
  Kernel::Property *getPointerToPropertyOrdinal(const int &index) const override;
 
protected:
  virtual void init() = 0;
  virtual void exec() = 0;
 
  void exec(Parallel::ExecutionMode executionMode);
  virtual void execDistributed();
  virtual void execMasterOnly();
 
  virtual Parallel::ExecutionMode
  getParallelExecutionMode(const std::map<std::string, Parallel::StorageMode> &storageModes) const;
 
  virtual const std::string workspaceMethodOnTypes() const { return ""; }
 
  void cacheWorkspaceProperties();
  void cacheInputWorkspaceHistories();
 
  void setExecutionState(const ExecutionState state); 
  void setResultState(const ResultState state);       
 
  void store();
 
  friend class Progress;
  void progress(double p, const std::string &msg = "", double estimatedTime = 0.0, int progressPrecision = 0);
  void interruption_point();
 
  Poco::NotificationCenter &notificationCenter() const;
 
  void handleChildProgressNotification(const Poco::AutoPtr<ProgressNotification> &pNf);
  const Poco::AbstractObserver &progressObserver() const;
 
  template <typename NumT> static bool isEmpty(const NumT toCheck);
 
  bool isWorkspaceProperty(const Kernel::Property *const prop) const;
 
  bool trackingHistory();
  virtual void fillHistory();
 
  std::atomic<bool> m_cancel;
  std::atomic<bool> m_parallelException;
 
  friend class WorkspaceHistory; // Allow workspace history loading to adjust
                                 // g_execCount
  static size_t g_execCount;     
 
  virtual void setOtherProperties(IAlgorithm *alg, const std::string &propertyName, const std::string &propertyValue,
                                  int periodNum);
 
  std::vector<IWorkspaceProperty *> m_inputWorkspaceProps;
  std::shared_ptr<AlgorithmHistory> m_history;
 
  Kernel::Logger m_log;
  Kernel::Logger &g_log;
 
  std::shared_ptr<AlgorithmHistory> m_parentHistory;
 
  std::vector<WorkspaceVector> m_unrolledInputWorkspaces;
  size_t m_groupSize;
  bool m_usingBaseProcessGroups = false;
 
  template <typename T, const int AllowedIndexTypes = static_cast<int>(IndexType::WorkspaceIndex),
            typename... WSPropArgs,
            typename = typename std::enable_if<std::is_convertible<T *, MatrixWorkspace *>::value>::type>
  void declareWorkspaceInputProperties(const std::string &propertyName, const std::string &doc,
                                       WSPropArgs &&...wsPropArgs);
 
private:
  template <typename T1, typename T2, typename WsType>
  void doSetInputProperties(const std::string &name, const T1 &wksp, IndexType type, const T2 &list);
  void lockWorkspaces();
 
  void unlockWorkspaces();
 
  void clearWorkspaceCaches();
 
  void linkHistoryWithLastChild();
 
  void logAlgorithmInfo() const;
 
  bool executeInternal();
 
  bool executeAsyncImpl(const Poco::Void &i);
 
  bool doCallProcessGroups(Mantid::Types::Core::DateAndTime &start_time);
 
  void fillHistory(const std::vector<Workspace_sptr> &outputWorkspaces);
 
  // Report that the algorithm has completed.
  void reportCompleted(const double &duration, const bool groupProcessing = false);
 
  void registerFeatureUsage() const;
 
  Parallel::ExecutionMode getExecutionMode() const;
  std::map<std::string, Parallel::StorageMode> getInputWorkspaceStorageModes() const;
  void setupSkipValidationMasterOnly();
 
  bool isCompoundProperty(const std::string &name) const;
 
  // --------------------- Private Members -----------------------------------
  std::unique_ptr<Poco::ActiveMethod<bool, Poco::Void, Algorithm, Poco::ActiveStarter<Algorithm>>> m_executeAsync;
 
  mutable std::unique_ptr<Poco::NotificationCenter> m_notificationCenter;
  mutable std::unique_ptr<Poco::NObserver<Algorithm, ProgressNotification>> m_progressObserver;
 
  std::atomic<ExecutionState> m_executionState;             
  std::atomic<ResultState> m_resultState;                   
  bool m_isChildAlgorithm;                                  
  bool m_recordHistoryForChild;                             
  bool m_alwaysStoreInADS;                                  
  bool m_runningAsync;                                      
  bool m_rethrow;                                           
  bool m_isAlgStartupLoggingEnabled;                        
  mutable double m_startChildProgress;                      
  mutable double m_endChildProgress;                        
  AlgorithmID m_algorithmID;                                
  std::vector<std::weak_ptr<IAlgorithm>> m_ChildAlgorithms; 
 
  WorkspaceVector m_readLockedWorkspaces;
  WorkspaceVector m_writeLockedWorkspaces;
 
  std::vector<IWorkspaceProperty *> m_outputWorkspaceProps;
  std::vector<IWorkspaceProperty *> m_pureOutputWorkspaceProps;
 
  std::vector<std::shared_ptr<WorkspaceGroup>> m_groupWorkspaces;
  int m_singleGroup;
  bool m_groupsHaveSimilarNames;
  std::vector<Workspace_sptr> m_inputWorkspaceHistories;
 
  std::vector<std::string> m_reservedList;
 
  std::unique_ptr<Parallel::Communicator> m_communicator;
 
  Mantid::Types::Core::DateAndTime m_gcTime;
 
  Mantid::Kernel::PropertyManagerOwner m_properties;
};
 
} // namespace API
} // namespace Mantid
 
/* Used to register classes into the factory. creates a global object in an
 * anonymous namespace. The object itself does nothing, but the comma operator
 * is used in the call to its constructor to effect a call to the factory's
 * subscribe method.
 */
#define DECLARE_ALGORITHM(classname)                                                                                   \
  namespace {                                                                                                          \
  Mantid::Kernel::RegistrationHelper                                                                                   \
      register_alg_##classname(((Mantid::API::AlgorithmFactory::Instance().subscribe<classname>()), 0));               \
  }