Skip to content

KKExtrap rangeout truncate - #2111

Merged
oksuzian merged 3 commits into
Mu2e:mainfrom
RobMina:kkextrap-rangeout-truncate
Nov 18, 2026
Merged

oksuzian merged 3 commits into
Mu2e:mainfrom
RobMina:kkextrap-rangeout-truncate

Conversation

@RobMina

@RobMina RobMina commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to #2084 and #2109, both merged. Based on
current main. Needs KFTrack/KinKal#234 (Track::truncate, in KinKal v3.9.2), so this PR moves .muse from envset
p110 to p111, which differs from p110 only by KinKal v03_09_02.

Problem

When KKExtrap finds that the particle ranges out in a material it is about to cross, the forwards extrapolation
stops and the KalSeed gets TrkFitFlag::RangedOut (#2084). The trajectory itself still runs past the stop: KinKal
extends the end piece in field-domain steps (field correction on) or MaxDtStep steps (off) before asking the sweep,
so it can end up to one domain or step beyond the crossing, and the saved segments and the domain bounds follow it.

Change

  • KKExtrap::rangeOut calls KinKal::Track::truncate(TimeDir::forwards, crossing time) after setRangedOut(). The
    fit trajectory ends at the crossing where the particle stops, and the field domains beyond it are dropped.
  • KinKal refuses the cut, changing nothing, when an active hit or material of the fit lies at or beyond it, so nothing
    the fit uses loses its trajectory piece. Inactive hits beyond the stop keep their own reference pieces.
  • Refused cuts are counted. At the end of the job each fit module that extrapolates prints one line:
    KKExtrap <module label>: N tracks ranged out, M of them not truncated at the stop (KinKal refused the cut). The
    modules are LoopHelixFit, CentralHelixFit, KinematicLineFit, KKTruthSeed, RegrowLoopHelix and
    RegrowKinematicLine. With Debug > 0, each refused cut is also printed.
  • Comments: when the refused-cut check can be revisited (if KinKal stops refusing cuts for material sites the fit never
    processed), and KKExtrap: process all requested surfaces in one time-ordered sweep per direction #2084's plane workaround in ExtrapolateSweep (visitPlaneExtrema, planeCrossing) is marked
    temporary until Offline uses a KinKal release with Bracketed refinement in stepIntersect; helix-plane window when the axis starts past the plane KFTrack/KinKal#235.
  • .muse: ENVSET p111.

No data-product or configuration change.

Validation

At this head (envset p111, KinKal v3.9.2): ExtrapolateSweepTest passes. On 10,000 nightly off-spill cosmics
(MDC2025an), the end-of-job line agrees with the per-track Debug prints:

Setting KKCHmu ranged out not truncated KKUmu ranged out not truncated
nightly, field correction on 100 0 131 0
nightly, field correction off 80 0 131 0
production off-spill setting 80 0 131 0

Refused cuts do occur: on oksuzian's 9,314 off-spill events (reviewing the #2109 build), KinKal refused 1 of 80 cuts
with field correction (1430:0:24052) and 9 of 149 in the production setting. In all 10 the only effects after the
stop were active straw-material crossings of the fit.

Against #2109 (7fcbd6a7b, envset p110, with KinKal#234's Track::truncate placed over v3.9.1; the candidate
differed only by the truncate call). KinKal ctest 28/28. KKCHmu with Debug: 1:

Sample range-out stops truncated refused
nightly off-spill, field correction on (10,000 events) 149 149 0
nightly off-spill, field correction off (10,000) 111 111 0
production off-spill setting (events 0-3,333) 39 39 0

This includes 1430:4376:429727, which has inactive hits about 20 ns after its stop: with field correction, its 9
sampled tracker crossings after the stop are gone (8 on the tracker outer surface, 1 on its back face, none of them in
truth).

Outputs:

  • EventNtuple, nightly off-spill (crvextrap abidentical, crvextrap rangeout --reference):
    • Field correction off: bit-identical (556 numeric leaves).
    • Field correction on: all 1,027 tracks without a range-out stop are identical. The 148 ranged-out ones differ only
      in the forwards tail after the stop (the 9 crossings above removed, none added).
    • Range-out efficiency and purity against truth are unchanged. Field correction on: purity 0.967, efficiency 0.221
      over all truth stops; off: 0.980 and 0.149.
  • EventNtuple, 10,352 Run 2 cosmics:
    • Field correction off: bit-identical (538 numeric leaves).
    • Field correction on: all 4,752 tracks without a stop are identical. The 624 ranged-out ones differ only in the
      forwards tail (4 sampled tracker outer-surface crossings after a stop removed, none added).
    • Range-out efficiency and purity are unchanged.
  • KalSeed printouts (crvextrap kalseedab, every collection; fit summaries and intersections):
    • Nightly reco_03 events 0-1,999: identical, including the 27 RangedOut KKUmu.
    • Production off-spill events 0-3,333: identical except one RangedOut KKCHmu (1430:5744:325716). Its printed t0
      moves from 21544.5 to 21544.2 ns, because PiecewiseTrajectory::t0 starts its search from the end pieces and the
      last one is now shorter. Its momentum, fit consistency, segments and 28 intersections are unchanged.
  • Not checked: the saved segment ranges themselves (the KalSeed printer writes them with 4 significant digits).

So in these samples the change ends ranged-out trajectories at their stop, and changes no sampled quantity except the
post-stop crossings and one t0.

🤖 Generated with Claude Code

@FNALbuild

Copy link
Copy Markdown
Collaborator

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

  • Mu2eKinKal
  • KinKalGeom
  • RecoDataProducts
  • GeometryService

which require these tests: build.

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

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

About FNALbuild. Code review on Mu2e/Offline.

@FNALbuild

Copy link
Copy Markdown
Collaborator

☔ The build is failing at 18a24ee.

scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/CentralHelixFit_module.os] Error 1
scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/KKTruthSeed_module.os] Error 1
scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/KinematicLineFit_module.os] Error 1
scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/LoopHelixFit_module.os] Error 1
scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/RegrowKinematicLine_module.os] Error 1
scons: *** [build/al9-prof-e29-p110/Offline/tmp/Mu2eKinKal/src/RegrowLoopHelix_module.os] Error 1
Test Result Details
test with ✅ Command did not list any other PRs to include
merge ✅ Merged 18a24ee at b24d416
build (prof) ❌ Log file.
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 (18) FIXME (4) in 23 files
clang-tidy ➡️ 6 errors 453 warnings
whitespace check ✅ no whitespace errors found

N.B. These results were obtained from a build of this Pull Request at 18a24ee 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 — #2111

Reviewed at head 18a24eeef753a82c0c5358974864226789aacdac. First pass.

Decision

  • 🟡 comment now, approve when green. I would approve this code. I built it with KFTrack/KinKal#234 and ran it on two samples. On the nightly reco_03 sample, every KalSeed is unchanged. On off-spill cosmics, the ranged-out tracks lose what lay past the stop and nothing else. One finding: KinKal refuses 10 of the 229 off-spill cuts, including one of the three tracks from my #2084 review, and only a Debug print says so (finding 1). It does not block.
  • FNALbuild build 3567 fails at this head, as expected (checked 22:02 UTC). The six Mu2eKinKal modules that include KKExtrap.hh do not compile against KinKal v3.9.1, which has no Track::truncate. I will approve once a KinKal tag with #234 is in an envset this branch builds with, and FNALbuild is green.

Scope understood

  • Only the last commit, 18a24eee (Mu2eKinKal/inc/KKExtrap.hh +3 −1), is new. The other 29 files belong to #2084 and #2109, which I reviewed there.
  • After setRangedOut(), KKExtrap::rangeOut now calls ktrk.truncate(TimeDir::forwards, inter.time_) (KKExtrap.hh:129).
    • It runs in the sweep after Track::extrapolate has returned, and the sweep stops right after it (:407).
    • The crossing is always on the end piece (:459), so the cut only shortens the last piece and the last domain.
    • Range-out is forwards only (KKShellXing.hh:133), which matches the fixed TimeDir::forwards.
  • Merge order: #2084, then #2109, then KinKal#234 merged and tagged, then an envset with that tag and .muse moved to it, then this PR.

Prior finding (from my #2084 review at 445cd49a, finding 1, crossings after the stop)

  • 🟡 Partly fixed. Three ranged-out KKCHmu tracks gained sampled tracker crossings after the stop: 5 on 1430:0:3926, 10 on 19224 and 12 on 24052.
    • The first two now lose all of them.
    • 24052 keeps its 12, because KinKal refuses the cut (finding 1).
    • The coplanar-crossing half of that finding is #2109's.

Findings

  1. 🟡 [S2] KinKal refuses 10 of 229 range-out cuts on my off-spill sample, and only a Debug print records it.
    • Evidence: I ran with ExtrapolationSettings.Debug: 1 on every KK fit.
      • Off-spill cosmics, 9,314 events. With the validation setting (field correction on), 1 of 80 stops is refused: 1430:0:24052. With the production setting (off), 9 of 149 are refused: 1430:0:7696, 8803, 12368, 18707, 26159, 49486, 50657, 86758 and 93112.
      • Nightly reco_03: 236 stops, none refused.
      • The cause, from a temporary print placed before the call (not committed): in all 10, the only effects after the stop are 1 to 8 active straw-material crossings of the fit. The last active hit is 2.1 to 3.9 ns before the stop.
      • With ProcessEnds: false, the fit does not process sites after the last hit. In the 9 production cases, these crossings lie even after the end of the trajectory, by up to 39 ns.
      • I raised the guard itself on KinKal#234.
    • Impact:
      • On 24052, 56 ns of trajectory and 12 sampled tracker crossings stay past the stop: the fitted trajectory re-enters the tracker 2.3 ns after it. Its saved segments still end 56 ns past the stop.
      • In the 9 production cases the overrun is 0.04 to 0.95 ns, and 2 of them still save a segment past the stop.
      • The description says every range-out stop is truncated. That does not hold on this sample, and with Debug 0 a production job cannot tell.
    • Suggested fix: record a refused cut somewhere a production job reports it, for example a count printed at the end of the job, and give these numbers in the description. The guard itself can be relaxed in KinKal#234.

Measured: this head with KinKal#234 against #2109 7fcbd6a7, same inputs

  • 🟢 Nightly reco_03, all 16,508 events: every KalSeed printout is identical in every collection. That covers the fit summaries including t0, the flags (236 KKUmu RangedOut, 1 KKDmu ExtrapolationFailed) and every crossing. All 236 stops are cut.
  • 🟢 Off-spill, validation setting: 15 TT_Outer crossings are removed, on 3926 and 19224, and none is added. Nothing else changes in any collection, except the printed cos θ of 19224 (0.052 to 0.050). Tracks saving a segment past the stop: 6 of 80 before (0.16 to 56.4 ns), 1 now (24052).
  • 🟢 Off-spill, production setting: every crossing is the same. The printed cos θ of 7 ranged-out KKCHmu tracks differs by 0.001. Tracks saving a segment past the stop: 50 of 149 before (0.03 to 1.0 ns), 2 now.
  • Why cos θ moves: the printed direction comes from the saved segment that holds t0. On these tracks that segment is the last one, which is now shorter, and a segment stores the state at the middle of its range (KKFit.hh:926). Momentum, t0, fit consistency and segment counts are unchanged.

Validation check

  • Build/tests run: yes.
    • muse build of this head (Production 94a4d81f, mu2e-trig-config 5999ffa2, p110), with KinKal#234's Fit/Track.hh and Fit/Domain.hh placed over the release headers. The release headers are byte-identical to git v3.9.1. Exit status 0, no warnings, and all 1168 compile lines used the overlay.
    • ExtrapolateSweepTest: all checks passed.
    • The off-spill sample in both settings and reco_03 in 6 chunks: every job exited with status 0. The baselines are the #2109 runs, with the same inputs and job files.
  • Config contract check: pass. No fcl or data-product change.
  • Cross-repo consistency: needs follow-up. This PR needs a KinKal tag with #234 and an envset.

Residual risk

  • KinKal's compiled libraries in my build are the v3.9.1 release. The change is header-only, so this matches what a tag would give, but FNALbuild has not built it.
  • Not checked: the Regrow modules, KinematicLine fits, and the calorimeter options.

Author follow-ups

  1. Finding 1: record refused cuts and update the description's numbers.
  2. Link #2109 and this PR in #2084's description, where <follow-up PR link> is still a placeholder.

@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.

Could you please update this PR to reference the current Offline head? that would remove a lot of changes that were already merged.


namespace {
// axis-aligned box in Mu2e coordinates
struct MuBox {

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.

MuBox strikes me as being more natural as part of KinKal/Geometry.

}
return box;
}
CLHEP::HepRotation inverseRotation(std::string const& orientation) {

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.

Did you consider using Rotation3D and XYZVector for these operations instead? Those are native to root and so more natural for interfacing with KinKal.

@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.

My recollection is this additional test will become unnecessary after an update to KinKal propagates to Offline, is that correct? If so, could you put in an appropriate comment so we don't forget to remove it later. thanks.

@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 — #2111

Reviewed at head cac2266d58dc64c5dcee7cd7da939ab6a9edb0e1. Re-review of 18a24ee.

Decision

  • 🟡 comment now, approve when green, as before. cac2266d merges main (8628ceb7) and changes nothing of its own. The PR's own change, 18 lines in Mu2eKinKal/inc/KKExtrap.hh, is the same as at 18a24eee, which I reviewed and would approve.
  • It still cannot build in CI. Track::truncate arrived in KinKal v3.9.2 (KinKal/Fit/Track.hh:121, :1084 at tag v3.9.2, the KFTrack/KinKal#234 merge d19623fe); v3.9.1 does not have it. Offline main still names envset p110 in .muse, and p110 provides kinkal@v03_09_01. A build at this head would fail in the same six Mu2eKinKal modules as build 3567, so I have not asked for one. Once an envset with KinKal v3.9.2 is in use, FNALbuild can be triggered and I will approve when it passes.

What changed since 18a24ee

  • One merge commit, cac2266d "Merge branch 'Mu2e:main' into kkextrap-rangeout-truncate", bringing in main up to 8628ceb7.
  • The PR's own diff against main is line-for-line identical before and after: git diff $(git merge-base <head> main) <head> gives the same 18 lines at both heads.

Prior findings

  1. 🟡 [S2] KinKal refuses 10 of the 229 off-spill cuts, and only a Debug print says so — still open, unchanged (the code did not change). Non-gating.

Validation check

  • Build/tests run: no. The increment is a merge of main only. The envset check: muse status on the CI backing main/8628ceb7_b2ef90eb_5f221e50 reports MUSE_ENVSET = p110 with kinkal@v03_09_01.
  • FNALbuild: mu2e/buildtest at this head reads "This test has not been triggered yet" (23:56 UTC). The only build of this PR, 3567 at 18a24eee, failed for the reason above.

Author follow-ups

  1. The PR needs an envset with KinKal v3.9.2, or a .muse change that selects one, together with or before it. Is a p111 (or similar) planned?

@RobMina

RobMina commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

@FNALbuild run build test

@FNALbuild

Copy link
Copy Markdown
Collaborator

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

@FNALbuild

Copy link
Copy Markdown
Collaborator

☀️ The build tests passed at 609ff61.

Test Result Details
test with ✅ Command did not list any other PRs to include
merge ✅ Merged 609ff61 at 554ef9f
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. Return Code 2.
check_cmake ✅ Log file.
FIXME, TODO ➡️ TODO (7) FIXME (1) in 8 files
clang-tidy ➡️ 6 errors 151 warnings
whitespace check ✅ no whitespace errors found

N.B. These results were obtained from a build of this Pull Request at 609ff61 after being merged into the base branch at 554ef9f.

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 — #2111

Reviewed at head 609ff61ec12d7997f77d99c783de59a4d5ea0ef2. Re-review of cac2266.

Decision

  • 🟢 approve. The envset now provides KinKal v3.9.2, so the PR builds, and FNALbuild passed at this head. My one open finding is fixed: refused truncations are now counted and reported at the end of the job. The temporary plane workaround is now marked for removal, as brownd1978 asked.

What changed since cac2266

  • One commit, 609ff61e "Address review comments, bump envset" (9 files, +44 −4).
  • .muse: ENVSET p110 becomes p111.
  • KKExtrap::rangeOut counts tracks that range out, and how many of them KinKal would not truncate. A new printSummary prints both numbers at the end of the job. All six modules that own a KKExtrap call it from endJob: CentralHelixFit, KKTruthSeed, KinematicLineFit, LoopHelixFit, RegrowKinematicLine and RegrowLoopHelix.
  • ExtrapolateSweep.hh gains a TEMPORARY note: once Offline uses a KinKal release with KFTrack/KinKal#235, remove visitPlaneExtrema and planeCrossing and use KinKal::intersect for planes.

Prior findings

  1. 🟢 [was S2] KinKal refused some cuts, and only a Debug print said so. FIXED in 609ff61.
    • Each refusal is now counted (KKExtrap.hh, rangeOut).
    • The count is printed once per module at the end of the job, whenever at least one track ranged out, whatever the debug level.
    • I checked that all six modules holding a std::unique_ptr<KKExtrap> call printSummary. No repository other than Offline uses KKExtrap.
  2. 🟢 [follow-up] The PR needed an envset with KinKal v3.9.2. Done.
    • p111 differs from p110 in two lines only: the spack environment name and KINKAL_VERSION (v03_09_01 to v03_09_02).
    • KinKal v3.9.1...v3.9.2 is the KFTrack/KinKal#234 merge only. It adds Track::truncate, Domain::setEdge and a unit test, and changes no existing line. So the bump brings in the function this PR needs and nothing else from KinKal.

Validation check

  • FNALbuild: build 3635 at this head, merged onto main 554ef9f9, passed at 13:07 UTC on 17 November, with every validation job green.
    • The trigger row is ❌ (Return Code 2). Its log lists the same four path changes, with the same counts, as #2163's build 3634 on the same main: apr_TC_calo 2078 against 1947, plus three small cpr_* changes. So the trigger counts do not change with this PR, even though the trigger paths run KinKal fits. The red comes from main; #2116 changed TZClusterFinder in the trigger paths.
    • The six clang-tidy errors are all in cetlib's LibraryManager.h:43. No clang-tidy warning points at a line this PR changes.
  • Build/tests run locally: none. The increment builds in CI, and I read every changed line.
  • Not checked: whether the CI validation jobs print the new summary. None of the logs I read shows a KKExtrap line (ceSimReco, cosmicSimReco, cosmicOffSpill). I did not compare the full spack environments p110 and p111, only the envset files.
  • Config contract check: pass, no fcl change.
  • Cross-repo consistency: pass. Production and mu2e-trig-config do not set an envset in their .muse files.

Residual risk

  • After merge, everyone who builds main moves to p111. Per the two points above, that changes only the KinKal version.

Author follow-ups

  • None from me. brownd1978's change request at 18a24ee asked for the branch to be brought up to date with main. cac2266d did that, but the request stays on the PR until he updates his review.

@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.

My principle request of asking to mark some of these changes as temporary is met. My comments about geometric structures being more natural as part of core KinKal remain, but they refer to earlier already-merged codes and so are out-of-scope for this PR.

@oksuzian
oksuzian merged commit 5f4d92f into Mu2e:main Nov 18, 2026
14 checks passed
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