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(getVersion());
    }
 
 
    /**
     * Set version.
     *
     * \param  version    version
     */
    void setVersion(const JDetectorVersion::JVersion_t& version)
    {
      setVersion(putDetectorVersion(version));
    }
 
 
    /**
     * 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 JModuleLocation& 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 JModuleLocation& 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