icarus::trigger::SlidingWindowPatternAlg Class Reference

Applies sliding window patterns to discriminated waveforms. More...

#include <SlidingWindowPatternAlg.h>

Inheritance diagram for icarus::trigger::SlidingWindowPatternAlg:

Classes
struct	AllTriggerInfo_t
	Complete information from this algorithm, standard + non-standard (extra). More...
struct	MoreInfo_t
	Additional information on the trigger. More...
struct	WindowTriggerInfo_t
	Data structure to communicate internally a trigger response. More...

Public Types
using	TriggerInfo_t = icarus::trigger::details::TriggerInfo_t
	Record of the trigger response. More...
using	InputTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate< sbn::OpDetWaveformMeta >
	Type of trigger gate provided as input. More...
using	TriggerGates_t = std::vector< InputTriggerGate_t >
	A list of trigger gates from input. More...
using	TriggerGateData_t = icarus::trigger::OpticalTriggerGateData_t
	Type of gate data without channel information (gate levels only). More...
using	WindowTopology_t = icarus::trigger::WindowChannelMap
	Type holding information about composition and topology of all windows. More...
using	WindowPattern_t = icarus::trigger::WindowPattern
	Type representing the requirement pattern for a window. More...

Public Member Functions
	SlidingWindowPatternAlg (WindowTopology_t windowTopology, WindowPattern_t windowPattern, icarus::trigger::ApplyBeamGateClass beamGate, std::string const &logCategory="SlidingWindowPatternAlg")
	Constructor: configures window topology and times. More...
	SlidingWindowPatternAlg (WindowTopology_t windowTopology, WindowPattern_t windowPattern, std::string const &logCategory="SlidingWindowPatternAlg")
	Constructor: configures window topology and times. More...
AllTriggerInfo_t	simulateResponse (TriggerGates_t const &gates) const
	Returns the trigger response from the specified gates. More...
TriggerGates_t	applyBeamGate (TriggerGates_t const &gates) const
	Returns a new collection of gates, set each in coincidence with beam gate. More...
bool	hasBeamGate () const
	Returns whether a beam gate is being applied. More...
void	setBeamGate (icarus::trigger::ApplyBeamGateClass beamGate)
	Changes the beam gate to the specified value. More...
void	clearBeamGate ()
	Do not apply any beam gate. More...
TriggerInfo_t	applyWindowPattern (WindowTopology_t::WindowInfo_t const &windowInfo, WindowPattern_t const &pattern, TriggerGates_t const &gates) const
	Returns the trigger response for the specified window pattern. More...
Public Member Functions inherited from icarus::ns::util::mfLoggingClass
	mfLoggingClass (std::string const &logCategory)
	Constructor: initializes with the specified log category. More...
std::string	logCategory () const
	Returns the logging category string for this object. More...
mfLoggingClass const &	loggingClass () const
	Returns this object (as a logging class object). More...
mf::LogError	mfLogError (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogError() stream for logging. More...
mf::LogWarning	mfLogWarning (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogWarning() stream for logging. More...
mf::LogProblem	mfLogProblem (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogProblem() stream for logging. More...
mf::LogInfo	mfLogInfo (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogInfo() stream for logging. More...
mf::LogVerbatim	mfLogVerbatim (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogVerbatim() stream for logging. More...
mf::LogDebug	mfLogDebug (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogDebug() stream for logging. More...
mf::LogTrace	mfLogTrace (std::string const &file={}, int const lineNumber=0) const
	Returns a mf::LogTrace() stream for logging. More...

Private Member Functions
TriggerInfo_t	applyWindowPattern (WindowPattern_t const &pattern, std::size_t iWindow, TriggerGates_t const &gates) const
	Returns the trigger response for the specified window pattern. More...
void	verifyInputTopology (TriggerGates_t const &gates) const
	Checks gates are compatible with the current window configuration. More...

Private Attributes
WindowTopology_t const	fWindowTopology
	Definition of the neighborhood of each window in terms of window indices. More...
WindowPattern_t const	fWindowPattern
	Requirement pattern to be applied to each window. More...
std::optional < icarus::trigger::ApplyBeamGateClass const >	fBeamGate
	Time interval when to evaluate the trigger. More...

Detailed Description

Applies sliding window patterns to discriminated waveforms.

This algorithm takes as input one trigger gate for each window. Each window is identified by an index, and the input gates are assigned one per window, in order.

The window mapping that defines the topology of the windows is passed to the algorithm.

If a beam gate is present, it is applied to all input before simulating the pattern. Otherwise, the full input is used.

For the definition of the windows, see icarus::trigger::WindowChannelMap.

Definition at line 51 of file SlidingWindowPatternAlg.h.

Member Typedef Documentation

using icarus::trigger::SlidingWindowPatternAlg::InputTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate<sbn::OpDetWaveformMeta>

Type of trigger gate provided as input.

Definition at line 62 of file SlidingWindowPatternAlg.h.

using icarus::trigger::SlidingWindowPatternAlg::TriggerGateData_t = icarus::trigger::OpticalTriggerGateData_t

Type of gate data without channel information (gate levels only).

Definition at line 68 of file SlidingWindowPatternAlg.h.

using icarus::trigger::SlidingWindowPatternAlg::TriggerGates_t = std::vector<InputTriggerGate_t>

A list of trigger gates from input.

Definition at line 65 of file SlidingWindowPatternAlg.h.

using icarus::trigger::SlidingWindowPatternAlg::TriggerInfo_t = icarus::trigger::details::TriggerInfo_t

Record of the trigger response.

Definition at line 58 of file SlidingWindowPatternAlg.h.

using icarus::trigger::SlidingWindowPatternAlg::WindowPattern_t = icarus::trigger::WindowPattern

Type representing the requirement pattern for a window.

Definition at line 74 of file SlidingWindowPatternAlg.h.

using icarus::trigger::SlidingWindowPatternAlg::WindowTopology_t = icarus::trigger::WindowChannelMap

Type holding information about composition and topology of all windows.

Definition at line 71 of file SlidingWindowPatternAlg.h.

Constructor & Destructor Documentation

icarus::trigger::SlidingWindowPatternAlg::SlidingWindowPatternAlg	(	WindowTopology_t	windowTopology,
		WindowPattern_t	windowPattern,
		icarus::trigger::ApplyBeamGateClass	beamGate,
		std::string const &	logCategory = "SlidingWindowPatternAlg"
	)

Constructor: configures window topology and times.

Parameters

windowTopology	full composition and topology description of windows
windowPattern	the pattern that this algorithm applies
beamGate	object applying the beam gate to trigger gates
logCategory	category tag for algorithm messages on screen

Window topology can be computed with icarus::trigger::WindowTopologyAlg starting from a (complete) set of trigger gates.

A beam gate application class can be constructed via icarus::trigger::makeApplyBeamGate() helper function.

Definition at line 34 of file SlidingWindowPatternAlg.cxx.

  : icarus::ns::util::mfLoggingClass(logCategory)
  , fWindowTopology(std::move(windowTopology))
  , fWindowPattern(std::move(windowPattern))
  , fBeamGate(std::move(beamGate))
  {}

icarus::trigger::SlidingWindowPatternAlg::SlidingWindowPatternAlg	(	WindowTopology_t	windowTopology,
		WindowPattern_t	windowPattern,
		std::string const &	logCategory = "SlidingWindowPatternAlg"
	)

Constructor: configures window topology and times.

Parameters

windowTopology	full composition and topology description of windows
windowPattern	the pattern that this algorithm applies
logCategory	category tag for algorithm messages on screen

Window topology can be computed with icarus::trigger::WindowTopologyAlg starting from a (complete) set of trigger gates.

The beam gate is set to be empty; it must be set before simulating the response (simulateResponse()) via setBeamGate().

Definition at line 48 of file SlidingWindowPatternAlg.cxx.

  : icarus::ns::util::mfLoggingClass(logCategory)
  , fWindowTopology(std::move(windowTopology))
  , fWindowPattern(std::move(windowPattern))
  {}

Member Function Documentation

TriggerGates_t icarus::trigger::SlidingWindowPatternAlg::applyBeamGate

(

TriggerGates_t const &

gates

)

const

Returns a new collection of gates, set each in coincidence with beam gate.

auto icarus::trigger::SlidingWindowPatternAlg::applyWindowPattern	(	WindowTopology_t::WindowInfo_t const &	windowInfo,
		WindowPattern_t const &	pattern,
		TriggerGates_t const &	gates
	)		const

Returns the trigger response for the specified window pattern.

Parameters

windowInfo	the topology of the windows
pattern	the trigger requirement pattern
gates	trigger gates, one per window

Returns

a TriggerInfo_t record with the response of the pattern

The input gates represent all the trigger gates relevant to the trigger determination, in a list by window index: the first gate belongs to the window 0, the second one to the window 1 and so on. The topology windowInfo identifies a window and its topology, i.e. its neighbours, by window index. It is required and assumed that the values of the window indices match the ones in the gates list. This function applies the requirements in the specified pattern to the window identified by windowInfo, using the actual trigger gates from the gates list as needed.

The return value includes the first tick at which the requirements have been all met. Note that if a beam gate needs to be applied, it should be applies to all gates before calling this function (see e.g. applyBeamGate()).

Definition at line 205 of file SlidingWindowPatternAlg.cxx.

{
  
  /*
   * 1. check that the pattern can be applied; if not, return no trigger
   * 2. discriminate all the relevant gates against their required minimum count
   * 3. combine them in AND
   * 4. find the trigger time, fill the trigger information accordingly
   */
  TriggerInfo_t res; // no trigger by default
  assert(!res);
  
  // undress the gate to get its data
  auto const gateAt = [&gates](std::size_t index) -> TriggerGateData_t const&
    { return gateIn(gates[index]); };
  
  //
  // 1. check that the pattern can be applied; if not, return no trigger
  //
  
  // check that the pattern centered into iWindow has all it needs:
  if (pattern.requireUpstreamWindow && !windowInfo.hasUpstreamWindow())
    return res;
  if (pattern.requireDownstreamWindow && !windowInfo.hasDownstreamWindow())
    return res;
  
  
  //
  // 2. discriminate all the relevant gates against their required minimum count
  // 3. combine them in AND
  //
  
  mfLogTrace()
    << "Window info #" << windowInfo.index << " pattern " << pattern.tag();
  
  // we have two different "modes" depending on whether we are constraining
  // the sum of main and opposite window, or not;
  std::optional<TriggerGateData_t> const mainPlusOpposite
    = (pattern.minSumInOppositeWindows > 0U)
    ? std::optional{
      windowInfo.hasOppositeWindow()
        ? sumGates(gateAt(windowInfo.index), gateAt(windowInfo.opposite))
        : gateAt(windowInfo.index)
    }
    : std::nullopt
    ;
  
  // the basic trigger primitive gate has the levels of the main or
  // main+opposite window depending on the requirements
  TriggerGateData_t trigPrimitive
    = mainPlusOpposite? *mainPlusOpposite: gateAt(windowInfo.index);
    
  mfLogTrace() << "  base: " << compactdump(trigPrimitive);
  
  // main window
  if (pattern.minInMainWindow > 0U) {
    trigPrimitive.Mul
      (discriminate(gateAt(windowInfo.index), pattern.minInMainWindow));
    mfLogTrace()
      << "  main >= " << pattern.minInMainWindow << ": "
      << compactdump(trigPrimitive);
  } // if
  
  // add opposite window requirement (if any)
  if ((pattern.minInOppositeWindow > 0U) && windowInfo.hasOppositeWindow()) {
    trigPrimitive.Mul
      (discriminate(gateAt(windowInfo.opposite), pattern.minInOppositeWindow));
    mfLogTrace() << "  opposite [#" << windowInfo.opposite << "]: "
      << compactdump(gateAt(windowInfo.opposite))
      << "\n  => " << compactdump(trigPrimitive);
  } // if
  
  // add main plus opposite window requirement (if any)
  if (pattern.minSumInOppositeWindows > 0U) {
    assert(mainPlusOpposite.has_value());
    trigPrimitive.Mul
      (discriminate(*mainPlusOpposite, pattern.minSumInOppositeWindows));
    mfLogTrace() << "  sum [+ #" << windowInfo.opposite << "]: "
      << compactdump(*mainPlusOpposite)
      << "\n  => " << compactdump(trigPrimitive);
    
  } // if
  
  // add upstream window requirement (if any)
  if ((pattern.minInUpstreamWindow > 0U) && windowInfo.hasUpstreamWindow()) {
    trigPrimitive.Mul
      (discriminate(gateAt(windowInfo.upstream), pattern.minInUpstreamWindow));
  } // if
  
  // add downstream window requirement (if any)
  if ((pattern.minInDownstreamWindow > 0U) && windowInfo.hasDownstreamWindow())
  {
    trigPrimitive.Mul(
      discriminate(gateAt(windowInfo.downstream), pattern.minInDownstreamWindow)
      );
  } // if
  
  mfLogTrace() << "  final: " << compactdump(trigPrimitive);
  
  //
  // 4. find the trigger time, fill the trigger information accordingly
  //
  icarus::trigger::details::GateOpeningInfoExtractor extractOpeningInfo
    { trigPrimitive };

  extractOpeningInfo.setLocation
    (TriggerInfo_t::LocationID_t{ windowInfo.index });

  while (extractOpeningInfo) {
    auto info = extractOpeningInfo();
    if (info) res.add(info.value());
  } // while

  return res;
  
} // icarus::trigger::SlidingWindowTriggerEfficiencyPlots::applyWindowPattern()

auto icarus::trigger::SlidingWindowPatternAlg::applyWindowPattern ( WindowPattern_t const &  pattern, std::size_t  iWindow, TriggerGates_t const &  gates  ) const

private

Returns the trigger response for the specified window pattern.

Parameters

pattern	the trigger requirement pattern
iWindow	index of the window to be tested
gates	trigger gates, one per window

Returns

a TriggerInfo_t record with the response of the pattern

See Also

applyWindowPattern(WindowChannelMap::WindowInfo const&, WindowPattern_t const&, TriggerGates_t const&)

Applies the specified pattern to the window with index iWindow of the configured window topology.

See the static version of applyWindowPattern() for details.

Definition at line 328 of file SlidingWindowPatternAlg.cxx.

{
  WindowTopology_t::WindowInfo_t const& windowInfo
    = fWindowTopology.info(iWindow);
  assert(windowInfo.index == iWindow);
  
  return applyWindowPattern(windowInfo, pattern, gates);
} // icarus::trigger::SlidingWindowTriggerEfficiencyPlots::applyWindowPattern()

void icarus::trigger::SlidingWindowPatternAlg::clearBeamGate

(

)

Do not apply any beam gate.

Definition at line 133 of file SlidingWindowPatternAlg.cxx.

  { fBeamGate.reset(); }

bool icarus::trigger::SlidingWindowPatternAlg::hasBeamGate

(

)

const

Returns whether a beam gate is being applied.

Definition at line 122 of file SlidingWindowPatternAlg.cxx.

  { return fBeamGate.has_value(); }

void icarus::trigger::SlidingWindowPatternAlg::setBeamGate

(

icarus::trigger::ApplyBeamGateClass

beamGate

)

Changes the beam gate to the specified value.

Definition at line 128 of file SlidingWindowPatternAlg.cxx.

  { fBeamGate.emplace(std::move(beamGate)); }

auto icarus::trigger::SlidingWindowPatternAlg::simulateResponse

(

TriggerGates_t const &

gates

)

const

Returns the trigger response from the specified gates.

Parameters

gates

the trigger gates to be used as input, one per window

Returns

the response to the configured pattern

See Also

applyWindowPattern(WindowChannelMap::WindowInfo const&, WindowPattern_t const&, TriggerGates_t const&)

The return value comprises a "standard" TriggerInfo_t object, which stores whether the pattern fired and when, and some extra information, including which window made the trigger fire first (in case of ties, the window with the smallest index is reported).

The list gates must contain a single trigger gate for each window, with the gate index in the list matching the window index in the configured window topology.

See the static version of applyWindowPattern() for more details.

Definition at line 61 of file SlidingWindowPatternAlg.cxx.

{
  
  // ensures input gates are in the same order as the configured windows
  verifyInputTopology(gates);
  
  auto const& inBeamGates = fBeamGate? fBeamGate->applyToAll(gates): gates;
  
  //
  // 2.   apply pattern:
  //
  std::size_t const nWindows = fWindowTopology.nWindows();
    
  //
  // 2.1.   for each main window, apply the pattern
  //
  WindowTriggerInfo_t triggerInfo; // start empty
  for (std::size_t const iWindow: util::counter(nWindows)) {
    
    TriggerInfo_t const windowResponse
      = applyWindowPattern(fWindowPattern, iWindow, inBeamGates);
    
    if (!windowResponse) continue;
    
    assert(windowResponse.hasLocation());
    assert(windowResponse.location() == iWindow);
    if (windowResponse.nTriggers() == 1U) {
      mfLogTrace() << "Pattern fired on window #" << iWindow
        << " at tick " << windowResponse.atTick();
    }
    else {
      std::vector<TriggerInfo_t::OpeningInfo_t> const& triggers
        = windowResponse.all();
      TriggerInfo_t::OpeningInfo_t const* pMain = &(windowResponse.main());
      auto log = mfLogTrace();
      log << "Pattern fired " << triggers.size()
        << " times on window #" << iWindow << ":";
      for (auto const& [ iTrigger, trigger ]: util::enumerate(triggers)) {
        log << " [#" << iTrigger << "] " << " on " << trigger.tick
          << " (";
        if (&trigger == pMain) log << "main; ";
        log << "lvl=" << trigger.level << ")";
      } // for
    }
    
    //
    // 2.2. pick the main window with the earliest successful response, if any;
    //      that defines location and time of the trigger
    //
    if (!triggerInfo || triggerInfo.info.atTick() > windowResponse.atTick()) {
      if (!triggerInfo) mfLogTrace() << "  (new global trigger)";
      triggerInfo.emplace(iWindow, windowResponse);
    }
    
  } // main window choice
  
  return { std::move(triggerInfo.info), MoreInfo_t{ triggerInfo.windowIndex } };
} // icarus::trigger::SlidingWindowPatternAlg::simulateResponse()

void icarus::trigger::SlidingWindowPatternAlg::verifyInputTopology ( TriggerGates_t const &  gates ) const

private

Checks gates are compatible with the current window configuration.

Parameters

gates

the combined sliding window trigger gates, per cryostat

Exceptions

cet::exception

(category: SlidingWindowTriggerEfficiencyPlots) or derived, if an incompatibility is found

The method verifies that the current channel mapping is compatible with the gates.

This currently means that the gates are in the expected order and have the expected channel content.

Definition at line 139 of file SlidingWindowPatternAlg.cxx.

{
  /*
   * Verifies that the `gates` are in the expected order and have
   * the expected channel content.
   */

  std::string errorMsg; // if this stays `empty()` there is no error
  for (auto const& [ iWindow, gate ]: util::enumerate(gates)) {
    
    std::string windowError; // if this stays `empty()` there is no error
    
    // more input gates than windows?
    if (iWindow >= fWindowTopology.nWindows()) {
      windowError = "unexpected input gate #" + std::to_string(iWindow) + " (";
      for (raw::Channel_t const channel: gate.channels())
        windowError += " " + std::to_string(channel);
      windowError += " )";
      errorMsg += windowError + '\n';
      continue; // we collect info of all spurious gates
    }
    
    WindowTopology_t::WindowInfo_t const& windowInfo
      = fWindowTopology.info(iWindow);
    
    auto const channelInWindow
      = [begin=windowInfo.channels.cbegin(),end=windowInfo.channels.cend()]
      (raw::Channel_t channel)
      { return std::binary_search(begin, end, channel); }
      ;
    
    for (raw::Channel_t const channel: gate.channels()) {
      if (channelInWindow(channel)) continue;
      if (windowError.empty()) {
        windowError =
          "channels not in window #" + std::to_string(windowInfo.index)
          + ":";
      } // if first error
      windowError += " " + std::to_string(channel);
    } // for all channels in gate
    
    if (!windowError.empty()) errorMsg += windowError + '\n';
  } // for gates

  // more input gates than windows?
  if (fWindowTopology.nWindows() > size(gates)) {
    errorMsg +=
      "Not enough input gates: " + std::to_string(size(gates)) + " gates for "
      + std::to_string(fWindowTopology.nWindows()) + " windows\n";
  }
  
  if (errorMsg.empty()) return;
  
  // put together the exception message and throw it.
  throw cet::exception("SlidingWindowPatternAlg")
    << "Some channels from trigger gates do not match"
    " the configured window allocation:\n"
    << errorMsg
    << "\n" // empty line
    << "Window configuration: "
    << fWindowTopology << "\n";
  
} // icarus::trigger::SlidingWindowPatternAlg::verifyInputTopology()

Member Data Documentation

std::optional<icarus::trigger::ApplyBeamGateClass const> icarus::trigger::SlidingWindowPatternAlg::fBeamGate

private

Time interval when to evaluate the trigger.

Definition at line 224 of file SlidingWindowPatternAlg.h.

WindowPattern_t const icarus::trigger::SlidingWindowPatternAlg::fWindowPattern

private

Requirement pattern to be applied to each window.

Definition at line 221 of file SlidingWindowPatternAlg.h.

WindowTopology_t const icarus::trigger::SlidingWindowPatternAlg::fWindowTopology

private

Definition of the neighborhood of each window in terms of window indices.

Definition at line 218 of file SlidingWindowPatternAlg.h.

---

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

• SlidingWindowPatternAlg.h
• SlidingWindowPatternAlg.cxx