Skip to content

Provide backup t0 algorithm for inconsistent piecewise trajectories - #231

Merged
brownd1978 merged 5 commits into
KFTrack:mainfrom
brownd1978:t0fix
Nov 3, 2026
Merged

brownd1978 merged 5 commits into
KFTrack:mainfrom
brownd1978:t0fix

Conversation

@brownd1978

@brownd1978 brownd1978 commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

The existing code chose an effectively random t0 value when the trajectory had no consistent piece. Now pick the closest to consistent piece. This avoids a rare exception when extrapolating.

@brownd1978
brownd1978 requested a review from RobMina October 28, 2026 21:38

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

Reviewed at head 4e68ec4656111e728840fc3ee786be2249e763e8. First pass.

Decision

  • 🟢 approve. The fallback does what the description says for a trajectory that cycles between pieces. On the full Mu2e nightly reconstruction sample, nothing changes. Two points are worth a look before a release: the fallback also fires on chains that converged (finding 1), and t0() can still lie outside the trajectory, so callers must keep clamping it (finding 2).

Scope understood

  • PiecewiseTrajectory::t0() iterates "take the t0 of the piece nearest the current t0" until the piece stops changing. The iteration limit drops from 10 to 5 (Trajectory/PiecewiseTrajectory.hh:252). When the limit is reached, a new fallback scans every piece and returns the t0 of the piece whose own t0 is closest to its own time range (:259-268), using a new TimeRange::minTimeTo (General/TimeRange.hh:44-46).
  • Before, a trajectory with no self-consistent piece returned whatever t0 the 10th iteration landed on.
  • In Mu2e, t0() is what KKFit stores as the KalSeed t0 (Offline Mu2eKinKal/inc/KKFit.hh:695). It is also used for the direction test in addStrawHits (:485-498), the charge in CentralHelixFit (:380, :404), and the extrapolation reference in KKExtrap (:101, :175).

Findings

  1. 🟡 [S2] The fallback also fires on chains that converged.
    • The test is if(niter >= maxniter) (:259), so it is true when the loop converges exactly on iteration 5. With the limit lowered from 10 to 5, it is also true for every chain that would have converged on iterations 6 to 10.
    • The fallback then returns the first piece with the smallest distance, which need not be the piece the iteration converged on.
    • Demonstration, a standalone program linked against the v3.9.0 libraries (source at the end of this review). The trajectory is 8 pieces. The iteration visits pieces 3, 4, 5, 6 and 7 and converges on piece 7 at iteration 5, while pieces 1 and 2 are also self-consistent. main returns 7.6, the converged value. This PR returns 1.5, piece 1's. A 10-piece version that converges on iteration 7 gives 9.6 against 1.5.
    • For a real track with one z=0 crossing, self-consistent pieces sit next to each other near the crossing, so the difference should be small. On the nightly sample below, no printed value changed.
    • Suggested fix: test non-convergence directly, if(static_cast<int>(index) != oldindex). Then a converged chain always keeps its result, whatever the limit.
  2. 🟡 [S2] t0() is still not guaranteed to lie inside the trajectory's time range, and the fallback can now move it outside.
    • A trajectory whose z=0 time is before its first piece is a fixed point of the iteration: the front piece's t0 maps back to the front piece. The fallback never runs, and the result is unchanged and outside the range (case "before-begin": -0.5 on [0,4], both builds).
    • This is the shape of the Mu2e nightly crash fixed in Offline#2076. On run 1430, subrun 1652, event 852, a KKUe track had t0 466.92 ns against a trajectory starting at 480.92 ns. With this PR's headers, that track still has t0 466.922 against a range of 480.916 to 587.867 ns, identical to v3.9.0. So this PR would not have prevented that crash.
    • In a cycle, the fallback can pick a piece whose t0 lies past the end of the whole trajectory. In case "cycle-fallout", pieces 1 and 2 cycle, and the end piece has the smallest distance (0.3) with t0 4.3 on [0,4]. main returns 1.1, inside. This PR returns 4.3, outside.
    • The case the PR targets does improve. In case "cycle-out", a 2-cycle where main's 10th iteration lands on 2.5, outside [0,2], this PR returns 0.5, inside.
    • So callers that build a TimeRange from t0() still have to clamp it. Offline does this in KKExtrap::toTrackerPerimeter and, since #2076, in toCaloDisk. A comment on t0() saying it can lie outside range() would help the next caller. Alternatively, the fallback could prefer pieces whose t0 lies inside the trajectory.
  3. ⚪ [S3] Small items.
    • for(auto piece : pieces_) (:262) copies a shared_ptr per piece. auto const& piece avoids the atomic reference-count traffic.
    • Ties keep the first piece (strict <). That is deterministic, but a comment would say so.
    • minTimeTo returns 0 for t == end(), although inRange(end()) is false for the half-open range. That is harmless here and arguably what "distance" should mean, but the comment "0 if in range" undersells it. For a null range it returns |t - begin|, which is fine.
    • The new comment says almost all trajectories converge in at most 2 iterations. I did not count iterations. The unchanged nightly output fits that claim but does not prove it.

Validation check

  • GitHub Actions: all four test configurations pass at this head (Release and Debug, Ubuntu and macOS).
  • Standalone t0() test: the same t0test.cc, built once with the KinKal v3.9.0 headers (main 8fa3f62c, the release Offline uses) and once with those headers plus this PR's two files, both linked against the v3.9.0 libraries. Each piece is a LoopHelix placed so its z=0 time is set independently of its range.
case main this PR
one self-consistent piece 2.5 (inside) 2.5
z=0 before the first piece -0.5 (outside) -0.5 (outside)
2-cycle, main ends outside 2.5 (outside) 0.5 (inside)
2-cycle, best-scoring piece past the end 1.1 (inside) 4.3 (outside)
converges on iteration 5 7.6 1.5
converges on iteration 7 9.6 1.5
  • Mu2e reconstruction: Offline main 77c4233d with Offline#2076's clamp, built twice against the v3.9.0 libraries. One build used the release headers. The other added this PR's two headers ahead of every include path, which I confirmed by preprocessing a Mu2eKinKal source. I ran the nightly Production/Validation/nightly/reco_03.fcl input, all 16508 events, with every KalSeed collection printed per event (PrintModule verbose 2: fit summary and all intersections).
    • All 16508 events run with both builds.
    • The printouts are identical, event by event, for KKDe, KKUe, KKDmu, KKUmu and the trigger-level fits. That is 1,277,862 intersections. The precision is 0.1 ns for track t0 and 0.001 ns for intersection times, so smaller shifts would not show.
  • Not checked: the KinKal test suite locally (CI covers it), and fit quantities other than the KalSeed printout.
Standalone test (t0test.cc)
#include "KinKal/Trajectory/PiecewiseTrajectory.hh"
#include "KinKal/Trajectory/LoopHelix.hh"
#include <cstdio>
#include <vector>
using namespace KinKal;
// a LoopHelix piece on [tbeg,tend) whose z=0 time (its t0 parameter) is t0wanted
static LoopHelix piece(double tbeg, double tend, double t0wanted){
  VEC4 pos(10.0,20.0,0.0,t0wanted);
  MOM4 mom(30.0,40.0,80.0,0.511);
  return LoopHelix(pos,mom,-1,VEC3(0.0,0.0,1.0),TimeRange(tbeg,tend));
}
// piece i spans [i,i+1) with t0 = t0s[i]
static void run(const char* name, std::vector<double> const& t0s){
  PiecewiseTrajectory<LoopHelix> ptraj(piece(0.0,1.0,t0s[0]));
  for(size_t i=1;i<t0s.size();++i) ptraj.append(piece(double(i),double(i+1),t0s[i]));
  printf("%-14s t0() = %.3f on [%g,%g]\n", name, ptraj.t0(), ptraj.range().begin(), ptraj.range().end());
}
int main(){
  run("consistent",    {2.5,2.5,2.5,2.5});
  run("before-begin",  {-0.5,-0.5,-0.5,-0.5});
  run("cycle-out",     {2.5,0.5});
  run("cycle-fallout", {1.5,2.9,1.1,4.3});
  run("converge-at-5", {3.5,1.5,2.5,4.5,5.5,6.5,7.5,7.6});
  run("converge-at-7", {3.5,1.5,2.5,4.5,5.5,6.5,7.5,8.5,9.5,9.6});
}

@RobMina RobMina 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! I think callers still need to ensure they pass valid time ranges.

@brownd1978

Copy link
Copy Markdown
Collaborator Author

I think callers still need to ensure they pass valid time ranges.

Agreed. There's nothing physical that guarantees t0 (time reference parameter) must be in range. Thanks for making that fix.

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

Reviewed at head 486d5b20988210f74406cebd858621e0c7cd2fe1. Re-review of 4e68ec4656111e728840fc3ee786be2249e763e8.

Decision

  • 🟢 approve. The increment fixes the case I showed in finding 1, documents finding 2 as I asked, and takes one of the small points. Nothing below blocks.

What changed

  • The fallback now runs only when the loop ended without converging, if(static_cast<int>(index) != oldindex) (Trajectory/PiecewiseTrajectory.hh:259), instead of niter >= maxniter.
  • The comment on t0() now says the result is not guaranteed to be in range (:245).
  • The fallback loop takes auto const& piece (:262).

Prior findings

  1. 🟡 [S2, now ⚪ S3] The fallback fired on chains that converged. PARTIAL.
    • Fixed: a chain that converges exactly at the limit keeps its result. In my test, converge-at-5 now gives 7.6, the same as main. At the previous head it gave 1.5.
    • Still open: the limit is now 5 instead of 10. So a chain that needs 6 to 10 iterations still ends unconverged and takes the fallback, where main would have converged. converge-at-7 gives 1.5 here and 9.6 on main. In that test the fallback still returns a self-consistent piece, just a different one.
    • Your comment says almost all trajectories converge within 2 iterations. If so, this never matters. Keeping the limit at 10 would make the change apply only to trajectories that never converge.
  2. 🟢 [was 🟡 S2] t0() is not guaranteed to lie inside the trajectory range. Addressed: the comment on t0() now says so, and you confirmed callers must pass valid time ranges. The behaviour is by design. cycle-fallout still returns 4.3 on [0,4], as documented.
  3. ⚪ [S3] Small items.
    • FIXED: the fallback loop no longer copies a shared_ptr per piece.
    • Open: the tie-break (first piece wins) has no comment.
    • Open: minTimeTo returns 0 at end(), although inRange(end()) is false (General/TimeRange.hh:44, unchanged).
    • Open: the "at most 2 iterations" claim in the comment is not measured.

New

  1. ⚪ [S3] A fixed point at either end of the trajectory skips the fallback, even when another piece is self-consistent. This is not changed by this PR.
    • nearestIndex maps any time at or before begin() to piece 0, and any time at or after end() to the last piece (PiecewiseTrajectory.hh:202-205).
    • So if the front piece's t0 lies before begin(), the first iteration maps it back to piece 0, and the loop counts that as converged.
    • Test case end-clamp: piece t0s {-0.5, 1.5, 1.5, 1.5} on [0,4]. Pieces 1 to 3 are self-consistent (1.5 lies in [1,2)), but t0() returns -0.5 on both main and this head.
    • This needs pieces that disagree about their z=0 time, so it is probably rare. If you want the fallback to catch it, the convergence test could also require pieces_[index]->range().inRange(t0).

Validation check

  • KinKal GitHub Actions: all four test configurations pass at this head.
  • The standalone t0test from my first review, unchanged. It is built against the KinKal v3.9.0 headers (main 8fa3f62c), and against those headers overlaid with this PR's two files at each head. All builds are linked against the v3.9.0 libraries. The overlay files are identical to the PR's at 486d5b20.
case main 4e68ec46 486d5b20
one self-consistent piece 2.5 2.5 2.5
z=0 before the first piece -0.5 -0.5 -0.5
2-cycle, main ends outside 2.5 0.5 0.5
2-cycle, best piece past the end 1.1 4.3 4.3
converges on iteration 5 7.6 1.5 7.6
converges on iteration 7 9.6 1.5 1.5
end-clamp (new) -0.5 not run -0.5
  • The Mu2e nightly comparison (all 16508 reco_03 events) was not rerun.
    • At this head, the fallback runs only when the loop ends unconverged after 5 iterations. That is a subset of the cases where it ran at 4e68ec46, and in those cases the fallback output is the same.
    • In every other case, t0() returns the loop result, which equals main's.
    • At 4e68ec46, every printout matched main, so this head matches too, at the same print precision.

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

Reviewed at head a6fad58be681313fdb33a105ece565a7ee1df835. Re-review of 486d5b20.

Decision

  • 🟢 approve. The new start check fixes the front-end case of my last finding, and in Mu2e it changes t0() for most downstream fits, in the right direction. Unlike the previous heads, this commit does change Mu2e reconstruction output, so finding 1 asks for that to be said in the description.

What changed

  • One commit, "Add test for first and last piece in t0 search" (Trajectory/PiecewiseTrajectory.hh:245-252). If the front piece's t0 lies before the front piece's range, the search now starts from the back piece's t0. If the start time then lies after the back piece's range, it starts from the middle of the trajectory. The comment now says the result is not guaranteed to be in range "or unique".
  • This only moves the starting point. The iteration, the 5-iteration limit and the fallback are unchanged, so the result can differ only when the front piece's t0 is before the trajectory or the start time is after it.

Findings

  1. 🟡 [S2] This commit changes Mu2e reconstruction output for most downstream fits, which the description does not mention
    • Evidence: I rebuilt Offline (the #2076 fix tree, 68b28d6e) with this head's two headers overlaid on the v3.9.0 release headers, and ran all 16,508 events of the nightly reco_03 job. I compared every KalSeed printout with the same tree built against v3.9.0. At 4e68ec46 the two were identical; at this head:
      • 13,290 of 16,491 KKDe and 13,179 of 16,316 KKDmu fits save more trajectory segments (median +13 and +16, never fewer).
      • The momentum and t0 that KalSeed reports from its saved segments change for 68 and 619 KKDe fits (at most 0.15 MeV/c and 0.4 ns) and for 100 and 778 KKDmu fits (at most 2.4 MeV/c and 1.8 ns).
      • One KKUe track gains four calorimeter crossings (see the checked items below). Nothing else changes: fit consistency, hit counts, flags, every other crossing and all five trigger collections are identical.
    • Mechanism: after Mu2e extrapolates a downstream fit upstream, the trajectory's front piece is usually the reflected leg, moving upstream, so its z=0 time lies before the trajectory. On v3.9.0 the search maps that time back to piece 0 and stops there. With this commit it starts from the back piece and converges on the tracker piece. Offline's KKFit::createSeed uses the direction at t0() to decide which tracker-boundary crossings bound the saved segments, so it now keeps the segments between TT_Front and the first hit.
      • Example: on 1430:1612:3 KKDmu, the first saved segment starts at 1568.04 ns on v3.9.0. At this head it starts at 1566.11 ns, at TT_Front (1566.12 ns).
    • Impact: this looks like a correction rather than a regression, because createSeed was meant to keep those segments. Still, once a KinKal tag with this PR is in a Mu2e envset, the nightly validation will show these shifts.
    • Suggested fix: say in the description that the start check changes t0() for consistent trajectories whose front piece lies before the trajectory (in Mu2e, reflected extrapolations), not only for the rare inconsistent case.

Prior findings

  • ⚪ [S3] The 5-iteration limit: carried over, still open. The new commit does not change it. converge-at-7 still gives 1.5 here and 9.6 on main.
  • 🟢 [was 🟡 S2] t0() not guaranteed to be in range: resolved by design at 486d5b20. The comment now also says the result is not unique, which matches the test below: with pieces 1 and 3 both self-consistent, main returns -0.5 and this head returns 3.5.
  • ⚪ [S3] Small items: still open, untouched by this commit. These are the missing tie-break comment, minTimeTo returning 0 at end(), and the unmeasured "at most 2 iterations" comment.
  • ⚪ [S3] A fixed point at either end skips the fallback: PARTIAL.
    • Fixed: when the front piece's t0 is before the trajectory, the search no longer stops at piece 0. end-clamp ({-0.5, 1.5, 1.5, 1.5} on [0,4]) now gives 1.5, against -0.5 on main.
    • Still open: a chain that reaches an end piece by iteration still counts as converged there. walk-to-front ({-0.5, 1.5, 0.5, 2.5}) gives -0.5, and walk-to-back ({3.5, 1.5, 1.5, 4.5}) gives 4.5, on main and at this head, although piece 1 is self-consistent in both. The suggestion from my last review covers both ends and the start: also require pieces_[index]->range().inRange(t0) before counting the loop as converged.
    • Related: when no piece is self-consistent, an out-of-range result can now land on the other side. side-flip ({-0.5, 3.5, 0.5, 4.5}) gives -0.5 on main and 4.5 here. Both are outside the range, as documented, but a caller that clamps now clamps to the opposite end.

Checked, no action needed

  • 🟢 The event behind Mu2e/Offline#2076 now gets a t0 inside its range. On 1430:1652:852, the second KKUe track's t0() was 466.922 against a range of 480.916 to 587.867 on v3.9.0 and at the earlier heads. At this head it is 531.674. The calorimeter search starting from it adds four calorimeter-disk crossings at 512 to 518 ns, and the job runs to completion as before.
  • 🟢 Consistent trajectories keep their result wherever the start is unchanged: consistent, before-begin (every piece before the range, -0.5) and after-end (every piece after it, 4.5) give the same value on main, 486d5b20 and this head.
  • 🟢 Merges: git merge-tree of this head with #232 (435af80d) and with main (8fa3f62c) is clean. #231 touches General/TimeRange.hh and Trajectory/PiecewiseTrajectory.hh, and #232 touches only Fit/Track.hh.
  • 🟢 GitHub Actions: all four test configurations pass at this head.

Validation check

  • Standalone t0() test, built against the v3.9.0 headers and against them with this PR's two files overlaid, at 486d5b20 and at this head, all linked against the v3.9.0 libraries. Piece i spans [i, i+1), and each case lists the pieces' z=0 times:

    case main 486d5b20 this head
    consistent {2.5 ×4} 2.5 2.5 2.5
    before-begin {-0.5 ×4} -0.5 -0.5 -0.5
    after-end {4.5 ×4} 4.5 4.5 4.5
    cycle-out {2.5, 0.5} 2.5 0.5 0.5
    cycle-fallout {1.5, 2.9, 1.1, 4.3} 1.1 4.3 4.3
    converge-at-5 7.6 7.6 7.6
    converge-at-7 9.6 1.5 1.5
    end-clamp {-0.5, 1.5, 1.5, 1.5} -0.5 -0.5 1.5
    end-clamp-back {2.5, 2.5, 2.5, 4.5} 2.5 2.5 2.5
    walk-to-front {-0.5, 1.5, 0.5, 2.5} -0.5 -0.5 -0.5
    walk-to-back {3.5, 1.5, 1.5, 4.5} 4.5 4.5 4.5
    side-flip {-0.5, 3.5, 0.5, 4.5} -0.5 -0.5 4.5
    two-consistent {-0.5, 1.5, 3.5, 3.5} -0.5 -0.5 3.5
  • Mu2e: a muse build (p109) of Offline 68b28d6e with this head's headers overlaid (all 1,166 compile lines carry the overlay, and the preprocessed LoopHelixFit_module.cc contains the new start check). I ran the full 16,508-event reco_03 job (all six chunks rc 0) and the two single-event jobs quoted above.

  • The 486d5b20 increment was not measured on its own. It only changes when the fallback runs, and only for unconverged chains. At 4e68ec46 the fallback already ran in a superset of those cases, and every printout matched v3.9.0. So the differences above come from this commit's start check.

  • Not run: KinKal's own tests locally, Offline#2084 with this head, the off-spill or CentralHelix fits, and any truth-matched comparison of the changed KalSeed t0 and momentum.

Author follow-ups

  1. Mention in the description that the start check changes t0() for consistent trajectories whose front piece lies before the trajectory (finding 1).
  2. Optional: count a fixed point as converged only when t0 is inside that piece's range, which also covers the remaining end cases.

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

Reviewed at head 69375ef37ffc7c6bee2ffa54a2f39af3f0697cd1. Re-review of a6fad58.

Decision

  • 🟢 approve. The new check closes the remaining end-piece case from my last review, and Mu2e reconstruction output is identical to the previous head.

What changed

  • One commit, "Add additional convergence test" (Trajectory/PiecewiseTrajectory.hh:263). The fallback to the piece closest to self-consistent now also runs when the iteration settles on a piece whose t0 is outside that piece's range. Because nearestIndex returns the piece containing an interior time, this can only change the result when the search settles on the front or back piece.

Prior findings

  • 🟢 [was ⚪ S3, partial] A chain that walks into an end piece counted as converged. FIXED in 69375ef, verified. In the standalone test, walk-to-front ({-0.5, 1.5, 0.5, 2.5} on [0,4]) and walk-to-back ({3.5, 1.5, 1.5, 4.5}) now give 1.5, the self-consistent piece 1, where main and a6fad58 gave -0.5 and 4.5. The side effect I noted last time is gone too: side-flip ({-0.5, 3.5, 0.5, 4.5}, no self-consistent piece) gives -0.5 again, the same as main, instead of 4.5. All other cases are unchanged from a6fad58.
  • 🟡 [S2] The description does not say that this PR changes Mu2e reconstruction output. Carried over, still open. The description is unchanged. This head gives the same shifts as a6fad58 (see Validation), so the earlier numbers still apply: against KinKal v3.9.0, 13,290 of 16,491 KKDe and 13,179 of 16,316 KKDmu fits save more segments, and the reported t0 and momentum move by at most 1.8 ns and 2.4 MeV/c.
  • ⚪ [S3] The 5-iteration limit. Carried over, still open. converge-at-7 still gives 1.5 here, against 9.6 on main.
  • 🟢 [was 🟡 S2] t0() is not guaranteed to be in range. This was resolved by design at 486d5b2, and it is unchanged.
  • ⚪ [S3] Small items. Carried over, still open. These are the missing tie-break comment, the "at most 2 iterations" comment that nothing measures, and minTimeTo returning 0 at end(). Since the fallback now runs in more cases, the tie-break matters a little more: in side-flip the front and back pieces are equally close, and the front one wins because it comes first.

Checked, no action needed

  • 🟢 Event 1430:1652:852, behind Mu2e/Offline#2076: its second KKUe track still gets t0() = 531.674, inside its range of 480.916 to 587.867, as at a6fad58.
  • 🟢 Merges: this head merges cleanly with KinKal main 095b69a, which now includes #232.
  • 🟢 GitHub Actions: all four test configurations pass at this head.

Validation check

  • Standalone t0() test with all 13 cases, built against the v3.9.0 headers and against this PR's headers at 486d5b2, a6fad58 and this head.
  • Mu2e: a muse build (p109) of Offline 68b28d6e with this head's two headers overlaid on the v3.9.0 release headers (all 1,166 compile lines carry the overlay, build rc 0). I ran all 16,508 events of the nightly reco_03 job, and all six chunks finished with rc 0. Every KalSeed printout (fit summaries, flags and intersections for all nine collections) is byte-identical to the a6fad58 run. I also ran the single-event debug job for 1430:1652:852.
  • Not run: KinKal's own tests locally, Offline#2084 with this head, and the off-spill or CentralHelix fits.

Author follow-ups

  1. Mention in the description that the start check changes t0() for consistent trajectories whose front piece lies before the trajectory (carried-over finding).

@brownd1978
brownd1978 merged commit fe14342 into KFTrack:main Nov 3, 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