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 "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"


/**
 * \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.
   *
   * Note that the (not) equal operator strictly applies to the detector identifier and version.
   * For quantitative comparisons, use JCompareDetector.cc.
   *
   * The official detector description document is available 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()
    {
      JPMT::setVersion(getVersion());
    }


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

      JPMT::setVersion(this->getVersion());
    }


    /**
     * 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;
    }


    /**
     * 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) {

        case V3:
        case V2:
          in >> static_cast<JDetectorHeader&>(detector);

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

        default:
          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;

      const ios::fmtflags format    = out.flags();
      const streamsize    precision = out.precision();

      out.setf(ios::fixed);
      out.precision(1);

      out << detector.comment;
      out << static_cast<const JObjectID&>(detector);

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

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

      default:
        out << " ";
        break;
      }

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

      out.precision(3);

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

      out.flags(format);
      out.precision(precision);

      return out;
    }


    /**
     * Read from input.
     *
     * \param  in     reader
     * \return        reader
     */
    virtual JReader& read(JReader& in)
    {
      clear();

      int n;

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

      JPMT::setVersion(getVersion());

      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
    {
      int n = size();

      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;
  };
}

#endif