Skip to content

Track-CRV association data product (TrkCrvMatch) with its MC truth (TrkCrvMatchMC) - #2106

Merged
brownd1978 merged 4 commits into
Mu2e:mainfrom
RobMina:trkcrv-match
Nov 8, 2026
Merged

brownd1978 merged 4 commits into
Mu2e:mainfrom
RobMina:trkcrv-match

Conversation

@RobMina

@RobMina RobMina commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR adds a reco data product that associates each KalSeed with the CRV coincidence clusters compatible with it,
and an MC product that labels those associations by SimParticle identity. Analyses today each make their own
track-CRV match (sector existence, nearest cluster in 3D, fixed time windows, ...). This product gives them one
definition, keeps the full candidate list with residuals, errors and flags, and leaves the selection to the analysis.

No existing module, product or configuration changes. The PR adds new products, two new modules, a matching helper
class, prolog entries, and their dictionary and build entries. Companion PRs: Offline validation histograms
(ValTrkCrvMatch, stacked on this branch), EventNtuple branches with a Python example, and the Production reco wiring.

Changes after review

  • Reference time is the tracker entry: the earliest intersection on TT_Front, TT_Back or TT_Outer
    (EarliestReference). The separate front and mid times are removed from the record; every intersection time is in
    the KalSeed.
  • Covariance: crossings and candidates carry the symmetric 2×2 covariance in the sector plane (TrkCrvPlaneCov,
    error model applied); sigU()/sigV() are accessors, and the χ² uses the full 2×2.
  • Sector frame: trkCrvSectors() (CRVReco/inc/TrkCrvGeom.hh) returns the KinKalGeom rectangle and its u, v, w
    axes per sector; the matcher and the truth module share it and the dominant-shield helper.
  • Truth: candidate relations are MCRelationships (closest over the cluster's deposits, compared with every
    simulation-stage copy of the track's particle), and the record points at the track's KalSeedMC.
  • Fail loudly: the truth module requires its inputs, with CrvSteps optional only through RequireCrvSteps : false
    (recorded as hasDeposits_); TrkCrvMatch::probe_ records which pulses the layer probe saw.
  • Configuration: no C++ defaults for physics settings; every value is in CRVReco/fcl/prolog_v12.fcl with its
    source. DtRefCenter is measured per fit type (below). Fibre speed and pulse delay come from
    CrvCoincidenceClusterFinder.
  • The trajectory crossings in the truth module use KinKal::LineSegment with the rectangle's intersect().

What is added

File Content
RecoDataProducts/inc/TrkCrvMatch.hh TrkCrvMatch (one per KalSeed, same order), TrkCrvXing (one per CRV KalIntersection), TrkCrvCandidate (one per associated cluster)
MCDataProducts/inc/TrkCrvMatchMC.hh TrkCrvMatchMC (one per TrkCrvMatch, same order), TrkCrvXingMC (true sector crossings of the track's particle and its ancestors), TrkCrvCandidateMC (truth relation of each candidate)
CRVReco/inc/TrkCrvMatchTool.hh, CRVReco/src/TrkCrvMatchTool.cc the matching, including the layer probe, as a helper class in the CRVReco library, so that a future fit using CRV clusters as constraints applies the same definition
CRVReco/src/TrkCrvMatcher_module.cc the producer: one TrkCrvMatch per KalSeed, through TrkCrvMatchTool
CRVResponse/src/TrkCrvMatchMCMaker_module.cc the truth producer, with an end-of-job summary of crossing and association truth
CRVReco/inc/TrkCrvPlaneError.hh the track covariance projected onto a plane reached by a straight step, shared by both modules (a stand-in until KinKal provides the projection)
CRVReco/inc/TrkCrvGeom.hh, CRVReco/src/TrkCrvGeom.cc the CRV sector rectangles and axes (trkCrvSectors()) and a cluster's dominant shield, shared by both modules
CRVReco/fcl/prolog_v12.fcl, CRVResponse/fcl/prolog_v12.fcl TrkCrvMatcher and TrkCrvMatchMC tables, every value with its source
CRVReco, CRVResponse CMakeLists.txt and src/SConscript; classes.h, classes_def.xml of both product packages build and dictionary entries (the truth plugin links CRVReco)

How the match works

For each KalSeed, TrkCrvMatcher:

  1. Takes a reference time tRef: the earliest intersection on any of ReferenceSurfaces (default TT_Front,
    TT_Back, TT_Outer), which is the tracker entry for downstream, upstream and cosmic tracks alike; t0 if none is
    present. EarliestReference : false takes the first surface of the list present instead. The surface used is
    stored; on the extracted KKLine sample TT_Outer is present on 99 % of tracks.
  2. Records the track's CRV crossings (CRV KalIntersections): position, direction, time, momentum, and the track
    covariance in the sector plane (u along the bars, v across: the axes of the KinKalGeom sector rectangle). It also
    stores the distance to the sector edge, in mm and in track sigmas.
  3. Keeps every cluster that passes a loose time test or a loose geometric test.
    • Time test: dtRef = tRef − t_cluster inside DtRefWindow.
    • Geometric test: from the track's CRV crossing nearest in path to the cluster's own sector plane, the track is
      projected in a straight line onto that plane. The residuals there are du (along the bars), dv (across) and
      dtXing. The track error is the crossing's full 6×6 covariance carried over the step. A cluster is kept when
      the residuals are inside MaxDu, MaxDv and DtXingWindow.
    • The cluster's sector is its dominant shield (largest PE sum).
    • Projecting from the nearest crossing in any sector, instead of requiring a crossing of the cluster's own
      sector, is what makes the match robust near sector edges and in the 103 mm wide muon taggers (see validation).
  4. Ranks the candidates. Geometric candidates come first, ordered by a space + time χ² with the full 2×2 track
    covariance plus the CRV resolution on the diagonal. For single-ended clusters, which have no along-bar
    measurement, only the across-bar term enters. Time-only candidates follow, ordered by their distance from
    DtRefCenter. The matcher sets bestGeom, bestTime, and a bestInSector flag per cluster sector.
  5. Runs a pass across the tracks of the collection.
    • nShare counts the tracks of the collection that hold the cluster as a candidate.
    • bestForCluster flags the cluster's best track.
    • A greedy one-to-one exclusive assignment runs over the geometric pairs: at most one track per cluster, and one
      cluster per track per sector.

Windows are loose by design (DtRefWindow ±350 ns, MaxDv 500 mm, MaxDu 3 m, DtXingWindow ±100 ns).
KeepAllClusters ignores them for commissioning. TimeOffset is a test knob only: data offsets belong in
conditions (DAQTiming, CRVTime). DoGeometric: false gives a time-only match for fits that do not extrapolate to
the CRV.

Error model:

  • Track: k²C + a²I on the projected 2×2 covariance C, with k = 1.5 and a = 24 mm.
  • CRV across-bar resolution SigmaV: 7, 13, 7 and 17 mm for EX, T1, T2 and the muon taggers. These are sector types
    1-4 of the extracted geometry; other geometries need their own list (the prolog says so).
  • CRV along-bar resolution SigmaU: 300 mm.
  • These are fitted on MC (below) and are configurable. A data fit is a follow-up.

DtRefCenter only centres the time ranking; the window does not move. It is the median dtRef of each track's own
cluster in MC truth, per fit type, set per instance:

Fit Sample Median Set to
KKLine extracted MDC2025bb cosmics 12.6 ns 13 (prolog default)
KKCHmu MDC2025au CosmicSignalOffSpill-CH 27.1 ns 27
KKDe, KKDmu, KKUe, KKUmu MDC2025au CosmicSignalOffSpill-LH 31.7, 30.2, 28.2, 25.8 ns 32, 30, 28, 26

TrkCrvMatchMCMaker gives each candidate the closest MCRelationship between the cluster's deposit particles and the
track's particle (same, daughter, mother, sibling, the u* relations, or none), with the energy from the
particle and from related particles. Multi-stage samples keep one SimParticle copy of the track's particle per
stage, so each deposit is compared with every copy. The module finds the true crossings of each sector's mid-plane
rectangle from MCTrajectories (gap-inclusive) and CrvSteps, and links reco crossings to true ones. It must run with
the simulation geometry. It requires all its inputs; RequireCrvSteps : false lets it run on reco output, which
drops the CrvSteps, and the record says so (hasDeposits_).

Validation

MC: MDC2025bb cosmics (KKLine, extracted v06 geometry), first 50 files, 1,072,232 tracks. This study predates
the review changes; its truth classes map onto the MCRelationship ones as knock-on family → daughter, mother,
sibling and same primary → the u* relations. On file 1 the review build reproduces every geometric association
count (reco crossings, true and fake, found and missed, own cluster as candidate, exclusive and best).

Sector Own cluster is a geometric candidate Crossing purity Crossing efficiency
EX 0.939 0.954 0.944
T1 0.894 0.861 0.866
T2 0.961 0.884 0.890
M1-M8 0.875-0.890 0.41-0.43 0.41-0.44
  • Best geometric candidate: it is the track's own particle in 97.3 % of tracks, knock-on family in 2.3 %, the
    same primary in 0.4 %, and unrelated in 7 tracks. For comparison, the best time-only candidate is the own particle
    in 86.6 % of tracks.
  • Exclusive assignment never takes a track's own cluster away from it: its rate equals the candidate rate in
    every sector.
  • Muon taggers: the low crossing purity is KinKal assigning the crossing to the neighbouring tagger (56 % of the
    fakes). Matching by projection recovers the own cluster in 0.88 of tracks, so analyses should not use CRV_M*
    crossings as a selection.
  • Misalignment: with the CRV 100 mm lower in simulation than in reco, own-cluster association drops by at most
    1.1 points in any sector.
  • Error model: fitted on 438,985 own-cluster matches.
    • Track-only robust pull widths of same-sector matches are 0.90-1.05 in EX, T1 and T2.
    • The taggers are overestimated (0.54-0.76).
    • Matches projected from another sector are underestimated (1.7-2.8). Those are the poorly measured tracks; a
      scale that depends on fit quality is a possible refinement.
  • SigmaV per sector type against a flat 40 mm: on the same 50 files, every association count is identical,
    and one track's best candidate changes truth class (SameFamily to SamePrimary). Only the χ² scale moves: the mean
    χ²/ndof of own-cluster candidates goes from about 1.4 to about 3, from tails, while the robust pulls are near 1.

Data: CRT combined run 125472, file 12 (27,142 events, PassN Combined_Pass1, KPP_reco conditions, v06).

  • The matcher runs in data mode with no MC module and default settings.

  • 8,408 KKLine tracks; 2,078 have CRV crossings, and 1,721 of those have a geometric candidate.

  • Residuals of the best geometric candidate, first 5,000 events (medians with their errors; dv is cluster − track
    across the bars):

    Sector type tracks dtXing data dtXing MC dv data dv MC
    EX 270 +0.13 ± 0.14 ns −0.40 ± 0.11 ns −14.6 ± 4.5 mm +0.8 ± 1.5 mm
    T1 38 +2.0 ± 0.9 ns +4.5 ± 0.5 ns −1 ± 11 mm −2 ± 6 mm
    T2 23 +1.1 ± 0.6 ns +0.7 ± 0.3 ns −9 ± 9 mm +2 ± 4 mm

    The time residuals are centred within a few ns with no tuned offset. The T1 offset is also in MC: its clusters are
    single-ended, so their time is not corrected for the light propagation. The EX dv offset in data is consistent
    with the tracker-CRV offset seen in the alignment studies; the matcher measures it and does not absorb it. The
    layer probe sees the same direction: in EX and T2, data finds the pulse one bar to one side 1.4-1.9 times as
    often as on the other, in all four layers, while MC is symmetric.

CPU: 0.16 ms/event on average for the matcher on the CRT file (median 0.08 ms), against 13 ms/event for the
reco.

I/O: both products are written and read back. The truth module has also run in a separate job on the matcher's
output file.

Several KalSeed collections in one job (OnSpill). SelectRecoMC writes one KalSeedMCAssns over every KalSeed
collection, so the truth module looks a track up by collection and index.

  • Mock data: the four time-only LoopHelix matchers (KKDe, KKUe, KKDmu, KKUmu) and their truth ran on one
    MDC2025au OnSpill mock-data file (9,905 events, about 7,500-8,100 tracks per collection). Every track of every
    collection has MC. The best time candidate is the track's own particle for 1,753-1,960 tracks per collection; the
    others are mostly tracks whose particle never reaches the CRV.
  • Production: recoMC/OnSpill.fcl from MDC2025au digis schedules the same four matchers and truth modules, and
    writes both products (200 events).

No change to existing output: no existing module, product or default configuration changes.

Layer probe (LayerProbe, default on). For each crossed sector, the track's straight line is followed through
every layer. The probe records the predicted bar and the best pulse within ProbeBarWindow bars whose time,
corrected for fibre propagation and the electronics delay, falls in ProbeDtWindow. Per layer it stores the bar
offset, time difference, PEs, whether the pulse is in a cluster, and the position along the bar from the two-end time
difference. It reads the full CrvRecoPulses, which production does not persist, so it runs inside the reco job.
The PEs are stored because an unclustered pulse exists nowhere else after reco. probe_ records what the probe
saw: off, no pulse collection (predicted bars only, with a warning), clustered pulses only, or all pulses.

usedInFit. The matcher reads an optional UsedInFitAssns (art::Assns<KalSeed, CrvCoincidenceCluster>, empty by
default) of the clusters each fit used as constraints, and flags those candidates, whose residuals are biased.

Truth back-pointers. Each TrkCrvMatchMC holds an art::Ptr to its TrkCrvMatch and to the track's KalSeedMC.

Why Ptrs and not an Assns: most of the payload is per track (crossings, probe, reference time, best indices),
one record per KalSeed in KalSeed order follows KalSeedDtDt and MVAResult, and the many-to-many relation is in
the records (nShare, bestForCluster, exclusive). An Assns view can be derived from them if wanted.

Not in this PR (follow-ups)

  • Print/ support for both products.
  • An Assns view derived from the records, if FindMany from the cluster side is wanted.
  • SigmaV keyed by sector name instead of sector type, for geometries other than the extracted one.
  • The error model on data, and a fit-quality-dependent scale for matches projected from another sector.
  • DtRefCenter on field-on CE + mix samples (the values here are from cosmics).
  • Storage-window completeness (≥ 99.9 % of true matches) with the CRV misaligned, and a dedicated multi-track
    sample for the cross-track pass.

Questions for reviewers

  1. Where the CRV resolutions and any time offsets live: FHiCL, as here, or conditions?
  2. Product layout: public members with trailing underscores and a few accessors, as here, or full accessors?
  3. Blinding: if a stream strips CRV clusters, this product must be stripped with it, or its Ptrs dangle.

How to run

One matcher per KalSeed collection, after SelectReco, from the prolog tables (CRVReco and CRVResponse
prolog.fcl). The truth module needs the simulation geometry and runs after compressRecoMCs and
CrvCoincidenceClusterMCAssns:

#include "Offline/CRVReco/fcl/prolog.fcl"
#include "Offline/CRVResponse/fcl/prolog.fcl"
physics.producers.TrkCrvMatchLine   : { @table::TrkCrvMatcher KalSeedCollection : "KKLine" }
physics.producers.TrkCrvMatchDe     : { @table::TrkCrvMatcher KalSeedCollection : "KKDe" DtRefCenter : 32 DoGeometric : false LayerProbe : false }
physics.producers.TrkCrvMatchLineMC : { @table::TrkCrvMatchMC TrkCrvMatchCollection : "TrkCrvMatchLine" }

LoopHelix fits do not reach the CRV, so their matchers are time only. The Production companion PR schedules these in
the standard reco paths, and the EventNtuple one runs them on existing reco files.

🤖 Generated with Claude Code

@FNALbuild

Copy link
Copy Markdown
Collaborator

Hi @RobMina,
You have proposed changes to files in these packages:

  • MCDataProducts
  • RecoDataProducts
  • CRVResponse
  • CRVReco

which require these tests: build.

@Mu2e/fnalbuild-users, @Mu2e/write have access to CI actions on main.

⌛ The following tests have been triggered for e2e5514: build (Build queue - API unavailable)

About FNALbuild. Code review on Mu2e/Offline.

@FNALbuild

Copy link
Copy Markdown
Collaborator

☀️ The build tests passed at e2e5514.

Test Result Details
test with ✅ Command did not list any other PRs to include
merge ✅ Merged e2e5514 at b24d416
build (prof) ✅ Log file. Build time: 04 min 37 sec
ceSimReco ✅ Log file.
g4test_03MT ✅ Log file.
transportOnly ✅ Log file.
POT ✅ Log file.
g4study ✅ Log file.
cosmicSimReco ✅ Log file.
cosmicOffSpill ✅ Log file.
ceSteps ✅ Log file.
ceDigi ✅ Log file.
muDauSteps ✅ Log file.
ceMix ✅ Log file.
rootOverlaps ✅ Log file.
g4surfaceCheck ✅ Log file.
trigger ✅ Log file.
check_cmake ✅ Log file.
FIXME, TODO ✅ TODO (0) FIXME (0) in 7 files
clang-tidy ➡️ 3 errors 110 warnings
whitespace check ✅ no whitespace errors found

N.B. These results were obtained from a build of this Pull Request at e2e5514 after being merged into the base branch at b24d416.

For more information, please check the job page here.
Build artifacts are deleted after 5 days. If this is not desired, select Keep this build forever on the job page.

@oksuzian oksuzian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review Summary — #2106

Reviewed at head e2e55145254dea1f5355876eeff9a04d1b1e057a. First pass.

Decision

  • 🟢 approve. The products are complete and correct, and I ran both modules on the 9,314-event off-spill cosmic sample through Production#595's wiring. Every collection has exactly one TrkCrvMatch per KalSeed, and every truth record lines up with its reco record. On KKCHmu the best geometric candidate is the track's own particle in 2,791 of 2,792 tracks. Two things should be fixed, neither blocking: the truth module and the layer probe degrade without saying so (finding 1), and the physics settings live only as C++ defaults, some of them specific to the extracted geometry or copied from another module (finding 2). FNALbuild build 3558 passed every test at this head.

Scope understood

  • New products TrkCrvMatch (one per KalSeed) and TrkCrvMatchMC (one per TrkCrvMatch), the TrkCrvMatchTool helper in CRVReco, the producers TrkCrvMatcher and TrkCrvMatchMCMaker, prolog tables, and dictionary and build entries. All 17 files are additions; no existing module, product or configuration changes.
  • Companions, all drafts and not reviewed here: Production#595 schedules the modules in reco and recoMC, EventNtuple#441 writes ntuple branches and can run both modules on existing reco files, and Offline#2107 adds validation histograms.

Findings

  1. 🟡 [S2] The truth module and the layer probe degrade without saying so.

    • Truth module. TrkCrvMatchMCMaker_module.cc:164-167 reads the SimParticles, MCTrajectories, CrvSteps and cluster-MC associations with getHandle, and each one is skipped silently when absent (:198, :222, :255, :285). Standard reco output does not keep the digi-stage CrvSteps: Production's recoMC/prolog.fcl sets compressRecoMCs.crvStepsToKeep : [ ], and no Production fcl includes recoMC/cosmic_epilog.fcl, the only file that keeps them. So the module run on existing reco files, which the description says was tested and which EventNtuple#441 configures, gets no CrvSteps. I ran it alone on my off-spill reco output, with the prolog table as committed. It exited with status 0 and printed no warning. Every TrkCrvXingMC then has edep_, nLayers_ and depPos_ equal to zero. Compared with the same module inside the reco job, the CRV_T1 summary changes as follows: true:dep goes from 2,866 to 0, fake from 119 to 130, and dep-no-geom from 28 to 0. The candidate relations are unaffected, because the cluster-MC associations are kept.
    • Layer probe. Without the pulse collection, TrkCrvMatcher_module.cc:78-80 warns once and continues. Every layer then has dBar_ = INT8_MAX and pe_ = 0, which is also what "no pulse in the window" looks like. Nothing in TrkCrvXing or TrkCrvMatch records that the probe ran without pulses. EventNtuple#441 runs it on SelectReco, which holds the clustered pulses only, so its unclustered-layer columns read as inefficiency.
    • Suggested fix: use getValidHandle for every input the truth module needs, or throw with a message naming the missing collection. Add a flag to the product saying whether the probe had the full pulse collection. While there:
      • :297-298 compare cluster keys without the ProductID check that :323-328 apply;
      • :125 is an empty catch, which clang-tidy also reports (bugprone-empty-catch).
  2. 🟡 [S2] The physics settings live only as C++ defaults, and some are specific to the extracted geometry or copied from another module.

    • All 22 settings of TrkCrvMatchTool::Config (TrkCrvMatchTool.hh:33-54) have C++ defaults. The prolog table (CRVReco/fcl/prolog_v12.fcl:393-398) sets only the input tags. Mu2e practice is that physics settings carry no C++ default, so that a job states them.

    • DtRefCenter : 75 ns has no source. On the Run 1A off-spill sample, the median dtRef of own-particle time candidates is:

      fit median dtRef (ns)
      KKCHmu 20.4 (68% between 11.2 and 28.8)
      KKDe 24.5
      KKDmu 24.7
      KKUe 35.8
      KKUmu 36.7

      Centring the time ranking on 20 ns turns 5 of the 3,222 KKCHmu best-time choices from Unrelated to SameParticle. The effect is small here because only 16 tracks have more than one time candidate. It would be larger in busy on-spill events.

    • The SigmaV comment names the sector types "EX, T1, T2, muon taggers". That is the extracted geometry's numbering (crv_counters_extracted_v04.txt:186-196). In the Run 1A geometry, T1 and T2 are both type 1 (crv_counters_run1a_v01.txt:77-78), so both get 7 mm. In crv_counters_v10.txt, type 1 is CRV-R.

    • FiberSignalSpeed (140) and ProbePulseDelay (34.5) copy CrvCoincidenceFinder's prolog values (prolog_v12.fcl:383, :385). The 140 there carries "FIXME: The correct value should be 175 mm/ns". If that is fixed, the probe keeps 140.

    • Suggested fix: set the values in prolog_v12.fcl with their sources, and take the fibre speed and delay from the finder's table with @local::. Then make the C++ settings mandatory, and either key SigmaV by sector name or say in the comment which geometry its types refer to.

  3. ⚪ [S3] Small items.

    • There is no Print/ support and no operator<< for the new products (CrvCoincidenceClusterPrinter is the sibling).

    • TrkCrvFitClusterAssns (UsedInFitAssns) has dictionaries and a reader, but nothing produces it, here or in the three companions. If it is for a fit still to come, the comment could say so.

    • Two pieces of code are written twice:

      • the dominant shield by PE (TrkCrvMatchTool.cc:77-84, TrkCrvMatchMCMaker_module.cc:182-185);
      • the KinKalGeom sector to shield map (TrkCrvMatchTool.cc:43-61, TrkCrvMatchMCMaker_module.cc:114-126).

      One helper would serve both.

    • cLight_ (TrkCrvMatchTool.hh:106) duplicates CLHEP::c_light. The map usedXing (TrkCrvMatchTool.cc:362) is keyed by track and sector, not by crossing.

Checked, no action needed

  • 🟢 Build.

    • A full muse build of this head on main b24d4163, with p110 and Production#595 (56523f10), finished with exit status 0 and no warnings.
    • A second build with Offline#2084 at 445cd49a merged in also finished with exit status 0; the two branches merge without conflict.
    • In FNALbuild build 3558, the three clang-tidy errors are in cetlib/LibraryManager.h. The 110 warnings in the new files are magic numbers and narrowing conversions, apart from the empty catch above.
  • 🟢 Data-product paperwork. classes_def.xml has every new type, its vectors, the Wrappers, Ptr<CrvCoincidenceCluster>, Ptr<TrkCrvMatch>, and both directions of the new Assns. RecoDataProducts carries no MC information. Every member is initialised where it is declared. I read both products back from the output file with PyROOT.

  • 🟢 The record order holds. On all 9,314 events, with both off-spill settings, every TrkCrvMatch collection has exactly one record per KalSeed, and track_.key() equals its index, for KKCHmu, KKDe, KKUe, KKDmu and KKUmu. Every TrkCrvMatchMC has cands_ and recoXingTruth_ parallel to its reco record, and every track has MC truth.

  • 🟢 Matching on KKCHmu, the off-spill sample through Production#595's wiring:

    setting tracks with a CRV crossing best geometric candidate own particle best time candidate own particle median χ²/ndof, own geometric
    validation (field correction on) 4,876 3,005 2,792 2,791 3,207 of 3,222 0.25
    production (field correction off) 5,384 2,419 2,057 2,055 3,562 of 3,588 0.67

    The truth module's own summary agrees. With the validation setting, the own CRV_T1 cluster is a geometric candidate in 2,766 of 3,183 tracks, and is then always exclusive and best in its sector. On the LoopHelix fits the match is time only, as configured. Between a third and a half of the best time candidates are SameFamily: the cluster belongs to the cosmic muon whose knock-on electron was fitted. That is the label the module is meant to give.

  • 🟢 Offline#2084. The matcher reads the CRV crossings of main's extrapolation and does not need #2084. With #2084 at 445cd49a merged:

    • 1 of 4,876 tracks (1430:0:90791) gets crossings of CRV_T1 and CRV_T2 at the same point, both in bounds. Its only candidate is unchanged: time only, because the extrapolated crossing is about 1 m from the true one. The truth module counts the CRV_T2 crossing as a fake next to the true sector.
    • With the production setting, on 1430:0:50204, the CRV_T1 cluster stays the best geometric candidate (χ² 0.24), and the extra CRV_T2 crossing is labelled the same way.
    • Over the whole sample, crossings go from 3,022 to 3,054, and best geometric candidates from 2,792 to 2,797, of which 2,796 are the track's own particle.
  • 🟢 CPU. The KKCHmu matcher takes 0.06 ms per event and its truth module 0.16 ms, against 17 ms for the whole event.

Validation check

  • Build/tests run: yes.

    • Two full muse builds.
    • Off-spill reco on 9,314 cosmic events in both settings, each with all five matchers and truth modules in the job. The input was read in place.
    • The same with #2084 merged, using the validation setting.
    • Single-event diagnostic runs of the two seam events.
    • A truth-module-only job on the reco output.

    All jobs exited with status 0.

  • Config contract check: pass. Both modules use validated FHiCL, and the prolog tables and Production#595's instances validate. Finding 2 covers the defaults.

  • Cross-repo consistency: pass, with finding 1's note on EventNtuple#441.

Residual risk

  • Not checked:
    • on-spill events with pileup, where the time ranking matters most;
    • the extracted KKLine configuration and data, which the description covers.
  • On KKCHmu the error model looks about twice too large in the validation setting (median χ²/ndof 0.25 for own-particle geometric matches). It was fitted on extracted KKLine, as the description says.

Author follow-ups

  1. Make the truth module and the layer probe fail or flag when an input is missing (finding 1).
  2. Move the physics settings into the prolog with sources, and share the fibre speed and delay with CrvCoincidenceFinder (finding 2).
  3. Optional: the small items in finding 3.

@brownd1978 brownd1978 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds important necessary functionality to reconstruction that previously existed only in various private analysis scripts. The basic structure looks complete and correct. My specific comments are mostly about improving code readability (= maintainability) and reducing redundant payload. I may not have caught all instances where those are relevant.

My only architectural question is whether the author considered using Assns to record the associations instead of Ptrs. Assns can have payload, and natively handle M<->N associations, which can be hard to implement via ptrs.

Comment thread CRVReco/inc/TrkCrvMatchTool.hh Resolved
Comment thread CRVReco/inc/TrkCrvPlaneError.hh Resolved
Comment thread RecoDataProducts/inc/TrkCrvMatch.hh Resolved
Comment thread RecoDataProducts/inc/TrkCrvMatch.hh Resolved
Comment thread RecoDataProducts/inc/TrkCrvMatch.hh Resolved
Comment thread MCDataProducts/inc/TrkCrvMatchMC.hh Resolved
Comment thread MCDataProducts/inc/TrkCrvMatchMC.hh Resolved
Comment thread MCDataProducts/inc/TrkCrvMatchMC.hh Resolved
Comment thread CRVReco/src/TrkCrvMatcher_module.cc Resolved
@RobMina

RobMina commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Thanks Dave for the careful review! I think I've addressed all of your comments. Regarding using Assns vs Ptrs, the main reason was to simplify the EventNtuple unpacking, since it already writes per-track branches without any lookup (as is done with KalSeedDtDt and MVAResult).

If an Assns view is useful (e.g. FindMany from the cluster side), a small producer can derive it from the records with the candidate as payload. I would add it as a follow-up rather than change the primary product.

@oksuzian oksuzian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review Summary — #2106

Reviewed at head addceca1281ee40c0404f4d86496331cabfce94e. Re-review of e2e5514.

Decision

  • 🟡 comment, for one S1 (finding 1). The two new commits answer all of Dave's review and fix both of my S2 findings, and the reconstruction product is right. On my 9,314-event off-spill sample every crossing and probe layer is identical to e2e55145, and the new reference time and full covariance behave as intended. But the truth module's candidate relations, now MCRelationships, label the cluster made by the fitted particle's own parent as unrelated whenever that parent was simulated in two stages. addceca1 fixes this for the true crossings but not for the candidates, so one record now contradicts itself. FNALbuild has not built this head: mu2e/buildtest says "This test has not been triggered yet" (checked 21:50 UTC). My own full build passed.

What changed since e2e5514

  • Two commits, f7eca129 and addceca1 (15 files, +409 −262). Neither is a rebase; the merge base is still main b24d4163.
  • TrkCrvMatch stores the track covariance in the sector plane as a symmetric 2×2 SMatrix (cov_), and the χ² uses its correlation. The reference time is the track's entry into the tracker, the earliest of TT_Front, TT_Back and TT_Outer. A probe_ field records which pulses the layer probe saw.
  • TrkCrvMatchMC references the KalSeedMC. Candidate relations and true-crossing relations are MCRelationships, and the truth module throws on missing inputs unless RequireCrvSteps : false.
  • The shared sector geometry moves to CRVReco/inc/TrkCrvGeom.hh. All physics settings are now in CRVReco/fcl/prolog_v12.fcl, with no C++ defaults.
  • MCRelationship gains a (relation, removal) constructor.

Findings

  1. 🟠 [S1] A cluster made by the track particle's parent is labelled unrelated when the parent was simulated in two stages.
    • Evidence: event 1430:0:1608, KKDe track 0.

      • The μ+ is key 0 in stage 0, where it crosses CRV-T1 and makes cluster 0. It continues as key 1 in stage 1, and the fitted electron, key 2, is a muIoni delta ray of key 1.
      • TrkCrvMatchMCMaker_module.cc:325 relates the deposit particle to the track's particle with MCRelationship(key 0, key 2). That compares key 0 with key 2's parent, key 1, and walks ancestors with originParticle().parent() (MCRelationship.cc:28-29, :44-49), which never contains key 0. So cands_[0].rel_ is none.
      • In the same TrkCrvMatchMC record, xings_[0] is key 0's crossing of CRV-T1. Its relation is mother, from the module's stage-aware lineage (:50-53, :265), and its trueCand_ is 0, the very candidate labelled unrelated.
    • Measured on the whole sample with the validation setting. The best time candidates are the same clusters as at e2e55145; only their labels change:

      fit e2e55145 this head
      KKDe 29 SameParticle, 30 SameFamily, 5 SamePrimary 29 same, 35 none
      KKUe 29, 30, 1 29 same, 31 none
      KKDmu 24, 16, 4 24 same, 20 none
      KKUmu 27, 17, 1 27 same, 18 none

      On KKCHmu, 7 SameFamily candidates become none with the validation setting, and 15 SameFamily plus 2 of 3 SamePrimary with the production setting.

    • Impact: on this sample the parent's cluster is the most common label of a LoopHelix fit's best time candidate. A purity or veto study built on rel_ != none, or on edepRelated_ (:337), would count the cosmic muon's own cluster as an accidental coincidence.

    • Suggested fix: relate deposits through the same lineage that addceca1 uses for the crossings. A deposit particle found there, matched by (simStage, key), gets ancestorRelation(gen); only the others need MCRelationship. The comment at :48-49 describes the problem as counting stage copies as generations. On this sample the relation is lost entirely.

Prior findings (from my review at e2e55145)

  • 🟢 [was 🟡 S2] The truth module and the layer probe degraded silently. FIXED, verified.
    • Run alone on reco output with the prolog defaults, the truth module stops with "no CrvStepCollection … (reco output drops it; set RequireCrvSteps : false to run without deposits)". With false it runs with exit status 0.
    • Every track records which pulses the probe saw (probe_): probeAllPulses on all 4,876 KKCHmu tracks of my run.
    • The cluster-key comparison checks the ProductID (:285), and the empty catch is gone.
  • 🟢 [was 🟡 S2] The physics settings lived only as C++ defaults. FIXED, verified.
    • All are mandatory and set in prolog_v12.fcl:392-428, with sources.
    • The fibre speed and pulse delay are @local:: references to the cluster finder; fhicl-dump gives 140 and 34.5.
    • The SigmaV comment names the extracted geometry's sector types.
  • ⚪ [S3, partial] Small items. Fixed: the duplicated geometry code, cLight_, the usedXing name, and the TrkCrvFitClusterAssns comment. Open: there is no Print/ support and no operator<< for the two products.

Checked, no action needed

  • 🟢 Dave's review is fully answered, including the Assns question (reply at 21:46 UTC).
  • 🟢 The new MCRelationship(relation, removal) constructor adds no data member, so stored MCRelationships and their dictionary are unchanged. No overload becomes ambiguous: every other two-argument call passes SimParticle Ptrs or StrawDigiMCs. I checked the 5 such calls in Offline and those in EventNtuple and ArtAnalysis on main. My full build of Offline and Production is clean; I did not build EventNtuple or ArtAnalysis.
  • 🟢 Reconstruction, this head against e2e55145, both off-spill settings:
    • Every KKCHmu crossing, its position, time and flags, and every probe layer are identical. The track errors shrink by at most 1 mm, from the quadrature term 25 → 24 mm.
    • I recomputed all 2,058 geometric χ² values of the production job from the stored covariance; they agree to within 1e-7.
    • With the tracker-entry reference, the own-particle dtRef narrows from 11.2–28.8 ns (16–84%) to 13.2–20.9 ns. The best geometric candidate does not change for any track.
  • 🟢 The true crossings of the track's particle and its ancestors are the same as at e2e55145; only two trueCand_ indices follow the changed candidate windows. They now carry stage-aware relations: on KKDe, 30 same, 23 mother and 8 umother.

Validation check

  • Build/tests run: yes. A full muse build with Production#595 a5b655c3 and mu2e-trig-config 5999ffa2 (p110) exited with status 0 and no warnings. I ran off-spill reconstruction on 9,314 cosmic events, in both settings, at this head and at e2e55145; every job exited with status 0. I also ran the truth module alone with deposit diagnostics, and the RequireCrvSteps check.
  • Config contract check: pass. EventNtuple#441 sets ProbeAllPulses : false and RequireCrvSteps : false where needed.
  • Cross-repo consistency: pass.

Residual risk

  • On this sample the own-particle dtRef medians are 16.9 ns for KKCHmu and 21.5, 24.9, 21.7 and 23.8 ns for the four LoopHelix fits. Production#595 centres them on 27, 32, 28, 30 and 26 ns. This affects only the best-time ranking.
  • Not checked: on-spill events with pileup, and the extracted KKLine configuration.

Author follow-ups

  1. Give candidate deposits the same stage-aware ancestor relation as the true crossings (finding 1).
  2. Optional: Print/ support for the two products.

@oksuzian

oksuzian commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

@FNALbuild run build test

@FNALbuild

Copy link
Copy Markdown
Collaborator

⌛ The following tests have been triggered for addceca: build (Build queue - API unavailable)

@FNALbuild

Copy link
Copy Markdown
Collaborator

☀️ The build tests passed at addceca.

Test Result Details
test with ✅ Command did not list any other PRs to include
merge ✅ Merged addceca at b24d416
build (prof) ✅ Log file. Build time: 04 min 50 sec
ceSimReco ✅ Log file.
g4test_03MT ✅ Log file.
transportOnly ✅ Log file.
POT ✅ Log file.
g4study ✅ Log file.
cosmicSimReco ✅ Log file.
cosmicOffSpill ✅ Log file.
ceSteps ✅ Log file.
ceDigi ✅ Log file.
muDauSteps ✅ Log file.
ceMix ✅ Log file.
rootOverlaps ✅ Log file.
g4surfaceCheck ✅ Log file.
trigger ✅ Log file.
check_cmake ✅ Log file.
FIXME, TODO ✅ TODO (0) FIXME (0) in 10 files
clang-tidy ➡️ 4 errors 105 warnings
whitespace check ✅ no whitespace errors found

N.B. These results were obtained from a build of this Pull Request at addceca after being merged into the base branch at b24d416.

For more information, please check the job page here.
Build artifacts are deleted after 5 days. If this is not desired, select Keep this build forever on the job page.

… (ancestors and siblings simulated in an earlier stage).
@RobMina

RobMina commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @oksuzian! That was a good catch -- fixed in f24602b

@oksuzian oksuzian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review Summary — #2106

Reviewed at head f24602b5b6e817b1fb2ac77b6f1f5ab3d0dd9283. Re-review of addceca.

Decision

  • 🟡 comment now, approve when green. I would approve this code. The new commit fixes my S1: a candidate cluster made by an ancestor of the track's particle is now labelled by its real relation, also when the ancestor was simulated in an earlier stage, and every candidate now agrees with the true crossing it belongs to. Reconstruction is unchanged. One optional small item is new (finding 1). FNALbuild passed at addceca1 (22:09 UTC) but has not built this head: mu2e/buildtest says "This test has not been triggered yet" (checked 01:21 UTC). I am triggering it and will approve once the build at f24602b5 is green.

What changed since addceca

  • One commit, f24602b5, in CRVResponse/src/TrkCrvMatchMCMaker_module.cc only (+47 −9). Not a rebase.
  • Each deposit particle and the track's particle get an origin chain: one entry per generation, each the earliest simulation-stage copy of that generation's particle (:196-211, cached per event). stageAwareRelation (:60-77) compares the two chains, so stage copies count as one particle at every generation. It replaces MCRelationship(deposit, track copy) for the candidates (:352, :363).

Prior findings (from my review at addceca1)

  • 🟢 [was 🟠 S1] A cluster made by the track particle's parent was labelled unrelated when the parent was simulated in two stages. FIXED, verified.
    • Event 1430:0:1608, KKDe track 0, candidate 0: the deposit of the stage-0 μ+ (key 0) now gets mother with removal 1 (deposit diagnostics: "rel 2/1 | track origin chain 2(stage 1) 0(stage 0)"). That matches xings_[0], the same μ+'s crossing, whose trueCand_ is 0.

    • Every candidate labelled SameFamily or SamePrimary at e2e55145 now has a relation, and nothing else moves. Same input, validation setting, all candidates (on these fits each is also the best time candidate):

      fit e2e55145 this head
      KKDe 29 SameParticle, 30 SameFamily, 5 SamePrimary 29 same, 21 mother, 13 umother, 1 sibling
      KKUe 29, 30, 1 29 same, 21 mother, 10 umother
      KKDmu 24, 16, 4 24 same, 9 mother, 11 umother
      KKUmu 27, 17, 1 27 same, 10 mother, 8 umother

      On KKCHmu the 7 SameFamily candidates become 4 mother and 3 umother with the validation setting. With the production setting, 15 SameFamily and 3 SamePrimary become 10 mother and 8 umother. The 12 candidates that e2e55145 called unrelated stay none in each setting.

    • Candidates and true crossings agree everywhere. For every true crossing that has a candidate, the candidate's relation is at least as close as the crossing's, and its removal counts generations the same way: 59, 59, 40, 44 and 3,224 crossings in the five validation fits and 3,583 in the production KKCHmu, no exception. At addceca1, event 1608 was one of the exceptions.

    • Read for edge cases: a null Ptr and a deposit particle missing from the track's SimParticle collection give none, as before. The self-parent walk handles any number of stages, and siblings are compared through the earliest copy of their parent. Only two-stage chains occur on this sample, so a third stage is not exercised.

  • ⚪ [S3, open] There is still no Print/ support and no operator<< for the two products.

Findings

  1. ⚪ [S3] The module now walks the track's ancestry two ways. lineage (:233-242) follows the stored parent() Ptrs up to MaxGenerations and labels the true crossings. The origin chain (:196-211) maps each step into the track's SimParticle collection, has no generation limit and labels the candidates. They agree on this sample, but an ancestor beyond MaxGenerations would get a candidate relation and no true crossing. Deriving lineage from the track's origin chain would leave one walk. Optional. stageAwareRelation is also what MCRelationship(SPPtr, SPPtr) itself lacks for its other callers; that belongs in a separate PR.

Validation check

  • Build/tests run: yes. Incremental muse build of this head (Production#595 a5b655c3, mu2e-trig-config 5999ffa2, p110): exit status 0, no warnings. Off-spill reconstruction on the same 9,314 cosmic events with both settings, and the truth module alone with deposit diagnostics: all exit status 0.
  • Reconstruction against addceca1, both settings: every crossing (3,022 and 2,420), probe layer (12,088 and 9,680), candidate set, best geometric and best time candidate, and true crossing is identical. Only the candidate relations above change.
  • Config contract check: pass. No fcl change.
  • Cross-repo consistency: pass.

Residual risk

  • Unchanged: on-spill events with pileup and the extracted KKLine configuration are not checked, and Production#595's time-ranking centres differ from this sample's medians.

Author follow-ups

  1. Optional: finding 1, and Print/ support for the two products.

@oksuzian

oksuzian commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator

@FNALbuild run build test

@oksuzian

oksuzian commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator

@FNALbuild run build test

@FNALbuild

Copy link
Copy Markdown
Collaborator

⌛ The following tests have been triggered for f24602b: build (already triggered: build) (Build queue - API unavailable)

@FNALbuild

Copy link
Copy Markdown
Collaborator

☀️ The build tests passed at f24602b.

Test Result Details
test with ✅ Command did not list any other PRs to include
merge ✅ Merged f24602b at b24d416
build (prof) ✅ Log file. Build time: 09 min 19 sec
ceSimReco ✅ Log file.
g4test_03MT ✅ Log file.
transportOnly ✅ Log file.
POT ✅ Log file.
g4study ✅ Log file.
cosmicSimReco ✅ Log file.
cosmicOffSpill ✅ Log file.
ceSteps ✅ Log file.
ceDigi ✅ Log file.
muDauSteps ✅ Log file.
ceMix ✅ Log file.
rootOverlaps ✅ Log file.
g4surfaceCheck ✅ Log file.
trigger ✅ Log file.
check_cmake ✅ Log file.
FIXME, TODO ✅ TODO (0) FIXME (0) in 10 files
clang-tidy ➡️ 4 errors 108 warnings
whitespace check ✅ no whitespace errors found

N.B. These results were obtained from a build of this Pull Request at f24602b after being merged into the base branch at b24d416.

For more information, please check the job page here.
Build artifacts are deleted after 5 days. If this is not desired, select Keep this build forever on the job page.

@oksuzian oksuzian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review Summary — #2106

Reviewed at head f24602b5b6e817b1fb2ac77b6f1f5ab3d0dd9283. Follow-up to my comment review at the same head.

Decision

  • 🟢 approve. FNALbuild build 3570 has now built this head, merged on main b24d4163, and every test passed: the prof build, all eleven validation jobs, rootOverlaps, g4surfaceCheck, trigger, check_cmake and the whitespace check. The FIXME/TODO count and clang-tidy rows are informational. This is the approval my comment review promised once the build was green. The two small items in that review, the two ancestry walks and the missing Print/ support, still stand and do not block.

@brownd1978 brownd1978 left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Rob for taking this on and for addressing my questions. This looks good to me!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants