JDetector.hh

Go to the documentation of this file.

#ifndef __JDETECTOR__JDETECTOR__
#define __JDETECTOR__JDETECTOR__

#include <istream>
#include <ostream>
#include <sstream>
#include <string>
#include <vector>

#include "JLang/JObjectID.hh"
#include "JLang/JMultiEquals.hh"
#include "JLang/JException.hh"
#include "JLang/JManip.hh"
#include "Jeep/JComment.hh"
#include "JDetector/JDetectorVersion.hh"
#include "JDetector/JDetectorHeader.hh"
#include "JDetector/JPMT.hh"
#include "JDetector/JModule.hh"
#include "JDetector/JPMTAddress.hh"
#include "JDetector/JModuleAddress.hh"
#include "JGeometry3D/JVector3D.hh"
#include "JIO/JSerialisable.hh"
#include "JIO/JByteArrayIO.hh"


/**
 * \file
 *
 * Data structure for detector geometry and calibration.
 * \author mdejong
 */
namespace JDETECTOR {}
namespace JPP { using namespace JDETECTOR; }

namespace JDETECTOR {

  using JLANG::JObjectID;
  using JLANG::JMultiEquals;
  using JLANG::JTYPELIST;
  using JLANG::JIndexOutOfRange;
  using JEEP::JComment;
  using JIO::JSerialisable;
  using JIO::JReader;
  using JIO::JWriter;
  using JGEOMETRY3D::JVector3D;


  /**
   * Detector data structure.
   *
   * A detector consists of a header and a list of modules, each of which consists of a list of PMTs.
   * Each PMT comprises position, orientation and time calibration data.
   * Note that the index of the PMT in the module data structure corresponds to the readout channel (TDC).
   *
   * The following formats and file name extension are supported:
   *
   * <table border="1" width="300">
   * <tr><th>  extension </th><th>  format         </th><th> function </th></tr>
   * <tr><td>  ".detx"   </td><td>  ASCII          </td><td>   I/O    </td></tr>
   * <tr><td>  ".gz"     </td><td>  gzipped ASCII  </td><td>   I/O    </td></tr>
   * <tr><td>  ".dat"    </td><td>  binary         </td><td>   I/O    </td></tr>
   * <tr><td>  ".det"    </td><td>  ASCII          </td><td>    I     </td></tr>
   * </table>
   *
   * The different formats can transparently be read and written using the methods:
   * <pre>
   *    inline void load(const JString& file_name, JDetector& detector);
   *    inline void store(const JString& file_name, const JDetector& detector);
   * </pre>
   * respectively.
   * These methods are available in the include file JDetectorToolkit.hh.
   *
   * The JDETECTOR::JModuleRouter and JDETECTOR::JPMTRouter classes provide for fast look-up
   * methods of module and PMT calibration data for real data and Monte Carlo data, respectively.\n
   * Note that the (not) equal operator strictly applies to the detector identifier and version.
   * For quantitative comparisons, use JCompareDetector.cc.\n
   * The official detector description document is accessible for anyone with a %KM3NeT account at
   * the <a href="https://drive.google.com/open?id=0B6l8SNtndcwaUTZPOWZOXzd6R3M">google drive</a>.
   */
  class JDetector :
    public JObjectID,
    public JDetectorVersion,
    public JDetectorHeader,
    public std::vector<JModule>,
    public JMultiEquals<JDetector, JTYPELIST<JObjectID, JVersion>::typelist>,
    public JSerialisable
  {
  public:
    /**
     * Default constructor.
     */
    JDetector() :
      JObjectID(),
      JDetectorVersion(),
      JDetectorHeader (),
      std::vector<JModule>(),
      JSerialisable()
    {}


    /**
     * Constructor.
     *
     * \param  id         detector identifier
     * \param  version    version
     * \param  header     header
     */
    JDetector(const JObjectID&       id,
              const JVersion&        version,
              const JDetectorHeader& header) :
      JObjectID(id),
      JDetectorVersion(version),
      JDetectorHeader (header),
      std::vector<JModule>(),
      JSerialisable()
    {
      setVersion();
    }


    /**
     * Set version.
     *
     * \param  version    version
     */
    void setVersion(const JVersion& version)
    {
      static_cast<JDetectorVersion&>(*this).setVersion(version);

      setVersion();
    }


    /**
     * Set version.
     *
     * Note that the version is only set to a higher version or when forced to set it.
     *
     * \param  version    version
     * \param  force      force setting of version
     * \return            true if set; else false
     */
    bool setVersion(const JDetectorVersion::JVersion_t& version, const bool force = false)
    {
      if (this->getVersion() == JDetectorVersion()  ||  version > getDetectorVersion(this->getVersion())  ||  force) {

        setVersion(putDetectorVersion(version));

        return true;
      }

      return false;
    }


    /**
     * Set to latest version.
     *
     * \return            true if set; else false
     */
    bool setToLatestVersion()
    {
      return setVersion(getLatestDetectorVersion<JDetectorVersion::JVersion_t>());
    }


    /**
     * Move detector elements.
     *
     * \param  pos        offset position
     * \return            this JDetector
     */
    JDetector& operator+=(const JVector3D& pos)
    {
      for (iterator i = begin(); i != end(); ++i) {
        i->add(pos);
      }

      return *this;
    }


    /**
     * Move detector elements.
     *
     * \param  pos        offset position
     * \return            this JDetector
     */
    JDetector& operator-=(const JVector3D& pos)
    {
      for (iterator i = begin(); i != end(); ++i) {
        i->sub(pos);
      }

      return *this;
    }


    /**
     * Get module parameters.
     *
     * \param  address    module address
     * \return            module parameters
     */
    const JModule& getModule(const JModuleAddress& address) const
    {
      return at(address.first);
    }


    /**
     * Get module parameters.
     *
     * \param  address    module address
     * \return            module parameters
     */
    JModule& getModule(const JModuleAddress& address)
    {
      return at(address.first);
    }


    /**
     * Get module parameters.
     *
     * \param  location   module location
     * \return            module parameters
     */
    const JModule& getModule(const JLocation& location) const
    {
      for (JDetector::const_iterator module = this->begin(); module != this->end(); ++module) {
        if (*module == location) {
          return *module;
        }
      }

      THROW(JIndexOutOfRange, "JDetector::getModule()");
    }


    /**
     * Get module parameters.
     *
     * \param  location   module location
     * \return            module parameters
     */
    JModule& getModule(const JLocation& location)
    {
      for (JDetector::iterator module = this->begin(); module != this->end(); ++module) {
        if (*module == location) {
          return *module;
        }
      }

      THROW(JIndexOutOfRange, "JDetector::getModule()");
    }


    /**
     * Get PMT parameters.
     *
     * \param  address    JPMTAddress
     * \return            JPMT
     */
    const JPMT& getPMT(const JPMTAddress& address) const
    {
      return at(address.first).at(address.second);
    }


    /**
     * Get PMT parameters.
     *
     * \param  address    JPMTAddress
     * \return            JPMT
     */
    JPMT& getPMT(const JPMTAddress& address)
    {
      return at(address.first).at(address.second);
    }


    /**
     * Read detector from input.
     *
     * \param  in         input stream
     * \param  detector   detector
     * \return            input stream
     */
    friend inline std::istream& operator>>(std::istream& in, JDetector& detector)
    {
      using namespace std;

      detector.clear();

      string buffer;

      if (in
          >> detector.comment
          >> static_cast<JObjectID&>(detector)
          >> buffer) {

        int n;
        int version = -1;

        try {
          version = getDetectorVersion(buffer);
        }
        catch(std::exception&) {}

        switch (version) {

        default:
          in >> static_cast<JDetectorHeader&>(detector);

        case V1:
          in >> n;
          detector.setVersion(buffer);
          break;

        case -1:
          detector.setVersion(putDetectorVersion(V1));
          istringstream(buffer) >> n;
          break;
        }

        for (JModule module; n != 0 && in >> module; --n) {
          detector.push_back(module);
        }
      }

      return in;
    }


    /**
     * Write detector to output.
     *
     * \param  out        output stream
     * \param  detector   detector
     * \return            output stream
     */
    friend inline std::ostream& operator<<(std::ostream& out, const JDetector& detector)
    {
      using namespace std;
      using namespace JPP;

      setFormat<JPosition3D>  (JFormat_t(9, 3, std::ios::fixed | std::ios::showpos));
      setFormat<JDirection3D> (JFormat_t(9, 6, std::ios::fixed | std::ios::showpos));
      setFormat<JQuaternion3D>(JFormat_t(9, 6, std::ios::fixed | std::ios::showpos));
      setFormat<JCalibration> (JFormat_t(9, 3, std::ios::fixed | std::ios::showpos));
                           
      out << detector.comment;
      out << static_cast<const JObjectID&>(detector);

      switch (getDetectorVersion(detector.getVariant())) {

      default:
        out << " ";
        out << static_cast<const JDetectorVersion&>(detector) << endl;
        out << static_cast<const JDetectorHeader&> (detector) << endl;
        break;

      case V1:
        out << " ";
        break;
      }

      out << detector.size() << endl;

      for (const_iterator i = detector.begin(); i != detector.end(); ++i) {
        out << *i << endl;
      }

      return out;
    }


    /**
     * Read from input.
     *
     * \param  in     reader
     * \return        reader
     */
    virtual JReader& read(JReader& in) override 
    {
      using namespace std;
      using namespace JPP;

      clear();

      char c;
      int  n;

      for (string buffer; in >> c && c == JComment::START_COMMENT; ) {

        in >> buffer;

        this->comment.add(buffer);
      }

      const int N = sizeof(JObjectID);

      char buffer[N];

      buffer[0] = c;

      in.read(&buffer[1], N - 1);

      JByteArrayReader is(buffer, N);

      is >> static_cast<JObjectID&>       (*this);
      in >> static_cast<JDetectorVersion&>(*this);
      in >> static_cast<JDetectorHeader&> (*this);
      in >> n;

      setVersion();

      for (JModule module; n != 0; --n) {

        in >> module;

        push_back(module);
      }

      return in;
    }


    /**
     * Write to output.
     *
     * \param  out     writer
     * \return         writer
     */
    virtual JWriter& write(JWriter& out) const override 
    {
      using namespace std;
      using namespace JPP;

      int  n = size();
      char c = JComment::START_COMMENT;

      for (JComment::const_iterator i = this->comment.begin(); i != this->comment.end(); ++i) {
        out <<  c;
        out << *i;
      }

      out << static_cast<const JObjectID&>       (*this);
      out << static_cast<const JDetectorVersion&>(*this);
      out << static_cast<const JDetectorHeader&> (*this);
      out << n;

      for (const_iterator i = begin(); i != end(); ++i) {
        out << *i;
      }

      return out;
    }


    JComment comment;

  protected:
    /**
     * Set version.
     *
     * This method should be called to set up the handling of detector version specific module and PMT I/O.
     */
    void setVersion() const
    {
      JModule::setVersion(this->getVersion());
      JPMT   ::setVersion(this->getVersion());
    }
  };
}

#endif