DaqDecoderICARUSPMT_module.cc

Go to the documentation of this file.

/**
 * @file    DaqDecoderICARUSPMT_module.cc
 * @brief   Produces `raw::OpDetWaveform` from V1730 artDAQ data fragments.
 * @authors Andrea Scarpelli, Gianluca Petrillo (petrillo@slac.stanford.edu)
 * @date    May 21, 2021
 * 
 */


// ICARUS/SBN libraries
#include "icaruscode/Decode/DecoderTools/details/PMTDecoderUtils.h"
#include "icaruscode/Decode/DecoderTools/Dumpers/FragmentDumper.h"
#include "icaruscode/Decode/ChannelMapping/IICARUSChannelMap.h"
#include "sbnobj/Common/Trigger/ExtraTriggerInfo.h" 
#include "sbnobj/Common/Trigger/BeamBits.h"
#include "icarusalg/Utilities/BinaryDumpUtils.h" // icarus::ns::util::bin()
#include "icaruscode/Utilities/ArtHandleTrackerManager.h"

#include "sbnobj/Common/PMT/Data/PMTconfiguration.h" // sbn::PMTconfiguration
#include "sbndaq-artdaq-core/Overlays/Common/CAENV1730Fragment.hh"
#include "sbndaq-artdaq-core/Overlays/FragmentType.hh" // sbndaq::FragmentType

// LArSoft libraries
#include "lardata/DetectorInfoServices/DetectorClocksService.h"

#include "lardataalg/DetectorInfo/DetectorTimings.h"
#include "lardataalg/DetectorInfo/DetectorClocks.h"
#include "lardataalg/Utilities/quantities/spacetime.h" // nanoseconds
#include "lardataalg/Utilities/intervals_fhicl.h" // for nanoseconds in FHiCL
#include "larcorealg/CoreUtils/enumerate.h"
#include "larcorealg/CoreUtils/counter.h"

#include "lardataobj/RawData/OpDetWaveform.h"
#include "lardataobj/RawData/TriggerData.h"

// artDAQ
#include "artdaq-core/Data/ContainerFragment.hh"
#include "artdaq-core/Data/Fragment.hh"

// framework libraries
#include "art_root_io/TFileService.h"
#include "art/Framework/Services/Registry/ServiceHandle.h" 
#include "art/Framework/Core/EDProducer.h"
#include "art/Framework/Core/ModuleMacros.h"
#include "art/Framework/Principal/Run.h"
#include "art/Framework/Principal/Event.h"
#include "art/Framework/Principal/Handle.h"
#include "canvas/Persistency/Provenance/EventID.h"
#include "canvas/Persistency/Provenance/Timestamp.h"
#include "canvas/Utilities/InputTag.h"
#include "messagefacility/MessageLogger/MessageLogger.h"
#include "fhiclcpp/types/TableAs.h"
#include "fhiclcpp/types/OptionalSequence.h"
#include "fhiclcpp/types/Sequence.h"
#include "fhiclcpp/types/OptionalAtom.h"
#include "fhiclcpp/types/Atom.h"
#include "cetlib_except/exception.h"

// ROOT libraries
#include "TTree.h"

// C/C++ standard libraries
#include <memory>
#include <ostream>
#include <unordered_map>
#include <map>
#include <set>
#include <vector>
#include <string>
#include <optional>
#include <cassert>


//------------------------------------------------------------------------------
using namespace util::quantities::time_literals;
using detinfo::timescales::electronics_time;

//------------------------------------------------------------------------------
namespace icarus { class DaqDecoderICARUSPMT; }
/**
 * @brief Produces `raw::OpDetWaveform` from V1730 artDAQ data fragments.
 * 
 * The module can read fragments from CAEN V1730 readout boards delivered by
 * artDAQ. It produces optical detector waveforms in LArSoft standards.
 * 
 * This decoder must support both a off-line mode (for storage and downstream
 * processing) and a on-line mode (for monitoring).
 * In particular, the on-line workflow is such that it may not be possible to
 * access the FHiCL configuration of the job and therefore the PMT configuration
 * data (see `icarus::PMTconfigurationExtraction` module).
 * 
 * 
 * Configuration
 * --------------
 * 
 * The set of supported parameters can be seen on command line by running
 * `lar --print-description DaqDecoderICARUSPMT`.
 * 
 * Description of the configuration parameters:
 * * `FragmentsLabels` (list of input tags): a list of possible input data
 *     products. A valid input data product contain a list of fragments from
 *     V1730. All input tags are tried. If only one is available, its content
 *     is used for decoding; otherwise, an exception is thrown.
 * * `DiagnosticOutput` (flag, default: `false`): enables additional console
 *     output, including dumping of the fragments (that is huge output).
 * * `PMTconfigTag` (data product tag, optional): if specified, the pre-trigger
 *     buffer duration is read from there; although optional, it is strongly
 *     recommended that this information be provided, since it is essential for
 *     the correct timing of the PMT waveforms (see
 *     @ref icarus_PMTDecoder_timestamps "the discussion on time stamps below").
 * * `BoardSetup` (list of board setup information): each entry specifies some
 *     information about a specific readout board; the boards are identified by
 *     their name; if a board is found in input that has no setup information,
 *     some time corrections are not applied (see
 *     @ref icarus_PMTDecoder_timestamps "the discussion on time stamps below").
 *     Each entry is in the form of a table:
 *     * `Name` (string, mandatory): the name of the board
 *        (e.g. `"icaruspmtwwtop01"`); this is use to match the setup
 *        information to a fragment ID in the PMT configuration.
 *     * `FragmentID` (integral, optional): if specified, allows the corrections
 *       using setup information to be applied even when no PMT configuration is
 *       provided (if neither PMT configuration nor setup information including
 *       `FragmentID` is available, no time correction is applied).
 *     * `TriggerDelay` (nanoseconds, default: 0 ns): measured delay from the
 *       primitive trigger time to the execution of the PMT trigger; specify
 *       the unit! (e.g. `"43 ns"`).
 *     * `SpecialChannels` (list of configurations): each entry described
 *       special features and settings of a specific channel, identified by
 *       its V1730B board channel number (`0` to `15`). The supported keys are:
 *         * `ChannelIndex` (integer, mandatory) the index of the channel in
 *           the board, from `0` to `15`; note that for this module to decode
 *           this channel index, the channel itself must be enabled on the
 *           readout board.
 *         * `Skip` (flag, optional): if specified, tells whether to always skip
 *           this channel or whether always store it. If not specified, a
 *           channel will be always stored unless it is not associated to any
 *           channel number (see `Channel` below). Note that if the channel is
 *           not enabled in the readout board, this option has no effect.
 *         * `OnlyOnGlobalTrigger` (flag, default: `false`): if set, waveforms
 *           are saved from this channel only when it includes the global
 *           trigger time; if no trigger time is available, such channels will
 *           never be saved.
 *         * `MinSpan` (integer, default: `0`): waveforms which have a span
 *           (highest sample minus lowest sample) smaller than this limit are
 *           not saved (unless `Skip` is set to `false`).
 *         * `Channel` (integral, optional): if specified, it overrides the
 *           channel number used for the waveforms on this channel; if not
 *           specified, the channel number is obtained from the channel mapping
 *           database. Note that insisting to save a waveform without an
 *           assigned channel number (from database or from this configuration)
 *           will trigger an exception.
 *         * `InstanceName` (string, default: empty): the waveform will be
 *           stored in a collection of `raw::OpDetWaveform` with the specified
 *           instance name; the default is an empty name, which is the standard
 *           data product where all the normal waveforms are saved.
 * * `RequireKnownBoards` (flag, default: `true`): if set, the readout boards
 *     in input must each have a setup configuration (`BoardSetup`) *and* must
 *     be present in the PMT DAQ configuration, or an exception is thrown;
 *     if not set, readout boards in input will be processed even when their
 *     setup or DAQ configuration is not known, at the cost of fewer corrections
 *     on the timestamps (which should then be considered unreliable).
 * * `RequireBoardConfig` (flag, default: `true`): if set, the readout boards
 *     which have a setup (`BoardSetup`) are required to be included in the DAQ
 *     configuration of the input file, or an exception is thrown; if not set,
 *     missing readout boards are unnoticed.
 * * `TriggerTag` (data product tag): tag for the information
 *     (`sbn::ExtraTriggerInfo`, produced by trigger decoding); if not
 *     specified, the _art_ event timestamp will be used as trigger time (*not*
 *     recommended).
 * * `TTTresetEverySecond` (optional): if set, the decoder will take advantage
 *     of the assumption that the Trigger Time Tag of all PMT readout boards is
 *     synchronised with the global trigger time and reset at every change of
 *     second of the timescale of the latter; this is currently the only
 *     implementation supporting multiple PMT readout windows on the same board;
 *     if this option is set to `false`, all PMT readout boards are assumed to
 *     have been triggered at the time of the global trigger. By default, this
 *     option is set to `true` unless `TriggerTag` is specified empty.
 * * `DataTrees` (list of strings, default: none): list of data trees to be
 *     produced; if none (default), then `TFileService` is not required.
 * * `SkipWaveforms` (flag, default: `false`) if set, waveforms won't be
 *     produced; this is intended as a debugging option for jobs where only the
 *     `DataTrees` are desired.
 * * `DropRawDataAfterUse` (flag, default: `true`): at the end of processing,
 *     the framework will be asked to remove the PMT data fragment from memory.
 *     Set this to `false` in the unlikely case where raw PMT fragments are
 *     still needed after decoding.
 * * `LogCategory` (string, default: `DaqDecoderICARUSPMT`): name of the message
 *     facility category where the output is sent.
 * 
 * 
 * Requirements
 * -------------
 * 
 * Services required include:
 * 
 * * `IICARUSChannelMap` for the association of fragments to LArSoft channel ID;
 * * `DetectorClocksService` for the correct decoding of the time stamps
 *   (always required, even when dumbed-down timestamp decoding is requested);
 * * `TFileService` only if the production of trees or plots is requested.
 * 
 * 
 * Waveform time stamp
 * --------------------
 * 
 * @anchor icarus_PMTDecoder_timestamps
 * 
 * All waveforms on the same readout board fragment share the same timestamp.
 * The same readout board can produce different fragments at different times
 * within an event in which case each fragment will be independently assigned
 * a timstamp .
 * 
 * The time stamp of the waveform is defined as the time when the first sample
 * of the waveform started (that is, if the sample represent the value of the
 * signal in an interval of 2 ns, the time stamp is pointing at the beginning
 * of those 2 ns). Whether we can honour that definition, though, is a different
 * matter.
 * The representation of the time stamp is in the
 * @ref DetectorClocksElectronicsTime "electronics time scale".
 * 
 * Waveforms all originate from a trigger primitive signal being sent to the
 * readout boards by NI7820 FPGA to start the acquisition of the waveform.
 * One of these primitives matches the global event trigger, but the
 * corresponding fragment is not treated in any special way.
 * Every delay between when that signal is emitted and when the PMT trigger is
 * executed shifts the timestamp of the waveform backward.
 * 
 * We assign the the time stamp of the waveforms as follow:
 * 1. the base time is the global trigger time; the global trigger time is read
 *   from the trigger data, where it is stored as an absolute time in TAI scale;
 *   the global trigger time itself effectively defines the electronics time
 *   scale used within a _art_ event, so its representation is a fixed number
 *   that is configured in LArSoft and can be accessed with
 *   `DetectorClocksData::TriggerTime()`;
 * 2. each V1730 data fragment comes with a time tag ("TTT") describing the time
 *   of the end of the readout buffer (unknown whether the start or the end of
 *   the tick of the last sample). This tag is a counter internal to the V1730
 *   board, incremented every 8 ns. The counter is reset at the beginning of
 *   every "new" TAI second, and it can thus be easily transformed into a time
 *   in the same TAI scale as the global trigger; the difference between TTT
 *   and the global trigger pins down the end of the readout buffer in the
 *   electronics time scale;
 * 3. a delay is subtracted to the timestamp, which encompasses all fixed delays
 *   occurring in the trigger signal transportation; the most prominent is the
 *   delay occurring between the start of the "new" TAI second and when the
 *   TTT reset signal reaches and is honoured by the readout board.
 *   This value must be independently measured and provided to this decoder via
 *   configuration as setup information (`TTTresetDelay`); if not present in the
 *   setup, this delay is not added;
 * 4. finally, the time of the beginning of the waveform, that is the target
 *   for `raw::OpDetWaveform` timestamp, is obtained from the time of its end
 *   by simply subtracting the readout buffer length.
 * 
 * A special decoding mode, hoped to be just historical by now, does not rely
 * on the global trigger time. This mode can be safely used only when the (only)
 * data fragment was triggered by the global trigger (e.g. in the simplest
 * minimum/zero bias trigger). It has the advantage that it does not use the TTT
 * information. It can be enabled explicitly by setting the option
 * `TTTresetEverySecond` to `true`, or by removing the specification of the
 * trigger time data product tag (`TriggerTag`).
 * 1. The trigger primitive time is assumed to be the global trigger time too,
 *   so that the trigger primitive time in electronics time also matches the
 *   global trigger time.
 * 2. upon receiving the trigger primitive signal, the readout board will keep
 *   some of the samples already digitized, in what we call pre-trigger buffer;
 *   the size of this buffer is a fixed number of samples which is specified in
 *   DAQ as a fraction of the complete buffer that is _post-trigger_; this
 *   amount, converted in time, is subtracted to the trigger time to point back
 *   to the beginning of the waveform instead that to the trigger primitive
 *   time. The necessary information is read from the PMT configuration
 *   (`PMTconfigTag`); if no configuration is available, this offset is not
 *   subtracted; note that this is a major shift (typically, a few microseconds)
 *   that should be always included. This step is equivalent to the step (4) of
 *   the regular mode, where here the adjustment starts from the trigger
 *   primitive time instead than from the end-of-buffer time.
 * 3. a delay is subtracted to the timestamp, which encompasses all fixed delays
 *   occurring in the trigger signal transportation; one component of it is the
 *   relative delay in the propagation of the trigger primitive signal from a
 *   board to the next (in fact, every three boards have the trigger signal in
 *   daisy chain). This value must be independently measured and provided to
 *   this decoder via configuration as setup information (`TriggerDelay`); if
 *   not present in the setup, this delay is not added.
 *   Note that the particular contribution of the daisy chain to the delay does
 *   not need to be explicitly taken into account in the main mode, because the
 *   TTT reset is independent  and not daisy-chained, so that the TTT times
 *   are all synchronized and when the primitive trigger arrives (via daisy
 *   chain) the TTT value at that instant is already including the delay.
 * 
 * 
 * 
 * Data trees
 * -----------
 * 
 * The module supports the following ROOT trees production on demand:
 * 
 * * `PMTfragments`: data pertaining a single fragment; each entry is about a
 *   single fragment, and it includes full event ID, event time stamp (from
 *   _art_, i.e. the one assigned to the event by artDAQ), the ID of the
 *   fragment the entry is describing, and then the rest of the data, including:
 *     * `TTT` (64-bit integer): (Extended) Trigger Time Tag value, in readout
 *       board ticks (each worth 8 ns) from the last board reset;
 *       currently the value includes the 31-bit counter and in addition the
 *       overflow bit as MSB; the overflow bit is set by the readout board
 *       the first time the counter passes its limit (2^31) and wraps, and never
 *       cleared until the next board reset.
 *       While the tree has room for the 48-bit version (ETTT), the rest of the
 *       decoder does not yet support it.
 *     * `trigger` (64-bit signed integer): global trigger time (from the
 *       trigger decoder), in nanoseconds from The Epoch.
 *     * `triggerSec`, `triggerNS` (32-bit integer each): same time as `trigger`
 *       branch, split into second and nanosecond components.
 *     * `relBeamGateNS`, (32-bit integer): beam gate time opening relative to
 *       the trigger time, in nanoseconds; it may be affected by rounding.
 *       branch, split into second and nanosecond components.
 *     * `fragTime` (64-bit signed integer), `fragTimeSec` (32-bit signed
 *       integer): the timestamp of the PMT fragment, assigned by the board
 *       reader constructing the fragment.
 *     * `fragCount` (unsigned integer): the counter of the fragment within a
 *       readout board (its "event counter").
 *     * `waveformTime` (double): time assigned to the waveforms from this
 *       fragment (electronics time scale).
 *     * `waveformSize` (unsigned integer): number of ticks for the waveforms
 *       from this fragment.
 *     * `triggerBits` (unsigned integer): bits from the `raw::Trigger`.
 *     * `gateCount` (unsigned integer): number of this gate from run start.
 *     * `onGlobalTrigger` (boolean): whether the waveform covers the nominal
 *       trigger time (which should be equivalent to whether the fragment was
 *       triggered by the global trigger).
 * 
 * 
 * Technical notes
 * ----------------
 * 
 * In order to correctly reconstruct the time stamp, this module needs several
 * pieces of information.
 * These include the size of the pre-trigger buffer, which is set by the readout
 * board configuration, and the delay either between the start of the "new"
 * second and the execution of the TTT reset, or between the global trigger and
 * the time that trigger is received and acted upon in the readout board,
 * depending of the time stamping mode; in both cases, the delays need to be
 * measured.
 * The first category of information, from readout board configuration, are read
 * from the input file (`sbn::PMTconfiguration`), while the second category
 * needs to be specified in the module FHiCL configuration.
 * 
 * PMT configuration is optional, in the sense that it can be omitted; in that
 * case, some standard values will be used for it. This kind of setup may be
 * good for monitoring, but it does not meet the requirements for physics
 * analyses.
 * For a board to be served, an entry of that board must be present in the
 * module configuration (`BoardSetup`). It is an error for a fragment in input
 * not to have an entry for the corresponding board setup.
 * 
 * The module extracts the needed information and matches it into a
 * sort-of-database keyed by fragment ID, so that it can be quickly applied
 * when decoding a fragment. The matching is performed by board name.
 * 
 * 
 * ### Proto-waveforms
 * 
 * The module has grown complex enough that some decisions need to be taken much
 * later after a waveform is created, but using information available only
 * during the creation. For example, a waveform can be ultimately routed to a
 * different data product depending on which readout board it comes from,
 * but that information is lost by the time the waveform needs to be written.
 * Rather than attempting to recreate that information, it is saved when still
 * available and travels together with the waveform itself in a data structure
 * called "proto-waveform". The extra-information is eventually discarded when
 * putting the actual waveform into the _art_ event.
 * 
 * 
 * ### Processing pipeline
 * 
 * Processing happens according to the following structure (in `produce()`):
 * 1. pre-processing: currently nothing
 * 2. processing of each board data independently: at this level, all the
 *    buffers from the 16 channels of a single board are processed together
 *    (`processBoardFragments()`)
 *     1. the configuration and parameters specific to this board are fetched
 *     2. each data fragment is processed independently: at this level, data
 *        from all 16 channels _at a given time_ are processed together,
 *        producing up to 16 proto-waveforms
 *     3. merging of contiguous waveforms is performed
 * 3. post-processing of proto-waveforms:
 *     * sorting by time (as opposed as roughly by channel, as they come)
 * 4. conversion to data products and output
 * 
 * 
 * 
 * Glossary
 * ---------
 * 
 * * **setup**, **[PMT] configuration**: this is jargon specific to this module.
 *     Information about a readout board can come from two sources: the "setup"
 *     is information included in the `BoardSetup` configuration list of this
 *     module; the "PMT configuration" is information included in the DAQ
 *     configuration that is delivered via `PMTconfigTag`.
 * * **TAI** (International Atomic Time): a time standard defining a universal
 *     time with a precision higher than it will ever matter for ICARUS.
 * * **TTT**: trigger time tag, from the V1730 event record (31 bits); may be:
 * * **ETTT**: extended trigger time tag, from the V1730 event record (48 bits).
 * * **trigger delay**: time point when a V1730 board processes a (PMT) trigger
 *     signal (and increments the TTT register) with respect to the time of the
 *     time stamp of the (SPEXi) global trigger that acquired the event.
 * 
 */
class icarus::DaqDecoderICARUSPMT: public art::EDProducer {
  
  // --- BEGIN -- some debugging tree declarations -----------------------------
  
  /// Enumerate the supported data trees.
  enum class DataTrees: std::size_t {
    Fragments, ///< Information about fragments
    N          ///< Counter.
  };
  using TreeNameList_t
    = std::array<std::string, static_cast<std::size_t>(DataTrees::N)>;
  static TreeNameList_t const TreeNames;
  
  /// Returns a string with all supported tree names.
  static std::string listTreeNames(std::string const& sep = "\n");
  
  // --- END ---- some debugging tree declarations -----------------------------
  
    public:
  
  // --- BEGIN -- public data types --------------------------------------------
  
  using nanoseconds = util::quantities::intervals::nanoseconds; ///< Alias.
  
  /// Data structure for trigger time.
  struct SplitTimestamp_t {
    static_assert(sizeof(int) >= 4U);
    struct Split_t {
        int seconds = std::numeric_limits<int>::min(); ///< The ongoing second.
        /// Nanoseconds from the start of current second.
        unsigned int nanoseconds = std::numeric_limits<unsigned int>::max();
    }; // Split_t
    
    /// Trigger time in nanoseconds from The Epoch.
    long long int time = std::numeric_limits<long long int>::min();
    /// Trigger time in nanoseconds from The Epoch (in components).
    Split_t split;
    
    constexpr SplitTimestamp_t() = default;
    constexpr SplitTimestamp_t(int sec, unsigned int ns);
    constexpr SplitTimestamp_t(long long int triggerTime);
  }; // SplitTimestamp_t
  
  // --- END ---- public data types --------------------------------------------
  
  
  // --- BEGIN -- FHiCL configuration ------------------------------------------
  
  /// Configuration of the V1730 readout board setup.
  struct BoardSetupConfig {
    
    struct ChannelSetupConfig {
      
      fhicl::Atom<unsigned short int> ChannelIndex {
        fhicl::Name("ChannelIndex"),
        fhicl::Comment
          ("index of the channel on the board these settings pertain")
        // mandatory
        };
      
      fhicl::OptionalAtom<bool> Skip {
        fhicl::Name("Skip"),
        fhicl::Comment(
          "set to true to force skipping this channel, false to force saving it"
          )
        };
      
      fhicl::Atom<bool> OnlyOnGlobalTrigger {
        fhicl::Name("OnlyOnGlobalTrigger"),
        fhicl::Comment
          ("save this channel only if its data includes global trigger time"),
        false // default
        };
      
      fhicl::Atom<std::uint16_t> MinSpan {
        fhicl::Name("MinSpan"),
        fhicl::Comment(
          "discard this channel if its span (maximum minus minimum)"
          " is smallerthan this"
          ),
        0 // default
        };
      
      fhicl::Atom<raw::Channel_t> Channel {
        fhicl::Name("Channel"),
        fhicl::Comment("Off-line channel ID associated to this board channel"),
        sbn::V1730channelConfiguration::NoChannelID
        };
      
      fhicl::Atom<std::string> InstanceName {
        fhicl::Name("InstanceName"),
        fhicl::Comment
          ("name of the data product instance where to add this channel"),
        "" // default
        };
      
    }; // struct ChannelSetupConfig
    
    
    fhicl::Atom<std::string> Name {
      fhicl::Name("Name"),
      fhicl::Comment("board name, as specified in the DAQ configuration")
      };
    
    fhicl::OptionalAtom<unsigned int> FragmentID {
      fhicl::Name("FragmentID"),
      fhicl::Comment("ID of the fragments associated with the board")
      };
    
    fhicl::Atom<nanoseconds> TriggerDelay {
      fhicl::Name("TriggerDelay"),
      fhicl::Comment
        ("from delay from the trigger timestamp to the PMT trigger [ns]"),
      0_ns
      };
    
    fhicl::Atom<nanoseconds> TTTresetDelay {
      fhicl::Name("TTTresetDelay"),
      fhicl::Comment
        ("assume that V1730 counter (Trigger Time Tag) is reset every second"),
      0_ns
      };
    
    fhicl::OptionalSequence<fhicl::Table<ChannelSetupConfig>> SpecialChannels {
      fhicl::Name("SpecialChannels"),
      fhicl::Comment("special settings for selected channels on the board")
      };
    
  }; // struct BoardSetupConfig
  
  
  /// Main module configuration.
  struct Config {
    
    using Name = fhicl::Name;
    using Comment = fhicl::Comment;
    
    fhicl::Sequence<art::InputTag> FragmentsLabels {
      Name("FragmentsLabels"),
      Comment("data product candidates with the PMT fragments from DAQ"),
      std::vector<art::InputTag>{ "daq:CAENV1730", "daq:ContainerCAENV1730" }
      };
    
    fhicl::Atom<bool> SurviveExceptions {
      Name("SurviveExceptions"),
      Comment
        ("when the decoding module throws an exception, print a message and move on"),
      true // default
      };
    
    fhicl::Atom<bool> DiagnosticOutput {
      Name("DiagnosticOutput"),
      Comment("enable additional console output"),
      false // default
      };
    
    fhicl::Atom<bool> PacketDump {
      Name("PacketDump"),
      Comment("enable dump of the whole V1730 data (huge)"),
      false // default
      };
    
    fhicl::Atom<bool> RequireKnownBoards {
      Name("RequireKnownBoards"),
      Comment
        ("all readout boards in input must be known (setup+PMT configuration)"),
      true
      };
    
    fhicl::Atom<bool> RequireBoardConfig {
      Name("RequireBoardConfig"),
      Comment
        ("all readout boards in setup must have a matching PMT configuration"),
      true
      };
    
    fhicl::OptionalAtom<art::InputTag> PMTconfigTag {
      Name("PMTconfigTag"),
      Comment("input tag for the PMT readout board configuration information")
      };
    
    fhicl::Sequence
      <fhicl::TableAs<daq::details::BoardSetup_t, BoardSetupConfig>>
    BoardSetup {
      Name("BoardSetup"),
      Comment("list of the setup settings for all relevant V1730 boards")
      };
    
    fhicl::OptionalAtom<art::InputTag> TriggerTag {
      Name("TriggerTag"),
      Comment("input tag for the global trigger object (sbn::ExtraTriggerInfo)")
      };
    
    fhicl::OptionalAtom<bool> TTTresetEverySecond {
      Name("TTTresetEverySecond"),
      Comment
        ("assume that V1730 counter (Trigger Time Tag) is reset every second")
      };
    
    fhicl::Sequence<std::string> DataTrees {
      fhicl::Name("DataTrees"),
      fhicl::Comment
        ("produces the specified ROOT trees (" + listTreeNames(",") + ")"),
      std::vector<std::string>{} // default
      };
    
    fhicl::Atom<bool> SkipWaveforms {
      Name("SkipWaveforms"),
      Comment("do not decode and produce waveforms"),
      false // default
      };
    
    fhicl::Atom<bool> DropRawDataAfterUse {
      Name("DropRawDataAfterUse"),
      Comment("drop PMT data fragments from memory after use"),
      true // default
      };
    
    fhicl::Atom<std::string> LogCategory {
      Name("LogCategory"),
      Comment("name of the category for message stream"),
      "PMTDecoder" // default
      };
    
  }; // Config
  
  using Parameters = art::EDProducer::Table<Config>;
  
  
  static constexpr electronics_time NoTimestamp
    = std::numeric_limits<electronics_time>::min();
  
  
  // --- END ---- FHiCL configuration ------------------------------------------
  
  
  /// Constructor.
  explicit DaqDecoderICARUSPMT(Parameters const& params);
  
  /// On a new run: cache PMT configuration information.
  void beginRun(art::Run& run) override;
  
  /// Processes the event.
  void produce(art::Event& event) override;
  
  /// Prints a end-of-job message.
  void endJob() override;
  
  
    private:
  
  /// Type of setup of all channels in a readout board.
  using AllChannelSetup_t = daq::details::BoardSetup_t::AllChannelSetup_t;
  
  /// Collection of useful information from fragment data.
  struct FragmentInfo_t {
    artdaq::Fragment::fragment_id_t fragmentID
      = std::numeric_limits<artdaq::Fragment::fragment_id_t>::max();
    artdaq::Fragment::timestamp_t fragmentTimestamp;
    unsigned int eventCounter = 0U;
    std::uint32_t TTT = 0U;
    std::uint16_t enabledChannels = 0U;
    std::size_t nSamplesPerChannel = 0U;
    std::uint16_t const* data = nullptr;
  }; // FragmentInfo_t
  
  /// Information used in decoding from a board.
  struct NeededBoardInfo_t {
    static AllChannelSetup_t const DefaultChannelSetup; // default-initialized
    
    std::string const name;
    nanoseconds bufferLength;
    nanoseconds preTriggerTime;
    nanoseconds PMTtriggerDelay;
    nanoseconds TTTresetDelay;
    AllChannelSetup_t const* specialChannelSetup = nullptr;
    
    AllChannelSetup_t const& channelSetup() const
      { return specialChannelSetup? *specialChannelSetup: DefaultChannelSetup; }
    
  }; // NeededBoardInfo_t
  
  /// Collection of information about the global trigger.
  struct TriggerInfo_t {
    SplitTimestamp_t time; ///< Time of the trigger (absolute).
    long int relBeamGateTime; ///< Time of beam gate relative to trigger [ns].
    sbn::triggerSourceMask bits; ///< Trigger bits.
    unsigned int gateCount = 0U; ///< Gate number from the beginning of run.
  }; // TriggerInfo_t
  
  /// All the information collected about a waveform (with the waveform itself).
  struct ProtoWaveform_t {
    
    raw::OpDetWaveform waveform; ///< The complete waveform.
    
    /// Pointer to the settings for the channel this waveform belongs to.
    daq::details::BoardSetup_t::ChannelSetup_t const* channelSetup = nullptr;
    
    /// Whether the waveform includes the global trigger time.
    bool onGlobal = false;
    
    ///< Lowest sample in the original waveform.
    std::uint16_t minSample = std::numeric_limits<std::uint16_t>::max();
    ///< Highest sample in the original waveform.
    std::uint16_t maxSample =  std::numeric_limits<std::uint16_t>::max();
    
    ///< Returns the span of the waveform (cached, not computed anew!).
    std::uint16_t span() const
      { return (maxSample > minSample)? (maxSample - minSample): 0; }
    
    /// Ordering: the same as the contained waveform.
    bool operator< (ProtoWaveform_t const& than) const
      { return waveform < than.waveform; }
    
  }; // struct ProtoWaveform_t

  // --- BEGIN -- Configuration parameters -------------------------------------
  
  ///< List of candidate data products with artDAQ data fragments.
  std::vector<art::InputTag> const fInputTags;
  
  bool const fSurviveExceptions; ///< Whether to "ignore" errors.
  
  /// If true will spew endless messages to output.
  bool const fDiagnosticOutput;
  
  bool const fPacketDump; ///< Dump V1730 data.
  
  /// Whether info on all input boards is required.
  bool const fRequireKnownBoards;
  
  /// Whether setup info on all boards is required.
  bool const fRequireBoardConfig;
  
  /// Input tag of the PMT configuration.
  std::optional<art::InputTag> const fPMTconfigTag;
  
  /// Input tag of the global trigger.
  std::optional<art::InputTag> const fTriggerTag;
  
  bool const fTTTresetEverySecond; ///< Whether V1730 TTT is reset every second.
  
  /// All board setup settings.
  std::vector<daq::details::BoardSetup_t> const fBoardSetup;
  
  bool const fSkipWaveforms; ///< Whether to skip waveform decoding.
  
  /// Clear fragment data product cache after use.
  bool const fDropRawDataAfterUse;
  
  std::string const fLogCategory; ///< Message facility category.
  
  // --- END ---- Configuration parameters -------------------------------------

  
  // --- BEGIN -- Services -----------------------------------------------------
  
  /// Interface to LArSoft configuration for detector timing.
  detinfo::DetectorTimings const fDetTimings;
  
  /// Fragment/channel mapping database.
  icarusDB::IICARUSChannelMap const& fChannelMap;

  // --- END ---- Services -----------------------------------------------------


  // --- BEGIN -- Cached values ------------------------------------------------
  
  /// Duration of the optical detector readout sampling tick (i.e. 2 ns; hush!).
  nanoseconds const fOpticalTick;
  
  /// Trigger time as reported by `detinfo::DetectorClocks` service.
  electronics_time const fNominalTriggerTime;
  
  // --- END ---- Cached values ------------------------------------------------
  
  
  // --- BEGIN -- Per-run data cache -------------------------------------------
  
  /// Find the information on a readout boards by fragment ID.
  std::optional<daq::details::BoardInfoLookup> fBoardInfoLookup;
  
  // --- END -- Per-run data cache ---------------------------------------------
  
  
  unsigned int fNFailures = 0U; ///< Number of event failures encountered.
  
  
  // --- BEGIN -- PMT readout configuration ------------------------------------
  
  /// Returns whether PMT configuration information is expected to be available.
  bool hasPMTconfiguration() const { return fPMTconfigTag.has_value(); }
  
  /// Updates the PMT configuration cache. How? Dunno. Placeholder.
  bool UpdatePMTConfiguration(sbn::PMTconfiguration const* PMTconfig);
  

  /**
   * @brief Returns a lookup object with board setup and configuration info.
   * @param PMTconfig the PMT configuration, if available
   * @return an object working like lookup table for all fragment information
   * 
   * This method merges the setup information from the module configuration with
   * the PMT configuration specified in the argument, and returns an object
   * that can look up all the information as a single record, with the
   * fragment ID as key. In addition, a few intermediate quantities ("facts",
   * see `BoardFacts_t`) are computed and stored in this object.
   * 
   * If a fragment ID is missing, it means that no PMT configuration was
   * provided and that the setup information did not include a fragment ID.
   * If some information (configuration or setup) is missing, the "facts"
   * depending on the missing information will have default values.
   */
  daq::details::BoardInfoLookup matchBoardConfigurationAndSetup
    (sbn::PMTconfiguration const* PMTconfig) const;
  
  /// Puts together all the needed information for a board.
  NeededBoardInfo_t fetchNeededBoardInfo(
    daq::details::BoardInfoLookup::BoardInfo_t const* boardInfo,
    unsigned int fragmentID
    ) const;

  /// Extracts the Trigger Time Tag (31+1 bits) value from the fragment
  static unsigned int extractTriggerTimeTag(artdaq::Fragment const& fragment);


  // --- END -- PMT readout configuration --------------------------------------


  /**
   * @brief Returns the count of set bits for each set bit.
   * @tparam NBits the number of bits to test
   * @param value the bit mask to be analyzed
   * @return a pair: `first` an array with the `NBits` values,
   *         `second` the number of bits set
   * 
   * Much better to go with an example.
   * Let's process `setBitIndices<16U>(0x6701)`: `value` is `0110 0111 0000 0001`,
   * and we request the `16` least significant bits (`NBits`).
   * There are six bit that are set, in position 0, 8, 9, 10, 13 and 14.
   * The returned value includes the number of set bits (6) as the `second`
   * element of the pair, an as `first` an array of 16 indices, one for each bit
   * position.
   * Its values are `0` at `[0]`, `1` at `[8]`, `2` at `[9]`, `3` at `[10]`,
   * `4` at `[13]` and `5` at `[14]`. That is, each value represents the number
   * of that bit in the list of set bits. All the other indices, associated to
   * the bits which are not set, are assigned a value that is equal or larger than
   * the number of bits set (i.e. `6` or larger).
   */
  template <std::size_t NBits, typename T>
  static constexpr std::pair<std::array<std::size_t, NBits>, std::size_t>
    setBitIndices(T value) noexcept;

  
  // --- BEGIN -- Trees and their data ---------------------------------------
  
  /// Data structure for basic event information in simple ROOT trees.
  struct TreeData_EventID_t {
    unsigned int run;    ///< Run number.
    unsigned int subrun; ///< Subrun number.
    unsigned int event;  ///< Event number.
    SplitTimestamp_t timestamp; ///< Event timestamp (seconds from the epoch).
  }; // TreeData_EventID_t
  
  /// Structure collecting all data for a fragment ROOT tree.
  struct TreeFragment_t {
    struct Data_t: public TreeData_EventID_t {
      
      int fragmentID = 0; ///< ID of the fragment of this entry.
      
      unsigned int fragCount = 0U; ///< Counter of the fragment in the board.
      
      ///< Trigger time tag from the fragment.
      unsigned long int TriggerTimeTag = 0;
      
      SplitTimestamp_t trigger; ///< Global trigger time.
      
      SplitTimestamp_t fragTime; ///< PMT fragment time stamp.
      
      long int relBeamGate; ///< Beam gate start relative to trigger [ns].
      
      /// Time assigned to the waveforms.
      double waveformTime = std::numeric_limits<double>::lowest();
      
      unsigned int waveformSize = 0U; ///< Ticks in the waveforms.
      
      unsigned int triggerBits = 0x0; ///< Trigger bits, from `raw::Trigger`.
      
      unsigned int gateCount = 0U; ///< The number of gate from run start.
      
      ///< Whether waveforms cover nominal trigger time.
      bool onGlobalTrigger = false;
      
      
    }; // Data_t
    
    Data_t data;
    TTree* tree = nullptr;
  }; // TreeFragment_t
  
  
  std::unique_ptr<TreeData_EventID_t> fEventInfo; ///< Event ID for trees.
  
  ///< Tree with fragment information.
  std::unique_ptr<TreeFragment_t> fTreeFragment;
  
  // --- END ---- Trees and their data -----------------------------------------
  
  
  // --- BEGIN -- Timestamps ---------------------------------------------------
  
  /// Retrieves the global trigger time stamp from the event.
  TriggerInfo_t fetchTriggerTimestamp(art::Event const& event) const;
  
  /// Returns the timestamp for the waveforms in the specified fragment.
  electronics_time fragmentWaveformTimestamp(
    FragmentInfo_t const& fragInfo,
    NeededBoardInfo_t const& boardInfo,
    SplitTimestamp_t triggerTime
    ) const;
  
  /**
   * @brief Returns the timestamp for the waveforms in the specified fragment.
   * 
   * This method assumes that all PMT readout board triggers happened at the
   * same time as the global trigger.
   * Unsurprisingly, this does not work well with multiple PMT windows.
   */
  electronics_time fragmentWaveformTimestampOnTrigger(
    FragmentInfo_t const& fragInfo,
    NeededBoardInfo_t const& boardInfo,
    SplitTimestamp_t triggerTime
    ) const;
  
  /**
   * @brief Returns the timestamp for the waveforms in the specified fragment.
   * 
   * This method assumes that the Trigger Time Tag counters are synchronised
   * with the global trigger and their value is reset on each new second of 
   * the global trigger timescale (International Atomic Time).
   * 
   * This assumptions enables timestamping of waveforms from the same readout
   * boards at different times ("multi-window PMT readout").
   * 
   * See `TTTresetEverySecond` configuration option.
   */
  electronics_time fragmentWaveformTimestampFromTTT(
    FragmentInfo_t const& fragInfo,
    NeededBoardInfo_t const& boardInfo,
    SplitTimestamp_t triggerTime
    ) const;
  
  
  /// Returns the timestamp difference `a - b`.
  static long long int timestampDiff(std::uint64_t a, std::uint64_t b)
    { return static_cast<long long int>(a) - static_cast<long long int>(b); }
  
  
  /// Returns the fragment ID to be used with databases.
  static constexpr std::size_t effectivePMTboardFragmentID
    (artdaq::Fragment::fragment_id_t id)
    { return id & 0x0fff; }
  
  // --- END ---- Timestamps ---------------------------------------------------
  
  
  // --- BEGIN -- Input data management ----------------------------------------
  
  /// Tracks _art_ data products and removes their cached data on demand.
  // As often happens, caches need to be mutable. Also, not thread-safe.
  mutable util::ArtHandleTrackerManager<art::Event> fDataCacheRemover;
  
  /// Reads the fragments to be processed.
  artdaq::Fragments const& readInputFragments(art::Event const& event) const;
  
  /// Throws an exception if `artdaqFragment` is not of type `CAEN1730`.
  void checkFragmentType(artdaq::Fragment const& artdaqFragment) const;
  
  /// Converts a fragment into a fragment collection
  /// (dispatcher based on fragment type).
  artdaq::FragmentPtrs makeFragmentCollection
    (artdaq::Fragment const& sourceFragment) const;

  /// Converts a plain fragment into a fragment collection.
  artdaq::FragmentPtrs makeFragmentCollectionFromFragment
    (artdaq::Fragment const& sourceFragment) const;

  /// Converts a container fragment into a fragment collection.
  artdaq::FragmentPtrs makeFragmentCollectionFromContainerFragment
    (artdaq::Fragment const& sourceFragment) const;

  /// Extracts waveforms from the specified fragments from a board.
  std::vector<ProtoWaveform_t> processBoardFragments(
    artdaq::FragmentPtrs const& artdaqFragment,
    TriggerInfo_t const& triggerInfo
    );
  
  // --- END ---- Input data management ----------------------------------------
  
  
  // --- BEGIN -- Output waveforms ---------------------------------------------
  
  /// Merges "in place" `waveforms` based on timestamp.
  /// @return the number of original waveforms merged into another
  unsigned int mergeWaveforms(std::vector<ProtoWaveform_t>& waveforms) const;

  /// Sorts in place the specified waveforms in channel order, then in time.
  void sortWaveforms(std::vector<ProtoWaveform_t>& waveforms) const;
  
  /// Returns pointers to all waveforms including the nominal trigger time.
  std::vector<ProtoWaveform_t const*> findWaveformsWithNominalTrigger
    (std::vector<ProtoWaveform_t> const& waveforms) const;
  
  /// Returns whether `waveform` includes the tick of the nominal trigger time.
  bool containsGlobalTrigger(raw::OpDetWaveform const& waveform) const;
  
  /// Returns whether nominal trigger time is within `nTicks` from `time`.
  bool containsGlobalTrigger(electronics_time time, std::size_t nTicks) const;
  
  /// Returns a waveform merging of the `indices` ones from `allWaveforms`.
  /// The merged waveforms are emptied of their content.
  ProtoWaveform_t mergeWaveformGroup(
    std::vector<ProtoWaveform_t>& allWaveforms,
    std::vector<std::size_t> const& indices
    ) const;

  electronics_time waveformStartTime(raw::OpDetWaveform const& wf) const
    { return electronics_time{ wf.TimeStamp() }; }

  electronics_time waveformStartTime(ProtoWaveform_t const& wf) const
    { return waveformStartTime(wf.waveform); }
  
  electronics_time waveformEndTime(raw::OpDetWaveform const& wf) const
    { return waveformStartTime(wf) + fOpticalTick * wf.size(); }
  
  electronics_time waveformEndTime(ProtoWaveform_t const& wf) const
    { return waveformEndTime(wf.waveform); }
  
  // --- END ---- Output waveforms ---------------------------------------------
  
  using BoardID_t = short int; ///< Type used internally to represent board ID.
  
  
  /**
   * @brief Create waveforms and fills trees for the specified artDAQ fragment.
   * @param artdaqFragment the fragment to process
   * @param boardInfo board information needed, from configuration/setup
   * @param triggerTime absolute time of the trigger
   * @return collection of PMT waveforms from the fragment
   * 
   * This method fills the information for the PMT fragment tree
   * (`fillPMTfragmentTree()`) and creates PMT waveforms from the fragment data
   * (`createFragmentWaveforms()`).
   */
  std::vector<ProtoWaveform_t> processFragment(
    artdaq::Fragment const& artdaqFragment,
    NeededBoardInfo_t const& boardInfo,
    TriggerInfo_t const& triggerInfo
    );

  
  /**
   * @brief Creates `raw::OpDetWaveform` objects from the fragment data.
   * @param fragInfo information extracted from the fragment
   * @param channelSetup settings channel by channel
   * @param timeStamp timestamp of the waveforms in the fragment
   * @return collection of newly created `raw::OpDetWaveform`
   * 
   * All fragment information needed is enclosed in `fragInfo`
   * (`extractFragmentInfo()`). The timestamp can be obtained with a call to
   * `fragmentWaveformTimestamp()`.
   */
  std::vector<ProtoWaveform_t> createFragmentWaveforms(
    FragmentInfo_t const& fragInfo,
    AllChannelSetup_t const& channelSetup,
    electronics_time const timeStamp
    ) const;
  
  /// Extracts useful information from fragment data.
  FragmentInfo_t extractFragmentInfo
    (artdaq::Fragment const& artdaqFragment) const;
  
  /// Extracts the fragment ID (i.e. board ID) from the specified `fragment`.
  static BoardID_t extractFragmentBoardID(artdaq::Fragment const& fragment);
  
  /// Returns the board information for this fragment.
  NeededBoardInfo_t neededBoardInfo
    (artdaq::Fragment::fragment_id_t fragment_id) const;
  
  /// Returns all the instance names we will produce.
  std::set<std::string> getAllInstanceNames() const;
  
  /// Throws an exception if the configuration of boards shows errors.
  void checkBoardSetup
    (std::vector<daq::details::BoardSetup_t> const& allBoardSetup) const;
  
  
  // --- BEGIN -- Tree-related methods -----------------------------------------
  
  /// Declares the use of event information.
  void usesEventInfo();
  
  /// Initializes all requested data trees.
  void initTrees(std::vector<std::string> const& treeNames);
  
  /// Initializes the event ID part of a tree.
  void initEventIDtree(TTree& tree, TreeData_EventID_t& data);
  
  /// Initializes the fragment data tree (`fTreeFragment`).
  void initFragmentsTree();

  /// Fills the base information of a tree data entry from an _art_ event.
  void fillTreeEventID
    (art::Event const& event, TreeData_EventID_t& treeData) const;

  /// Assigns the cached event information to the specified tree data.
  void assignEventInfo(TreeData_EventID_t& treeData) const;
  
  /// Fills the PMT fragment tree with the specified information
  /// (additional information needs to have been set already).
  void fillPMTfragmentTree(
    FragmentInfo_t const& fragInfo,
    TriggerInfo_t const& triggerInfo,
    electronics_time waveformTimestamp
    );
  
  
  /// Returns the name of the specified tree.
  static std::string const& treeName(DataTrees treeID);

  /// Static initialization.
  static TreeNameList_t initTreeNames();
  
  // --- END ---- Tree-related methods -----------------------------------------
  
  friend struct dumpChannel;
  friend std::ostream& operator<< (std::ostream&, ProtoWaveform_t const&);
  
}; // icarus::DaqDecoderICARUSPMT


//------------------------------------------------------------------------------
// --- implementation
//------------------------------------------------------------------------------
namespace {
  
  /// Moves the contend of `src` into the end of `dest`.
  template <typename T>
  std::vector<T>& appendTo(std::vector<T>& dest, std::vector<T>&& src) {
    if (dest.empty()) dest = std::move(src);
    else {
      dest.reserve(dest.size() + src.size());
      std::move(src.begin(), src.end(), std::back_inserter(dest));
    }
    src.clear();
    return dest;
  } // appendTo()
  
  /// Returns whether an element `value` is found in `coll`.
  template <typename Coll, typename T>
  bool contains(Coll const& coll, T const& value) {
    auto const cend = end(coll);
    return std::find(begin(coll), cend, value) != cend;
  } // contains()
  
} // local namespace


//------------------------------------------------------------------------------
namespace icarus {

  /// Special function `fhicl::TableAs` uses to convert BoardSetupConfig.
  daq::details::BoardSetup_t convert
    (DaqDecoderICARUSPMT::BoardSetupConfig const& config)
  {
    
    daq::details::BoardSetup_t bs {
        config.Name()                                          // name
      , config.FragmentID()
          .value_or(daq::details::BoardSetup_t::NoFragmentID)  // fragmentID
      , config.TriggerDelay()                                  // triggerDelay
      , config.TTTresetDelay()                                 // TTTresetDelay
      };
    
    // set the special configuration for the board channels that have one;
    // the others will stay with the default one (which implies that a channel
    // is saved in the standard data product, and only if it has a channel ID
    // entry from the database)
    for (
      DaqDecoderICARUSPMT::BoardSetupConfig::ChannelSetupConfig const& chConfig
      : config.SpecialChannels().value_or(
        std::vector<DaqDecoderICARUSPMT::BoardSetupConfig::ChannelSetupConfig>{}
        )
    ) {
      try {
        bs.channelSettings.at(chConfig.ChannelIndex()) = {
            chConfig.Channel()              // channelID
          , chConfig.Skip()                 // forcedSkip
          , chConfig.OnlyOnGlobalTrigger()  // onGlobalOnly
          , chConfig.MinSpan()              // minSpan
          , chConfig.InstanceName()         // category
          };
      }
      catch (std::out_of_range const&) {
        throw art::Exception(art::errors::Configuration)
          << "Configuration requested for invalid channel index "
          << chConfig.ChannelIndex() << " of the board '"
          << config.Name() << "'\n";
      }
    } // for
    
    return bs;
  } // convert(BoardSetupConfig)


  struct dumpChannel {
    DaqDecoderICARUSPMT::ProtoWaveform_t const& wf;
    dumpChannel(DaqDecoderICARUSPMT::ProtoWaveform_t const& wf): wf{ wf } {}
  };
  
  std::ostream& operator<< (std::ostream& out, dumpChannel const& d) {
    return out << (d.wf.channelSetup->category.empty()? std::dec: std::hex)
      << d.wf.waveform.ChannelNumber() << std::dec;
  }

} // namespace icarus


//------------------------------------------------------------------------------
// --- icarus::DaqDecoderICARUSPMT::SplitTimestamp_t
//------------------------------------------------------------------------------
constexpr icarus::DaqDecoderICARUSPMT::SplitTimestamp_t::SplitTimestamp_t
  (int sec, unsigned int ns)
  : time { static_cast<long long int>(sec) * 1'000'000'000LL + ns }
  , split { sec, ns }
{}


//------------------------------------------------------------------------------
constexpr icarus::DaqDecoderICARUSPMT::SplitTimestamp_t::SplitTimestamp_t
  (long long int triggerTime)
  : time { triggerTime }
  , split {
      static_cast<int>(time / 1'000'000'000), // seconds
      static_cast<unsigned int>(time % 1'000'000'000) // nanoseconds
    }
{}


//------------------------------------------------------------------------------
namespace icarus {
  
  std::ostream& operator<<
    (std::ostream& out, DaqDecoderICARUSPMT::SplitTimestamp_t const& time)
  {
    out << time.split.seconds << '.'
      << std::setfill('0') << std::setw(9) << time.split.nanoseconds;
    return out;
  } // operator<< (std::ostream&, PMTDecoder::SplitTimestamp_t)
  
} // namespace icarus


//------------------------------------------------------------------------------
// --- icarus::DaqDecoderICARUSPMT
//------------------------------------------------------------------------------
// --- template implementation
//------------------------------------------------------------------------------
template <std::size_t NBits, typename T>
constexpr std::pair<std::array<std::size_t, NBits>, std::size_t>
icarus::DaqDecoderICARUSPMT::setBitIndices(T value) noexcept {
  
  std::pair<std::array<std::size_t, NBits>, std::size_t> res;
  auto& [ indices, nSetBits ] = res;
  for (std::size_t& index: indices) {
    index = (value & 1)? nSetBits++: NBits;
    value >>= 1;
  } // for
  return res;
  
} // icarus::DaqDecoderICARUSPMT::setBitIndices()


//------------------------------------------------------------------------------
// --- static definitions
//------------------------------------------------------------------------------
icarus::DaqDecoderICARUSPMT::AllChannelSetup_t const
icarus::DaqDecoderICARUSPMT::NeededBoardInfo_t::DefaultChannelSetup;

//------------------------------------------------------------------------------
icarus::DaqDecoderICARUSPMT::TreeNameList_t const
icarus::DaqDecoderICARUSPMT::TreeNames
  = icarus::DaqDecoderICARUSPMT::initTreeNames();

auto icarus::DaqDecoderICARUSPMT::initTreeNames() -> TreeNameList_t {
  TreeNameList_t names;
  names[static_cast<std::size_t>(DataTrees::Fragments)] = "PMTfragments";
  return names;
} // icarus::DaqDecoderICARUSPMT::initTreeNames()


//------------------------------------------------------------------------------
std::string const& icarus::DaqDecoderICARUSPMT::treeName(DataTrees treeID)
  { return TreeNames[static_cast<std::size_t>(treeID)]; }


//------------------------------------------------------------------------------
std::string icarus::DaqDecoderICARUSPMT::listTreeNames
  (std::string const& sep /* = " " */)
{
  std::string l;
  for (std::string const& name: TreeNames) {
    if (!l.empty()) l += sep;
    l += '\'';
    l += name;
    l += '\'';
  } // for
  return l;
} // icarus::DaqDecoderICARUSPMT::listTreeNames()


//------------------------------------------------------------------------------
// --- implementation
//------------------------------------------------------------------------------
icarus::DaqDecoderICARUSPMT::DaqDecoderICARUSPMT(Parameters const& params)
  : art::EDProducer(params)
  , fInputTags{ params().FragmentsLabels() }
  , fSurviveExceptions{ params().SurviveExceptions() }
  , fDiagnosticOutput{ params().DiagnosticOutput() }
  , fPacketDump{ params().PacketDump() }
  , fRequireKnownBoards{ params().RequireKnownBoards() }
  , fRequireBoardConfig{ params().RequireBoardConfig() }
  , fPMTconfigTag{ params().PMTconfigTag() }
  , fTriggerTag{ params().TriggerTag() }
  , fTTTresetEverySecond
    { params().TTTresetEverySecond().value_or(fTriggerTag.has_value()) }
  , fBoardSetup{ params().BoardSetup() }
  , fSkipWaveforms{ params().SkipWaveforms() }
  , fDropRawDataAfterUse{ params().DropRawDataAfterUse() }
  , fLogCategory{ params().LogCategory() }
  , fDetTimings
    { art::ServiceHandle<detinfo::DetectorClocksService const>()->DataForJob() }
  , fChannelMap{ *(art::ServiceHandle<icarusDB::IICARUSChannelMap const>{}) }
  , fOpticalTick{ fDetTimings.OpticalClockPeriod() }
  , fNominalTriggerTime{ fDetTimings.TriggerTime() }
{
  //
  // configuration check
  //
  checkBoardSetup(fBoardSetup); // throws on error
  
  //
  // consumed data products declaration
  //
  for (art::InputTag const& inputTag: fInputTags)
    consumes<artdaq::Fragments>(inputTag);
  if (fPMTconfigTag) consumes<sbn::PMTconfiguration>(*fPMTconfigTag);
  if (fTriggerTag) {
    consumes<std::vector<sbn::ExtraTriggerInfo>>(*fTriggerTag);
    if (contains(params().DataTrees(), treeName(DataTrees::Fragments)))
      consumes<std::vector<raw::Trigger>>(*fTriggerTag);
  } // if trigger
  
  //
  // produced data products declaration
  //
  if (!fSkipWaveforms) {
    for (std::string const& instanceName: getAllInstanceNames())
      produces<std::vector<raw::OpDetWaveform>>(instanceName);
  }
  
  //
  // additional initialization
  //
  initTrees(params().DataTrees());
  
  
  //
  // configuration dump
  //
  mf::LogInfo log(fLogCategory);
  log << "Configuration:"
    << "\n * data from one of " << fInputTags.size() << " data products:";
  for (art::InputTag const& inputTag: fInputTags)
    log << " '" << inputTag.encode() << "'";
  log
    << "\n * boards with setup: " << fBoardSetup.size();
  if (fPMTconfigTag)
    log << "\n * PMT configuration from '" << fPMTconfigTag->encode() << "'";
  else 
    log << "\n * PMT configuration not used (and some corrections will be skipped)";
  if (fTriggerTag)
    log << "\n * trigger information from: '" << fTriggerTag->encode() << '\'';
  else
    log << "\n * trigger time from event timestamp [fallback]";
  if (fRequireKnownBoards) {
    log << "\n * all readout boards in input must be known (from `"
      << params().BoardSetup.name() << "` or `"
      << params().PMTconfigTag.name() << "`)"
      ;
  }
  else {
    log << "\n * readout boards with no information (from neither `"
      << params().BoardSetup.name() << "` or `"
      << params().PMTconfigTag.name()
      << "`) are processed at the best we can (skipping corrections)"
      ;
  }
  if (fRequireBoardConfig) {
    log << "\n * all readout boards in `"
      << params().BoardSetup.name()
      << "` must appear in the PMT configuration from `"
      << params().PMTconfigTag.name() << "`"
      ;
  }
  else {
    log << "\n * all readout boards in `"
      << params().BoardSetup.name()
      << "` may lack a matching PMT configuration from `"
      << params().PMTconfigTag.name() << "`"
      ;
  }
  if (fSkipWaveforms) {
    log << "\n * PMT WAVEFORMS WILL NOT BE DECODED AND STORED";
  }
  
  //
  // sanity checks
  //
  
  if (fChannelMap.nPMTfragmentIDs() == 0) {
    throw cet::exception("DaqDecoderICARUSPMT")
      << "Channel mapping database does not report any PMT fragment ID!\n";
  } // if no PMT in database
  
  
} // icarus::DaqDecoderICARUSPMT::DaqDecoderICARUSPMT()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::beginRun(art::Run& run) {
  
  //sbn::PMTconfiguration const* PMTconfig = fPMTconfigTag
  //  ? run.getPointerByLabel<sbn::PMTconfiguration>(*fPMTconfigTag): nullptr;
  sbn::PMTconfiguration const* PMTconfig = fPMTconfigTag
    ? run.getHandle<sbn::PMTconfiguration>(*fPMTconfigTag).product(): nullptr;
  
  UpdatePMTConfiguration(PMTconfig);
  
} // icarus::DaqDecoderICARUSPMT::beginRun()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::produce(art::Event& event) {
  
  // ---------------------------------------------------------------------------
  // preparation
  //
  
  fDataCacheRemover.useEvent(event);
  
  //
  // global trigger
  //
  TriggerInfo_t const triggerInfo = fetchTriggerTimestamp(event);
  {
    mf::LogDebug log { fLogCategory };
    if (fTriggerTag)
      log << "Trigger time ('" << fTriggerTag->encode() << "'): ";
    else
      log << "Trigger from event timestamp: ";
    log << triggerInfo.time << " s, bits: "
        << icarus::ns::util::bin(triggerInfo.bits.bits);
    if (triggerInfo.bits) {
      log << " {";
      for (std::string const& name: names(triggerInfo.bits)) log << ' ' << name;
      log << " }";
    } // if
    if (fTriggerTag) log << ", spill count: " << triggerInfo.gateCount;
  } // local block
  
  //
  // event ID
  //
  
  // if needed, fill the record with the basic information of the event
  if (fEventInfo) fillTreeEventID(event, *fEventInfo);
  
  //
  // output data product initialization
  //
  std::vector<ProtoWaveform_t> protoWaveforms; // empty if `fSkipWaveforms`
  
  
  // ---------------------------------------------------------------------------
  // pre-processing
  //
  
  
  // ---------------------------------------------------------------------------
  // processing
  //
  
  std::unordered_map<BoardID_t, unsigned int> boardCounts;
  bool duplicateBoards = false;
  try { // catch-all
    auto const& fragments = readInputFragments(event);
    
    for (artdaq::Fragment const& fragment: fragments) {
      
      artdaq::FragmentPtrs const& fragmentCollection
        = makeFragmentCollection(fragment);
      
      if (empty(fragmentCollection)) {
        mf::LogWarning("DaqDecoderICARUSPMT")
          << "Found a data fragment (ID=" << extractFragmentBoardID(fragment)
          << ") containing no data.";
        continue;
      } // if no data
      
      BoardID_t const boardID
        = extractFragmentBoardID(*(fragmentCollection.front()));
      if (++boardCounts[boardID] > 1U) duplicateBoards = true;
      
      appendTo(
        protoWaveforms,
        processBoardFragments(fragmentCollection, triggerInfo)
        );
      
    } // for all input fragments
    
  }
  catch (cet::exception const& e) {
    if (!fSurviveExceptions) throw;
    mf::LogError("DaqDecoderICARUSPMT")
      << "Error while attempting to decode PMT data:\n" << e.what() << '\n';
    protoWaveforms.clear();
    ++fNFailures;
  }
  catch (...) {
    if (!fSurviveExceptions) throw;
    mf::LogError("DaqDecoderICARUSPMT")
      << "Error while attempting to decode PMT data.\n";
    protoWaveforms.clear();
    ++fNFailures;
  }
  
  if (duplicateBoards) {
    mf::LogWarning log { "DaqDecoderICARUSPMT" };
    log << "found multiple data product entries for the same board:";
    for (auto [ boardID, count ]: boardCounts) {
      if (count < 2U) continue;
      log << " " << std::hex << boardID << std::dec << " (x" << count << ");";
    } // for
  } // if duplicate board fragments
  
  
  // we are done with the input: drop the caches
  // (if we were asked not to, no data is registered)
  fDataCacheRemover.removeCachedProducts();
  
  //
  // post-processing
  //
  sortWaveforms(protoWaveforms);
  
  if (!fSkipWaveforms) {
    std::vector<ProtoWaveform_t const*> const waveformsWithTrigger
      = findWaveformsWithNominalTrigger(protoWaveforms);
    mf::LogTrace(fLogCategory) << waveformsWithTrigger.size() << "/"
      << protoWaveforms.size() << " decoded waveforms include trigger time ("
      << fNominalTriggerTime << ").";
  } // if !fSkipWaveforms
  
  // ---------------------------------------------------------------------------
  // output
  //
  
  if (!fSkipWaveforms) {
    // split the waveforms by destination
    std::map<std::string, std::vector<raw::OpDetWaveform>> waveformProducts;
    for (std::string const& instanceName: getAllInstanceNames())
      waveformProducts.emplace(instanceName, std::vector<raw::OpDetWaveform>{});
    for (ProtoWaveform_t& waveform: protoWaveforms) {
      
      // on-global and span requirements override even `mustSave()` requirement;
      // if this is not good, user should not set `mustSave()`!
      bool const keep =
        (waveform.onGlobal || !waveform.channelSetup->onGlobalOnly)
        && (waveform.span() >= waveform.channelSetup->minSpan)
        ;
      
      if (!keep) continue;
      waveformProducts.at(waveform.channelSetup->category).push_back
        (std::move(waveform.waveform));
    } // for
    
    // put all the categories
    for (auto&& [ category, waveforms ]: waveformProducts) {
      mf::LogTrace(fLogCategory)
        << waveforms.size() << " PMT waveforms saved for "
        << (category.empty()? "standard": category) << " instance.";
      event.put(
        std::make_unique<std::vector<raw::OpDetWaveform>>(std::move(waveforms)),
        category // the instance name is the category the waveforms belong to
        );
    }
  } // if !fSkipWaveforms
  
} // icarus::DaqDecoderICARUSPMT::produce()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::endJob() {
  
  if (fNFailures > 0U) {
    mf::LogError(fLogCategory) << "Encountered errors on " << fNFailures
      << " events. Errors were ignored.";
  }
  
} // icarus::DaqDecoderICARUSPMT::endJob()


//------------------------------------------------------------------------------
artdaq::Fragments const& icarus::DaqDecoderICARUSPMT::readInputFragments
  (art::Event const& event) const
{
  art::Handle<artdaq::Fragments> handle;
  art::InputTag selectedInputTag; // empty
  for (art::InputTag const& inputTag: fInputTags) {
    
    mf::LogTrace(fLogCategory)
      << "DaqDecoderICARUSPMT trying data product: '" << inputTag.encode()
      << "'";
    
    auto const& thisHandle = event.getHandle<artdaq::Fragments>(inputTag);
    if (!thisHandle.isValid() || thisHandle->empty()) continue;
    
    mf::LogTrace(fLogCategory)
      << "  => data product: '" << inputTag.encode() << "' is present and has "
      << thisHandle->size() << " entries";
    
    if (!selectedInputTag.empty()) {
      throw cet::exception("DaqDecoderICARUSPMT")
        << "Found multiple suitable input candidates: '"
        << inputTag.encode() << "' and '" << selectedInputTag << "'\n";
    }
    selectedInputTag = inputTag;
    handle = thisHandle;
  } // for
  
  if (!handle.isValid()) {
    cet::exception e { "DaqDecoderICARUSPMT" };
    e << "No suitable input data product found among:";
    for (art::InputTag const& inputTag: fInputTags)
      e << " '" << inputTag.encode() << "'";
    throw e << "\n";
  }
  
  if (fDropRawDataAfterUse) fDataCacheRemover.registerHandle(handle);
  
  return *handle;
} // icarus::DaqDecoderICARUSPMT::readInputFragments()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::findWaveformsWithNominalTrigger
  (std::vector<ProtoWaveform_t> const& waveforms) const
  -> std::vector<ProtoWaveform_t const*>
{
  std::vector<ProtoWaveform_t const*> matchedWaveforms;
  for (ProtoWaveform_t const& waveform: waveforms) {
    if (waveform.onGlobal) matchedWaveforms.push_back(&waveform);
  } // for
  return matchedWaveforms;
} // icarus::DaqDecoderICARUSPMT::findWaveformsWithNominalTrigger()


//------------------------------------------------------------------------------
bool icarus::DaqDecoderICARUSPMT::containsGlobalTrigger
  (electronics_time time, std::size_t nTicks) const
{
  return (fNominalTriggerTime >= time)
    && (fNominalTriggerTime < time + nTicks * fOpticalTick);
} // icarus::DaqDecoderICARUSPMT::containsGlobalTrigger(time, ticks)


//------------------------------------------------------------------------------
bool icarus::DaqDecoderICARUSPMT::containsGlobalTrigger
  (raw::OpDetWaveform const& waveform) const
{
  return containsGlobalTrigger
    (electronics_time{ waveform.TimeStamp() }, waveform.size());
} // icarus::DaqDecoderICARUSPMT::containsGlobalTrigger(waveform)


//------------------------------------------------------------------------------
bool icarus::DaqDecoderICARUSPMT::UpdatePMTConfiguration
  (sbn::PMTconfiguration const* PMTconfig)
{
  fBoardInfoLookup.emplace(matchBoardConfigurationAndSetup(PMTconfig));
  
  mf::LogDebug(fLogCategory)
    << "Board information as cached:\n" << *fBoardInfoLookup;
  
  return true;
} // icarus::DaqDecoderICARUSPMT::UpdatePMTConfiguration()


auto icarus::DaqDecoderICARUSPMT::matchBoardConfigurationAndSetup
  (sbn::PMTconfiguration const* PMTconfig) const
  -> daq::details::BoardInfoLookup
{
  /*
   * We need to support the case where no PMT configuration is known
   * (that is the standard situation in the online monitor).
   * The "strategy" is that in such cases we give up the correct time stamp
   * decoding; if the setup information contains a fragment ID, it may be
   * possible to do a little better, that is to use the setup information
   * (this is not possible without knowing the fragment ID that each bit of
   * setup information pertains).
   * 
   * So the cases for a board are:
   * * setup information is not present: encountering such a board will cause
   *   an exception to be thrown (implemented elsewhere)
   * * PMT configuration and setup present: full configuration
   *     * exception thrown if setup fragment ID is present and inconsistent
   * * PMT configuration not present: a general warning is printed;
   *     * boards with setup fragment ID information: add setup information
   *       to the "database" for the board: it will be used for partial
   *       timestamp reconstruction
   *     * boards without setup fragment ID information: board will not be
   *       added into the database; no specific correction will be performed;
   *       a warning is printed for each board
   * 
   */
  
  // dictionary of board configurations (if any)
  std::vector<std::pair<std::string, sbn::V1730Configuration const*>>
    configByName;
  if (PMTconfig) {
    if (!PMTconfig->boards.empty())
      configByName.reserve(PMTconfig->boards.size());
    for (sbn::V1730Configuration const& boardConfig: PMTconfig->boards)
      configByName.emplace_back(boardConfig.boardName, &boardConfig);
    std::sort(configByName.begin(), configByName.end()); // sorted by board name
  } // if we have configuration
  
  
  auto findPMTconfig = [this, &configByName]
    (std::string const& name) -> sbn::V1730Configuration const*
    {
      if (!hasPMTconfiguration()) return nullptr;
      auto const* ppBoardConfig
        = daq::details::binarySearch(configByName, name);
      if (!ppBoardConfig) {
        if (!fRequireBoardConfig) return nullptr;
        throw cet::exception("DaqDecoderICARUSPMT")
          << "No DAQ configuration found for PMT readout board '"
          << name << "'\n"
            "If this is expected, you may skip this check by setting "
            "DaqDecoderICARUSPMT module configuration `RequireBoardConfig`"
            " to `false`.\n"
          ;
      }
      return ppBoardConfig->second;
    }; // findPMTconfig()
  
  // the filling is driven by boards configured in the module
  // (which is the reason a setup entry is mandatory)
  daq::details::BoardInfoLookup::Database_t boardInfoByFragment;
  
  for (daq::details::BoardSetup_t const& boardSetup: fBoardSetup) {
    
    std::string const& boardName = boardSetup.name;
    
    sbn::V1730Configuration const* pBoardConfig = findPMTconfig(boardName);
    
    if (pBoardConfig) {
      // fragment ID from configuration and setup must match if both present
      if (boardSetup.hasFragmentID()
        && (boardSetup.fragmentID != pBoardConfig->fragmentID)
      ) {
        throw cet::exception("DaqDecoderICARUSPMT")
          << "Board '" << boardName << "' has fragment ID "
          << std::hex << pBoardConfig->fragmentID << std::dec
          << " but it is set up as "
          << std::hex << boardSetup.fragmentID << std::dec
          << "!\n";
      } // if fragment ID in setup
    }
    else {
      if (boardSetup.hasFragmentID()) {
        mf::LogPrint(fLogCategory)
          << "Board '" << boardName
          << "' has no configuration information;"
            " some time stamp corrections will be skipped.";
        // to avoid this, make a PMT configuration available from input file
      }
      else {
        mf::LogPrint(fLogCategory)
          << "Board '" << boardName
          << "' can't be associated to a fragment ID;"
            " its time stamp corrections will be skipped.";
        // to avoid this, add a `BoardSetup.FragmentID` entry for it in the
        // configuration of this module, or make a PMT configuration available
        continue; // no entry for this board at all
      }
    }
    
    unsigned int const fragmentID
      = pBoardConfig? pBoardConfig->fragmentID: boardSetup.fragmentID;
    assert(fragmentID != daq::details::BoardSetup_t::NoFragmentID);
    
    nanoseconds const preTriggerTime
      = pBoardConfig
      ? (pBoardConfig->bufferLength * (1.0f - pBoardConfig->postTriggerFrac))
        * fOpticalTick
      : nanoseconds{ 0.0 }
      ;
    
    daq::details::BoardFacts_t boardFacts {
      preTriggerTime  // ditto
      };
    
    boardInfoByFragment.push_back({
      fragmentID,               // fragmentID
      &boardSetup,              // setup
      pBoardConfig,             // config
      std::move(boardFacts)     // facts
      });
  } // for
  
  return daq::details::BoardInfoLookup{ std::move(boardInfoByFragment) };
  
} // icarus::DaqDecoderICARUSPMT::matchBoardConfigurationAndSetup()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::fetchNeededBoardInfo(
  daq::details::BoardInfoLookup::BoardInfo_t const* boardInfo,
  unsigned int fragmentID
) const -> NeededBoardInfo_t {
  
  using util::quantities::intervals::microseconds;
  
  return NeededBoardInfo_t{
    // name
      ((boardInfo && boardInfo->config)
        ? boardInfo->config->boardName: ("<ID=" + std::to_string(fragmentID)))
    // bufferLength
    , ((boardInfo && boardInfo->config)
        ? boardInfo->config->bufferLength * fOpticalTick: nanoseconds{ 0.0 }
      )
    // preTriggerTime
    , (boardInfo? boardInfo->facts.preTriggerTime: nanoseconds{ 0.0 })
    // PMTtriggerDelay
    , ((boardInfo && boardInfo->setup)
        ? boardInfo->setup->triggerDelay: nanoseconds{ 0.0 })
    // TTTresetDelay
    , ((boardInfo && boardInfo->setup)
        ? boardInfo->setup->TTTresetDelay: nanoseconds{ 0.0 })
    , ((boardInfo && boardInfo->setup)?
        &(boardInfo->setup->channelSettings): nullptr)
    };
      
} // icarus::DaqDecoderICARUSPMT::fetchNeededBoardInfo()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::fetchTriggerTimestamp
  (art::Event const& event) const -> TriggerInfo_t
{
  
  if (!fTriggerTag)
    return { SplitTimestamp_t(event.time().value()), 0U };
  
  
  auto const& extraTrigger
    = event.getProduct<sbn::ExtraTriggerInfo>(*fTriggerTag);
  if (!extraTrigger.isValid()) {
    // this means there is some problem from trigger decoder;
    // while we might recover additional information from other data products,
    // we expect those to be as problematic.
    throw cet::exception("DaqDecoderICARUSPMT")
      << "Extra trigger information from '"
      << fTriggerTag->encode() << "' is marked as invalid!\n";
  }
  
  if (fDiagnosticOutput) {
    mf::LogVerbatim(fLogCategory)
      << "Extended trigger information:\n" << extraTrigger;
  }
  
  auto const& triggers
    = event.getProduct<std::vector<raw::Trigger>>(*fTriggerTag);
  if (triggers.size() != 1U) {
    // if this is hit, the decoder needs some development to correctly deal
    // with input with no trigger, or more than one
    throw cet::exception("DaqDecoderICARUSPMT")
      << "Found " << triggers.size() << " raw::Trigger from '"
      << fTriggerTag->encode() << "', can deal only with 1.\n";
  }
  raw::Trigger const& trigger = triggers.front();
  
  long long int const relBeamGate = timestampDiff
    (extraTrigger.beamGateTimestamp, extraTrigger.triggerTimestamp);
  
  unsigned int const gateCount = extraTrigger.gateID;
  
  return {
      SplitTimestamp_t
        { static_cast<long long int>(extraTrigger.triggerTimestamp) }
    , relBeamGate
    , {trigger.TriggerBits()}
    , gateCount
    };
  
} // icarus::DaqDecoderICARUSPMT::fetchTriggerTimestamp()


//------------------------------------------------------------------------------
artdaq::FragmentPtrs icarus::DaqDecoderICARUSPMT::makeFragmentCollection
  (artdaq::Fragment const& sourceFragment) const
{
  switch (sourceFragment.type()) {
    case sbndaq::FragmentType::CAENV1730:
      return makeFragmentCollectionFromFragment(sourceFragment);
    case artdaq::Fragment::ContainerFragmentType:
      return makeFragmentCollectionFromContainerFragment(sourceFragment);
    default:
      throw cet::exception("DaqDecoderICARUSPMT")
        << "Unexpected PMT data product fragment type: "
        << static_cast<int>(sourceFragment.type()) << " ('"
        << sbndaq::fragmentTypeToString
          (static_cast<sbndaq::FragmentType>(sourceFragment.type()))
        << "')\n";
  } // switch
} // icarus::DaqDecoderICARUSPMT::makeFragmentCollection()


//------------------------------------------------------------------------------
artdaq::FragmentPtrs
icarus::DaqDecoderICARUSPMT::makeFragmentCollectionFromFragment
  (artdaq::Fragment const& sourceFragment) const
{
  assert(sourceFragment.type() == sbndaq::FragmentType::CAENV1730);
  artdaq::FragmentPtrs fragColl;
  fragColl.push_back(std::make_unique<artdaq::Fragment>(sourceFragment));
  return fragColl;
} // icarus::DaqDecoderICARUSPMT::makeFragmentCollectionFromFragment()


//------------------------------------------------------------------------------
artdaq::FragmentPtrs
icarus::DaqDecoderICARUSPMT::makeFragmentCollectionFromContainerFragment
  (artdaq::Fragment const& sourceFragment) const
{
  assert(sourceFragment.type() == artdaq::Fragment::ContainerFragmentType);
  artdaq::ContainerFragment const containerFragment{ sourceFragment };
  
  if (containerFragment.block_count() == 0) return {};
    
  artdaq::FragmentPtrs fragColl;
  for (auto const iFrag: util::counter(containerFragment.block_count()))
    fragColl.push_back(containerFragment.at(iFrag));
  
  return fragColl;
} // icarus::DaqDecoderICARUSPMT::makeFragmentCollectionFromContainerFragment()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::checkFragmentType
  (artdaq::Fragment const& artdaqFragment) const
{
  if (artdaqFragment.type() == sbndaq::FragmentType::CAENV1730) return;
  
  throw cet::exception("DaqDecoderICARUSPMT")
    << "Unexpected PMT fragment data type: '"
    << sbndaq::fragmentTypeToString
      (static_cast<sbndaq::FragmentType>(artdaqFragment.type()))
    << "'\n";
  
} // icarus::DaqDecoderICARUSPMT::checkFragmentType


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::processBoardFragments(
  artdaq::FragmentPtrs const& artdaqFragments,
  TriggerInfo_t const& triggerInfo
) -> std::vector<ProtoWaveform_t> {
  
  if (artdaqFragments.empty()) return {};
  
  artdaq::Fragment const& referenceFragment = *(artdaqFragments.front());
  assert(&referenceFragment);
  
  checkFragmentType(referenceFragment);
  
  NeededBoardInfo_t const boardInfo
    = neededBoardInfo(artdaqFragments.front()->fragmentID());
  
  mf::LogTrace(fLogCategory)
    << " - " << boardInfo.name << ": " << artdaqFragments.size()
    << " fragments";
  
  std::vector<ProtoWaveform_t> waveforms;
  for (artdaq::FragmentPtr const& fragment: artdaqFragments)
    appendTo(waveforms, processFragment(*fragment, boardInfo, triggerInfo));
  
  mergeWaveforms(waveforms);
  
  return { waveforms };
  
} // icarus::DaqDecoderICARUSPMT::processBoardFragments()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::processFragment(
  artdaq::Fragment const& artdaqFragment,
  NeededBoardInfo_t const& boardInfo,
  TriggerInfo_t const& triggerInfo
) -> std::vector<ProtoWaveform_t> {
  
  checkFragmentType(artdaqFragment);
  
  if (fPacketDump) {
    mf::LogVerbatim{ fLogCategory } << "PMT packet:"
      << "\n" << std::string(80, '-')
      << "\n" << sbndaq::dumpFragment(artdaqFragment)
      << "\n" << std::string(80, '-')
      ;
  } // if diagnostics
  
  FragmentInfo_t const fragInfo = extractFragmentInfo(artdaqFragment);
  
  auto const timeStamp
    = fragmentWaveformTimestamp(fragInfo, boardInfo, triggerInfo.time);
    
  if (fTreeFragment) fillPMTfragmentTree(fragInfo, triggerInfo, timeStamp);
  
  return ((timeStamp != NoTimestamp) && !fSkipWaveforms)
    ? createFragmentWaveforms(fragInfo, boardInfo.channelSetup(), timeStamp)
    : std::vector<ProtoWaveform_t>{}
    ;
  
} // icarus::DaqDecoderICARUSPMT::processFragment()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::createFragmentWaveforms(
  FragmentInfo_t const& fragInfo, AllChannelSetup_t const& channelSetup,
  electronics_time const timeStamp
) const -> std::vector<ProtoWaveform_t>
{

  assert(timeStamp != NoTimestamp);
  
  std::vector<ProtoWaveform_t> protoWaveforms; // output collection
    
  std::optional<mf::LogVerbatim> diagOut;
  if (fDiagnosticOutput) diagOut.emplace(fLogCategory);
  
  icarusDB::DigitizerChannelChannelIDPairVec const& digitizerChannelVec
    = fChannelMap.getChannelIDPairVec
      (effectivePMTboardFragmentID(fragInfo.fragmentID))
    ;
  
  // allocate the vector outside the loop since we'll reuse it over and over
  std::vector<std::uint16_t> wvfm(fragInfo.nSamplesPerChannel);
  
  // all waveforms share the same timestamp,
  // so either all contain the global trigger, or they all do not
  bool const onGlobal = containsGlobalTrigger(timeStamp, wvfm.size());
  
  auto channelNumberToChannel
    = [&digitizerChannelVec](unsigned short int channelNumber) -> raw::Channel_t
    {
      for (auto const [ chNo, chID ]: digitizerChannelVec)
        if (chNo == channelNumber) return chID;
      return sbn::V1730channelConfiguration::NoChannelID;
    };
  
  if (diagOut)
    (*diagOut) << "      " << digitizerChannelVec.size() << " channels:";
  
  std::size_t iNextChunk = 0;
  for (unsigned short int const channelNumber: util::counter(16U)) {
    
    if ((fragInfo.enabledChannels & (1 << channelNumber)) == 0) {
      if (diagOut)
        (*diagOut) << " " << channelNumber << " [disabled];";
      continue;
    }
    
    std::size_t const iChunk = iNextChunk++;
    
    daq::details::BoardSetup_t::ChannelSetup_t const& thisChannelSetup
      = channelSetup.at(channelNumber); // this setup must be available
      
    if (thisChannelSetup.mustSkip()) {
      mf::LogTrace(fLogCategory)
        << "Channel number " << channelNumber << " of board 0x"
        << std::hex << fragInfo.fragmentID << std::dec
        << " is enabled but is requested to be skipped.";
      continue;
    }
    
    //
    // assign the offline channel ID
    //
    raw::Channel_t channel = thisChannelSetup.hasChannel()
      ? thisChannelSetup.channelID: channelNumberToChannel(channelNumber);
    
    if (!thisChannelSetup.isChannel(channel)) {
      if (thisChannelSetup.mustSave()) {
        /*
         * Assuming that there are no errors in the database and in the logic
         * of this function, this is a "special" channel not connected to a PMT,
         * and the configuration of the module is explicitly asking for it to
         * be saved but it does not specify a channel ID for it
         * (the module configuration is the only source of ID for such channels)
         * Together with the request for saving the channel is,
         * the configuration should also provide the ID to save it with.
         */
        throw cet::exception("DaqDecoderICARUSPMT")
          << "Channel number " << channelNumber << " of board 0x"
          << std::hex << fragInfo.fragmentID << std::dec 
          << " is not associated to any channel ID"
          << " but was demanded to be saved.\n"
          ;
      }
      mf::LogTrace(fLogCategory)
        << "Channel number " << channelNumber << " of board 0x"
        << std::hex << fragInfo.fragmentID << std::dec
        << " is enabled but not associated to any channel ID:"
           " it will be skipped.";
      continue;
    } // if no channel ID
    assert(thisChannelSetup.isChannel(channel));
    
    //
    // global trigger
    //
    
    // we never skip waveforms not on global trigger here, because after merging
    // they may become part of a waveform that is on it; same about minimum span
    
    
    //
    // fill the waveform data
    //
    std::size_t const ch_offset = iChunk * fragInfo.nSamplesPerChannel;
    std::copy_n(fragInfo.data + ch_offset, wvfm.size(), wvfm.begin());
    
    //
    // create the proto-waveform
    //
    auto const [ itMin, itMax ] = std::minmax_element(wvfm.begin(), wvfm.end());
    protoWaveforms.push_back({ // create the waveform and its ancillary info
        raw::OpDetWaveform{ timeStamp.value(), channel, wvfm }  // waveform
      , &thisChannelSetup                                       // channelSetup
      , onGlobal                                                // onGlobal
      , *itMin                                                  // minSample
      , *itMax                                                  // maxSample
      });
    
    mf::LogTrace log(fLogCategory);
    log << "PMT channel " << dumpChannel(protoWaveforms.back())
      << " has " << wvfm.size() << " samples (read from entry #" << iChunk
      << " in fragment data) starting at electronics time " << timeStamp;
    if (protoWaveforms.back().onGlobal) log << ", on global trigger";
    if (!protoWaveforms.back().channelSetup->category.empty()) {
      log << "; category: '" << protoWaveforms.back().channelSetup->category
        << "'";
    }
    
  } // for all channels in the board
  
  
  if (diagOut) {
    (*diagOut)
      << "      - number of waveforms decoded: " << protoWaveforms.size();
    if (!protoWaveforms.empty() && protoWaveforms.back().onGlobal)
      (*diagOut) << "      - matches global trigger!";
  } // if diagnostics
  
  return protoWaveforms;
  
} // icarus::DaqDecoderICARUSPMT::createFragmentWaveforms()


//------------------------------------------------------------------------------
unsigned int icarus::DaqDecoderICARUSPMT::mergeWaveforms
  (std::vector<ProtoWaveform_t>& waveforms) const
{
  std::size_t const nWaveforms = waveforms.size();
  if (nWaveforms < 2) return 0U;
  
  // matching criteria: allow rounding error (10 ps)
  // and require the second time closer than half a tick from the first one
  auto const matchTimes = [this](electronics_time a, electronics_time b)
    { return ((a - 0.01_ns) < b) && (b  < a + fOpticalTick / 2.0); };
  
  sortWaveforms(waveforms);
  
  // define the merging groups
  std::vector<std::vector<std::size_t>> waveformGroups;
  std::size_t iWave = 0U;
  do {
    // start a new group with the next available waveform
    std::vector<std::size_t> group{ iWave }; // one element: `iWave`
    
    // merge all following waveforms contiguous to this group
    electronics_time currentEnd = waveformEndTime(waveforms[iWave]);
    raw::Channel_t const currentChannel
      = waveforms[iWave].waveform.ChannelNumber();
    while (++iWave < nWaveforms) {
      raw::OpDetWaveform const& waveform = waveforms[iWave].waveform;
      if (waveform.ChannelNumber() != currentChannel) break;
      if (!matchTimes(currentEnd, waveformStartTime(waveform))) break;
      group.push_back(iWave);
      currentEnd = waveformEndTime(waveform);
    } // while matching times
    
    waveformGroups.push_back(std::move(group));
  } while (iWave < nWaveforms);
  
  std::vector<ProtoWaveform_t> mergedWaveforms;
  mergedWaveforms.reserve(waveformGroups.size());
  for (auto const& group: waveformGroups)
    mergedWaveforms.push_back(mergeWaveformGroup(waveforms, group));
  waveforms = std::move(mergedWaveforms);
  return nWaveforms - waveforms.size();
} // icarus::DaqDecoderICARUSPMT::mergeWaveforms()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::mergeWaveformGroup(
  std::vector<ProtoWaveform_t>& allWaveforms,
  std::vector<std::size_t> const& indices
) const -> ProtoWaveform_t {
  
  if (indices.empty()) {
    throw std::logic_error
      { "DaqDecoderICARUSPMT::mergeWaveformGroup(): empty waveform group." };
  }
  
  auto itIndex = indices.begin();
  auto const iend = indices.end();
  ProtoWaveform_t mergedWaveform{ std::move(allWaveforms.at(*itIndex)) };
  /*
  mf::LogTrace("DaqDecoderICARUSPMT")
    << "Extending waveform [#" << (*itIndex) << "] channel="
    << dumpChannel(mergedWaveform) << " time="
    << waveformStartTime(mergedWaveform) << " -- "
    << waveformEndTime(mergedWaveform) << " (" << mergedWaveform.waveform.size()
    << " samples)"
    ;
  */
  while (++itIndex != iend) {
    ProtoWaveform_t& wf = allWaveforms.at(*itIndex);
    mf::LogTrace("DaqDecoderICARUSPMT")
      << " - extending waveform channel=" << dumpChannel(mergedWaveform)
      << " time=" << waveformStartTime(mergedWaveform)
      << " -- " << waveformEndTime(mergedWaveform)
      << " (" << mergedWaveform.waveform.size()
      << " samples) with waveform [#" << (*itIndex) << "] channel="
      << dumpChannel(wf) << " at time=" << waveformStartTime(wf.waveform)
      << " (" << wf.waveform.size() << " samples)"
      ;
    if (mergedWaveform.waveform.ChannelNumber() != wf.waveform.ChannelNumber())
    {
      throw std::logic_error{
        "DaqDecoderICARUSPMT::mergeWaveformGroup(): "
        "attempt to merge waveforms from channels "
        + std::to_string(mergedWaveform.waveform.ChannelNumber())
        + " and " + std::to_string(wf.waveform.ChannelNumber())
        };
    }
    if (wf.waveform.empty()) {
      throw std::logic_error{
        "DaqDecoderICARUSPMT::mergeWaveformGroup(): "
        "attempt to merge a waveform (channel "
        + std::to_string(mergedWaveform.waveform.ChannelNumber())
        + ", timestamp " + std::to_string(wf.waveform.TimeStamp()) + " again"
        };
    }
    if (wf.channelSetup->category != mergedWaveform.channelSetup->category) {
      throw std::logic_error{
        "DaqDecoderICARUSPMT::mergeWaveformGroup(): "
        "attempt to merge a waveform (channel "
        + std::to_string(mergedWaveform.waveform.ChannelNumber())
        + " of category '" + mergedWaveform.channelSetup->category
        + "' with a waveform (channel "
        + std::to_string(wf.waveform.ChannelNumber())
        + " of the different category '" + wf.channelSetup->category + "'"
        };
    }
    if (wf.channelSetup != mergedWaveform.channelSetup) {
      throw std::logic_error{
        "DaqDecoderICARUSPMT::mergeWaveformGroup(): "
        "attempt to merge a waveform (channel "
        + std::to_string(mergedWaveform.waveform.ChannelNumber())
        + " with channel settings different than the other waveform (channel "
        + std::to_string(wf.waveform.ChannelNumber())
        };
    }
    // raw::OpDetWaveform happen to be `std::vector`, so this will work:
    std::size_t const expectedSize [[maybe_unused]]
      = mergedWaveform.waveform.size() + wf.waveform.size();
    appendTo(mergedWaveform.waveform, std::move(wf.waveform));
    mergedWaveform.onGlobal |= wf.onGlobal;
    if (wf.minSample < mergedWaveform.minSample)
      mergedWaveform.minSample = wf.minSample;
    if (wf.maxSample > mergedWaveform.maxSample)
      mergedWaveform.maxSample = wf.maxSample;
    assert(wf.waveform.empty());
    assert(mergedWaveform.waveform.size() == expectedSize);
  } // while
  return mergedWaveform;
} // icarus::DaqDecoderICARUSPMT::mergeWaveformGroup()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::fillPMTfragmentTree(
  FragmentInfo_t const& fragInfo,
  TriggerInfo_t const& triggerInfo,
  electronics_time waveformTimestamp
) {
  
  if (!fTreeFragment) return;
  
  fTreeFragment->data.fragmentID = fragInfo.fragmentID;
  fTreeFragment->data.fragCount = fragInfo.eventCounter;
  fTreeFragment->data.TriggerTimeTag = fragInfo.TTT;
  fTreeFragment->data.trigger = triggerInfo.time;
  fTreeFragment->data.relBeamGate = triggerInfo.relBeamGateTime;
  fTreeFragment->data.fragTime
    = { static_cast<long long int>(fragInfo.fragmentTimestamp) };
  fTreeFragment->data.waveformTime = waveformTimestamp.value();
  fTreeFragment->data.waveformSize = fragInfo.nSamplesPerChannel;
  fTreeFragment->data.triggerBits = triggerInfo.bits;
  fTreeFragment->data.gateCount = triggerInfo.gateCount;
  fTreeFragment->data.onGlobalTrigger
    = containsGlobalTrigger(waveformTimestamp, fragInfo.nSamplesPerChannel);
  assignEventInfo(fTreeFragment->data);
  fTreeFragment->tree->Fill();
  
} // icarus::DaqDecoderICARUSPMT::fillPMTfragmentTree()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::extractFragmentBoardID
  (artdaq::Fragment const& fragment) -> BoardID_t
{
  return static_cast<BoardID_t>(fragment.fragmentID());
} // icarus::DaqDecoderICARUSPMT::extractFragmentBoardID()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::extractFragmentInfo
  (artdaq::Fragment const& artdaqFragment) const -> FragmentInfo_t
{
  //
  // fragment ID, timestamp and data begin
  //
  artdaq::Fragment::fragment_id_t const fragment_id
    = artdaqFragment.fragmentID();
  artdaq::Fragment::timestamp_t const fragmentTimestamp
    = artdaqFragment.timestamp();
  std::uint16_t const* data_begin = reinterpret_cast<std::uint16_t const*>
    (artdaqFragment.dataBeginBytes() + sizeof(sbndaq::CAENV1730EventHeader));

  //
  // event counter, trigger time tag, enabled channels
  //
  sbndaq::CAENV1730Fragment const fragment { artdaqFragment };
  sbndaq::CAENV1730FragmentMetadata const& metafrag = *(fragment.Metadata());
  sbndaq::CAENV1730EventHeader const& header = fragment.Event()->Header;
  
  unsigned int const eventCounter = header.eventCounter;
  
  unsigned int const TTT =  header.triggerTimeTag;
  
  std::uint16_t const enabledChannels = header.ChannelMask();

  //
  // samples per channel
  //
  // artDAQ size is measured in 4-byte words
  std::size_t const eventSize = header.eventSize * sizeof(std::uint32_t);
  
  constexpr std::size_t headerSize = sizeof(sbndaq::CAENV1730EventHeader);
  
  std::size_t const sampleDataSize = eventSize - headerSize;
  
  std::size_t const samplesInFragment = sampleDataSize / sizeof(std::uint16_t);
  
  std::size_t const nChannelsPerBoard = metafrag.nChannels;
  std::size_t const nSamplesPerChannel = samplesInFragment / nChannelsPerBoard;
  
  //
  // diagnostics dump
  //
  if (fDiagnosticOutput) {
    
    mf::LogVerbatim{ fLogCategory }
      << "----> PMT Fragment ID: " << std::hex << fragment_id << std::dec
        << ", size: " << eventSize << " B"
        << ", data size: " << samplesInFragment << " samples"
      << "\n    "
        << "  channels/board: " << nChannelsPerBoard
        << ", enabled: " << icarus::ns::util::bin(enabledChannels)
        << ", samples/channel: " << nSamplesPerChannel
      << "\n    "
        << "  event counter: " << eventCounter
        << ", trigger time tag: " << TTT
        << ", time stamp: " << (fragmentTimestamp / 1'000'000'000UL)
          << "." << (fragmentTimestamp % 1'000'000'000UL) << " s"
      ;
    
  } // if diagnostics

  //
  // all done
  //
  return { // C++20: write the member names explicitly
    fragment_id,
    fragmentTimestamp,
    eventCounter,
    TTT,
    enabledChannels,
    nSamplesPerChannel,
    data_begin
    };
  
} // icarus::DaqDecoderICARUSPMT::extractFragmentInfo()


//------------------------------------------------------------------------------
electronics_time icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestamp(
  FragmentInfo_t const& fragInfo,
  NeededBoardInfo_t const& boardInfo,
  SplitTimestamp_t triggerTime
) const {
  
  // check availability of mapping for this board, otherwise can't do anything
  std::size_t const fragment_id = fragInfo.fragmentID;
  std::size_t const eff_fragment_id = effectivePMTboardFragmentID(fragment_id);
  
  if (!fChannelMap.hasPMTDigitizerID(eff_fragment_id)) {
    mf::LogError(fLogCategory)
      << "*** PMT could not find channel information for fragment: "
      << fragment_id
      ;
    return NoTimestamp;
  }
  
  if (fTTTresetEverySecond)
    return fragmentWaveformTimestampFromTTT(fragInfo, boardInfo, triggerTime);
  else
    return fragmentWaveformTimestampOnTrigger(fragInfo, boardInfo, triggerTime);
  
} // icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestamp()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestampOnTrigger(
  FragmentInfo_t const& /* fragInfo */,
  NeededBoardInfo_t const& boardInfo,
  SplitTimestamp_t /* triggerTime */
) const -> electronics_time {
  
  nanoseconds const preTriggerTime = boardInfo.preTriggerTime;
  nanoseconds const PMTtriggerDelay = boardInfo.PMTtriggerDelay;
  
  auto const timestamp = fNominalTriggerTime - PMTtriggerDelay - preTriggerTime;
  mf::LogTrace(fLogCategory) << "V1730 board '" << boardInfo.name
    << "' has data starting at electronics time " << timestamp
    << " = " << fNominalTriggerTime
    << " - " << PMTtriggerDelay << " - " << preTriggerTime
    ;
  return timestamp;
  
} // icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestampOnTrigger()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestampFromTTT(
  FragmentInfo_t const& fragInfo,
  NeededBoardInfo_t const& boardInfo,
  SplitTimestamp_t triggerTime
) const -> electronics_time {
  
  /*
   * 1. goal is a timestamp in electronics time
   * 2. we have the global trigger time in electronics time
   *    (from raw::Trigger data product or from DetectorClocks service)
   * 3. board TTT and global trigger time are on the same timescale:
   *    their difference directly describes the time of the board trigger
   *    relative to the global trigger
   * 4. TTT tags the last (or after the last?) sample of the collected waveform;
   *    the time of the first sample precedes that tag by the full buffer length
   * 5. the PMT trigger itself is subject to a sequence of delays compared to
   *    the (local or global) trigger from SPEXi; here we quantify these delays
   *    from calibration offsets collectively passed via job configuration.
   */
  
  using namespace util::quantities::time_literals;
  
  //
  // 2. global trigger time
  //
  electronics_time waveformTime = fNominalTriggerTime;
  
  //
  // 3. PMT readout board trigger relative to global trigger time
  //
  unsigned int const triggerTimeNS = triggerTime.split.nanoseconds;
  
  // converted into nanoseconds (each TTT tick is 8 nanoseconds):
  unsigned int const TTT = fragInfo.TTT * 8;
  
  /*
   * The trigger time tag (TTT) on the PMT readout board is incremented every 8
   * nanoseconds, and the board is sent a reset signal every second, matching
   * the time of the change of second of the global trigger time scale
   * (International Atomic Time from White Rabbit). If the global trigger and
   * the trigger of the PMT readout happen at the same instant (which would be
   * ideally true for one fragment for each board and each event), the TTT will
   * represent exactly the number of nanoseconds of the global trigger passed
   * since the last crossing of a second boundary.
   * (in practice, this is biassed by the signal creation, propagation and
   * interpretation delays, and smeared by the clocks of the SPEXi board sending
   * the signal and the CAEN V1730 readout board, which have a period of 25 ns
   * and 8 ns, respectively).
   *
   * Multiple fragments can be collected from one PMT readout board for the same
   * event by sending the board multiple "local" triggers; these triggers are
   * all supposed to be in the neighbourhood of the global trigger time;
   * in fact, they should not be more than 1 ms away from it, since PMT readout
   * enable window is +/- 1 ms around the expected beam arrival time.
   *
   * In the most common case when global trigger and fragment tag are not
   * separated by a boundary of the second
   * (e.g. global trigger at 1620'284'028 seconds + 799'800'000 nanoseconds
   * and fragment tag 0.5 milliseconds earlier, at 1620'284'028 seconds
   * + 799'300'000 nanoseconds, i.e. with a trigger tag around 799'300'000);
   * in this example, the fragment is 0.5 ms earlier:
   * -500'000 nanoseconds = 799'300'000 (TTT) - 799'800'000 (glob. trigger)
   */
  int fragmentRelTime = static_cast<int>(TTT) - triggerTimeNS;
  if (TTT > triggerTimeNS + 500'000'000U) { // 0.5 seconds
    /*
     * case when global trigger arrives just after the boundary of the second
     * (e.g. global trigger at 1620'284'029 seconds + 300'000 nanoseconds)
     * and this fragment was tagged before that crossing (e.g. 0.5 milliseconds
     * earlier, at 1620'284'028 seconds + 999'800'000 nanoseconds, i.e. with a
     * trigger tag around 999'800'000);
     * in this example, the fragment is 0.5 ms earlier: -500'000 nanoseconds =
     * 999'800'000 (TTT) - 1'000'000'000 (second step) - 300'000 (glob. trigger)
     * and the plain difference,
     * 999'800'000 (TTT) - 300'000 (glob. trigger) = 999'500'000,
     * must be corrected by removing a whole second:
     */
    fragmentRelTime -= 1'000'000'000;
  }
  else if (TTT + 500'000'000U < triggerTimeNS) { // 0.5 seconds
    /*
     * case when global trigger arrives just before the boundary of the second
     * (e.g. global trigger at 1620'284'028 seconds + 999'800'000 nanoseconds)
     * and this fragment was tagged after that crossing (e.g. 0.5 milliseconds
     * later, at 1620'284'029 seconds + 300'000 nanoseconds, i.e. with a
     * trigger tag around 300'000 because of the pulse-per-second reset);
     * in this example, the fragment is 0.5 ms late: 500'000 nanoseconds =
     * 300'000 (TTT) + 1'000'000'000 (second step) - 999'800'000 (glob. trigger)
     * and the plain difference,
     * 300'000 (TTT) - 999'800'000 (glob. trigger) = -999'500'000,
     * must be corrected by adding a whole second:
     */
    fragmentRelTime += 1'000'000'000;
  }
  
  waveformTime += nanoseconds::castFrom(fragmentRelTime);
  
  //
  // 4. correction for relative position of sample tagged by TTT in the buffer
  //
  waveformTime -= fragInfo.nSamplesPerChannel * fOpticalTick;
  
  //
  // 5. correction for calibrated delays
  //
  /*
   * Waveform time has been expressed based on the "absolute" trigger time plus
   * an offset based on the Trigger Time Tag, which is synchronous with the
   * global trigger and reset every second.
   * We are missing a possible delay between the time of the trigger time scale
   * stepping into a new second and the the time TTT reset is effective.
   * 
   * 
   */
  
  waveformTime += boardInfo.TTTresetDelay;
  
  mf::LogTrace(fLogCategory) << "V1730 board '" << boardInfo.name
    << "' has data starting at electronics time " << waveformTime
    << " = " << fNominalTriggerTime << " (global trigger)"
    << " + " << nanoseconds(fragmentRelTime) << " (TTT - global trigger)"
    << " - " << (fragInfo.nSamplesPerChannel * fOpticalTick) << " (buffer size)"
    << " + " << boardInfo.TTTresetDelay << " (reset delay)"
    ;
  
  return waveformTime;
  
  
} // icarus::DaqDecoderICARUSPMT::fragmentWaveformTimestampFromTTT()


//------------------------------------------------------------------------------
auto icarus::DaqDecoderICARUSPMT::neededBoardInfo
  (artdaq::Fragment::fragment_id_t fragment_id) const -> NeededBoardInfo_t
{
  
  assert(fBoardInfoLookup);

  /*
   * The trigger time is always the nominal one, because that is the
   * reference time of the whole DAQ (PMT, TPC...).
   * We only need to know how sooner than the trigger the V1730 buffer
   * starts. Oh, and the delay from the global trigger time to when
   * the readout board receives and processes the trigger signal.
   */
  daq::details::BoardInfoLookup::BoardInfo_t const* boardInfo
    = fBoardInfoLookup->findBoardInfo(fragment_id);
  if (!boardInfo) {
    if (fRequireKnownBoards) {
      cet::exception e("DaqDecoderICARUSPMT");
      e << "Input fragment has ID " << fragment_id
        << " which has no associated board information (`BoardSetup`";
      if (!hasPMTconfiguration()) e << " + `.FragmentID`";
      throw e << ").\n";
    }
  }
  else {
    assert(boardInfo->fragmentID == fragment_id);
    assert(boardInfo->setup);
  }
  
  return fetchNeededBoardInfo(boardInfo, fragment_id);
} // icarus::DaqDecoderICARUSPMT::neededBoardInfo()


//------------------------------------------------------------------------------
std::set<std::string> icarus::DaqDecoderICARUSPMT::getAllInstanceNames() const {
  std::set<std::string> names;
  for (daq::details::BoardSetup_t const& setup: fBoardSetup) {
    for (daq::details::BoardSetup_t::ChannelSetup_t const& chSetup
      : setup.channelSettings
    ) {
      if (chSetup.mustSkip()) continue;
      names.insert(chSetup.category);
    } // for all channels
  } // for all boards
  return names;
} // icarus::DaqDecoderICARUSPMT::getAllInstanceNames()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::checkBoardSetup
  (std::vector<daq::details::BoardSetup_t> const& allBoardSetup) const
{
  //
  // duplicate special channel ID check
  //
  std::unordered_map<raw::Channel_t, unsigned int> assignedChannels;
  bool hasDuplicates = false;
  for (daq::details::BoardSetup_t const& setup: allBoardSetup) {
    for (daq::details::BoardSetup_t::ChannelSetup_t const& chSetup
      : setup.channelSettings
    ) {
      if (chSetup.mustSkip()) continue; // skipped channels do not matter anyway
      // special channels by definition have a non-empty category
      if (!chSetup.hasChannel() || chSetup.category.empty()) continue;
      if (++assignedChannels[chSetup.channelID] > 1) hasDuplicates = true;
    } // for all channels
  } // for all boards
  if (!hasDuplicates) return;
  
  art::Exception e { art::errors::Configuration };
  e << "Some channel ID are specified in multiple board special channel setup:";
  for (auto [ channelID, entries ]: assignedChannels) {
    if (entries <= 1) continue; // not a duplicate
    e << "\n - channel ID 0x" << std::hex << channelID << std::dec << ": "
      << entries << " times";
  } // for
  
  throw e;
} // icarus::DaqDecoderICARUSPMT::checkBoardSetup()


//------------------------------------------------------------------------------
unsigned int icarus::DaqDecoderICARUSPMT::extractTriggerTimeTag
  (artdaq::Fragment const& fragment)
{
  sbndaq::CAENV1730Fragment const V1730fragment { fragment };
  sbndaq::CAENV1730EventHeader const header = V1730fragment.Event()->Header;
  
  unsigned int TTT { header.triggerTimeTag }; // prevent narrowing
  return TTT;
  
} // icarus::DaqDecoderICARUSPMT::extractTriggerTimeTag()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::sortWaveforms
  (std::vector<ProtoWaveform_t>& waveforms) const
{
  auto byChannelThenTime = []
    (ProtoWaveform_t const& left, ProtoWaveform_t const& right)
    {
      return (left.waveform.ChannelNumber() != right.waveform.ChannelNumber())
        ? left.waveform.ChannelNumber() < right.waveform.ChannelNumber()
        : left.waveform.TimeStamp() < right.waveform.TimeStamp();
    };
  
  std::sort(waveforms.begin(), waveforms.end(), byChannelThenTime);

} // icarus::DaqDecoderICARUSPMT::sortWaveforms()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::initTrees
  (std::vector<std::string> const& treeNames)
{
  
  auto findTree = [](std::string const& name)
    {
      return static_cast<DataTrees>(
          std::distance(TreeNames.begin(),
          std::find(TreeNames.begin(), TreeNames.end(), name))
        );
    };
  
  for (std::string const& name: treeNames) {
    switch (findTree(name)) {
      case DataTrees::Fragments: initFragmentsTree(); break;
      case DataTrees::N:
      default:
        throw cet::exception("DaqDecoderICARUSPMT")
          << "initTrees(): no data tree supported with name '" << name
          << "'.\n";
    } // switch
  } // for names
  
} // icarus::DaqDecoderICARUSPMT::initTrees()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::initEventIDtree
  (TTree& tree, TreeData_EventID_t& data)
{
  
  usesEventInfo(); // this tree includes event information
  
  tree.Branch("run", &data.run);
  tree.Branch("subrun", &data.subrun);
  tree.Branch("event", &data.event);
  tree.Branch("timestamp", &data.timestamp.time, "timestamp/L");
  
} // icarus::DaqDecoderICARUSPMT::initEventIDtree()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::initFragmentsTree() {
  
  if (fTreeFragment) return;
  
  TTree* tree = art::ServiceHandle<art::TFileService>()
    ->make<TTree>("PMTfragments", "PMT fragment data");
  
  fTreeFragment = std::make_unique<TreeFragment_t>();
  fTreeFragment->tree = tree;
  auto& data = fTreeFragment->data;
  
  initEventIDtree(*tree, data);
  
  tree->Branch("fragmentID", &data.fragmentID);
  tree->Branch("fragCount", &data.fragCount);
  tree->Branch("fragTime", &data.fragTime.time, "fragTime/L"); // ROOT 6.24 can't detect 64-bit
  tree->Branch("fragTimeSec", &data.fragTime.split.seconds);
  tree->Branch("TTT", &data.TriggerTimeTag, "TTT/l"); // ROOT 6.24 can't detect 64-bit
  tree->Branch("trigger", &data.trigger.time, "trigger/L"); // ROOT 6.24 can't detect 64-bit
  tree->Branch("triggerSec", &data.trigger.split.seconds);
  tree->Branch("triggerNS", &data.trigger.split.nanoseconds);
  tree->Branch("relBeamGateNS", &data.relBeamGate, "relBeamGateNS/I"); // ROOT 6.24 can't handle `long` neither
  tree->Branch("waveformTime", &data.waveformTime);
  tree->Branch("waveformSize", &data.waveformSize);
  tree->Branch("triggerBits", &data.triggerBits);
  tree->Branch("gateCount", &data.gateCount);
  tree->Branch("onGlobal", &data.onGlobalTrigger);
  
} // icarus::DaqDecoderICARUSPMT::initFragmentsTree()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::usesEventInfo() {
  
  // the allocation of fEventInfo is the flag for event information usage
  if (!fEventInfo) fEventInfo = std::make_unique<TreeData_EventID_t>();
  
} // icarus::DaqDecoderICARUSPMT::usesEventInfo()


void icarus::DaqDecoderICARUSPMT::assignEventInfo
  (TreeData_EventID_t& treeData) const
{
  
  assert(fEventInfo);
  treeData = *fEventInfo; // nice slicing
  
} // icarus::DaqDecoderICARUSPMT::assignEventInfo()


//------------------------------------------------------------------------------
void icarus::DaqDecoderICARUSPMT::fillTreeEventID
  (art::Event const& event, TreeData_EventID_t& treeData) const
{
  art::EventID const& id = event.id();
  treeData.run    = id.run();
  treeData.subrun = id.subRun();
  treeData.event  = id.event();
  
  art::Timestamp const& timestamp = event.time();
  treeData.timestamp
    = { static_cast<int>(timestamp.timeHigh()), timestamp.timeLow() };
  
} // icarus::DaqDecoderICARUSPMT::fillTreeEventID()


//------------------------------------------------------------------------------
DEFINE_ART_MODULE(icarus::DaqDecoderICARUSPMT)


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