Turns PMT readout fragments from DAQ into LArSoft data products. More...

Inheritance diagram for daq::PMTDecoder:

Classes
struct	BoardSetupConfig
	Configuration of the V1730 readout board setup. More...

struct	Config
	Main tool configuration. More...

struct	NeededBoardInfo_t
	Information used in decoding from a board. More...

struct	SplitTimestamp_t
	Data structure for trigger time. More...

struct	TreeData_EventID_t
	Data structure for basic event information in simple ROOT trees. More...

struct	TreeFragment_t
	Structure collecting all data for a fragment ROOT tree. More...

Public Types
using	nanoseconds = util::quantities::intervals::nanoseconds
	Alias. More...

using	Parameters = art::ToolConfigTable< Config >

Public Member Functions
	PMTDecoder (Parameters const &params)
	Constructor. More...

virtual void	consumes (art::ConsumesCollector &consumerColl) override
	I hereby declare I will consume trigger and PMT configuration products. More...

virtual void	produces (art::ProducesCollector &) override
	Each algorithm may have different objects it wants "produced" so use this to let the top level producer module "know" what it is outputting. More...

virtual void	configure (const fhicl::ParameterSet &) override
	Reconfiguration is not supported: all configuration at construction time. More...

virtual void	setupRun (art::Run const &run) override
	Reads the PMT configuration from the run. More...

virtual void	setupEvent (art::Event const &event) override
	Will read trigger information one day if needed. More...

virtual void	initializeDataProducts () override
	Initialize any data products the tool will output. More...

virtual void	process_fragment (const artdaq::Fragment &fragment) override
	Given a set of recob hits, run DBscan to form 3D clusters. More...

virtual void	outputDataProducts (art::Event &event) override
	Output the data products to the event store. More...

Public Member Functions inherited from daq::IDecoder
virtual	~IDecoder () noexcept=default
	Virtual Destructor. More...

Private Types
enum	DataTrees : std::size_t { DataTrees::Fragments, DataTrees::N }
	Enumerate the supported data trees. More...

using	TreeNameList_t = std::array< std::string, static_cast< std::size_t >(DataTrees::N)>

using	OpDetWaveformCollection = std::vector< raw::OpDetWaveform >

using	OpDetWaveformCollectionPtr = std::unique_ptr< OpDetWaveformCollection >

Private Member Functions
bool	hasPMTconfiguration () const
	Returns whether PMT configuration information is expected to be available. More...

bool	UpdatePMTConfiguration (sbn::PMTconfiguration const *PMTconfig)
	Updates the PMT configuration cache. How? Dunno. Placeholder. More...

details::BoardInfoLookup	matchBoardConfigurationAndSetup (sbn::PMTconfiguration const *PMTconfig) const
	Returns a lookup object with board setup and configuration info. More...

NeededBoardInfo_t	fetchNeededBoardInfo (details::BoardInfoLookup::BoardInfo_t const *boardInfo, unsigned int fragmentID) const
	Puts together all the needed information for a board. More...

template<std::size_t NBits, typename T >
constexpr std::pair < std::array< std::size_t, NBits >, std::size_t >	setBitIndices (T value) noexcept
	Returns the count of set bits for each set bit. More...

void	usesEventInfo ()
	Declares the use of event information. More...

void	initTrees (std::vector< std::string > const &treeNames)
	Initializes all requested data trees. More...

void	initEventIDtree (TTree &tree, TreeData_EventID_t &data)
	Initializes the event ID part of a tree. More...

void	initFragmentsTree ()
	Initializes the fragment data tree (`fTreeFragment`). More...

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

void	assignEventInfo (TreeData_EventID_t &treeData) const
	Assigns the cached event information to the specified tree data. More...

Static Private Member Functions
static std::string	listTreeNames (std::string const &sep="\n")
	Returns a string with all supported tree names. More...

static TreeNameList_t	initTreeNames ()
	Static initialization. More...

Private Attributes
bool const	fDiagnosticOutput
	If true will spew endless messages to output. More...

bool const	fRequireKnownBoards
	Whether info on all input boards is required. More...

bool const	fRequireBoardConfig
	Whether setup info on all boards is required. More...

std::optional< art::InputTag > const	fPMTconfigTag
	Input tag of the PMT configuration. More...

art::InputTag const	fTriggerTag
	Input tag of the global trigger. More...

std::vector < details::BoardSetup_t > const	fBoardSetup
	All board setup settings. More...

std::string const	fLogCategory
	Message facility category. More...

geo::GeometryCore const &	fGeometry
	Geometry service provider. More...

detinfo::DetectorTimings const	fDetTimings
	Interface to LArSoft configuration for detector timing. More...

icarusDB::IICARUSChannelMap const &	fChannelMap
	Fragment/channel mapping database. More...

nanoseconds const	fOpticalTick
	Duration of the optical detector readout sampling tick (i.e. 2 ns; shh!). More...

detinfo::timescales::electronics_time const	fNominalTriggerTime
	Trigger time as reported by `DetectorClocks` service. More...

OpDetWaveformCollectionPtr	fOpDetWaveformCollection
	The output data collection pointer. More...

std::optional < details::BoardInfoLookup >	fBoardInfoLookup
	Find the information on a readout boards by fragment ID. More...

SplitTimestamp_t	fTriggerTimestamp
	Trigger timestamp for the current event. More...

std::unique_ptr < TreeData_EventID_t >	fEventInfo
	Event ID for trees. More...

std::unique_ptr< TreeFragment_t >	fTreeFragment
	Tree with fragment information. More...

Static Private Attributes
static TreeNameList_t const	TreeNames = daq::PMTDecoder::initTreeNames()

Detailed Description

Turns PMT readout fragments from DAQ into LArSoft data products.

The tool can read fragments from CAEN V1730 readout boards delivered by artDAQ.

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 PMTDecoder.

Description of the configuration parameters:

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 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 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").
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, mandatory): tag for the information (currently required to be a collection of raw::ExternalTrigger, in the future it should become raw::Trigger);
DataTrees (list of strings, default: none): list of data trees to be produced; if none (default), then TFileService is not required.
LogCategory (string, default: PMTDecoder): 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

All waveforms on the same readout board share the same timestamp.

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 electronics time scale.

There are two "types" of waveforms: the ones acquired at global trigger time, and the ones acquired because of a "trigger primitive" which did not upgrade to global (likely because not in coincidence with the beam gate). In both cases, it is the same type of signal, a trigger primitive from the NI7820 FPGA, which initializes the acquisition of the waveform. Every delay between when that signal is emitted and when the PMT trigger is executed shifts the time stamp of the waveform backward.

We assign the the time stamp of the waveforms matching the global trigger as follow:

the base time is the global trigger time; this effectively defines the electronics time scale, so its representation is a fixed number that is configured in LArSoft and can be accessed with DetectorClocksData::TriggerTime();
the delay of the propagation from the trigger board to the readout board is subtracted to the timestamp; this value must be independently measured and provided to this decoder via tool configuration as setup information (TriggerDelay); if not present in the setup, this delay is not considred;
upon receiving the trigger, 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.

We do not assign the the time stamp of the waveforms not matching the global trigger because we have no clue how to do that. Ok, that is a to-do!

Each V1730 event record includes a trigger time tag (TTT), which is the value of an internal counter of the board at the time the board received a trigger. This can be used to relate the various waveforms (and the various fragments) in the art event.

Data trees

The tool 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.
- fragTime (64-bit signed integer), fragTimeSec (32-bit signed integer): the timestamp of the PMT fragment, assigned by the board reader constructing the fragment.

Technical notes

In order to correctly reconstruct the time stamp, this tool 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 between the global trigger and the time that trigger is received and acted upon in the readout board, which needs 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 tool 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. For a board to be served, an entry of that board must be present in the tool configuration (BoardSetup). It is an error for a fragment in input not to have an entry for the corresponding board setup.

The tool code extract 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.

Glossary

setup, **[PMT] configuration**: this is jargon specific to this tool. Information about a readout board can come from two sources: the "setup" is information included in the BoardSetup configuration list of this tool; the "PMT configuration" is information included in the DAQ configuration that is delivered via PMTconfigTag.
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.

Definition at line 267 of file PMTDecoder_tool.cc.

Member Typedef Documentation

using daq::PMTDecoder::nanoseconds = util::quantities::intervals::nanoseconds

Alias.

Definition at line 284 of file PMTDecoder_tool.cc.

using daq::PMTDecoder::OpDetWaveformCollection = std::vector<raw::OpDetWaveform>

private

Definition at line 485 of file PMTDecoder_tool.cc.

using daq::PMTDecoder::OpDetWaveformCollectionPtr = std::unique_ptr<OpDetWaveformCollection>

private

Definition at line 486 of file PMTDecoder_tool.cc.

using daq::PMTDecoder::Parameters = art::ToolConfigTable<Config>

Definition at line 384 of file PMTDecoder_tool.cc.

using daq::PMTDecoder::TreeNameList_t = std::array<std::string, static_cast<std::size_t>(DataTrees::N)>

private

Definition at line 276 of file PMTDecoder_tool.cc.

Member Enumeration Documentation

enum daq::PMTDecoder::DataTrees : std::size_t

strongprivate

Enumerate the supported data trees.

Enumerator
Fragments	Information about fragments.
N	Counter.

Definition at line 271 of file PMTDecoder_tool.cc.

                       : std::size_t {
     Fragments, ///< Information about fragments
     N          ///< Counter.
   };

Constructor & Destructor Documentation

daq::PMTDecoder::PMTDecoder ( Parameters const & params )

explicit

Constructor.

Parameters

params configuration parameter set

Definition at line 680 of file PMTDecoder_tool.cc.

   : fDiagnosticOutput{ params().DiagnosticOutput() }
   , fRequireKnownBoards{ params().RequireKnownBoards() }
   , fRequireBoardConfig{ params().RequireBoardConfig() }
   , fPMTconfigTag{ ::util::fhicl::getOptionalValue(params().PMTconfigTag) }
   , fTriggerTag{ params().TriggerTag() }
   , fBoardSetup{ params().BoardSetup() }
   , fLogCategory{ params().LogCategory() }
   , fGeometry{ *(lar::providerFrom<geo::Geometry const>()) }
   , fDetTimings
     { art::ServiceHandle<detinfo::DetectorClocksService const>()->DataForJob() }
   , fChannelMap{ *(art::ServiceHandle<icarusDB::IICARUSChannelMap const>{}) }

Member Function Documentation

void daq::PMTDecoder::assignEventInfo ( TreeData_EventID_t & treeData ) const

private

Assigns the cached event information to the specified tree data.

virtual void daq::PMTDecoder::configure ( const fhicl::ParameterSet & )

overridevirtual

Reconfiguration is not supported: all configuration at construction time.

Implements daq::IDecoder.

virtual void daq::PMTDecoder::consumes ( art::ConsumesCollector & consumerColl )

overridevirtual

I hereby declare I will consume trigger and PMT configuration products.

Reimplemented from daq::IDecoder.

NeededBoardInfo_t daq::PMTDecoder::fetchNeededBoardInfo	(	details::BoardInfoLookup::BoardInfo_t const *	boardInfo,
		unsigned int	fragmentID
	)		const

private

Puts together all the needed information for a board.

void daq::PMTDecoder::fillTreeEventID	(	art::Event const &	event,
		TreeData_EventID_t &	treeData
	)		const

private

Fills the base information of a tree data entry from an art event.

bool daq::PMTDecoder::hasPMTconfiguration ( ) const

inlineprivate

Returns whether PMT configuration information is expected to be available.

Definition at line 499 of file PMTDecoder_tool.cc.

499 { return fPMTconfigTag.has_value(); }

daq::PMTDecoder::fPMTconfigTag

std::optional< art::InputTag > const fPMTconfigTag

Input tag of the PMT configuration.

Definition: PMTDecoder_tool.cc:451

void daq::PMTDecoder::initEventIDtree	(	TTree &	tree,
		TreeData_EventID_t &	data
	)

private

Initializes the event ID part of a tree.

void daq::PMTDecoder::initFragmentsTree ( )

private

Initializes the fragment data tree (fTreeFragment).

virtual void daq::PMTDecoder::initializeDataProducts ( )

overridevirtual

Initialize any data products the tool will output.

Implements daq::IDecoder.

auto daq::PMTDecoder::initTreeNames ( )

staticprivate

Static initialization.

Definition at line 661 of file PMTDecoder_tool.cc.

                                                     {
   TreeNameList_t names;
   names[static_cast<std::size_t>(DataTrees::Fragments)] = "PMTfragments";
   return names;
 } // daq::PMTDecoder::initTreeNames()

void daq::PMTDecoder::initTrees ( std::vector< std::string > const & treeNames )

private

Initializes all requested data trees.

std::string daq::PMTDecoder::listTreeNames ( std::string const & sep = "\n" )

staticprivate

Returns a string with all supported tree names.

Definition at line 667 of file PMTDecoder_tool.cc.

                                                              {
   std::string l;
   for (std::string const& name: TreeNames) {
     if (!l.empty()) l += sep;
     l += '\'';
     l += name;
     l += '\'';
   } // for
   return l;
 } // daq::PMTDecoder::listTreeNames()

details::BoardInfoLookup daq::PMTDecoder::matchBoardConfigurationAndSetup ( sbn::PMTconfiguration const * PMTconfig ) const

private

Returns a lookup object with board setup and configuration info.

Parameters

PMTconfig the PMT configuration, if available

Returns: an object working like lookup table for all fragment information

This method merges the setup information from the tool 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.

virtual void daq::PMTDecoder::outputDataProducts ( art::Event & event )

overridevirtual

Output the data products to the event store.

Parameters

event The event store objects

Implements daq::IDecoder.

virtual void daq::PMTDecoder::process_fragment ( const artdaq::Fragment & fragment )

overridevirtual

Given a set of recob hits, run DBscan to form 3D clusters.

Parameters

fragment	The artdaq fragment to process
rawDigitColllection	The output RawDigits

Implements daq::IDecoder.

virtual void daq::PMTDecoder::produces ( art::ProducesCollector & )

overridevirtual

Each algorithm may have different objects it wants "produced" so use this to let the top level producer module "know" what it is outputting.

Implements daq::IDecoder.

template<std::size_t NBits, typename T >

constexpr std::pair<std::array<std::size_t, NBits>, std::size_t> daq::PMTDecoder::setBitIndices ( T value )

privatenoexcept

Returns the count of set bits for each set bit.

Template Parameters

NBits the number of bits to test

Parameters

value the bit mask to be analyzed

Returns: 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).

virtual void daq::PMTDecoder::setupEvent ( art::Event const & event )

overridevirtual

Will read trigger information one day if needed.

Reimplemented from daq::IDecoder.

virtual void daq::PMTDecoder::setupRun ( art::Run const & run )

overridevirtual

Reads the PMT configuration from the run.

Reimplemented from daq::IDecoder.

bool daq::PMTDecoder::UpdatePMTConfiguration ( sbn::PMTconfiguration const * PMTconfig )

private

Updates the PMT configuration cache. How? Dunno. Placeholder.

void daq::PMTDecoder::usesEventInfo ( )

private

Declares the use of event information.

Member Data Documentation

std::optional<details::BoardInfoLookup> daq::PMTDecoder::fBoardInfoLookup

private

Find the information on a readout boards by fragment ID.

Definition at line 491 of file PMTDecoder_tool.cc.

std::vector<details::BoardSetup_t> const daq::PMTDecoder::fBoardSetup

private

All board setup settings.

Definition at line 455 of file PMTDecoder_tool.cc.

icarusDB::IICARUSChannelMap const& daq::PMTDecoder::fChannelMap

private

Fragment/channel mapping database.

Definition at line 469 of file PMTDecoder_tool.cc.

detinfo::DetectorTimings const daq::PMTDecoder::fDetTimings

private

Interface to LArSoft configuration for detector timing.

Definition at line 467 of file PMTDecoder_tool.cc.

bool const daq::PMTDecoder::fDiagnosticOutput

private

If true will spew endless messages to output.

Definition at line 446 of file PMTDecoder_tool.cc.

std::unique_ptr<TreeData_EventID_t> daq::PMTDecoder::fEventInfo

private

Event ID for trees.

Definition at line 582 of file PMTDecoder_tool.cc.

geo::GeometryCore const& daq::PMTDecoder::fGeometry

private

Geometry service provider.

Definition at line 464 of file PMTDecoder_tool.cc.

std::string const daq::PMTDecoder::fLogCategory

private

Message facility category.

Definition at line 457 of file PMTDecoder_tool.cc.

detinfo::timescales::electronics_time const daq::PMTDecoder::fNominalTriggerTime

private

Trigger time as reported by DetectorClocks service.

Definition at line 480 of file PMTDecoder_tool.cc.

OpDetWaveformCollectionPtr daq::PMTDecoder::fOpDetWaveformCollection

private

The output data collection pointer.

Definition at line 488 of file PMTDecoder_tool.cc.

nanoseconds const daq::PMTDecoder::fOpticalTick

private

Duration of the optical detector readout sampling tick (i.e. 2 ns; shh!).

Definition at line 477 of file PMTDecoder_tool.cc.

std::optional<art::InputTag> const daq::PMTDecoder::fPMTconfigTag

private

Input tag of the PMT configuration.

Definition at line 451 of file PMTDecoder_tool.cc.

bool const daq::PMTDecoder::fRequireBoardConfig

private

Whether setup info on all boards is required.

Definition at line 449 of file PMTDecoder_tool.cc.

bool const daq::PMTDecoder::fRequireKnownBoards

private

Whether info on all input boards is required.

Definition at line 448 of file PMTDecoder_tool.cc.

std::unique_ptr<TreeFragment_t> daq::PMTDecoder::fTreeFragment

private

Tree with fragment information.

Definition at line 583 of file PMTDecoder_tool.cc.

art::InputTag const daq::PMTDecoder::fTriggerTag

private

Input tag of the global trigger.

Definition at line 453 of file PMTDecoder_tool.cc.

SplitTimestamp_t daq::PMTDecoder::fTriggerTimestamp

private

Trigger timestamp for the current event.

Definition at line 495 of file PMTDecoder_tool.cc.

daq::PMTDecoder::TreeNameList_t const daq::PMTDecoder::TreeNames = daq::PMTDecoder::initTreeNames()

staticprivate

Definition at line 277 of file PMTDecoder_tool.cc.

The documentation for this class was generated from the following file:

PMTDecoder_tool.cc

Classes

Public Types

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Configuration

Requirements

Waveform time stamp

Data trees

Technical notes

Glossary

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation