Skip to content

Feature: detector hits as values, moving a detector empties it - #164

Merged
StackEnjoyer merged 6 commits into
masterfrom
fix/detector-value-hits
Oct 19, 2026
Merged

StackEnjoyer merged 6 commits into
masterfrom
fix/detector-value-hits

Conversation

@StackEnjoyer

@StackEnjoyer StackEnjoyer commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

Features

  • Breaking: detector hits store values only, no reference to the ray or beamlet
  • Breaking: any kinematic call on a detector empties it, also through a group
  • Breaking: position of detector hits removed, use hit_point

Bugfixes

  • Hits of earlier solves changed when the same beam was solved again

Doc changes

  • Detector page: new section "Reading out a detector"
  • Agent skill: SKILL.md, WORKFLOW.md, CHECKLIST.md, components/detectors.md updated

Internal changes

  • Field of stigmatic hits about 2× faster, beamlet hits need 5–10× less memory
  • hit_point(ray) replaces the end point of a ray written out in 15 places

Closes #42

A hit kept a reference to the ray or beamlet that made it, so solving the same beam again
changed the hits of earlier solves (#42). All four hit types now store only the values their
evaluation needs and are isbits:

- RayHit, PolarizedRayHit: hit point, direction, opl, λ, n, projection factor (and E)
- AstigmaticGaussianBeamletHit: its cache plus polarization, segment length and λ
- GaussianBeamletHit: the complex beam parameter q0 = s0 + i z_R at the segment start; the
  field within the segment follows in closed form from q(l) = q0 + l, instead of evaluating
  the waist and divergence rays at every field point. s0, w0 and the divergence come from the
  rays (_local_beam, split off gauss_parameters), so the result equals the ray construction
  for rays in one plane with the chief ray.

The kinematic primitives of AbstractDetector call empty! first: the stored hits belong to the
pose of the detector during the solve. Docs and agent skill state that a detector keeps the
hits of consecutive solves side by side, and that the field functions superpose all of them
coherently.

Closes #42

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.34146% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.18%. Comparing base (0d364ad) to head (66437e9).

Files with missing lines Patch % Lines
src/OpticalComponents/Detectors/Detector.jl 93.33% 2 Missing ⚠️
src/Beam.jl 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #164      +/-   ##
==========================================
+ Coverage   90.13%   90.18%   +0.04%     
==========================================
  Files          82       82              
  Lines        4581     4593      +12     
==========================================
+ Hits         4129     4142      +13     
+ Misses        452      451       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

The beam parameter q0 = s0 + i z_R at the segment start follows from the curvature c and the
local Gouy phase ψ that gauss_parameters already returns: q0 = −i sin(ψ) exp(iψ) / c. This keeps
the invariant of the waist and divergence rays, as _local_beam did, so gauss_parameters is
unchanged against master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StackEnjoyer

StackEnjoyer commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner Author

@TacHawkes some benchmark results:

Benchmark: master (0d364ad3) vs. this branch

Same script on both checkouts, Julia 1.13, 8 threads, Windows. Setup: thin lens → mirror → detector, every beam solved on its own, field on a 200×200 grid. Three alternating runs; the machine varied by up to 50 % between runs, so ranges are given.

Hits on the detector electric_field master electric_field branch Speedup Memory of hits, master Memory of hits, branch
100 GaussianBeamletHit 187–245 ms 43–65 ms 3–5× 222 kB 40 kB
1000 GaussianBeamletHit 1.79–2.84 s 0.63–0.69 s 3–4× 2.1 MB 0.23 MB
1000 AstigmaticGaussianBeamletHit 1.00–1.45 s 1.44–1.92 s not really 6.4 MB 0.62 MB
10 000 RayHit 1.21–1.89 s 1.90–2.03 s not really 1.39 MB 1.07 MB
10 000 PolarizedRayHit 2.07–2.57 s 2.24–2.50 s not really 1.86 MB 1.72 MB
  • Stigmatic hits: the field follows in closed form from the beam parameter at the segment start, instead of evaluating the waist and divergence rays at every grid point.
  • Memory: beamlet hits no longer keep the traced beam tree alive (9–10× less); ray hits store values instead of a reference to the ray.
  • Solve time (including building the hits) and spot_diagram: no difference beyond the noise.
  • Memory measured with Base.summarysize(hits(detector)).

@TacHawkes

Copy link
Copy Markdown
Collaborator

Review

Seems like a better option to solve #42. There are some points you should look into.

Points

  1. "Up to 2 %" understates the change. Beam at (4 mm, 0, 3 mm) through a strong lens (R = ±40 mm, n = 1.7) tilted by 20° about z and 25° about x: at the focus the PR gives a 15.5 µm radius, master 23.8 µm (−35 %); intensity differs by more than 100 % of the peak there.
    • At the segment start both agree. The difference builds up during propagation, because the skew auxiliary rays do not cross.
    • The AstigmaticGaussianBeamlet gives 48 µm there, so neither value is right; the stigmatic model does not apply. The closed form is the more self-consistent of the two.
    • Suggested wording: "Agrees with the ray construction to ≤ 1e-6 where the stigmatic model applies; near the focus of a beam made astigmatic by a tilted lens the radius can differ by tens of percent; use AstigmaticGaussianBeamlet there."
    • Optional: when the invariant check substitutes H = λ/π, the z_R implied by q0 from (R, ψ) differs by 3.6 % from the one implied by w0. A q0 built from (w, R) at the segment start, 1/q0 = R − iλ/(π n w²), would be marginally more consistent (15.97 vs. 15.54 µm in the case above). Not blocking.
  2. Removed API: position(::AbstractRayHit) and length(::AbstractRayHit) are gone, while position(::AbstractBeamletHit) still returns the segment start, not the hit point. Either document that or drop it in favour of hit_point.
  3. Nit, naming: _projection returns |d·n|, _projection_factor returns √|d·n|, and the public projection_factor returns |d·n|. Renaming the second to _sqrt_projection would avoid confusion.
  4. Pre-existing, not from this PR: the AstigmaticGaussianBeamletHit constructor sets l_parent/opl_parent to a literal 0.0 (hard Float64, an AD issue); belongs to Fix AD on optical axis #148.
  5. Release: 0.14.0 is not tagged yet, so the breaking change fits; please list it in the release notes.

uitt_hu and others added 2 commits October 17, 2026 17:37
… hits

- Docstring of GaussianBeamletHit and the stigmatic beam page: the detector field agrees with the
  waist and divergence rays to about 1e-6 where the stigmatic model applies; near the focus of a
  beam made astigmatic by a tilted or decentered lens the radius can differ by tens of percent
- position(::AbstractBeamletHit) removed, as for ray hits: it returned the segment start, not the
  hit point; hit_point reads the fields
- _projection_factor renamed _sqrt_projection, it returns √|d·n|

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Against an AstigmaticGaussianBeamlet, the closed form from q0 at the segment start focused a
beam behind a tilted, decentered lens to the diffraction limit (9.4 µm at 2° tilt, AGB 33 µm,
master 28 µm): it drops that the waist and divergence rays no longer cross. The hit stores the
two rays instead, as offsets y0 + l v from the chief ray on the planes normal to it
(GaussianSegment, isbits), and gauss_parameters(segment, l) evaluates them with the formula of
Arnaud and DeJager. gauss_parameters(gauss, z, ψ0; hint) uses the same method, so a hit and its
beamlet give the same field; w, R and ψ equal master to 1e-9.

The slopes are cot θ = (ŷ·a)/|ŷ × a| instead of tan(π/2 − acos(ŷ·a)), and the plane crossings
are linear in l, so no line-plane intersection per evaluation.

The validity notes of the previous commit are removed, the hit and gauss_parameters no longer
differ.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StackEnjoyer

StackEnjoyer commented Oct 17, 2026 •

Copy link
Copy Markdown
Owner Author

Thanks, all good points.

  1. Going for a complete scalar hit representation was too ambitious. So the hit now stores the waist and divergence rays as values (GaussianSegment, offsets y0 + l v from the chief ray, isbits), and gauss_parameters(segment, l) evaluates them. gauss_parameters(gauss, z, ψ0; hint) uses the same method, so a hit and its beamlet give the same field, and w, R and ψ equal master to 1e-9. The validity notes are therefore gone. The slopes are cot θ = (ŷ·a)/|ŷ × a| and the plane crossings are linear in l, so the field of stigmatic hits is still about 2× faster than on master.
  2. position(::AbstractBeamletHit) is removed, as for ray hits; hit_point is the accessor.
  3. Renamed to _sqrt_projection.
  4. Left for Fix AD on optical axis #148.
  5. Will go into the release notes of 0.14.0.

Fixed in bc9a701.

uitt_hu and others added 2 commits October 18, 2026 22:41
_ray_end and _projection computed what hit_point and projection_factor already name for hits;
they are now methods of these verbs for an AbstractRay. _sqrt_projection is gone, the two
beamlet hits take sqrt(projection_factor(ray)).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The end point position(ray) + length(ray) * direction(ray) was written out in 15 places
(beamsplitters, lenses, mirrors, polarizers, the Gaussian beamlet, Base.show of a beam).
hit_point and projection_factor of an AbstractRay move to the ray interface in AbstractRay.jl,
and these places call hit_point(ray).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StackEnjoyer
StackEnjoyer marked this pull request as ready for review October 18, 2026 21:04
@StackEnjoyer
StackEnjoyer merged commit 7ddb34c into master Oct 19, 2026
7 checks passed
@StackEnjoyer
StackEnjoyer deleted the fix/detector-value-hits branch October 19, 2026 10:42
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.

Bug: Detector hits change when their beam is solved again

2 participants