refactor(alert): move AHDC track-finding from AHDCEngine to ALERTEngine by mathieuouillon · Pull Request #1242 · JeffersonLab/coatjava

mathieuouillon · 2026-05-04T15:01:25Z

AHDCEngine now only reads AHDC::adc, applies calibration via HitReader, and writes AHDC::hits. The full track-finding pipeline (preclustering, AI/CV_Distance/CV_Hough finder, DOCA refinement, helix fit) runs in ALERTEngine on top of AHDC::hits + ATOF::hits/clusters, alongside the existing projection / matching / prePID / Kalman steps.

The track finder is selected via the ALERT.Mode YAML key (was AHDC.Mode); ModelTrackFinding only loads when AI_Track_Finding is selected. The ATOF::tdc gate now fires after the AHDC pipeline so events without ATOF still get their AHDC::* banks, matching the pre-refactor behavior.

mathieuouillon · 2026-05-04T15:03:18Z

Note: AHDC::hits.adc is stored as int (calibrated ADC truncated). Track.get_sum_adc rounds Hit.getADC() per hit, so when track-finding ran inside AHDCEngine it summed the original full-precision double. Reading back from the bank here gives integer adc values, so sum_adc and dEdx in AHDC::track can drift by 0-1 per hit relative to the pre-refactor output (≈1-6 counts in sum_adc on ~1% of events). Eliminating the drift would require widening AHDC::hits.adc from I to F/D in the schema.

mathieuouillon · 2026-05-04T19:01:30Z

Compared AHDC::track row counts between the two finders on the same 1000-event input (clas_021903.evio.00000, recon-util -n 1000), toggling only the ALERT.Mode YAML key.

Metric	MLP	GNN
Total tracks	9	35
Mean tracks / event	0.009	0.035
Events with ≥1 track	9	34

GNN finds ~3.9× more tracks overall.

Per-event breakdown (1000 events)

Bucket	Count
Both finders have tracks	9
Only MLP has tracks	0
Only GNN has tracks	25
Neither has tracks	966
MLP rows > GNN rows (per event)	0
MLP rows < GNN rows (per event)	25
MLP rows == GNN rows	975

mathieuouillon · 2026-05-11T12:26:04Z

Tested on 100 files for the run 22991, no error or warning with clara

whit2333 · 2026-05-14T21:59:13Z

@@ -0,0 +1,34 @@
+package org.jlab.rec.ahdc.TrackFinding;
+
+import org.jlab.rec.ahdc.Track.Track;


The track finder doesn't find Tracks it finds TrackCandidates.
A Track s something different (ie the result of track fitting). A candidate should have hits associated with it and can be specialized: AHDC only, AHDC+ATOF, AHDC+verex, etc. Which then dictates the specifics of how the fitting is done.

Thanks for all the comments. I started work on that.
For that, it is a very good idea.
My first draft for that comment is in the commit: 28dc412

Verified byte-identical: recon-util on clas_021903 (config_p0v9, MLP_Track_Finding, 1000 events) before/after gives 0 mismatched rows / 0 mismatched entries across AHDC::track, AHDC::kftrack, AHDC::hits, AHDC::clusters, AHDC::interclusters, AHDC::preclusters and AHDC::docaclusters

whit2333 · 2026-05-14T22:05:26Z

We should have skeleton engine ready to go called ALERTEventBuilderEngine as a way of developing reconstruction code that will eventually be merged into the event builder. It will be the last engine in the processing chain until it is all merged into the event builder.

It is a good idea, but it should probably be in a different pull request

whit2333 · 2026-05-14T22:07:00Z

Since Cluster is an overloaded term. It would be a good idea to rename this class AHDCCluster. Or be explicit with interfaces using clusters

whit2333 · 2026-05-18T16:33:25Z


 public enum ModeTrackFinding {
-    AI_Track_Finding,
+    MLP_Track_Finding,


Should be TrackFindingMode not ModeTrackFinding

whit2333 · 2026-05-18T16:36:20Z

+    MLP_Track_Finding,
    CV_Distance,
    CV_Hough,
+    GNN_Track_Finding,


These need to be documented -- add a short description of each. What does CV stand for?

whit2333 · 2026-05-18T16:48:04Z

The TrackFinding methods probably shouldn't be located in rec/ahdc but rather rec/alert

whit2333 · 2026-05-18T16:50:19Z

The file should be named TrackFindingMode and it should be located with TrackFinding which should be in rec/alert not rec/ahdc

whit2333 · 2026-05-18T16:52:30Z

+        // --- ATOF nodes -------------------------------------------------------------
+        // Deduplicate by (sector, layer, component) — inference-time variant of the
+        // Python dedup which also keys on track id (only needed at training time).
+        if (atofHitsBank != null) {


This leads me to think this directory rec/ahdc/AI should not be in rec/ahdc, but in rec/alert

whit2333 · 2026-05-18T16:57:31Z

+ *  Exported forward signature (see SingleGraphEdgeScorer):
+ *    forward(x: float32[N, 10], edge_index: int64[2, E], edge_attr: float32[E, 9])
+ *      -&gt; float32[E]   (sigmoid edge scores in [0, 1])
+ */


Link to DJL's documentation somewhere.

whit2333 · 2026-05-18T16:58:42Z

+/** Track extraction from per-edge scores via union-find connected components
+ *  at a single threshold. Ports the {@code method="cc"} branch of
+ *  {@code track-finding/gnn/inference.py::extract_tracks}, which is the
+ *  extractor that gnn/evaluate.py uses.


Where is this code?

AHDCEngine now only reads AHDC::adc, applies calibration via HitReader, and writes AHDC::hits. The full track-finding pipeline (preclustering, AI/CV_Distance/CV_Hough finder, DOCA refinement, helix fit) runs in ALERTEngine on top of AHDC::hits + ATOF::hits/clusters, alongside the existing projection / matching / prePID / Kalman steps. The track finder is selected via the ALERT.Mode YAML key (was AHDC.Mode); ModelTrackFinding only loads when AI_Track_Finding is selected. The ATOF::tdc gate now fires after the AHDC pipeline so events without ATOF still get their AHDC::* banks, matching the pre-refactor behavior.

…erface Introduce TrackFinder { findTracks(hits) -> TrackFinderResult } with three implementations — AITrackFinder, DistanceTrackFinder, HoughTrackFinder — each owning its own preclustering, cluster building, and mode-specific logic. AITrackFinder owns ModelTrackFinding, the MAX_HITS_FOR_AI Distance fallback, and the greedy non-overlap selection; the "too many candidates" exit becomes TrackFinderResult.invalid() instead of a return-false from processDataEvent. ALERTEngine becomes a thin dispatcher: init() picks the strategy from ALERT.Mode via a switch, and processDataEvent calls findTracks(hits) once. Output is byte-identical to the prior refactor (same 9/999 sum_adc/dEdx precision drift, no new mismatches).

Introduce GNN_Track_Finding as a fourth track-finding mode alongside the renamed MLP_Track_Finding (was AI_Track_Finding), CV_Distance, and CV_Hough. The new path runs a GravNet edge scorer (TorchScript via DJL) on a per-event AHDC + ATOF hit graph, extracts tracks as connected components on edges with sigmoid score >= 0.1, then re-preclusters each surviving track's AHDC hits and pairs them into per-superlayer Clusters so the existing DOCA refinement + helix fit + Kalman stages consume them unchanged. Selected via ALERT.Mode in YAML. MLP regression is bit-identical (same pre-existing AHDC::track sum_adc/ dEdx precision drift); only COAT::config changes, reflecting the renamed mode.

…tching prediction handling

…Track (fit result) The AHDC track finders produced org.jlab.rec.ahdc.Track.Track, and the helix fit + Kalman filter then mutated that same object in place. One class was doing two jobs: a track-finder output (hits + clusters) and a fit result (vertex, momentum, chi2). A "Track" should mean the result of track fitting. Split the conflated class into two: - TrackCandidate: the track-finder output. Owns hits, clusters, and interclusters. Carries a CandidateType (AHDC_ONLY / AHDC_ATOF, plus a reserved AHDC_VERTEX) describing its specialization; the type is what will dictate how the candidate is fitted. The two old Track constructors (from Clusters, from Hits) move here. - Track: the fit result, produced by fitting a TrackCandidate. Composes the candidate it was fitted from and adds the fitted vertex, momentum, chi2, path, dEdx, p_drift, sum_residuals. It stays a full facade: every accessor the old Track exposed still works, and the candidate-side ones are delegated to the underlying TrackCandidate. All four finders (MLP / Distance / Hough / GNN) plus Distance and HoughTransform now produce TrackCandidate; TrackFinderResult wraps List<TrackCandidate>. ALERTEngine's fit stage turns each candidate into a Track, with a switch (CandidateType) dispatch seam.

…CClusterFinder

mathieuouillon force-pushed the rgl_trackfinding_gnn branch 2 times, most recently from 26ba2cb to d09f721 Compare May 11, 2026 12:24

mathieuouillon marked this pull request as ready for review May 11, 2026 12:24

mathieuouillon requested review from N-Plx, baltzell, efuchey, ftouchte, mpaolone and whit2333 as code owners May 11, 2026 12:24

mathieuouillon force-pushed the rgl_trackfinding_gnn branch from 187e956 to f21c966 Compare May 11, 2026 15:24

mathieuouillon added the rg-l label May 11, 2026

baltzell force-pushed the rgl_trackfinding_gnn branch from f21c966 to dc61b1e Compare May 12, 2026 20:31

whit2333 requested changes May 18, 2026

View reviewed changes

mathieuouillon added 5 commits May 18, 2026 13:13

test(ahdc): AHDCTest should test hits-only AHDCEngine

b2b0d24

fix(alert): unify DatabaseConstantProvider usage and improve track ma…

36f990b

…tching prediction handling

mathieuouillon force-pushed the rgl_trackfinding_gnn branch from dc61b1e to 36f990b Compare May 18, 2026 17:13

mathieuouillon added 2 commits May 18, 2026 14:51

refactor(alert): rename AHDC Cluster/ClusterFinder -> AHDCCluster/AHD…

76cfe77

…CClusterFinder

		@@ -0,0 +1,34 @@
		package org.jlab.rec.ahdc.TrackFinding;

		import org.jlab.rec.ahdc.Track.Track;

Conversation

mathieuouillon commented May 4, 2026

Uh oh!

mathieuouillon commented May 4, 2026

Uh oh!

mathieuouillon commented May 4, 2026

Uh oh!

mathieuouillon commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mathieuouillon May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mathieuouillon May 18, 2026 •

edited

Loading