JTimesliceRouter.hh

Go to the documentation of this file.

#ifndef __JTRIGGER__JTIMESLICEROUTER__
#define __JTRIGGER__JTIMESLICEROUTER__

#include <vector>
#include <iterator>
#include <utility>
#include <limits>
#include <algorithm>

#include "JTools/JRouter.hh"
#include "JTools/JElement.hh"
#include "JTools/JGrid.hh"
#include "JTools/JGridCollection.hh"
#include "km3net-dataformat/online/JDAQ.hh"
#include "km3net-dataformat/online/JDAQModuleIdentifier.hh"
#include "km3net-dataformat/online/JDAQSuperFrame.hh"
#include "km3net-dataformat/online/JDAQTimeslice.hh"
#include "JDetector/JTimeRange.hh"
#include "JTrigger/JTriggerException.hh"
#include "JLang/JPointer.hh"


/**
 * \author mdejong
 */

namespace JTRIGGER {}
namespace JPP { using namespace JTRIGGER; }

namespace JTRIGGER {

  using JLANG::JPointer;
  using KM3NETDAQ::JDAQTimeslice;
  using KM3NETDAQ::JDAQModuleIdentifier;
  using KM3NETDAQ::JDAQFrameSubset;
  using JDETECTOR::JTimeRange;


  /**
   * Router for fast addressing of hits in KM3NETDAQ::JDAQTimeslice data structure
   * as a function of the optical module identifier and time.
   *
   * Note that the data in a frame from the same PMT are time ordered 
   * but the data from different PMTs are not necessarily time orderd.\n
   * The fast routing is based on the assumption that the time difference
   * between consecutive hits in the same frame is limited.\n
   * The access speed is then determined by this time difference.
   *
   * The time slice router class comprises two internal look-up tables:
   *
   * - The first table consists of a one dimensional look-up table which is 
   *   is used to map the module identifier to the index of the corresponding
   *   data frame in the time slice.
   *
   * - The second table consists of a two dimensional array.
   *   In this, the first index of matches with the index of the corresponding data frame in the time slice.
   *   Each first index is mapped to a one dimensional look-up table.
   *   This one dimensional look-up table maps an uncalibrated time <tt>t</tt>
   *   to a pair of indices <tt>(lpos,rpos)</tt>, where:
   *     -# <tt>lpos</tt> is the index of the first hit in the data frame with time <tt>>= t</tt>;
   *     -# <tt>rpos</tt> is the index of the last  hit in the data frame with time <tt><  t</tt>;
   */
  class JTimesliceRouter :
    public JPointer<const JDAQTimeslice>    
  {
    /**
     * Auxiliary structure for indexing hits in a data frame.
     */ 
    struct JPair_t {
      int lpos;
      int rpos;
    };

  public:

    typedef JTOOLS::JElement2D<double, JPair_t>        element_type;
    typedef JTOOLS::JGridCollection<element_type>      grid_type;
    typedef JTOOLS::JRouter<int>                       router_type;
    typedef JDAQTimeslice::const_iterator              const_iterator;


    /**
     * Constructor.
     *
     * \param  numberOfBins    number of bins of the hit look-up table
     */
    JTimesliceRouter(const int numberOfBins) :
      number_of_bins(numberOfBins),
      router(-1)
    {}


    /**
     * Constructor.
     *
     * \param  timeslice       timeslice
     * \param  numberOfBins    number of bins of the hit look-up table
     */
    JTimesliceRouter(const JDAQTimeslice& timeslice,
                     const int numberOfBins) :
      number_of_bins(numberOfBins),
      router(-1)
    {
      configure(timeslice);
    }


    /**
     * Configure.
     *
     * \param  timeslice       timeslice
     */
    void configure(const JDAQTimeslice& timeslice)
    {
      using namespace std;
      using namespace JPP;
      using namespace KM3NETDAQ;


      this->set(&timeslice);


      for (const_iterator i = this->get()->begin(); i != this->get()->end(); ++i) {
        router.put(i->getModuleID(), distance(this->get()->begin(), i));
      }


      const JDAQHit::JTDC_t TMIN = numeric_limits<JDAQHit::JTDC_t>::min();
      const JDAQHit::JTDC_t TMAX = numeric_limits<JDAQHit::JTDC_t>::max();

      double Tmin = getTimeSinceRTS(this->get()->getFrameIndex()) - 0.05 * getFrameTime();    // [ns]
      double Tmax = getTimeSinceRTS(this->get()->getFrameIndex()) + 1.05 * getFrameTime();    // [ns]

      if (Tmin < TMIN) { Tmin = TMIN; }
      if (Tmax > TMAX) { Tmax = TMAX; }


      int number_of_elements = 2;

      for (const_iterator i = this->get()->begin(); i != this->get()->end(); ++i) {
        if (i->size() > number_of_elements) {
          number_of_elements = i->size();
        }
      }

      if (number_of_bins > 1 && number_of_bins < number_of_elements) {
        number_of_elements = number_of_bins;
      }


      const JGrid<double> bounds(number_of_elements, Tmin, Tmax);


      typedef vector<JDAQHit::JTDC_t> JBuffer_t;                             // temporary buffer to store bin edges with proper data type

      JBuffer_t buffer(bounds.getSize() + 1);

      for (int i = 0; i != bounds.getSize(); ++i) {
        buffer[i] = (JDAQHit::JTDC_t) bounds.getX(i);
      }

      buffer[bounds.getSize()] = TMAX;


      table.resize(this->get()->size());                                      // same indexing as time slice

      const JDAQHit JDAQHitMin(0, TMIN, 0);                                   // begin marker
      const JDAQHit JDAQHitMax(0, TMAX, 0);                                   // end   marker

      typedef vector<JDAQHit>    JDAQFrame_t;

      JDAQFrame_t zbuf;                                                       // copy of raw data with additional begin and end marker

      vector<grid_type>::iterator grid = table.begin();

      for (const_iterator frame = this->get()->begin(); frame != this->get()->end(); ++frame, ++grid) {

        grid->configure(bounds);

        if (!frame->empty()) {

          if (frame-> begin()->getT() < grid->getXmin()) {
            THROW(JTriggerException, "Hit time out of range " << frame-> begin()->getT() << " < " << grid->getXmin());
          }
            
          if (frame->rbegin()->getT() > grid->getXmax()) {
            THROW(JTriggerException, "Hit time out of range " << frame->rbegin()->getT() << " > " << grid->getXmax());
          }

          zbuf.resize(frame->size() + 2);                                     // reserve space end markers

          copy(frame->begin(), frame->end(), zbuf.begin() + 1);

          *zbuf. begin() = JDAQHitMin;
          *zbuf.rbegin() = JDAQHitMax;

          {
            JDAQFrame_t::const_iterator hit = zbuf.begin(); ++hit;            // skip begin marker
            JBuffer_t  ::const_iterator t1  = buffer.begin();

            for (grid_type::iterator i = grid->begin(); i != grid->end(); ++i, ++t1) {
            
              while (hit->getT() < *t1) { ++hit; }
              
              i->getY().lpos = distance(static_cast<const JDAQFrame_t&>(zbuf).begin(), hit)        - 1;
            }
          }

          {
            JDAQFrame_t::const_reverse_iterator hit = zbuf.rbegin(); ++hit;   // skip end marker
            JBuffer_t  ::const_reverse_iterator t1  = buffer.rbegin();

            for (grid_type::reverse_iterator i = grid->rbegin(); i != grid->rend(); ++i, ++t1) {
                
              while (hit->getT() >= *t1) { ++hit; }
              
              i->getY().rpos = distance(static_cast<const JDAQFrame_t&>(zbuf).begin(), hit.base()) - 1;
            }
          }
        }
      }
    }
    

    /**
     * Get address of module.
     *
     * \param  module          module
     * \return                 address
     */
    const int getAddress(const JDAQModuleIdentifier& module) const
    {
      return router.get(module.getModuleID());
    }
    

    /**
     * Check presence of module.
     *
     * \param  module          module
     * \return                 true if module present; else false
     */
    bool hasSuperFrame(const JDAQModuleIdentifier& module) const
    {
      return router.has(module.getModuleID());
    }
    

    /**
     * Get super frame.
     *
     * \param  module          module
     * \return                 super frame
     */
    const JDAQSuperFrame& getSuperFrame(const JDAQModuleIdentifier& module) const
    {
      return (*(this->get()))[this->getAddress(module)];
    }


    /**
     * Get subset of frame given module identifier and range of hit times.
     *
     * Note that the hit times should have been corrected for the maximal and minimal 
     * time offsets of the PMTs in the corresponding optical module.
     *
     * \param  module          module
     * \param  timeRange       time range [ns]
     * \return                 subset with begin and end iterators
     */
    JDAQFrameSubset getFrameSubset(const JDAQModuleIdentifier& module, const JTimeRange& timeRange) const
    {
      const int address = this->getAddress(module);

      const grid_type&      grid  = table           [address];
      const JDAQSuperFrame& frame = (*(this->get()))[address];

      const int first  = grid.getIndex(timeRange.getLowerLimit());
      const int second = grid.getIndex(timeRange.getUpperLimit());

      if (first < 0 || second >= grid.getSize()) {
        THROW(JTriggerException, "Time range [ns] " << timeRange << " bounds " << grid.getXmin() << ' ' << grid.getXmax() << " indices " << first << ' ' << second);
      }

      return frame.subset(grid.getY(first).lpos, grid.getY(second).rpos);
    }

  private:
    int                    number_of_bins;
    router_type            router;
    std::vector<grid_type> table;
  };
}

#endif