Repository navigation
Bracketed refinement in stepIntersect; helix-plane window when the axis starts past the plane - #235
Conversation
oksuzian
left a comment
There was a problem hiding this comment.
PR Review Summary — #235
Reviewed at head 9c36012ceea48e2f6e286112793e889104a47099. First pass.
Decision
- 🟢 approve. The new test fails on
mainexactly as the PR describes and passes here. Every other unit test prints the same output apart from fit timings. I checked 94,383 random helix queries against planes, cylinders and frustums against a brute-force root search. No crossing thatmainfinds is lost, 2,025 missed crossings are recovered, and the refinement always converges, in at most 13 iterations. In a 600-event Mu2eceSimRecorun on Offlinemain, the 185 fitted tracks are unchanged at printed precision, and only 3 of their 3,880 intersections move, by at most 0.01 mm. KinKal's GitHub Actions passed at this head on Ubuntu and macOS, Debug and Release. The one S2 below is an older problem that this PR makes slightly more visible; it does not block.
Scope understood
stepIntersectkeeps the step in whichisInsidechanged as a bracket and refines inside it. A ray (Newton) step is taken only if it lands inside the bracket and is shorter than half the previous step. Otherwise, or when the ray misses the surface, the bracket is bisected. The search stops when the ray distance or the bracket length falls belowtol, with a cap of 100 iterations.hpIntersectbuilds its search window around the crossing of the helix axis ray with the plane in either direction (forwards = false). A crossing just after the query start is then found even when the axis point at the start is already past the plane.- New unit test
IntersectReturn(32 return-crossing cases, 64 axis-tilt cases), registered inTests/CMakeLists.txt.
Findings
-
🟡 [S2]
hpIntersectsetsinrange_against its narrowed window, not against the caller's range.- Evidence:
Geometry/Intersect.hh:212callsstepIntersect(helix,plane,srange,tol,tdir), andstepIntersectsetsinrange_ = trange.inRange(time_)with thatsrange(:98). The sign-change step can end pastsrange, so a root inside the caller's query but just outside the window comes back withinrange_ = false. In the random comparison below this happens 48 times at this head and 42 times onmain, and 47 of the 48 are the correct first crossing of the query. 40 are CentralHelix planes. The other 8 are cylinders, through the same pattern inhcIntersect(:164), which this PR does not touch. The 6 new cases are CentralHelix planes wheremainreturned nothing, so no caller loses a crossing it had before. - Why CentralHelix:
CentralHelix::linearizereturns the tangent, sotmid ± dtdoes not bound the crossings, as the PR notes. For LoopHelix the window contains every crossing, and I found no such case. - Suggested fix: after the window search, set
retval.inrange_ = trange.inRange(retval.time_)inhpIntersect, and inhcIntersecttoo. The root cause is the CentralHelix window. Building it from the true helix axis (center(t)alongbnom, asLoopHelix::axisdoes) would also recover the 1,930 CentralHelix-plane misses listed under Residual risk. That can be a follow-up.
- Evidence:
-
⚪ [S3]
Tests/IntersectReturn_unit.cc:128-129calls the queries that start before the first crossing "control". The cylinder ones fail onmainbecause the tangent ray misses the cylinder, as the PR body says. On an old build the output therefore reads "control ... FAIL". Calling them reproductions, or labelling the plane and cylinder cases separately, would avoid that confusion.
Verified
- 🟢 The test shows the bug and the fix. I built
maind19623fwith only the new test added, and this head, both Release in the Mu2e p110 environment (GCC 13.3, ROOT 6.38). Onmain,ctestpasses 28 of 29:IntersectReturnfails 16 of 32 return-crossing cases and 6 of 64 axis-tilt cases. The failing times match the PR body: ±2.51748679341 ns withinrange 0for the plane; ±1.91908793842e+12 ns for CentralHelix from the turning point, and nothing for LoopHelix. At this head 29 of 29 pass, with no warnings under-Wall -Werror. - 🟢 The other unit tests print the same output. I ran each of the other 28 test binaries in both builds and compared their full output. Only the
Time/fitline of the four*Fittests differs.Intersection_unitprints its intersection times and positions, and they are identical. - 🟢 The bracket always has one end on each side of the surface.
tstart = ttest - tstepis the last step on the starting side, andtcross = ttestis the first step on the other side (:49-50). Each new point is either the bisection midpoint or a ray step that passed(tnext-tstart)*(tnext-tcross) <= 0(:69), so it lies inside the current bracket, and it replaces the end on its own side (:58-63). The returned time is therefore always inside the step that changed sides. It can lie outside the query only when that step is the last one and overshoots the end of the range. That was already the case before, andinrange_is then false. - 🟢 The search always ends, and
tolkeeps its meaning. The loop is capped at 100 iterations (:53,:55). Each bisection halves the bracket, and each accepted ray step is less than half the one before. Both stopping tests usetolas a distance in mm. The ray step stops at|dist| < tol, the old test with<=changed to<. Bisection stops when the bracket length times the speed is belowtol, so its answer is withintol/2of the root along the path. Time, position, direction, normal andinbounds_are computed at the final time (:88-95). When every ray step is accepted, the iterates are the same as onmain. - 🟢 Iteration counts, measured with counters added to a copy of each header. Over 67,495 brackets at this head the mean is 2.5 to 2.7 iterations (2.5 to 2.6 on
main) and the maximum is 13 (9 onmain). None hit the cap. Withtollowered to 1e-6 mm (2,000 cases) and to 1e-8 mm (400 cases, the value KinKal's trajectory test uses), the maximum is 7 and none hit the cap. If the cap were ever reached, the function returns an emptyIntersection, asmaindoes when it detects non-convergence. - 🟢 Degenerate inputs. A ray parallel to a plane, or one that misses a cylinder, gives
onsurface_ = false;diststarts at 0, and the code bisects. A particle with zero speed cannot produce a sign change, so the refinement is never entered. A bracket with opposite signs at its ends holds an odd number of roots. If it holds three, any of them can be returned, as onmain, and all three lie within one sagitta-limited step. - 🟢 The LoopHelix window holds every crossing, for any field tilt and either time direction. The helix lies on a cylinder of radius R around its axis. Every plane crossing is therefore within R·tanθ, measured along the axis, of where the axis crosses the plane; θ is the angle between the axis and the plane normal.
vaxcarries its sign, sotmidis right for both time directions and either axis orientation. The random comparison has 19,887 LoopHelix plane queries, with the field tilted up to 0.1 rad, normals in all directions, and particles moving both towards and away from the plane. This head misses 19 of them and returns a later root in 4; in all 23 the helix goes less thantolpast the plane.mainmisses 1,312. - 🟢 Random comparison against a brute-force root search. There are 80,000 cases on planes and cylinders, 30% of the cylinders finite, plus 14,383 on frustums. They mix LoopHelix and CentralHelix; electrons, positrons and muons from 20 to 110 MeV/c; a 1 T field tilted up to 0.1 rad; queries 0.2 to 15 ns long in both time directions; and
tolof 0.01, 0.1 or 1 mm. The expected answer is the first sign change ofisInside, found by sampling every 0.02 mm and then bisecting. No case thatmaingets right is wrong at this head. 2,025 cases are recovered: 1,975 on planes and cylinders and 50 on frustums.
Validation check
- Build/tests run: yes. KinKal standalone (CMake, Release) at
d19623fplus the new test, and at this head. I ranctest, then every test binary on its own, and compared their outputs. The harness, cases and results are under/exp/mu2e/data/users/oksuzian/claude-scratch/kinkal235_review/. - Speed: same harness,
-O3, three alternating rounds of 15 passes over the 80,000 cases. Median time perintersectcall for planes is 1,572 to 1,599 ns onmainand 1,837 to 1,849 ns here (+16%). For cylinders it is 3,138 to 3,176 ns and 3,241 to 3,245 ns (+3%). The plane increase is not in the new refinement: where both builds take the same path, the steps (8.00 and 8.00 for LoopHelix) and the refinement iterations (1.54 and 1.56) are the same. It comes from the 4,082 plane queries (10%) thatmainskipped because the axis crossing was behind the start, and that are now searched. In 1,769 of them a crossing is now found. - Mu2e reconstruction: the spack KinKal 3.9.1 in envset p110 has an
Intersect.hhbyte-identical to this PR's base, so the CI build of Offlinemain70243009served as the base. For the head I rebuilt, on that backing, every Offline library that includesIntersect.hh(Mu2eKinKal,CommonRecoand theRecoDataProductsdictionary). Only this PR'sIntersect.hhwas placed first on the include path.LD_DEBUG=bindingsconfirmed that everyintersect,stepIntersectandhpIntersectcall in the head job binds to a rebuilt library. I ran ProductionValidation/ceSimReco.fclwith seed 8 for 600 events in each: 188 events pass the filter, and the fits run on 342. I printed both outputs with the same build (KalSeedPrinterverbose 2, plus helix seeds and straw digis). Straw digis and helix seeds are identical. The 185 keptKKDeKalSeeds have identical summary lines: fit consistency, hits, momentum, t0 and status. Their 3,880 intersections have the same count on every surface (ST_Outer 1,379, IPA 379, foils, TSDA 24, tracker and calorimeter). Three change in the third printed decimal: one IPA crossing moves by 0.001 ns and 0.01 mm, and two ST_Outer crossings by 0.001 mm or 0.001 MeV/c. The fit modules took 17 to 20 ms per event in both builds, within 1 to 4% (one run each). This is a small electron-only sample. The PR's own Mu2e samples cover much more; in its 20,000-event CE sample ST_Outer gains 326 crossings (+0.06%). - Cross-repo consistency: not applicable; KinKal reaches Offline through a release. Offline#2084's plane workaround can go once Offline takes a KinKal tag with this change, as the PR notes.
Residual risk
- The CentralHelix plane window is not changed here. 1,930 of 19,887 random low-momentum CentralHelix plane queries still return nothing at this head (2,426 on
main), while stepping over the whole query finds the crossing. Mu2e's CentralHelix fits are high-momentum cosmics with bend radii of metres, which should mostly take the no-loop branch, and #233 found no disagreement in 134,639 Mu2e queries. So I do not expect a Mu2e effect today. canIntersect(:116), also not touched here, misses cylinder crossings when the field is tilted from the cylinder axis. It tests whether the helix circle and the cylinder circle are nested only at the two ends of the query, while the helix axis drifts across in between. This accounts for 1,038 of the 28,083 random queries on long cylinders, the same in both builds. The angle between field and cylinder axis in those cases has a median of 165 mrad and a minimum of 1.2 mrad. In one example the circle centres are 160.3 mm and 151.96 mm apart at the two ends, against a cut of 152.4 mm (|R_cyl − R_bend| − tol), yet the helix goes 5.4 mm into the cylinder in between. Mu2e's cylinders along z take this branch whenever a piece loops within the query, so a piece whosebnomis tilted from z can lose a crossing. It deserves its own issue.- Not checked: a local Debug build (CI ran Debug on both platforms).
Author follow-ups
- Optional in this PR: report
inrange_against the caller's range after the window search inhpIntersect(finding 1). - Consider opening issues for the CentralHelix window (build it from the helix axis) and for
canIntersectwith a tilted field. Neither blocks this PR.
brownd1978
left a comment
There was a problem hiding this comment.
Thanks for this improvement, I like the bracketed test better than the previous cycle count logic. Thanks also for adding the intersection unit test. My only (minor) concern is improving human readability.
oksuzian
left a comment
There was a problem hiding this comment.
PR Review Summary — #235
Reviewed at head d1b19c87b0af7ec1f7990a0617a1e3a10d94aef6. Re-review of 9c36012.
Decision
- 🟢 approve, as before. The increment fixes both of my findings and both of brownd1978's comments. The bracket rewrite gives the same results as before. The new
inrange_rule recovers 43 correct crossings in my earlier random comparison and loses none. KinKal's GitHub Actions passed at this head on Ubuntu and macOS, Debug and Release (12:59 to 13:01 UTC on 17 November).
What changed since 9c36012
- One commit,
d1b19c87"Improve readability" (Geometry/Intersect.hh+13 −5,Tests/IntersectReturn_unit.cc+7 −5). stepIntersectbuilds the bracket as an unorderedTimeRange. The ray step must land inside it, ends included. Bisection usesbracket.mid()andbracket.range().- After a search in a narrowed window,
hcIntersect,hpIntersectand the frustum function setinrange_against the caller's range. - The
hpIntersectcomment now says the ray is the helix axis for LoopHelix and the tangent for CentralHelix. - The "control" test cases are renamed "small-tol" and "first-crossing".
Prior findings
- 🟢 [was S2]
inrange_was set against the narrowed window, not the caller's range. FIXED in d1b19c8, verified.- The new line follows each window search at
Intersect.hh:169,:219and:263. In each,trangeis the caller's range. - The bracket rewrite does not change any returned time, so I replayed the new rule on my 94,383 cases from 9c36012:
- 43 crossings that were found but marked out of range are now correct: 40 CentralHelix planes, 2 finite cylinders and 1 frustum.
- No case that was correct changes.
- 6 crossings of a finite cylinder that has no in-bounds crossing now report
inrange_true. All 6 haveinbounds_false, so a caller that also checks bounds is not affected. - The one case whose crossing really lies outside the query is still reported out of range.
- The new line follows each window search at
- 🟢 [was S3] The "control" label in
IntersectReturn_unit.cc. FIXED: the cases are now called "small-tol" and "first-crossing", and a comment says why the cylinder ones failed before #233 was fixed.
Checked, no action needed
- 🟢 The bracket rewrite is the same test as before.
TimeRange(tstart,tcross,false)swaps the ends whentcross < tstart(General/TimeRange.hh:16-23), so the bracket is ordered in both time directions.tnext >= begin && tnext <= endis the closed test the old product(tnext-tstart)*(tnext-tcross) <= 0made.mid()is0.5*(tstart+tcross), andrange()isfabs(tcross-tstart).- The comment correctly gives the reason for not using
inRange: a converged step lands exactly on a bracket end, andinRangeexcludes the end.
- 🟢 brownd1978's two comments are addressed: the bracket now uses
TimeRange, and thehpIntersectcomment no longer assumes a LoopHelix.
Validation check
- Build/tests run: no new build. The replay above reuses the harness results from my first pass (
claude-scratch/kinkal235_review/cases/) and recomputesinrange_with the new rule. That is valid because the returned times are unchanged, as shown above. - CI: 4 of 4 GitHub Actions jobs passed at this head.
- Cross-repo consistency: not applicable. Offline picks this up through a KinKal release; Offline#2111 now marks its plane workaround for removal once that happens.
Residual risk
- Unchanged from my first pass: the CentralHelix plane window and
canIntersectwith a tilted field can still miss crossings. Neither is touched here, and neither blocks.
Author follow-ups
- None blocking. The two issues suggested in my first pass (the CentralHelix window and
canIntersectwith a tilted field) are still worth opening.
|
@brownd1978 @oksuzian replies on the two readability threads are above (addressed in |
brownd1978
left a comment
There was a problem hiding this comment.
Thanks for maximal reuse of TimeRange class. I understand the issue with closed vs open brackets.
Beyond the scope of this PR: 'closed' could be added as an optional argument to inRange (default false). what do you think?
Fixes #233
Problem
KinKal::intersectfor helices can miss a crossing inside the query, in three ways (all inGeometry/Intersect.hh):stepIntersectleaves the sign-change step. After stepping to the first step in whichisInsidechanges, therefinement backs up one step and iterates
ttest += dist/speedwith the ray intersection (forwards = false)without any bound. If that step contains a turning point of the distance to the surface, the tangent at the
backed-up start points away from the surface and the iteration converges to the earlier root, outside the query
(
inrange_ = false); the root inside the step is never tried. This is the case in Helix-planeintersectreturns an earlier root outside the time range and misses the crossing inside it #233.stepIntersectgives up when the ray misses. If the tangent ray does not meet the surface, the iteration stopsand returns no intersection. This happens at a turning point (ray parallel to a plane: LoopHelix returns nothing;
CentralHelix converges on a crossing of another turn, ~1.9e12 ns away), and when the tangent of a helix
approaching a cylinder at a grazing angle passes outside the cylinder although the helix curves into it.
hpIntersectrequires the axis crossing to be ahead. When the helix loops within the query, the search windowis centred on the crossing of the helix axis ray (
linearize) with the plane, found withforwards = true. If thepoint on the axis at the query start is already past the plane (field tilted from the plane normal, particle less
than about
R sin(tilt)in front of the plane), there is no forward crossing,stepIntersectis never called, anda crossing just after the start is lost. This matches the two in-bounds TSDA misses reported in Helix-plane
intersectreturns an earlier root outside the time range and misses the crossing inside it #233 (Mu2eLoopHelix fits starting 0.48 and 0.52 mm in front of the plane, crossings 0.003 and ~0.06 ns into the query); it is
reproduced in the unit test below. The TSDA misses do not occur on current Offline main, so they could not be
rechecked in Mu2e reco.
Change
stepIntersect: the sign-change step is kept as a bracket[tstart, tcross]and shrunk by the side(
isInside) of each new point. A linear (ray) step is taken only if it lands inside the bracket and is less thanhalf the previous step; otherwise the bracket is bisected, and the search ends when the bracket is shorter than
tol. A ray that misses the surface also bisects. This is a safeguarded Newton search (rtsafe), so the root found isalways inside the step that changed sides, for every surface type. When every linear step stays in the bracket and halves
the previous one, the iterates are the same as before. The non-convergence test over cycles of 5 iterations is replaced by an iteration
cap of 100.
hpIntersect: the axis-ray crossing is found in either direction (forwards = false). The windowtmid +- dtcontains every crossing of the helix with the plane and is then restricted to the query, so this only recovers
crossings.
Test
New
Tests/IntersectReturn_unit.cc, registered with the other unit tests (no ROOT output):intersectreturns an earlier root outside the time range and misses the crossing inside it #233: muon, p = (100, 0, 20) MeV/c, 1 T, R = 333.6 mm; the helix goes 0.15 mm pastthe surface and comes back;
tol= 0.1 mm), for aRectangleand for aCylinderalong the field whose axis isoffset by R/2 (same half-width), LoopHelix and CentralHelix, forwards and backwards. The query starts 0.5
half-widths before the turning point (outside the tolerance slab) or at it, and ends after the return crossing,
which must be found. Controls:
tol= 0.05 mm, and a query that starts before the first crossing (which must befound).
of the plane with cos = -0.53, 8 momentum azimuths, both directions, both helix types; the crossing 0.003 ns after
the start must be found.
Results (AL9, e29, Release, GCC 13.3, ROOT from envset p111):
d19623f+ testctestIntersectReturnfails)On main:
inrange 0(expected±2.61548917256), as in Helix-plane
intersectreturns an earlier root outside the time range and misses the crossing inside it #233; from the turn: LoopHelix nothing, CentralHelix ±1.91908793842e+12 ns;inrange 0; query frombefore the first crossing: nothing (the tangent ray misses the cylinder). From the turn, the cylinder cases pass;
CentralHelix cases pass (its
linearizeis the tangent ray, which starts at the particle);tol= 0.05 mm controls pass, for both surfaces.The output of every other unit test is identical between the two builds except the
Time/fitlines of the four*Fittests.Validation in Mu2e reconstruction
Offline main
30088f392(envset p110) built twice with a local KinKal: maind19623f, andd19623f+ this change.The two areas differ only in
Geometry/Intersect.hh. In Offline,KinKal::intersectis used by the fits' materialcrossings (
KKShellXing) and by the KKExtrap sweep for non-planar surfaces; the sweep finds plane crossings itself(
planeCrossing, the #2084 workaround). The same inputs and event counts went through both builds.avggapdiffers by ~1e-12 on 5 tracks)data_like_no_primaryST_Outer(stopping-target outer cylinder) crossingsST_Outer(+0.06 %)TT_Outer,EMC_Disk_1_Inner)The added crossings are on cylinders, where
stepIntersecton main can give up when the tangent ray misses thesurface (case 2).
Plane check with a temporary diagnostic (not part of any PR): every plane query of the sweep is also passed to
KinKal::intersect, and disagreements with the sweep's bracketed search are counted (LoopHelix; CentralHelix had nonein either build):
With this change every remaining disagreement is on the stopping-target foil planes at grazing incidence (|cos| <
0.025: a touch within the tolerance, or a query that starts inside the tolerance slab), and all but 3 are outside the
foil annulus. Those 3 are on a foil at |cos| < 0.02 in both builds, below the incidence floor Mu2e applies to foils,
so no material changes. Of the misses on main with |cos| >= 0.02, all 6 in reco_03 and 7 of 10 in off-spill are
recovered; the other 3 are at |cos| 0.020-0.023, off the foils.
CPU and memory (art TimeReport; the two builds ran on two GPVMs of the same type, 4-core AMD EPYC):
The fit modules change by the same fraction as the modules this change cannot affect, so there is no measurable CPU
difference. Peak virtual memory is identical; the resident high-water mark is 2-3 % higher in both runs of the PR
build, which ran on the other host, and identical for KinematicLine. The change allocates nothing.
Notes
CentralHelix::linearizereturns the tangent, not the axis, so for CentralHelix the window inhpIntersectisbuilt around the tangent-ray crossing. That window is not guaranteed to contain every crossing; the Mu2e cross-check
in Helix-plane
intersectreturns an earlier root outside the time range and misses the crossing inside it #233 found no CentralHelix disagreement in 134,639 plane queries, and this PR does not change it.ExtrapolateSweep::visitPlaneExtrema/planeCrossing); thatworkaround can be removed once Offline uses a KinKal tag with this change.
🤖 Generated with Claude Code