Skip to content

Truncate trajectory for ranged-out particles. - #234

Merged
brownd1978 merged 1 commit into
KFTrack:mainfrom
RobMina:truncate-trajectory
Nov 7, 2026
Merged

brownd1978 merged 1 commit into
KFTrack:mainfrom
RobMina:truncate-trajectory

Conversation

@RobMina

@RobMina RobMina commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Companion to Mu2e/Offline#2084 (follow-up Offline PR: Mu2e/Offline#2111)

Problem

Track::extrapolate extends the end piece of the fit trajectory in field-domain steps (field correction on) or in
maxDtStep steps (off), and the predicate is only asked after each step. When the predicate stops at a time inside the
last step (in Mu2e, where the particle ranges out in a material it is about to cross), the trajectory and the
outermost domain already run past it, by up to one domain or step. Track has no way to shorten them again, so
everything downstream of the extrapolation (saved segments, sampled surface crossings, the saved domain bounds) also
continues past the stop.

Change

A public bool Track::truncate(TimeDir tdir, double time): the fit trajectory ends at time in direction tdir. The
domains beyond time are removed together with the DomainWalls into them, and the domain containing time ends
there (new Domain::setEdge, which moves a domain's end or begin). Nothing changes, and the return value is false,
unless the fit is usable, time is inside the trajectory, and no active hit or material effect is at or beyond time,
so no piece the fit uses is removed or shortened past it. Inactive hits and crossings beyond time are kept: they
change nothing in the fit, and each holds its own reference piece. Forwards, the trajectory is cut with
PiecewiseTrajectory::setRange(range, true); backwards it is rebuilt from the first piece reaching beyond time, since
setRange keeps the last piece before the range at the front. The state at and before time is unchanged, and a later
extrapolate in the same direction continues from time (the outermost domain edge is time, so coverEndDomain
does nothing). It can be called from inside an extrapolation
predicate: each walk in extrapolate ends as soon as the predicate returns false, without using the end piece again.
Header-only (Fit/Track.hh, Fit/Domain.hh); no class layout changes.

Test

New Tests/Truncate_unit.cc (registered with the other unit tests): ToyMC tracks in the uniform 1 T field of the
other fit unit tests, LoopHelix and CentralHelix, field correction on and off, 3 fits each. Each fit is extrapolated
20 ns past each end and cut twice in each direction: inside the outermost domain beyond the last active hit or
material, then, after extrapolating again, halfway between that effect and the end, which with field correction
removes several domains. It checks that:

  • cuts at the last active effect, outside the trajectory, or non-finite are refused and change nothing;
  • the trajectory ends at the cut, its other end is unchanged, and no piece is added;
  • exactly the domains beyond the cut and the DomainWalls into them are removed, and no wall into a removed domain remains;
  • position and momentum at the cut are unchanged, and so is the fit status;
  • no domain reaches beyond the cut, the domains stay contiguous, and a later extrapolation continues from the cut.

A second case makes the last 4 hits of a track inactive (with no material after the last active hit): after one long
extrapolation step past them, a cut between the last active effect and the first inactive hit is accepted, every
effect is kept, and each inactive hit beyond the cut keeps a usable reference piece.

ctest on v3.9.1 + this change (AL9, e29, Release): 28/28 pass, Truncate with 3 usable fits in each of its 8 cases.

The test uses a uniform field because the ToyMC fits do not converge in a field gradient at v3.9.1, independent of
this change: LoopHelixFit --nevents 20 converges 19/20 fits in the uniform field (both schedule files), 1-5/20 with
--Bgrad -0.036 and 0/20 with --Bgrad -0.1 (GapDiverged/ParamsDiverged), with field correction on or off.

Validation in Mu2e

With the follow-up Offline call (truncate(TimeDir::forwards, stop time) where KKExtrap finds the particle ranges
out), every range-out stop is truncated: 149 of 149 and 111 of 111 on Mu2e nightly off-spill cosmics (10,000 events,
field correction on and off), 39 of 39 on 3,334 production off-spill events. Every track without a stop is unchanged,
and the ranged-out ones lose only what lay beyond the stop: 9 sampled tracker crossings on one nightly track (none in
truth) and 4 on 10,352 Run 2 cosmics, all with field correction; with it off the ntuples are bit-identical.

🤖 Generated with Claude Code

@oksuzian oksuzian left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

PR Review Summary — #234

Reviewed at head 61bd31663ab6746c32bcf615badc9661a085cf54. First pass.

Decision

  • 🟢 approve. Track::truncate does what the description says, and it changes nothing when it refuses. I read it line by line against Track, Domain, DomainWall and PiecewiseTrajectory, and ran it through Mu2e/Offline#2111 on 9,314 off-spill cosmics in two settings and 16,508 nightly reco_03 events: 455 of 465 cuts were made, and every output change is the intended one. One finding: the guard also refuses a cut for material sites that the fit never processed. In Mu2e this blocks 10 of the 465 cuts, including one of the tracks the cut is meant for (finding 1). It does not block.

Scope understood

  • A public bool Track::truncate(TimeDir tdir, double time) (Fit/Track.hh:1084-1122). It ends the fit trajectory at time, removes the domains beyond it with the DomainWalls into them, and trims the domain that contains time with the new Domain::setEdge (Fit/Domain.hh:27). It returns false, changing nothing, unless the fit is usable, time is finite and strictly inside the trajectory, no active non-wall effect lies at or beyond time, and at least one domain remains.
  • A new Tests/Truncate_unit.cc. The change is header-only, with no class layout change.

Findings

  1. 🟡 [S2] The guard counts active material sites that the fit never processed, so it refuses cuts that would remove nothing the fit used.
    • Evidence: Track.hh:1094 refuses whenever any active effect other than a DomainWall lies at or beyond the cut. With Config::ends_ false, iterate processes only the effects between the first and last active measurement (setBounds, Track.hh:735-760). processEnds runs only when ends_ is set (:554). So an active material site after the last active measurement creates no trajectory piece.
      • In Mu2e (Offline#2111, off-spill cosmics, KKCHmu with ProcessEnds: false), 10 of 229 range-out cuts were refused.
      • A temporary print showed that every refusal came from 1 to 8 active straw-material crossings (KKStrawXing) after the cut, and from nothing else. In each case the last active hit was 2.1 to 3.9 ns before the cut.
      • In 9 of the 10, the latest of these crossings lies after the end of the trajectory, by 0.2 to 39 ns.
      • The nightly reco_03 sample had 236 cuts and no refusal.
    • Impact: the protection the PR gives inactive hits ("each holds its own reference piece") applies equally to these sites, but they still block the cut. On one Mu2e track (1430:0:24052), 56 ns of trajectory and 12 sampled tracker crossings stay past the stop. The caller gets only false, so it cannot tell this case apart from a cut that would really remove a piece the fit used.
    • Suggested fix: skip active sites that the fit did not process. A simple test on the last active measurement is not enough, because material added by extrapolate(exing,tdir) also lies after it and does own pieces. If that distinction is too much for this PR, record why a cut was refused (a history_ entry, or a reason the caller can read), so the caller can count it.

Checked, no action needed

  • 🟢 A refusal changes nothing. Every condition is tested before the first change (:1085-1098). After that point, nothing in the function can fail.
  • 🟢 Domains and walls.
    • Forwards, a wall is removed when its next domain is removed; backwards, when its previous domain is (:1099-1101).
    • domains_ is ordered by begin() (Track.hh:68). Moving the first domain's begin later keeps it below its own end, and that end is at or below the next domain's begin. So the order the set relies on still holds.
  • 🟢 A cut exactly on a domain boundary. The unit test does not hit this case; I traced it by reading.
    • Forwards: the domain that begins at time is removed, and outer->end() > time is false, so setEdge is not called.
    • setRange(...,true) (:1107) erases the piece that begins at time, because TimeRange::overlaps uses half-open ranges.
    • Backwards, the end() <= time loop (:1113) does the same.
  • 🟢 Extrapolating again continues from the cut. The outermost domain edge is the cut, so coverEndDomain does nothing. The unit test extrapolates again after each cut.
  • 🟢 Calling it from inside an extrapolate predicate is safe. Each loop in Track::extrapolate ends right after a false predicate, without using endpiece or nearestPiece again. Mu2e calls it outside the predicate anyway: in the sweep, after extrapolate returns.
  • 🟢 The unit test covers both directions, both fields, refusals and repeated cuts.
    • Both directions, LoopHelix and CentralHelix, with field correction on and off.
    • Refusals at the last active effect, outside the trajectory and for a NaN cut.
    • Two cuts per direction, the second removing several domains, each followed by a re-extrapolation.
    • Inactive hits beyond a cut.
    • GitHub Actions ran Truncate at this head in all four configurations (Debug and Release, Ubuntu and macOS): 28 of 28 tests pass. These three files produce no compiler warnings.

Validation check

  • Build/tests run: KinKal standalone build and ctest not run; my session blocked running the PR's build. The GitHub Actions logs above stand in.
  • Mu2e build: Offline#2111 head 18a24eee, with this PR's Fit/Track.hh and Fit/Domain.hh placed over the p110 release headers. Those release headers are byte-identical to git v3.9.1, this PR's base.
    • muse build exited with status 0 and no warnings, and all 1168 compile lines used the overlay.
    • ExtrapolateSweepTest passes.
    • Off-spill cosmics (9,314 events, two settings) and nightly reco_03 (16,508 events): all jobs exited with status 0. Results are in my Offline#2111 review.
  • Config contract check: not applicable.
  • Cross-repo consistency: Offline#2111 needs a tag with this PR and an envset carrying it.

Residual risk

  • Mu2e only cuts forwards, and only inside the end piece and the last domain: KKExtrap adds crossings only on the end piece. So the backwards path and the removal of whole domains run only in the unit test.
  • Not checked: KinematicLine trajectories.

Author follow-ups

  1. Optional: finding 1.

@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 looks good. My only qualm is that the domain time trim is unprotected, and could be used in error. But, since that's a non-const function and no non-const accessor exists outside Track itself the space for an error in negligible.

@brownd1978
brownd1978 merged commit d19623f into KFTrack:main Nov 7, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants