Unit.h

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2008 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 "MantidKernel/UnitLabel.h"
#include "MantidKernel/Unit_fwd.h"
#include <utility>
 
#include <algorithm>
#include <unordered_map>
#include <vector>
 
#include "tbb/concurrent_unordered_map.h"
 
namespace Mantid {
namespace Kernel {
 
enum class UnitParams { l2, twoTheta, efixed, delta, difa, difc, tzero };
 
// list of parameter names and values - some code may relay on map behaviour
// where [] creates element with value 0 if param name not present
using UnitParametersMap = std::unordered_map<UnitParams, double>;
 
class MANTID_KERNEL_DLL Unit {
public:
  Unit();
  virtual ~Unit() = default;
 
  virtual Unit *clone() const = 0;
 
  virtual const std::string unitID() const = 0;
  virtual const std::string caption() const = 0;
 
  virtual const UnitLabel label() const = 0;
 
  virtual bool isConvertible() const { return true; }
 
  // Equality operators based on the value returned by unitID();
  bool operator==(const Unit &u) const;
  bool operator!=(const Unit &u) const;
 
  // Check whether the unit can be converted to another via a simple factor
  bool quickConversion(const Unit &destination, double &factor, double &power) const;
  bool quickConversion(std::string destUnitName, double &factor, double &power) const;
 
  void toTOF(std::vector<double> &xdata, std::vector<double> const &ydata, const double &_l1, const int &_emode,
             std::initializer_list<std::pair<const UnitParams, double>> params);
  void toTOF(std::vector<double> &xdata, std::vector<double> const &ydata, const double &_l1, const int &_emode,
             const UnitParametersMap &params);
 
  template <typename Iterator>
  void toTOF(Iterator const xbegin, Iterator const xend, double const l1, int const emode,
             UnitParametersMap const &params) {
    this->initialize(l1, emode, params);
    std::transform(xbegin, xend, xbegin, [this](double const x) { return this->singleToTOF(x); });
  }
 
  double convertSingleToTOF(const double xvalue, const double &l1, const int &emode, const UnitParametersMap &params);
 
  void fromTOF(std::vector<double> &xdata, std::vector<double> const &ydata, const double &_l1, const int &_emode,
               std::initializer_list<std::pair<const UnitParams, double>> params);
 
  void fromTOF(std::vector<double> &xdata, std::vector<double> const &ydata, const double &_l1, const int &_emode,
               const UnitParametersMap &params);
 
  template <typename Iterator>
  void fromTOF(Iterator const xbegin, Iterator const xend, double const l1, int const emode,
               UnitParametersMap const &params) {
    this->initialize(l1, emode, params);
    std::transform(xbegin, xend, xbegin, [this](double const tof) { return this->singleFromTOF(tof); });
  }
 
  double convertSingleFromTOF(const double xvalue, const double &l1, const int &emode, const UnitParametersMap &params);
 
  void initialize(const double &_l1, const int &_emode, const UnitParametersMap &params);
 
  virtual void init() = 0;
 
  virtual double singleToTOF(const double x) const = 0;
 
  virtual double singleFromTOF(const double tof) const = 0;
 
  bool isInitialized() const { return initialized; }
 
  virtual double conversionTOFMin() const = 0;
 
  virtual double conversionTOFMax() const = 0;
 
  virtual std::pair<double, double> conversionRange() const;
 
protected:
  // Add a 'quick conversion' for a unit pair
  void addConversion(std::string to, const double &factor, const double &power = 1.0) const;
 
  // validate the contents of the unit parameters map. Throw
  // std::invalid_argument if it's a global error or std::runtime_error if it's
  // a detector specific error
  virtual void validateUnitParams(const int emode, const UnitParametersMap &params);
 
  bool initialized;
  double l1;
  int emode;
  const UnitParametersMap *m_params;
 
private:
  using ConstantAndPower = std::pair<double, double>;
  using UnitConversions = tbb::concurrent_unordered_map<std::string, ConstantAndPower>;
  using ConversionsMap = tbb::concurrent_unordered_map<std::string, UnitConversions>;
  static ConversionsMap s_conversionFactors;
};
 
//----------------------------------------------------------------------
// Now the concrete units classes
//----------------------------------------------------------------------
 
namespace Units {
 
//=================================================================================================
class MANTID_KERNEL_DLL Empty : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return ""; }
  const UnitLabel label() const override;
 
  bool isConvertible() const override { return false; }
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
 
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  Empty() : Unit() {}
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Label : public Empty {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return m_caption; }
  const UnitLabel label() const override;
 
  Label();
  Label(const std::string &caption, const std::string &label);
  void setLabel(const std::string &cpt, const UnitLabel &lbl = UnitLabel(""));
  Unit *clone() const override;
 
private:
  std::string m_caption;
  UnitLabel m_label;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL TOF : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Time-of-flight"; }
  const UnitLabel label() const override;
 
  TOF();
  void init() override;
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Wavelength : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Wavelength"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
 
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  Wavelength();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double efixed;
  double sfpTo;      
  double factorTo;   
  double sfpFrom;    
  double factorFrom; 
  bool do_sfpFrom;   
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Energy : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Energy"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
 
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  Energy();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double factorTo;   
  double factorFrom; 
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Energy_inWavenumber : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Energy"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  Energy_inWavenumber();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double factorTo;   
  double factorFrom; 
};
 
MANTID_KERNEL_DLL double tofToDSpacingFactor(const double l1, const double l2, const double twoTheta,
                                             const double offset);
 
MANTID_KERNEL_DLL double calculateDIFCCorrection(const double l1, const double l2, const double twotheta,
                                                 const double offset, const double binWidth);
 
//=================================================================================================
class MANTID_KERNEL_DLL dSpacing : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "d-Spacing"; }
  const UnitLabel label() const override;
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
  double calcTofMin(const double difc, const double difa, const double tzero, const double tofmin = 0.);
  double calcTofMax(const double difc, const double difa, const double tzero, const double tofmax = 0.);
 
  dSpacing();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  std::string toDSpacingError;
  double difa;
  double difc;
  double tzero;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL dSpacingPerpendicular : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "d-SpacingPerpendicular"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  dSpacingPerpendicular();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double twoTheta;
  double factorTo;   
  double sfpTo;      
  double factorFrom; 
  double sfpFrom;    
};
 
//=================================================================================================
class MANTID_KERNEL_DLL MomentumTransfer : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "q"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
  MomentumTransfer();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double difc;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL QSquared : public MomentumTransfer {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Q2"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  QSquared();
};
 
//=================================================================================================
class MANTID_KERNEL_DLL DeltaE : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Energy transfer"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
 
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  DeltaE();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double efixed;
  double factorTo;    
  double factorFrom;  
  double t_other;     
  double t_otherFrom; 
  double unitScaling; 
};
 
//=================================================================================================
class MANTID_KERNEL_DLL DeltaE_inWavenumber : public DeltaE {
public:
  const std::string unitID() const override; 
  const UnitLabel label() const override;
 
  void init() override;
  Unit *clone() const override;
  DeltaE_inWavenumber();
};
 
//=================================================================================================
class MANTID_KERNEL_DLL DeltaE_inFrequency : public DeltaE {
public:
  const std::string unitID() const override; 
  const UnitLabel label() const override;
 
  void init() override;
  Unit *clone() const override;
  DeltaE_inFrequency();
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Momentum : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Momentum"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double ki) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  Momentum();
 
protected:
  void validateUnitParams(const int emode, const UnitParametersMap &params) override;
  double efixed;
  double sfpTo;      
  double factorTo;   
  double sfpFrom;    
  double factorFrom; 
  bool do_sfpFrom;   
};
 
//=================================================================================================
class MANTID_KERNEL_DLL SpinEchoLength : public Wavelength {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Spin Echo Length"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  SpinEchoLength();
 
private:
  double efixed;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL SpinEchoTime : public Wavelength {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "Spin Echo Time"; }
  const UnitLabel label() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  void init() override;
  Unit *clone() const override;
  double conversionTOFMin() const override;
  double conversionTOFMax() const override;
 
  SpinEchoTime();
 
private:
  double efixed;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Time : public Unit {
public:
  const std::string unitID() const override; 
  const std::string caption() const override { return "t"; }
  const UnitLabel label() const override;
 
  bool isConvertible() const override { return false; }
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
  double conversionTOFMax() const override;
  double conversionTOFMin() const override;
  void init() override;
  Unit *clone() const override;
 
  Time();
 
protected:
  double factorTo;   
  double factorFrom; 
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Degrees : public Empty {
public:
  Degrees();
  const std::string unitID() const override; 
  const std::string caption() const override { return "Scattering angle"; }
  const UnitLabel label() const override;
 
  Unit *clone() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
 
private:
  UnitLabel m_label;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Phi : public Degrees {
  const std::string unitID() const override;
  const std::string caption() const override { return "Phi"; }
  Unit *clone() const override { return new Phi(*this); }
};
 
//=================================================================================================
class MANTID_KERNEL_DLL Temperature : public Empty {
public:
  Temperature();
  const std::string unitID() const override; 
  const std::string caption() const override { return "Temperature"; }
  const UnitLabel label() const override;
 
  Unit *clone() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
 
private:
  UnitLabel m_label;
};
 
//=================================================================================================
class MANTID_KERNEL_DLL AtomicDistance : public Empty {
public:
  AtomicDistance();
  const std::string unitID() const override; 
  const std::string caption() const override { return "Atomic Distance"; }
  const UnitLabel label() const override;
 
  Unit *clone() const override;
 
  double singleToTOF(const double x) const override;
  double singleFromTOF(const double tof) const override;
 
private:
  UnitLabel m_label;
};
 
//=================================================================================================
 
MANTID_KERNEL_DLL double timeConversionValue(const std::string &input_unit, const std::string &output_unit);
 
template <typename T>
void timeConversionVector(std::vector<T> &vec, const std::string &input_unit, const std::string &output_unit) {
  double factor = timeConversionValue(std::move(input_unit), std::move(output_unit));
  if (factor != 1.0)
    std::transform(vec.begin(), vec.end(), vec.begin(), [factor](T x) -> T { return x * static_cast<T>(factor); });
}
 
} // namespace Units
 
} // namespace Kernel
} // namespace Mantid