DetectorTimings.h

Go to the documentation of this file.

#ifndef LARDATAALG_DETECTORINFO_DETECTORTIMINGS_H
#define LARDATAALG_DETECTORINFO_DETECTORTIMINGS_H

// LArSoft libraries
#include "lardataalg/DetectorInfo/DetectorClocksData.h"
#include "lardataalg/DetectorInfo/DetectorTimingTypes.h" // ns. timescales
#include "lardataalg/Utilities/quantities/electronics.h"
#include "lardataalg/Utilities/quantities/frequency.h"
#include "lardataalg/Utilities/quantities/spacetime.h"

// C/C++ standard libraries
#include <type_traits> // std::enable_if_t, std::is_same_v, std::void_t

namespace detinfo {

  // ---------------------------------------------------------------------------
  class DetectorClocksWithUnits {

    detinfo::DetectorClocksData fClockData; // non-const to allow copy

  public:
    // import types
    using nanosecond = util::quantities::nanosecond;
    using microsecond = util::quantities::microsecond;
    using megahertz = util::quantities::megahertz;
    using ticks_d = util::quantities::ticks_d;

    // @{
    explicit DetectorClocksWithUnits(detinfo::DetectorClocksData const* detClocks)
      : DetectorClocksWithUnits(*detClocks)
    {}
    explicit DetectorClocksWithUnits(detinfo::DetectorClocksData const& detClocks)
      : fClockData(detClocks)
    {}
    // @}

    detinfo::DetectorClocksData const& clockData() const { return fClockData; }

    microsecond TriggerTime() const { return microsecond{clockData().TriggerTime()}; }

    microsecond BeamGateTime() const { return microsecond{clockData().BeamGateTime()}; }

    microsecond TPCTime() const { return microsecond{clockData().TPCTime()}; }

    // @{
    microsecond G4ToElecTime(nanosecond simTime) const
    {
      return microsecond{clockData().G4ToElecTime(simTime.value())};
    }
    microsecond G4ToElecTime(double simTime) const { return G4ToElecTime(nanosecond{simTime}); }
    // @}

    // @{
    ticks_d TPCTick2TDC(ticks_d tpcticks) const
    {
      return ticks_d{clockData().TPCTick2TDC(tpcticks.value())};
    }
    ticks_d TPCTick2TDC(double tpcticks) const { return TPCTick2TDC(ticks_d{tpcticks}); }
    // @}

    microsecond OpticalClockPeriod() const
    {
      return microsecond{clockData().OpticalClock().TickPeriod()};
    }

    megahertz OpticalClockFrequency() const
    {
      return megahertz{clockData().OpticalClock().Frequency()};
    }

  }; // class DetectorClocksWithUnits

  inline detinfo::DetectorClocksWithUnits makeDetectorClocksWithUnits(
    detinfo::DetectorClocksData const& clockData)
  {
    return detinfo::DetectorClocksWithUnits{clockData};
  }

  // ---------------------------------------------------------------------------
  class DetectorTimings : private detinfo::DetectorClocksWithUnits {

    template <typename TimeScale>
    using traits_of = detinfo::timescales::timescale_traits<typename TimeScale::category_t>;

    template <typename TimeScale>
    using time_interval_for = typename traits_of<TimeScale>::time_interval_t;

    template <typename TimeScale>
    using frequency_for = typename traits_of<TimeScale>::frequency_t;

  public:
    // --- BEGIN -- Imported time scale types ----------------------------------

    using electronics_time = detinfo::timescales::electronics_time;
    using TPCelectronics_time = detinfo::timescales::TPCelectronics_time;
    using optical_time = detinfo::timescales::optical_time;
    using trigger_time = detinfo::timescales::trigger_time;
    using simulation_time = detinfo::timescales::simulation_time;

    using electronics_tick = detinfo::timescales::electronics_tick;
    using TPCelectronics_tick = detinfo::timescales::TPCelectronics_tick;
    using optical_tick = detinfo::timescales::optical_tick;
    using trigger_tick = detinfo::timescales::trigger_tick;

    using electronics_tick_d = detinfo::timescales::electronics_tick_d;
    using TPCelectronics_tick_d = detinfo::timescales::TPCelectronics_tick_d;
    using optical_tick_d = detinfo::timescales::optical_tick_d;
    using trigger_tick_d = detinfo::timescales::trigger_tick_d;

    using time_interval = detinfo::timescales::time_interval;

    using electronics_time_ticks = detinfo::timescales::electronics_time_ticks;
    using TPCelectronics_time_ticks = detinfo::timescales::TPCelectronics_time_ticks;
    using optical_time_ticks = detinfo::timescales::optical_time_ticks;
    using trigger_time_ticks = detinfo::timescales::trigger_time_ticks;

    // --- END -- Imported time scale types ------------------------------------

    // note that `makeDetectorTimings()` provides an additional construction way
    // @{
    explicit DetectorTimings(detinfo::DetectorClocksData const& clockData)
      : detinfo::DetectorClocksWithUnits(clockData)
    {}
    explicit DetectorTimings(detinfo::DetectorClocksData const* clockData)
      : detinfo::DetectorClocksWithUnits(clockData)
    {}
    // @}

    // --- BEGIN -- Access to underlying service providers ---------------------

    detinfo::DetectorClocksWithUnits const& detClocksUnits() const
    {
      return static_cast<detinfo::DetectorClocksWithUnits const&>(*this);
    }

    detinfo::DetectorClocksData const& clockData() const { return detClocksUnits().clockData(); }

    // --- END -- Access to underlying service providers -----------------------

    // --- BEGIN -- Electronics times ------------------------------------------

    electronics_time TriggerTime() const
    {
      return electronics_time{detClocksUnits().TriggerTime()};
    }

    electronics_time BeamGateTime() const
    {
      return electronics_time{detClocksUnits().BeamGateTime()};
    }

    // --- END -- Electronics times --------------------------------------------

    // --- BEGIN -- Conversions ------------------------------------------------

    template <typename TargetTime, typename FromTime>
    TargetTime toTimeScale(FromTime time) const;

    template <typename TargetTick, typename FromTime>
    TargetTick toTick(FromTime time) const;

    template <typename Ticks>
    Ticks toTicks(time_interval time) const
    {
      return Ticks::castFrom(time / ClockPeriodFor<Ticks>());
    }

    template <typename FromTime>
    electronics_time toElectronicsTime(FromTime time) const
    {
      return toTimeScale<electronics_time>(time);
    }

    template <typename FromTime>
    electronics_tick_d toElectronicsTickD(FromTime time) const
    {
      return toTick<electronics_tick_d>(time);
    }

    template <typename FromTime>
    electronics_tick toElectronicsTick(FromTime time) const
    {
      return toTick<electronics_tick>(time);
    }

    template <typename FromTime>
    trigger_time toTriggerTime(FromTime time) const
    {
      return toTimeScale<trigger_time>(time);
    }

    template <typename FromTime>
    simulation_time toSimulationTime(FromTime time) const
    {
      return toTimeScale<simulation_time>(time);
    }

    // --- END -- Conversions --------------------------------------------------

    // --- BEGIN -- Clocks -----------------------------------------------------

    template <typename TimeScale>
    detinfo::ElecClock const& ClockFor() const;

    template <typename TimeScale>
    time_interval_for<TimeScale> ClockPeriodFor() const
    {
      return time_interval_for<TimeScale>{microsecond{ClockFor<TimeScale>().TickPeriod()}};
    }

    template <typename TimeScale>
    frequency_for<TimeScale> ClockFrequencyFor() const
    {
      return frequency_for<TimeScale>{megahertz{ClockFor<TimeScale>().Frequency()}};
    }
    // --- END -- Clocks -------------------------------------------------------

    // --- BEGIN -- Optical clock ----------------------------------------------

    auto OpticalClockPeriod() const { return ClockPeriodFor<optical_time>(); }

    megahertz OpticalClockFrequency() const { return ClockFrequencyFor<optical_time>(); }

    template <typename Ticks = optical_time_ticks>
    Ticks toOpticalTicks(time_interval time) const
    {
      static_assert(traits_of<Ticks>::template same_category_as<optical_tick>,
                    "Specified ticks are not for optical time scale!");
      return toTicks<Ticks>(time);
    }

    template <typename TimePoint>
    optical_tick toOpticalTick(TimePoint time) const
    {
      return toTick<optical_tick>(time);
    }

    template <typename TimePoint>
    optical_tick_d toOpticalTickD(TimePoint time) const
    {
      return toTick<optical_tick_d>(time);
    }

    // --- END -- Optical clock ------------------------------------------------

    // --- BEGIN -- Reference times --------------------------------------------

    time_interval fromStart(electronics_time time) const;

    template <typename TimePoint, typename TimeScale = electronics_time>
    constexpr TimeScale startTime() const;

    template <typename TickPoint, typename TimeTickScale = electronics_tick>
    constexpr TimeTickScale startTick() const;

    // --- END -- Reference times ----------------------------------------------

  private:
    friend detinfo::DetectorTimings makeDetectorTimings(detinfo::DetectorClocksWithUnits const&);

  }; // class DetectorTimings

  inline detinfo::DetectorTimings makeDetectorTimings(detinfo::DetectorClocksData const& detClocks)
  {
    return detinfo::DetectorTimings{detClocks};
  }

  inline detinfo::DetectorTimings makeDetectorTimings(detinfo::DetectorClocksData const* detClocks)
  {
    return makeDetectorTimings(*detClocks);
  }

  inline detinfo::DetectorTimings makeDetectorTimings(
    detinfo::DetectorClocksWithUnits const& detClocksWU)
  {
    return static_cast<detinfo::DetectorTimings const&>(detClocksWU);
  }

  // ---------------------------------------------------------------------------

} // namespace detinfo

//------------------------------------------------------------------------------
//---  template implementation
//------------------------------------------------------------------------------
namespace detinfo {

  // ---------------------------------------------------------------------------
  namespace details {

    using namespace util::quantities::time_literals;
    using namespace util::quantities::electronics_literals;

    // -------------------------------------------------------------------------
    // --- StartTimeImpl
    // -------------------------------------------------------------------------
    template <typename TimePoint, typename TimeScale = TimePoint, typename = void>
    struct StartTimeImpl {

      static constexpr TimeScale startTime [[noreturn]] (DetectorTimings const*)
      {
        static_assert(util::always_false_v<TimePoint>,
                      "Start time not implemented for this time in this time scale.");
        throw false;
      }

    }; // StartTimeImpl

    // -------------------------------------------------------------------------
    template <typename TimePoint>
    struct StartTimeImpl<TimePoint, TimePoint> {

      static constexpr TimePoint startTime(DetectorTimings const*) { return TimePoint{0_us}; }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    // --- to electronics time
    // ---
    template <>
    struct StartTimeImpl<detinfo::timescales::TPCelectronics_time, // source
                         detinfo::timescales::electronics_time     // destination
                         > {
      static detinfo::timescales::electronics_time startTime(DetectorTimings const* detTiming)
      {
        return detinfo::timescales::electronics_time(detTiming->detClocksUnits().TPCTime());
      }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    template <>
    struct StartTimeImpl<detinfo::timescales::optical_time,    // source
                         detinfo::timescales::electronics_time // destination
                         > {
      static constexpr detinfo::timescales::electronics_time startTime(DetectorTimings const*)
      {
        return detinfo::timescales::electronics_time(0_us);
      }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    template <>
    struct StartTimeImpl<detinfo::timescales::simulation_time, // source
                         detinfo::timescales::electronics_time // destination
                         > {
      static detinfo::timescales::electronics_time startTime(DetectorTimings const* detTiming)
      {
        return detinfo::timescales::electronics_time{
          detTiming->detClocksUnits().G4ToElecTime(0.0_ns)};
      } // startTime()

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    template <>
    struct StartTimeImpl<detinfo::timescales::trigger_time,    // scale to convert the start of
                         detinfo::timescales::electronics_time // destination scale
                         > {
      static detinfo::timescales::electronics_time startTime(DetectorTimings const* detTiming)
      {
        return detTiming->TriggerTime();
      }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    // --- from electronics time
    // ---
    template <typename TimeScale>
    struct StartTimeImpl<
      detinfo::timescales::electronics_time, // source
      TimeScale,                             // destination
      std::enable_if_t<!std::is_same_v<TimeScale, detinfo::timescales::electronics_time>>> {
      static TimeScale startTime(DetectorTimings const* detTiming)
      {
        return TimeScale{
          -(detTiming->startTime<TimeScale, detinfo::timescales::electronics_time>().quantity())};
      }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    // --- via electronics time
    // ---

    /*
     * this is a very generic version, which I hope C++ rules will prevent from
     * clashing with:
     * * the most generic version (this is a specialization)
     * * the one with same target and destination (explicitly vetoed)
     * * any one involving electronics_time (explicitly vetoed)
     * * any full specialization (this being partial, the full ones should win)
     */
    template <typename TimePoint, typename TimeScale>
    struct StartTimeImpl<
      TimePoint, // source
      TimeScale, // destination
      std::enable_if_t<!std::is_same_v<TimePoint, detinfo::timescales::electronics_time> &&
                       !std::is_same_v<TimeScale, detinfo::timescales::electronics_time> &&
                       !std::is_same_v<TimeScale, TimePoint>>> {
      static TimeScale startTime(DetectorTimings const* detTiming)
      {
        return detTiming->toTimeScale<TimeScale>(detTiming->startTime<TimePoint>());
      }
    }; // StartTimeImpl<> (via electronics_time)

    // -------------------------------------------------------------------------
    // --- StartTickImpl
    // -------------------------------------------------------------------------
    template <typename TickPoint, typename TimeTickScale = TickPoint>
    struct StartTickImpl;

    // -------------------------------------------------------------------------
    template <typename TickPoint>
    struct StartTickImpl<TickPoint, TickPoint> {

      static constexpr TickPoint startTick(DetectorTimings const*)
      {
        return TickPoint::castFrom(0.0);
      }

    }; // StartTickImpl<>

    // -------------------------------------------------------------------------
    template <>
    struct StartTickImpl<detinfo::timescales::TPCelectronics_tick_d, // source
                         detinfo::timescales::electronics_tick_d     // destination
                         > {
      static detinfo::timescales::electronics_tick_d startTick(DetectorTimings const* detTiming)
      {
        return detinfo::timescales::electronics_tick_d(
          detTiming->detClocksUnits().TPCTick2TDC(0_tickd));
      }

    }; // StartTimeImpl<>

    // -------------------------------------------------------------------------
    template <>
    struct StartTickImpl<detinfo::timescales::optical_tick,      // source
                         detinfo::timescales::electronics_tick_d // destination
                         > {
      static constexpr detinfo::timescales::electronics_tick_d startTick(DetectorTimings const*)
      {
        return 0_tickd;
      }

    }; // StartTickImpl<>

    // -------------------------------------------------------------------------

    // default implementation (for any time)
    template <typename FromTime, typename TargetTime, typename = void>
    struct TimeScaleConverter {

      static TargetTime convert(FromTime time, DetectorTimings const* timings)
      {
        return timings->startTime<FromTime, TargetTime>() + time.quantity();
      }
    };

    // special implementation when source and target are the same: passthrough
    template <typename TargetTime>
    struct TimeScaleConverter<TargetTime, TargetTime> {

      static TargetTime convert(TargetTime time, DetectorTimings const*) { return time; }

    }; // TimeScaleConverter<TargetTime, TargetTime>

    // special implementation for ticks as source
    template <typename FromTick, typename TargetTime>
    struct TimeScaleConverter<FromTick,
                              TargetTime,
                              std::enable_if_t<detinfo::timescales::is_tick_v<FromTick>>> {

      static TargetTime convert(FromTick tick, DetectorTimings const* timings)
      {
        using FromTime = typename detinfo::timescales::timescale_traits<
          typename FromTick::category_t>::time_point_t;
        return timings->toTimeScale<TargetTime>(
          FromTime{tick.value() * timings->ClockPeriodFor<FromTick>().quantity()});
      }

    }; // TimeScaleConverter<FromTick>

    // -------------------------------------------------------------------------
    // default implementation (for any time)
    template <typename FromTime, typename TargetTick, typename = void>
    struct TickConverter {

      static TargetTick convert(FromTime time, DetectorTimings const* timings)
      {
        // dispatcher
        if constexpr (detinfo::timescales::is_tick_v<FromTime>)
          return convertTick(time, timings);
        else
          return convertTime(time, timings);
      } // convert()

      static TargetTick convertTime(FromTime time, DetectorTimings const* timings)
      {
        static_assert(!detinfo::timescales::is_tick_v<FromTime>);
        using TargetTime = typename detinfo::timescales::timescale_traits<
          typename TargetTick::category_t>::time_point_t;
        auto const timeFromStart = time - timings->startTime<TargetTime, FromTime>();
        auto const clockPeriod = timings->ClockPeriodFor<TargetTick>();
        return TargetTick::castFrom(timeFromStart / clockPeriod);
      } // convertTime()

      static TargetTick convertTick(FromTime tick, DetectorTimings const* timings)
      {
        static_assert(detinfo::timescales::is_tick_v<FromTime>);
        // effectively we must go very close to the times from the tick;
        // so we go all the way there
        using TargetTime = typename detinfo::timescales::timescale_traits<
          typename TargetTick::category_t>::time_point_t;
        auto const time = timings->toTimeScale<TargetTime>(tick);
        return timings->toTick<TargetTick>(time);
      } // convertTick()

    }; // TickConverter

    // -------------------------------------------------------------------------

    // -------------------------------------------------------------------------
    template <typename TimeScale, typename = void>
    struct ClockForImpl {

      static detinfo::ElecClock const& get [[noreturn]] (DetectorTimings const*)
      {
        static_assert(util::always_false_v<TimeScale>,
                      "Electronics clock not defined for this time scale.");
        throw false;
      }

    }; // struct ClockForImpl

    template <typename TimeScale>
    struct ClockForImpl<TimeScale, std::void_t<typename TimeScale::category_t>>
      : ClockForImpl<typename TimeScale::category_t> {};

    template <>
    struct ClockForImpl<detinfo::timescales::TPCelectronicsTimeCategory> {
      static detinfo::ElecClock const& get(DetectorTimings const* timings)
      {
        return timings->clockData().TPCClock();
      }
    };

    template <>
    struct ClockForImpl<detinfo::timescales::OpticalTimeCategory> {
      static detinfo::ElecClock const& get(DetectorTimings const* timings)
      {
        return timings->clockData().OpticalClock();
      }
    };

    template <>
    struct ClockForImpl<detinfo::timescales::TriggerTimeCategory> {
      static detinfo::ElecClock const& get(DetectorTimings const* timings)
      {
        return timings->clockData().TriggerClock();
      }
    };

    template <>
    struct ClockForImpl<detinfo::timescales::ElectronicsTimeCategory>
      : ClockForImpl<detinfo::timescales::TPCelectronicsTimeCategory> {};

    // -------------------------------------------------------------------------

  } // namespace details

  // ---------------------------------------------------------------------------
  template <typename TimePoint, typename TimeScale /* = electronics_time */>
  constexpr TimeScale DetectorTimings::startTime() const
  {
    return details::StartTimeImpl<TimePoint, TimeScale>::startTime(this);
  }

  // ---------------------------------------------------------------------------
  template <typename TickPoint, typename TimeTickScale /* = electronics_tick */>
  constexpr TimeTickScale DetectorTimings::startTick() const
  {
    return details::StartTickImpl<TickPoint, TimeTickScale>::startTick(this);
  }

  // ---------------------------------------------------------------------------
  template <typename TargetTime, typename FromTime>
  TargetTime DetectorTimings::toTimeScale(FromTime time) const
  {
    return details::TimeScaleConverter<FromTime, TargetTime>::convert(time, this);
  } // DetectorTimings::toTimeScale()

  // ---------------------------------------------------------------------------
  template <typename TargetTick, typename FromTime>
  TargetTick DetectorTimings::toTick(FromTime time) const
  {
    return details::TickConverter<FromTime, TargetTick>::convert(time, this);
  } // DetectorTimings::toTick()

  // ---------------------------------------------------------------------------
  template <typename TimeScale>
  detinfo::ElecClock const& DetectorTimings::ClockFor() const
  {
    return details::ClockForImpl<TimeScale>::get(this);
  }

  // ---------------------------------------------------------------------------
  inline auto DetectorTimings::fromStart(electronics_time time) const -> time_interval
  {
    return time - startTime<electronics_time, electronics_time>();
  }

  // ---------------------------------------------------------------------------

} // namespace detinfo

//------------------------------------------------------------------------------

#endif // LARDATAALG_DETECTORINFO_DETECTORTIMINGS_H