Track Score standard handlers¶

This page lists handlers related to clusters of hits found on the signal from various types of detectors. Instances of na64dp::event::APVCluster, na64dp::event::StwTDCHit, etc. are grouped into an item named here a :cpp:class:na64dp::event::TrackScore for further treatment in track reconstruction procedures. A track is defined as a composition of track scores – instances of a special class of assotiation objects referring to a particular hit or set of hits. One can also think on track score as on something more commonly named track point or spatial point (yet, it is usually not a point geometrically – it can be line, line segment, a surface, volume, etc).

Note

Conception of event object model (track and track scores are the subject of this model) in more abstract terms is described in Event object model section of key concepts chapter.

This section is focused on score creation topic. Namely, NA64sw delibirately foresees multiple ways to create a score since there is a plethora of various detector entities that should contribute into the tracking in some form (APV clusters, hodoscopic hits, time-dependent ambigious drift detector measurements, etc even shower centers in calorimeters).

Important

Essentially, a score object itself provides the tracking procedures with a common and uniform interface to all these data, in terms of spatial primitive and corresponding uncertainties.

Current API foresees score created in the following ways:

So-called “ad-hoc handlers” fully comprises score creation out of event object, with minimal intermediate C++ API.
Score created from a single hit (e.g. APV cluster)
Score created from combination of hits or other scores (combined or geometrically conjugated)

Last two ways are interconnected – for instance, same procedure of reconstructing geometrical information from single hit is useful also in the latter case.

Besides of ad-hoc score-creation procedures that are usually individual for a certain detector type, there is a generic way to combine layered detectors with minimal effort (however its C++ API is really tedious, see Hits combining).

Subject: track score struct¶

All the handlers listed below operate with the instances of the TrackScore C/C++ structure that is defined as a subclass hits collection:

struct TrackScore¶

A particle hit point representation.

Track score is a helper object representing set of ra measurement (or set of raw measurements) bound together to represent a spatial item that can become a subject of track fitting.

Keeps references to raw measurements (hits) together with DRS-normalized coordinates and uncertainties.

GETTER:

getter for field TrackScore::hitRefs disabled
getter for field TrackScore::lR disabled
getter for field TrackScore::gR disabled
getter for field TrackScore::lRErr disabled
driftFts.distance – Estimated distance, cm (propagated from driftFts:DriftDetScoreFeatures, returns distance)
driftFts.distanceError – Error of distance estimation, cm (propagated from driftFts:DriftDetScoreFeatures, returns distanceError)
driftFts.maxDistance – max distance (cm) from the wire; typically a wire’s stride (propagated from driftFts:DriftDetScoreFeatures, returns maxDistance)
driftFts.sideHitUError – unbiased error on other side of isochrone (propagated from driftFts:DriftDetScoreFeatures, returns sideHitUError)
driftFts.sideHitBError – biased error on other side of isochrone (propagated from driftFts:DriftDetScoreFeatures, returns sideHitBError)
driftFts.sideWeight – tracking weight of other side isochrone (propagated from driftFts:DriftDetScoreFeatures, returns sideWeight)
time – Hit time, global to event (averaged on hits or provided by MC)
mcTruth.geant4TrackID – (only for MC) Geant4 track ID for this score (propagated from mcTruth:MCTrueTrackScore, returns geant4TrackID)
u – Local U of the measurement
v – Local V of the measurement
w – Local W of the measurement
uE – Local uncertainty by U of the measurement
vE – Local uncertainty by V of the measurement
wE – Local uncertainty by W of the measurement

Public Functions

TrackScore(LocalMemory&)¶: A ctr, needs the pool allocator instance to be bound with.

Public Members

MapTraits<DetID, std::variant<std::monostate, mem::Ref<APVCluster>, mem::Ref<StwTDCHit>, mem::Ref<CaloHit>, mem::Ref<F1Hit>, mem::Ref<TrackScore>>, MapTag::sparse_ambig, NA64SW_EVMALLOC_STRATEGY>::type hitRefs¶: Collection of hits this score is built from.

float lR[3]¶: Local track (point) coordinates, up to three: u, v, w, normalized to (-0.5/0.5)

float gR[3]¶: Assumed global coordinates of track point, MRS: x, y, z, [cm].

float lRErr[3]¶: Local track uncertainties, up to three: u, v, w, normalized.

mem::Ref<DriftDetScoreFeatures> driftFts¶: Supplementary data for drift detectors.

float time¶: Hit time, global to event (averaged on hits or provided by MC)

mem::Ref<MCTrueTrackScore> mcTruth¶: Monte-Carlo true values.

Note

na64dp::event::TrackScore sometimes may have its underlying hits collections empty for certain data sources (like Monte-Carlo data).

Handlers list¶

This handlers deal with TrackScore.

group track-score-handlers

template<typename HitT> class CreateTrackScores : public na64dp::AbstractHitHandler<HitT>, public na64dp::handlers::CombinedSubScoreProducer<HitT>¶

#include <createScore.hh>

Creates track scores based on detector digits.

Combines geametrical information and measurements of the detector into TrackScore — these objects are supposed then to be used by various track pre-selection and/or track reconstruction routines.

This handler is responsible for creation of simplest-possible (elementary) scores that are not combined (conjugated) from projections, i.e. one hit/cluster item should be converted to a single score.

- _type: CreateScores
  # hit type name; str, required
  subject: ...

This class is somewhat versatile track scores creator. It is extensible via template CombinedSubScoreProducer traits.

Public Functions

inline virtual bool process_hit(EventID eventID, typename AbstractHitHandler<HitT>::HitKey hk, HitT &hit) override¶

Creates track score for certain hit type.

Forwards execution to corresponding traits trying to instantiate the track score using cache and binds the score with hit.

inline virtual void finalize() override¶: Prints the information of faulty planes at the end of data processing.

template<typename RuleT> class ConjugateHits : public na64dp::AbstractHitHandler<RuleT::HitType>, protected RuleT, public na64dp::handlers::CombinedSubScoreProducer<RuleT::HitType>¶

#include <createScore.hh>

Template implementation for rule-based hit conjugation handler.

A generic handler that needs to be parameterised with rule class to generate handler for hit conjugation.

Usage (common part):

- _type: CreateScores
  # Defines the rule and subject; str, required
  subject: ...
  # Wether (and how) to combine hits; str, optional
  combinationRule: ...
  # prevents enables units conversion for certain detectors (usually,
  # wire units to metric)
  convertUnits: true
  # hit selection expression; optional, str
  applyTo: null
  # defines logging category; optional, str
  loggingCategory: "handlers.conjugate"
  # defines naming info subclass; optional, str
  detectorNamingCategory: "default"
  # ... other arguments, specific to particular subject

The handler relies on the presence of 1D cluster/hit objects in the event structure that were previously being added with clustering handler (like APVFindClusters). If combinationRule is not set or set to null, no combination/conjugation will be performed for hits, a score will be created for every “hit” of the subject. Otherwise, various n-tuplets are supported by handler:

doublets — simple conjugation rule for two-layered APV detectors.
quadruplets — complex conjugation rule for four-layered Sraw detectors

For non-null combinationRule there are different ways to treat hits:

Scores can be created one-per-hit. This way doublets will cause two scores created within the event. This mode is useful when conjugation rule provides some hit discrimination logic, so hits that, say, have no paired ones won’t be considered in track finding/fitting.
One score per every hit is created and unified within some extra, “owning” score. Say for two-layered wire detector, two 1-dimensional scores are created and subjugated to some third 2-dimensional score.
One score is created per entire n-tuplet.

Parameter controlling the mode of scores creation is called mode and can be of following variants: “perHit” (1), “subScores” (2) and “singular” (3).

../_images/mm4.png

convertUnits option might be used to prevent handler from converting internal detector’s units of cluster or hit (usually, wires) into length (cm). Might be useful for certain types of debug, but generally handlers assumes corresponding fields of track scores to be in length untis (so careless usage of this option may cause severe mistake).

Todo:: ”applyTo” (only detectors) is currently being ignored

Hits combining¶

Basic idea of combining the hits is following:

certain hit combination rule yields lightweight stateful generators providing user code with iterable set of permitted combinations.

A rule instance is a stateful object as well; its lifecycle implies filling it with a series of hits, (optionally) extraction with generator and re-setting.

Base class for hit combination rule is na64dp::util::iHitCombinationRule whose hits_generator() method should create subclasses of na64dp::util::iCombinedHitsGenerator. It exposes consider_hit() method to collect hits and reset() to drop the collection.

All the subsequent machinery is based on this simple idea. For instance:

na64dp::util::iPerStationHitCombinationRule rule subclass implements the rule in a most common way: as n-layered station yielding combined scores as cartesian product. This is still an interface meaning that what shall be included in a station should be decided by subclass.

na64dp::util::DSuLHitCombinationRule is based on per-station rule, but adds support to on/off particular planes implementing per-station so that it relies on detector ID semantics (see Detectors naming)

na64dp::util::TwoLayerScoreCombinationRule involves geometrical information to produce scores for two-layered detectors

Then, there are some templated handlers based on the rules implemented:

na64dp::handlers::CreateTrackScores is most primitive one designed for direct association of the hits with simple scores using primitive traits.

na64dp::handlers::ConjugateHits is more elaborated one benefitting from rules.

For pipeline configuration both C++ classes are available under single configuration: _type: CreateScores, however their sets of parameters differ (see corresponding references).

Important

Key difference between na64dp::handlers::CreateTrackScores and na64dp::handlers::ConjugateHits is that the former one does not need the conjugation conjugation rule while second one requires it.

Combination/conjugation routines frequently use the traits, so one cas think on traits as a base implementation for more generic reentrant rule(s): introducing new hit type for custom detector and custom (local) geometry would require only basic definitions in traits while combination of them immediately becomes available by means of rules.

From API point of view both generic implementations exploit rules via partial template specialization na64dp::handlers::CombinedSubScoreProducer shim which interfaces traits struct na64dp::aux::TrackScoreTraits together with relevant geometry informaton in order to perform scores creation. Detailed relation is considered at section .

group track-combining-hits

Functions

static std::shared_ptr<iCombinedHitsGenerator<HitRefT, NT>> construct_basic_cartesian_generator(StationKey, const std::array<Hits, NT>&, const iPerStationHitCombinationRule<HitRefT, NT>&)¶

Default ctr for N-tuplet product

See CartesianProduct.

template<> struct TrackScoreTraits<event::APVCluster>¶

#include <apvConjugate.hh>

Specialization for 1D scores creation.

Creates one dimensional TrackScore based on APVCluster. Used for “1D hits” provided by single strip detector plane.

Created score contains only first lR and lRErr, normalized to detecto size.

class TwoLayerAPVCombinationRule : public na64dp::util::DSuLHitCombinationRule<2, event::APVCluster>, public na64dp::util::Observable<T>::iObserver¶

#include <apvConjugate.hh>

Hit conjugation rule for APV detectors.

This is an utility class that may be used in various contexts to combine and conjugate APV clusters providing 1D measurement of track intersection point into 2D point in DRS or 3D MRS.

Assumes two-layered detector, each layer measuring one coordinate of the hit. Layers define affine transform (see util::Transformation). This class finds the POCA following geometrical assumptions:

Each plane define a pair ( \(n=1,2\)) of skew lines of the form: \([ \vec{v}_n * m_n + \vec{r}_{0,n} = \vec{l}_n. \)]
here \(\vec{v}_n\) is the 2nd vector of local basis.
and \(\vec{r}_{0,n} = m_n \vec{u}_n\) where \(m_{1,2}\) — normalized local (measured) coordinates.

Then, mid (mutual POCA) for both \(\vec{l}_{1,2}\) assumed to be a result of two scores combination.

class FourLayerStrawCombinationRule : public na64dp::util::DSuLHitCombinationRule<4, event::StwTDCHit>¶

#include <strawConjugate.hh>

Hit conjugation rule for straw detectors.

Assumes four-layered detector with X1&X2 and Y1&Y2 set of paired layers.

template<typename HitT> class CombinedSubScoreProducer<HitT, false>¶: #include <createScore.hh>

Partial implementation stub for conjugated handler that can not produce scores based on individual detector entity hit

template<typename HitT> class CombinedSubScoreProducer<HitT, true> : public na64dp::util::Observable<T>::iObserver, protected na64dp::calib::Handle<nameutils::DetectorNaming>¶

#include <createScore.hh>

Partial implementation for handler producing scores based on individual detector entity hit.

This partial specialization represents certain placements subscription. Its make_score() method forwards execution to TrackScoreTraits::create() method to create a score directly from a hit of certain type with relevant placement information.

This specialization is used for hit types with aux::TrackScoreTraits fully defined.

Needs to be parameterised with external selector to filter placements updates.

class TwoLayerScoreCombinationRule : public na64dp::util::DSuLHitCombinationRule<2, event::TrackScore>, public na64dp::calib::SetupGeometryCache¶

#include <createScore.hh>

Generic rule combining two 1D scores into one 2D (into a spatial point)

This is pretty generic rule to combine two 1D scores into a spatial point, a very common case (e.g. two-layered strip detectors).

Uses na64sw_projected_lines_intersection() to derive the pseudo-intersection point of two lines defined by 1D hits. This spatial point then defines a new score.

Todo:: Sight vector parameter can be of use here.

template<typename HitRefT, Arity_t NT> struct iCombinedHitsGenerator¶

#include <conjugationRule.hh>

Generator producing hits combinations.

The represents a state to iterate over set of combined hits of certain unit (usually, a station composed from few layers).

Subclassed by na64dp::util::iPerStationHitCombinationRule< HitRefT, NT >::BaseCartesianGenerator

template<typename HitRefT, typename CollectionIDT, Arity_t NT> struct iHitCombinationRule¶

#include <conjugationRule.hh>

A rule maintaining collections of hits.

A rule essentially defines how to consider the hits and iterate over combinations of them. Defines a method to produce a sequence generator (see iCombinedHitsGenerator).

Has three-staged lifecycle:

filling it with consider_hit()
(optionally) retrieving combinations of hits with hits_generator()
Emptying collected hits with reset()

This interface also exposes methods to conjugate hits geometrically into local (detector) reference system and global (main) reference system with calc_score_values() method.

template<typename HitRefT, util::Arity_t NT> class iPerStationHitCombinationRule : public na64dp::util::iHitCombinationRule<HitRefT, StationKey, NT>¶

#include <conjugationRule.hh>

Template implementation to collect n-tuplets of hits per station.

This is probably most common case of hits conjugation rule. Assumes station with N layers so that hit on each layer can be part of the combined spatial point. How exactly multiple hits should be combined is defined by subclasses, but certain features are constrained at the level of this class’ utilities.

At this level a rule should be parameterised by number of layers (template parameter), and the Generator constructor class (factory). Generator instance is used to iterate over hits combinations and is customizable.

Interface of rule at this level is defined by _check_plane_id() that may select stations by ID and _n_set() which is responsible for choosing n-th set (returns layer number) of hits to provide a cartesian product (by overriding hits_generator()).

iHitCombinationRule::hits_generator() is implemented to delegate generator construction to per-station generator constructor.

Note

to utilize cartesian generator for partial combinations, consider adding “empty” valued items into the set.

template<util::Arity_t NT, typename HitT> class DSuLHitCombinationRule : public na64dp::util::iPerStationHitCombinationRule<std::pair<bool, event::Association<event::Event, HitT>::Collection::iterator>, NT>, public na64dp::SelectiveHitHandler<HitT>¶

#include <DSuLConjugationRule.hh>

Hit conjugation rule based on DSuL.

Implements hit-selection interface of iPerStationHitCombinationRule to use DSuL-based detector-selection mechanism. Parameterised with (input) hit type.