IFunction.h

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2009 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
 
//----------------------------------------------------------------------
// Includes
//----------------------------------------------------------------------
#include "MantidAPI/DllConfig.h"
#include "MantidAPI/FunctionDomain.h"
#include "MantidAPI/FunctionValues.h"
#include "MantidAPI/IConstraint.h"
#include "MantidAPI/Jacobian.h"
#include "MantidAPI/ParameterTie.h"
#include "MantidKernel/IValidator.h"
#include "MantidKernel/Matrix.h"
#include "MantidKernel/Unit.h"
#include "MantidKernel/WarningSuppressions.h"
 
#ifndef Q_MOC_RUN
#include <boost/variant.hpp>
#include <memory>
#endif
 
#include <string>
#include <utility>
 
#include <vector>
 
#ifdef _WIN32
#pragma warning(disable : 4250)
#endif
 
namespace Mantid {
namespace Kernel {
//----------------------------------------------------------------------
// Forward declaration
//----------------------------------------------------------------------
class ProgressBase;
} // namespace Kernel
namespace API {
class Workspace;
class MatrixWorkspace;
class FunctionHandler;
 
template <class... Ts> struct AttributeLambdaVisitor : Ts... {
  using Ts::operator()...;
};
template <class... Ts> AttributeLambdaVisitor(Ts...) -> AttributeLambdaVisitor<Ts...>;
 
class MANTID_API_DLL IFunction {
public:
  struct ValidationException : public std::runtime_error {
  public:
    ValidationException(const std::string &ErrorMsg) : std::runtime_error(ErrorMsg) {}
  };
 
  struct ValidatorEvaluator {
  public:
    ValidatorEvaluator() {}; // default constructor
    template <typename T1> static void evaluate(T1 &inputData, Mantid::Kernel::IValidator_sptr validator) {
      std::string error;
 
      if (validator != nullptr) {
        error = validator->isValid(inputData);
      }
 
      if (error != "") {
        throw IFunction::ValidationException("Set Attribute Error: " + error);
      }
    }
  };
 
  template <typename T = void> class DLLExport AttributeVisitor : public boost::static_visitor<T> {
  public:
    virtual ~AttributeVisitor() = default;
    T operator()(std::string &str) const { return apply(str); }
    T operator()(double &d) const { return apply(d); }
    T operator()(int &i) const { return apply(i); }
    T operator()(bool &b) const { return apply(b); }
    T operator()(std::vector<double> &v) const { return apply(v); }
 
  protected:
    virtual T apply(std::string &) const = 0;
    virtual T apply(double &) const = 0;
    virtual T apply(int &) const = 0;
    virtual T apply(bool &) const = 0;
    virtual T apply(std::vector<double> &) const = 0;
 
    template <typename T1> void evaluateValidator(T1 &inputData) const {
      if (m_validator != nullptr) {
        ValidatorEvaluator::evaluate(inputData, m_validator);
      }
    }
 
    Mantid::Kernel::IValidator_sptr m_validator = Mantid::Kernel::IValidator_sptr();
  };
 
  template <typename T = void> class DLLExport ConstAttributeVisitor : public boost::static_visitor<T> {
  public:
    virtual ~ConstAttributeVisitor() = default;
    T operator()(const std::string &str) const { return apply(str); }
    T operator()(const double &d) const { return apply(d); }
    T operator()(const int &i) const { return apply(i); }
    T operator()(const bool &b) const { return apply(b); }
    T operator()(const std::vector<double> &v) const { return apply(v); }
 
  protected:
    virtual T apply(const std::string &str) const = 0;
    virtual T apply(const double &d) const = 0;
    virtual T apply(const int &i) const = 0;
    virtual T apply(const bool &i) const = 0;
    virtual T apply(const std::vector<double> &) const = 0;
 
    template <typename T1> void evaluateValidator(T1 &inputData) const {
      if (m_validator != nullptr) {
        ValidatorEvaluator::evaluate(inputData, m_validator);
      }
    }
 
    Mantid::Kernel::IValidator_sptr m_validator = Mantid::Kernel::IValidator_sptr();
  };
 
  class MANTID_API_DLL Attribute {
  public:
    explicit Attribute() : m_data(std::string()), m_quoteValue(false) {}
    explicit Attribute(const std::string &str, bool quoteValue = false) : m_data(str), m_quoteValue(quoteValue) {}
    explicit Attribute(const int &i) : m_data(i), m_quoteValue(false) {}
    explicit Attribute(const double &d) : m_data(d), m_quoteValue(false) {}
    explicit Attribute(const bool &b) : m_data(b), m_quoteValue(false) {}
    explicit Attribute(const char *c) : m_data(std::string(c)), m_quoteValue(false) {}
    explicit Attribute(const std::vector<double> &v) : m_data(v), m_quoteValue(false) {}
 
    template <typename T> T apply(AttributeVisitor<T> &v) { return boost::apply_visitor(v, m_data); }
    template <typename T> T apply(ConstAttributeVisitor<T> &v) const { return boost::apply_visitor(v, m_data); }
    template <typename... Ts> void apply(AttributeLambdaVisitor<Ts...> &v) { boost::apply_visitor(v, m_data); }
 
    void setValidator(const Kernel::IValidator_sptr &validator) const;
    void evaluateValidator() const;
    template <typename T> void evaluateValidator(T &inputData) const {
      if (m_validator != nullptr) {
        ValidatorEvaluator::evaluate(inputData, m_validator);
      }
    }
    Kernel::IValidator_sptr getValidator() { return m_validator; }
 
    std::string type() const;
    std::string value() const;
    std::string asString() const;
    std::string asQuotedString() const;
    std::string asUnquotedString() const;
    int asInt() const;
    double asDouble() const;
    bool asBool() const;
    std::vector<double> asVector() const;
    bool isEmpty() const;
 
    void setString(const std::string &str);
    void setDouble(const double &);
    void setInt(const int &);
    void setBool(const bool &);
    void setVector(const std::vector<double> &);
    // Set value
    template <typename T> void setValue(const T &v) {
      evaluateValidator(v);
 
      m_data = v;
    }
    void fromString(const std::string &str);
 
  private:
    mutable boost::variant<std::string, int, double, bool, std::vector<double>> m_data;
    bool m_quoteValue = false;
    mutable Kernel::IValidator_sptr m_validator;
  };
 
  template <typename T = void> class DLLExport AttributeValidatorVisitor : public boost::static_visitor<T> {
  public:
    AttributeValidatorVisitor(const IFunction::Attribute *attrToValidate) : m_attrToValidate{attrToValidate} {}
 
    T operator()(std::string &str) const { m_attrToValidate->evaluateValidator(str); }
    T operator()(double &d) const { m_attrToValidate->evaluateValidator(d); }
    T operator()(int &i) const { m_attrToValidate->evaluateValidator(i); }
    T operator()(bool &b) const { m_attrToValidate->evaluateValidator(b); }
    T operator()(std::vector<double> &v) const { m_attrToValidate->evaluateValidator(v); }
 
  protected:
    const IFunction::Attribute *m_attrToValidate;
  };
 
  //---------------------------------------------------------//
  IFunction();
  virtual ~IFunction();
  IFunction(const IFunction &) = delete;
  IFunction &operator=(const IFunction &) = delete;
  virtual std::string name() const = 0;
  std::string asString() const;
  virtual std::shared_ptr<IFunction> clone() const;
 
  virtual void registerFunctionUsage(bool internal);
  virtual void setWorkspace(std::shared_ptr<const Workspace> ws) { UNUSED_ARG(ws); }
  virtual void setMatrixWorkspace(std::shared_ptr<const API::MatrixWorkspace> workspace, size_t wi, double startX,
                                  double endX);
  virtual void initialize() { this->init(); }
  virtual int64_t estimateNoProgressCalls() const { return 1; }
 
  void setProgressReporter(std::shared_ptr<Kernel::ProgressBase> reporter);
  void reportProgress(const std::string &msg = "") const;
  bool cancellationRequestReceived() const;
 
  virtual const std::string category() const { return "General"; }
  virtual const std::vector<std::string> categories() const;
  virtual const std::string categorySeparator() const { return ";"; }
 
  virtual void function(const FunctionDomain &domain, FunctionValues &values) const = 0;
  virtual void functionDeriv(const FunctionDomain &domain, Jacobian &jacobian);
 
  /* @name Callbacks to perform work at various points other than in the
   * function */
  virtual void iterationStarting() {}
  virtual void iterationFinished() {}
 
  virtual void setParameter(size_t, const double &value, bool explicitlySet = true) = 0;
  virtual void setParameterDescription(size_t, const std::string &description) = 0;
  virtual double getParameter(size_t i) const = 0;
  virtual void setParameter(const std::string &name, const double &value, bool explicitlySet = true) = 0;
  virtual void setParameterDescription(const std::string &name, const std::string &description) = 0;
  virtual double getParameter(const std::string &name) const = 0;
  virtual bool hasParameter(const std::string &name) const = 0;
  virtual size_t nParams() const = 0;
  virtual size_t parameterIndex(const std::string &name) const = 0;
  virtual std::string parameterName(size_t i) const = 0;
  virtual std::string parameterDescription(size_t i) const = 0;
  virtual bool isExplicitlySet(size_t i) const = 0;
  virtual double getError(size_t i) const = 0;
  virtual double getError(const std::string &name) const = 0;
  virtual void setError(size_t i, double err) = 0;
  virtual void setError(const std::string &name, double err) = 0;
 
  [[nodiscard]] bool isFixed(size_t i) const;
  [[nodiscard]] bool isFixedByDefault(size_t i) const;
  void fix(size_t i, bool isDefault = false);
  void unfix(size_t i);
  void fixParameter(const std::string &name, bool isDefault = false);
  void unfixParameter(const std::string &name);
  void fixAll(bool isDefault = false);
  void unfixAll();
  void unfixAllDefault();
  void fixAllActive(bool isDefault = false);
 
  virtual size_t getParameterIndex(const ParameterReference &ref) const = 0;
  [[nodiscard]] std::vector<std::string> getParameterNames() const;
 
  [[nodiscard]] virtual double activeParameter(size_t i) const;
  virtual void setActiveParameter(size_t i, double value);
  [[nodiscard]] virtual std::string nameOfActive(size_t i) const;
  [[nodiscard]] virtual std::string descriptionOfActive(size_t i) const;
  [[nodiscard]] bool isActive(size_t i) const;
 
  virtual void tie(const std::string &parName, const std::string &expr, bool isDefault = false);
  virtual void addTies(const std::string &ties, bool isDefault = false);
  virtual void applyTies();
  virtual void removeTie(const std::string &parName);
  virtual void clearTies();
  virtual bool removeTie(size_t i);
  virtual ParameterTie *getTie(size_t i) const;
  virtual bool ignoreTie(const ParameterTie &) const { return false; }
  void sortTies(const bool checkOnly = false);
  [[nodiscard]] std::string writeTies() const;
 
  virtual void addConstraints(const std::string &str, bool isDefault = false);
  virtual void addConstraint(std::unique_ptr<IConstraint> ic);
  [[nodiscard]] virtual IConstraint *getConstraint(size_t i) const;
  virtual void removeConstraint(const std::string &parName);
  virtual void setConstraintPenaltyFactor(const std::string &parName, const double &c);
  [[nodiscard]] std::string writeConstraints() const;
  virtual void clearConstraints();
 
  [[nodiscard]] virtual size_t nAttributes() const;
  [[nodiscard]] virtual std::vector<std::string> getAttributeNames() const;
  [[nodiscard]] virtual std::string attributeName(size_t index) const;
  [[nodiscard]] virtual Attribute getAttribute(const std::string &name) const;
  virtual void setAttribute(const std::string &name, const Attribute &);
  [[nodiscard]] virtual bool hasAttribute(const std::string &name) const;
  GNU_DIAG_OFF("maybe-uninitialized")
  template <typename T> void setAttributeValue(const std::string &attName, const T &value) {
    // Since we can't know T and we would rather not create a universal setter
    // copy and replace in-place
    auto attr = getAttribute(attName);
    attr.setValue(value);
    setAttribute(attName, attr);
  }
  GNU_DIAG_ON("maybe-uninitialized")
  void setAttributeValue(const std::string &attName, const char *value);
  void setAttributeValue(const std::string &attName, const std::string &value);
 
  [[nodiscard]] virtual std::shared_ptr<IFunction> getFunction(size_t i) const;
  [[nodiscard]] virtual std::size_t nFunctions() const { return 0; }
  virtual void setUpForFit();
  [[nodiscard]] virtual size_t getValuesSize(const FunctionDomain &domain) const;
  [[nodiscard]] virtual size_t getNumberDomains() const;
  [[nodiscard]] virtual std::vector<std::shared_ptr<IFunction>> createEquivalentFunctions() const;
  void calNumericalDeriv(const FunctionDomain &domain, Jacobian &jacobian);
  [[nodiscard]] double calculateStepSize(const double parameterValue) const;
  void setCovarianceMatrix(const std::shared_ptr<Kernel::Matrix<double>> &covar);
  std::shared_ptr<const Kernel::Matrix<double>> getCovarianceMatrix() const { return m_covar; }
  void setReducedChiSquared(double chi2) { m_chiSquared = chi2; }
  [[nodiscard]] double getReducedChiSquared() const { return m_chiSquared; }
 
  void setParallel(bool on) { m_isParallel = on; }
  [[nodiscard]] bool isParallel() const { return m_isParallel; }
 
  void setHandler(std::unique_ptr<FunctionHandler> handler);
  [[nodiscard]] FunctionHandler *getHandler() const { return m_handler.get(); }
 
  enum ParameterStatus { Active, Fixed, FixedByDefault, Tied };
  virtual void setParameterStatus(size_t i, ParameterStatus status) = 0;
  [[nodiscard]] virtual ParameterStatus getParameterStatus(size_t i) const = 0;
 
  enum class StepSizeMethod { DEFAULT, SQRT_EPSILON };
  virtual void setStepSizeMethod(const StepSizeMethod method);
 
protected:
  virtual void init();
  virtual void declareParameter(const std::string &name, double initValue = 0, const std::string &description = "") = 0;
 
  [[nodiscard]] double convertValue(double value, Kernel::Unit_sptr &outUnit,
                                    const std::shared_ptr<const MatrixWorkspace> &ws, size_t wsIndex) const;
 
  void convertValue(std::vector<double> &values, Kernel::Unit_sptr &outUnit,
                    const std::shared_ptr<const MatrixWorkspace> &ws, size_t wsIndex) const;
 
  virtual void declareAttributes() {}
  virtual void declareParameters() {}
 
  void declareAttribute(const std::string &name, const API::IFunction::Attribute &defaultValue);
  void declareAttribute(const std::string &name, const API::IFunction::Attribute &defaultValue,
                        const Kernel::IValidator &validator);
  void checkAttributeName(const std::string &name);
  void storeAttributeValue(const std::string &name, const API::IFunction::Attribute &value);
  void storeReadOnlyAttribute(const std::string &name, const API::IFunction::Attribute &value) const;
  virtual void addTie(std::unique_ptr<ParameterTie> tie);
  [[nodiscard]] bool hasOrderedTies() const;
  void applyOrderedTies();
  [[nodiscard]] virtual std::string writeToString(const std::string &parentLocalAttributesStr = "") const;
 
  friend class ParameterTie;
  friend class CompositeFunction;
  friend class FunctionParameterDecorator;
  friend class FunctionGenerator;
 
  bool m_isParallel;
 
  std::unique_ptr<FunctionHandler> m_handler;
 
  std::shared_ptr<Kernel::ProgressBase> m_progReporter;
 
private:
  std::map<std::string, API::IFunction::Attribute> m_attrs;
  std::shared_ptr<Kernel::Matrix<double>> m_covar;
  double m_chiSquared;
  std::vector<std::unique_ptr<ParameterTie>> m_ties;
  std::vector<std::unique_ptr<IConstraint>> m_constraints;
  std::vector<ParameterTie *> m_orderedTies;
  bool m_isRegistered{false};
  std::function<double(const double)> m_stepSizeFunction;
 
  // Creates and processes a single tie, handling constant expressions and validation
  std::unique_ptr<ParameterTie> createAndProcessTie(const std::string &parName, const std::string &expr,
                                                    bool isDefault);
  // Insert a new tie to the correct position
  std::pair<std::size_t, std::string> insertTie(std::unique_ptr<ParameterTie> tie);
};
 
using IFunction_sptr = std::shared_ptr<IFunction>;
using IFunction_const_sptr = std::shared_ptr<const IFunction>;
 
class FunctionHandler {
public:
  FunctionHandler(IFunction_sptr fun) : m_fun(std::move(fun)) {}
  FunctionHandler(const FunctionHandler &) = delete;
  FunctionHandler &operator=(const FunctionHandler &) = delete;
  virtual ~FunctionHandler() = default;
  virtual void init() = 0;
  IFunction_sptr function() const { return m_fun; }
 
protected:
  IFunction_sptr m_fun; 
};
 
} // namespace API
} // namespace Mantid