|
| 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...
|
| |
| daq::details::BoardInfoLookup | matchBoardConfigurationAndSetup (sbn::PMTconfiguration const *PMTconfig) const |
| | Returns a lookup object with board setup and configuration info. More...
|
| |
| NeededBoardInfo_t | fetchNeededBoardInfo (daq::details::BoardInfoLookup::BoardInfo_t const *boardInfo, unsigned int fragmentID) const |
| | Puts together all the needed information for a board. More...
|
| |
| TriggerInfo_t | fetchTriggerTimestamp (art::Event const &event) const |
| | Retrieves the global trigger time stamp from the event. More...
|
| |
| electronics_time | fragmentWaveformTimestamp (FragmentInfo_t const &fragInfo, NeededBoardInfo_t const &boardInfo, SplitTimestamp_t triggerTime) const |
| | Returns the timestamp for the waveforms in the specified fragment. More...
|
| |
| electronics_time | fragmentWaveformTimestampOnTrigger (FragmentInfo_t const &fragInfo, NeededBoardInfo_t const &boardInfo, SplitTimestamp_t triggerTime) const |
| | Returns the timestamp for the waveforms in the specified fragment. More...
|
| |
| electronics_time | fragmentWaveformTimestampFromTTT (FragmentInfo_t const &fragInfo, NeededBoardInfo_t const &boardInfo, SplitTimestamp_t triggerTime) const |
| | Returns the timestamp for the waveforms in the specified fragment. More...
|
| |
| artdaq::Fragments const & | readInputFragments (art::Event const &event) const |
| | Reads the fragments to be processed. More...
|
| |
| void | checkFragmentType (artdaq::Fragment const &artdaqFragment) const |
| | Throws an exception if artdaqFragment is not of type CAEN1730. More...
|
| |
| artdaq::FragmentPtrs | makeFragmentCollection (artdaq::Fragment const &sourceFragment) const |
| |
| artdaq::FragmentPtrs | makeFragmentCollectionFromFragment (artdaq::Fragment const &sourceFragment) const |
| | Converts a plain fragment into a fragment collection. More...
|
| |
| artdaq::FragmentPtrs | makeFragmentCollectionFromContainerFragment (artdaq::Fragment const &sourceFragment) const |
| | Converts a container fragment into a fragment collection. More...
|
| |
| std::vector< ProtoWaveform_t > | processBoardFragments (artdaq::FragmentPtrs const &artdaqFragment, TriggerInfo_t const &triggerInfo) |
| | Extracts waveforms from the specified fragments from a board. More...
|
| |
| unsigned int | mergeWaveforms (std::vector< ProtoWaveform_t > &waveforms) const |
| |
| void | sortWaveforms (std::vector< ProtoWaveform_t > &waveforms) const |
| | Sorts in place the specified waveforms in channel order, then in time. More...
|
| |
std::vector< ProtoWaveform_t
const * > | findWaveformsWithNominalTrigger (std::vector< ProtoWaveform_t > const &waveforms) const |
| | Returns pointers to all waveforms including the nominal trigger time. More...
|
| |
| bool | containsGlobalTrigger (raw::OpDetWaveform const &waveform) const |
| | Returns whether waveform includes the tick of the nominal trigger time. More...
|
| |
| bool | containsGlobalTrigger (electronics_time time, std::size_t nTicks) const |
| | Returns whether nominal trigger time is within nTicks from time. More...
|
| |
| ProtoWaveform_t | mergeWaveformGroup (std::vector< ProtoWaveform_t > &allWaveforms, std::vector< std::size_t > const &indices) const |
| |
| electronics_time | waveformStartTime (raw::OpDetWaveform const &wf) const |
| |
| electronics_time | waveformStartTime (ProtoWaveform_t const &wf) const |
| |
| electronics_time | waveformEndTime (raw::OpDetWaveform const &wf) const |
| |
| electronics_time | waveformEndTime (ProtoWaveform_t const &wf) const |
| |
| std::vector< ProtoWaveform_t > | processFragment (artdaq::Fragment const &artdaqFragment, NeededBoardInfo_t const &boardInfo, TriggerInfo_t const &triggerInfo) |
| | Create waveforms and fills trees for the specified artDAQ fragment. More...
|
| |
| std::vector< ProtoWaveform_t > | createFragmentWaveforms (FragmentInfo_t const &fragInfo, AllChannelSetup_t const &channelSetup, electronics_time const timeStamp) const |
| | Creates raw::OpDetWaveform objects from the fragment data. More...
|
| |
| FragmentInfo_t | extractFragmentInfo (artdaq::Fragment const &artdaqFragment) const |
| | Extracts useful information from fragment data. More...
|
| |
| NeededBoardInfo_t | neededBoardInfo (artdaq::Fragment::fragment_id_t fragment_id) const |
| | Returns the board information for this fragment. More...
|
| |
| std::set< std::string > | getAllInstanceNames () const |
| | Returns all the instance names we will produce. More...
|
| |
| void | checkBoardSetup (std::vector< daq::details::BoardSetup_t > const &allBoardSetup) const |
| | Throws an exception if the configuration of boards shows errors. 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...
|
| |
| void | fillPMTfragmentTree (FragmentInfo_t const &fragInfo, TriggerInfo_t const &triggerInfo, electronics_time waveformTimestamp) |
| |
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 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").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
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 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:
- 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();
- 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;
- 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;
- 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).
- 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.
- 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.
- 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.
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()):
- pre-processing: currently nothing
- processing of each board data independently: at this level, all the buffers from the 16 channels of a single board are processed together (
processBoardFragments())
- the configuration and parameters specific to this board are fetched
- 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
- merging of contiguous waveforms is performed
- post-processing of proto-waveforms:
- sorting by time (as opposed as roughly by channel, as they come)
- 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.
Definition at line 406 of file DaqDecoderICARUSPMT_module.cc.
1.8.5