Make ROOT tree with information about event and trigger input. More...

Inheritance diagram for icarus::trigger::MakeTriggerSimulationTree:

Classes
struct	Config

Public Types
using	microseconds = util::quantities::intervals::microseconds

using	Parameters = art::EDAnalyzer::Table< Config >

Public Member Functions
	MakeTriggerSimulationTree (Parameters const &config)

	MakeTriggerSimulationTree (MakeTriggerSimulationTree const &)=delete

	MakeTriggerSimulationTree (MakeTriggerSimulationTree &&)=delete

MakeTriggerSimulationTree &	operator= (MakeTriggerSimulationTree const &)=delete

MakeTriggerSimulationTree &	operator= (MakeTriggerSimulationTree &&)=delete

virtual void	analyze (art::Event const &event) override
	Fills the plots. Also extracts the information to fill them with. More...

Private Member Functions
TriggerGatesInfo	extractTriggerInfo (art::Event const &event, detinfo::DetectorTimings const &detTimings) const
	Returns a `TriggerGatesInfo` with trigger information for the tree. More...

geo::Point_t	gateChannelCentroid (icarus::trigger::OpticalTriggerGateData_t const &gate) const

Static Private Member Functions
static icarus::trigger::details::EventInfoExtractor::EDepTags_t	makeEdepTag (fhicl::OptionalSequence< art::InputTag > const &EnergyDepositTags, fhicl::OptionalAtom< art::InputTag > const &EnergyDepositSummaryTag)
	Creates a `EDepTags_t` from two optional parameters. More...

Private Attributes
microseconds const	fBeamGateDuration
	Duration of the gate during with global optical triggers are accepted. More...

microseconds const	fBeamGateStart
	Start of the beam gate with respect to `BeamGate()`. More...

microseconds const	fPreSpillWindow
	Duration of the pre-spill gate. More...

microseconds const	fPreSpillStart
	Start of the pre-spill gate. More...

art::InputTag const	fTriggerGatesTag
	Tag for optical trigger gate data product. More...

std::string const	fLogCategory
	Name of output stream for message facility. More...

geo::GeometryCore const &	fGeom

details::EventIDTree	fIDTree
	Main ROOT tree: event ID. More...

std::optional < details::EventInfoTree >	fEventTree
	ROOT tree: event information. More...

std::optional< TriggerGateTree >	fTriggerGateTree
	ROOT tree: trigger gates. More...

details::EventInfoExtractorMaker const	fEventInfoExtractorMaker
	Helper to fill a `EventInfo_t` from an art event. More...

icarus::ns::util::ThreadSafeChangeMonitor < icarus::trigger::BeamGateStruct >	fBeamGateChangeCheck
	Functor returning whether a gate has changed. More...

Detailed Description

Make ROOT tree with information about event and trigger input.

This module produces a ROOT tree with information about the event and about the trigger input.

Trigger simulation logic is applied in a time interval that we call "beam gate", although it would more precisely dubbed as "trigger gate". The reference time of this gate is the ("real") beam gate opening time as reported by detinfo::DetectorClocksData::BeamGateTime(), whose absolute value may vary event by event (see note below). The configuration of this module allows to shift pre-beam and beam gates with respect to that time.

Note: detector data and simulated data have intrinsically different time references. In LArSoft, the TPC waveform time reference is the most static and less flexible. Since the detector pins the TPC timing to the trigger time, TPC waveforms are written referring to that time, and then the whole event is also written in that frame. In simulated data, instead, a trigger is not known until after the (PMT) waveforms are produced, and it is therefore more convenient to refer to a time that is less dependent on data itself: the beam gate opening. In detector data, the value of beam gate opening time will appear to change event by event, as trigger(s) time do in simulated data. For this reason, all the analysis should be performed on relative times (e.g. relative to the trigger, which is the "native" LArSoft reference), i.e. in the trigger timescale or, equivalently, subtracting detinfo::DetectorClocksData::TriggerTime() from the times.

Input

The following data products are required in input:

std::vector<simb::MCTruth> (tag: configured in GeneratorTags): any number of truth information records;
std::vector<sim::SimEnergyDeposits> (tag: configured in EnergyDepositTags): energy depositions to be counted in the event information;
std::vector<icarus::trigger::OpticalTriggerGateData_t> (tag: configured in TriggerGatesTag): list of trigger gate outputs to be put into the tree.

Output

The output tree is written via TFileService in the ROOT directory assigned to this module.

The tree contains three "sections":

event identification: see icarus::trigger::details::EventIDTree for the details;
event information: see icarus::trigger::details::EventInfoTree for the details;
information on the trigger gates (data product configured via TriggerGatesTag parameter): information on the state of each trigger gate during the beam gate is extracted, including the number of times the gate is opened and when; see TriggerGateTree for details on the structure of the tree, and extractTriggerInfo() for the details of how each value is computed.

Configuration parameters

GeneratorTags (list of input tags, default: [ generator ]): a list of data products containing the particles generated by event generators.
EnergyDepositTags (list of input tags, default: [ "largeant:TPCActive" ]): a list of data products with energy depositions.
EnergyDepositSummaryTag (input tag): alternative to EnergyDepositTags, uses energy deposition information from a summary data product instead of extracting the information.
TriggerGatesTag (string, mandatory): name of the module instance which produced the trigger primitives to be used as input. The typical trigger primitives used as input may be LVDS discriminated output (e.g. from icarus::trigger::LVDSgates module) or combinations of them (e.g. from icarus::trigger::SlidingWindowTrigger module).
BeamGateDuration (time, mandatory): the duration of the beam gate; the time requires the unit to be explicitly specified: use "1.6 us" for BNB, 9.5 us for NuMI (also available as BNB_settings.spill_duration and NuMI_settings.spill_duration in trigger_icarus.fcl).
BeamGateStart (time, default: 0 s): open the beam gate this long after the formal beam gate time.
PreSpillWindow (time, default: 10 s): duration of the pre-spill window;
PreSpillWindowGap (time, default: 0 s): gap from the end of pre-spill window to the start of beam gate;
EventTreeName (string, default: "Treegger"): the name of the ROOT tree being written on disk;
LogCategory (string, default MakeTriggerSimulationTree): name of category used to stream messages from this module into message facility.

Technical description of the module

Definition at line 263 of file MakeTriggerSimulationTree_module.cc.

Member Typedef Documentation

using icarus::trigger::MakeTriggerSimulationTree::microseconds = util::quantities::intervals::microseconds

Definition at line 267 of file MakeTriggerSimulationTree_module.cc.

using icarus::trigger::MakeTriggerSimulationTree::Parameters = art::EDAnalyzer::Table<Config>

Definition at line 333 of file MakeTriggerSimulationTree_module.cc.

Constructor & Destructor Documentation

icarus::trigger::MakeTriggerSimulationTree::MakeTriggerSimulationTree ( Parameters const & config )

explicit

Definition at line 560 of file MakeTriggerSimulationTree_module.cc.

   : art::EDAnalyzer(config)
   // persistent configuration
   , fBeamGateDuration     (config().BeamGateDuration())
   , fBeamGateStart        (config().BeamGateStart())
   , fPreSpillWindow       (config().PreSpillWindow())
   , fPreSpillStart
       (fBeamGateStart - config().PreSpillWindowGap() - fPreSpillWindow)
   , fTriggerGatesTag(config().TriggerGatesTag())
   , fLogCategory(config().LogCategory())
   // setup
   , fGeom(*lar::providerFrom<geo::Geometry>())
   // other data
   , fIDTree(*(art::ServiceHandle<art::TFileService>()
       ->make<TTree>(config().EventTreeName().c_str(), "Event information")
       ))
   , fEventTree(fIDTree.tree())
   , fTriggerGateTree(fIDTree.tree())
   , fEventInfoExtractorMaker(
     config().GeneratorTags(),              // truthTags
     makeEdepTag(config().EnergyDepositTags, config().EnergyDepositSummaryTag),
                                            // edepTags
     fGeom,                                 // geom
     nullptr,                               // detProps
     nullptr,                               // detTimings
     fLogCategory,                          // logCategory
     consumesCollector()                    // consumesCollector
     )
 {
   
   //
   // declaration of further input (more is by `fEventInfoExtractorMaker`)
   //
   
   // none so far
   
 } // icarus::trigger::MakeTriggerSimulationTree::MakeTriggerSimulationTree()

icarus::trigger::MakeTriggerSimulationTree::MakeTriggerSimulationTree ( MakeTriggerSimulationTree const & )

delete

icarus::trigger::MakeTriggerSimulationTree::MakeTriggerSimulationTree ( MakeTriggerSimulationTree && )

delete

Member Function Documentation

void icarus::trigger::MakeTriggerSimulationTree::analyze ( art::Event const & event )

overridevirtual

Fills the plots. Also extracts the information to fill them with.

Definition at line 601 of file MakeTriggerSimulationTree_module.cc.

 {
   
   // we need to convert the two relevant gates with the proper parameters
   detinfo::DetectorTimings const detTimings
     = icarus::ns::util::makeDetTimings(event);
   
   auto const beamGate = icarus::trigger::makeBeamGateStruct
     (detTimings, fBeamGateDuration, fBeamGateStart);
   
   if (auto oldGate = fBeamGateChangeCheck(beamGate); oldGate) {
     MF_LOG_DEBUG(fLogCategory)
       << "Beam gate has changed from " << oldGate->asOptTickRange()
       << " to " << beamGate.asOptTickRange() << " (optical tick)!";
   }
   
   details::EventInfo_t const eventInfo = fEventInfoExtractorMaker(
     beamGate.asSimulationRange(),
     icarus::trigger::makeBeamGateStruct
       (detTimings, fPreSpillStart, fPreSpillStart + fPreSpillWindow)
       .asSimulationRange()
     )(event);
   
   TriggerGatesInfo const triggerInfo = extractTriggerInfo(event, detTimings);
   
   mf::LogDebug(fLogCategory) << event.id() << " trigger info: " << triggerInfo;
   
   fIDTree.assignID(event.id());
   if (fEventTree) fEventTree->assignEvent(eventInfo);
   if (fTriggerGateTree) fTriggerGateTree->assignTriggerGatesInfo(triggerInfo);
   
   fIDTree.tree().Fill();
   
 } // icarus::trigger::MakeTriggerSimulationTree::analyze()

TriggerGatesInfo icarus::trigger::MakeTriggerSimulationTree::extractTriggerInfo	(	art::Event const &	event,
		detinfo::DetectorTimings const &	detTimings
	)		const

private

Returns a TriggerGatesInfo with trigger information for the tree.

Parameters

event	the art event where to find the trigger gates
detTimings	detector timings updated for this event

Returns: a TriggerGatesInfo with trigger information for the tree

Information from the trigger gates configured in the module is extracted and stored into a TriggerGatesInfo object, which is returned. The data fields are defined as follows:

a TriggerGateInfo element is stored in TriggerGatesInfo::info for each and every trigger gate in the input, in the same order as the input data product;
for each gate:
- TriggerGateInfo::center: for each channel associated to the trigger gate, the geometric center of the optical detector connected to that channel is taken; center is set to the middle point (unweighted 3D centroid) of all those points; the center is in world coordinates and in centimeters;it is assumed that the trigger gate is associated to at least one channel, otherwise behavior is undefined;
- TriggerGateInfo::nOpenings: the number of times in coincidence with the beam gate, when the gate changes state from closed (opening level 0) to open (opening level 1 or larger);
- TriggerGateInfo::firstOpenTime: the time the first of the openings (as defined in nOpenings) happens; the time is in simulation time scale; if there was no opening during the beam gate (nOpenings zero), the value is undefined;
- 'TriggerGateInfo::Amplitude': the amplitude of the PMT

Definition at line 639 of file MakeTriggerSimulationTree_module.cc.

 {
   /*
    * 1. get the data product from the event
    * 2. fill one "channel" of `TriggerGateInfo` per entry in the data product
    *   1. get centroid of associated detectors
    *   2. find and convert to `simulation_time` the first opening
    *   3. find the number of openings
    *   4. find the amplitude
    *   4. fill the information
    * 
    */
   
   using detinfo::timescales::optical_tick;
   using icarus::trigger::OpticalTriggerGateData_t;
   
   //
   // 0. construct the beam gate for this event
   //
   auto const beamGate = icarus::trigger::BeamGateMaker{ detTimings }
     .make(fBeamGateDuration, fBeamGateStart);
   
   //
   // 1. get the data product from the event
   //
   auto const& gates
     = event.getProduct<std::vector<OpticalTriggerGateData_t>>(fTriggerGatesTag);
   
   //
   // 2. fill one "channel" of `TriggerGateInfo` per entry in the data product
   //
   TriggerGatesInfo info;
   
   unsigned int nOpenChannels = 0U; // count for debugging message
   for (OpticalTriggerGateData_t const& gate: gates) {
     
     // the gate, in coincidence with the beam gate:
     auto const beamAndGate = OpticalTriggerGateData_t::Mul(gate, beamGate);
     
     //
     // 2.2. find and convert to `simulation_time` the first opening
     //
     OpticalTriggerGateData_t::ClockTick_t const firstOpenTick
       = beamAndGate.findOpen();
     
     //
     // 2.3. find the number of openings
     //
     unsigned int nOpenings = 0U;
     OpticalTriggerGateData_t::ClockTick_t openTick = firstOpenTick;
     while (openTick != OpticalTriggerGateData_t::MaxTick) {
       ++nOpenings;
       // move out of this open region, then find the next one
       openTick = beamAndGate.findClose(1U, openTick);
       openTick = beamAndGate.findOpen(1U, openTick);
     } // while
     if (nOpenings > 0) ++nOpenChannels;
     
     //
     // 2.4. fill the information
     //
     info.TriggerGates.push_back({
       gateChannelCentroid(gate), // 2.1. get centroid of associated detectors
       nOpenings,
         // users should ignore this if `nOpenings == 0`:
       (nOpenings == 0U)
         ? std::numeric_limits<simulation_time>::max() //std::numeric_limits<T>::max Returns the maximum finite value representable by the 
                                                       //numeric type T. Meaningful for all bounded types.
         : detTimings.toSimulationTime
           (detinfo::timescales::optical_tick{ firstOpenTick })
        //,amplitude
       });
     
   } // for all gates
   
   mf::LogTrace(fLogCategory)
     << "Information from '" << fTriggerGatesTag.encode() << "' ("
     << gates.size() << " trigger gates, " << nOpenChannels
     << " channels) written to tree."
     ;
   
   return info;
 } // icarus::trigger::MakeTriggerSimulationTree::extractTriggerInfo()

geo::Point_t icarus::trigger::MakeTriggerSimulationTree::gateChannelCentroid ( icarus::trigger::OpticalTriggerGateData_t const & gate ) const

private

Returns the centroid (middle point) of all the centers of optical detectors contributing to the specified gate, in world coordinates [cm]

Definition at line 726 of file MakeTriggerSimulationTree_module.cc.

 {
   
   geo::vect::MiddlePointAccumulator centroid;
   
   for (auto const channel: gate.channels()) {
     
     try {
       centroid.add(fGeom.OpDetGeoFromOpChannel(channel).GetCenter());
     }
     catch (cet::exception const& e) {
       throw cet::exception("MakeTriggerSimulationTree", "", e)
         << "Error while accessing position of optical detector with channel "
         << channel << "\n";
     }
     
   } // for
   
   return centroid.middlePoint();
   
 } // icarus::trigger::MakeTriggerSimulationTree::gateChannelCentroid()

icarus::trigger::details::EventInfoExtractor::EDepTags_t icarus::trigger::MakeTriggerSimulationTree::makeEdepTag	(	fhicl::OptionalSequence< art::InputTag > const &	EnergyDepositTags,
		fhicl::OptionalAtom< art::InputTag > const &	EnergyDepositSummaryTag
	)

staticprivate

Creates a EDepTags_t from two optional parameters.

Definition at line 751 of file MakeTriggerSimulationTree_module.cc.

   {
   
   if (EnergyDepositSummaryTag.hasValue()) {
     if (EnergyDepositTags.hasValue()) {
       throw art::Exception(art::errors::Configuration)
         << "MakeTriggerSimulationTree: "
         << "both EnergyDepositTags and EnergyDepositSummaryTag "
         << "have been specified, but they are exclusive: @erase one.\n";
     }
     
     art::InputTag tag;
     EnergyDepositSummaryTag(tag);
     return { 
       icarus::trigger::details::EventInfoExtractor::SimEnergyDepositSummaryInputTag
         { tag }
       };
   }
   else {
     
     std::vector<art::InputTag> tags;
     if (!EnergyDepositTags(tags)) tags.push_back("largeant:TPCActive");
     return { std::move(tags) };
     
   }
   
 } // icarus::trigger::MakeTriggerSimulationTree::makeEdepTag()