From bd7ba007eb4f342817fad3fca8b3c579602bba27 Mon Sep 17 00:00:00 2001 From: Oliver Kliebisch Date: Sat, 10 Oct 2026 10:15:26 +0200 Subject: [PATCH 1/2] Detector hits keep a copy of the traced beam, not the live beam A detector keeps the hits of earlier solves, such that several sources solved one after another superpose. The hits however referred to the traced beam: `RayHit`/`PolarizedRayHit` to its ray, the beamlet hits to the beamlet and a segment index. `solve_system!` reuses the beam, its first ray and its vectors of rays, and moving a beam moves its first ray, hence solving the same beam again without initializing changed the stored hits: e.g. the field of a `GaussianBeamletHit` on the second segment of a beamlet dropped from 690 to 17 V/m after the beamlet was solved again with a moved mirror. Affected were hits on the first ray of every beam type and hits of beamlets on later rays. The hits now store `detached_copy`s: of the ray for ray hits, of the whole beamlet (with copies of its parent beamlets) for beamlet hits. The copies share the `Intersection`s, which are not changed after the tracing step that computes them. Copying the whole beamlet, not only the segments up to the hit, keeps the hits of intermediate segments (e.g. built by the OpticsBase extension) as they were. Solving a beamlet onto a detector through three lenses takes 1-4 % longer and allocates 29 % more for beamlets. Fixes #42 --- src/AstigmaticGaussian.jl | 6 +++ src/Beam.jl | 12 +++++ src/Gaussian.jl | 7 +++ src/OpticalComponents/Detectors/Detector.jl | 28 ++++++++--- src/PolarizedRays.jl | 5 ++ src/Rays.jl | 18 ++++++- test/Components/TestDetector.jl | 56 +++++++++++++++++++++ 7 files changed, 125 insertions(+), 7 deletions(-) diff --git a/src/AstigmaticGaussian.jl b/src/AstigmaticGaussian.jl index d7b165360..bcb7a6ada 100644 --- a/src/AstigmaticGaussian.jl +++ b/src/AstigmaticGaussian.jl @@ -285,6 +285,12 @@ function parent!(child::AstigmaticGaussianBeamlet, parent::AstigmaticGaussianBea return nothing end +function detached_copy(agb::AstigmaticGaussianBeamlet, n::Integer = length(rays(agb.c))) + snapshot = AstigmaticGaussianBeamlet(map(b -> detached_copy(b, n), _component_beams(agb))...) + isnothing(agb.parent) || parent!(snapshot, detached_copy(agb.parent)) + return snapshot +end + function Base.show(io::IO, agb::AstigmaticGaussianBeamlet) p0 = position(first(rays(agb.c))) d0 = direction(first(rays(agb.c))) diff --git a/src/Beam.jl b/src/Beam.jl index 009655785..233c50770 100644 --- a/src/Beam.jl +++ b/src/Beam.jl @@ -43,6 +43,18 @@ end first_ray(b::Beam) = first(rays(b)) +""" + detached_copy(beam, n = length(rays(beam))) + +Returns a copy of the first `n` rays of the `beam` that shares no mutable state with it, see +`detached_copy(ray)`. The copy of a [`Beam`](@ref) has no parent and no children. The copy of a +beamlet ([`GaussianBeamlet`](@ref), [`AstigmaticGaussianBeamlet`](@ref)) has the copies of its +parent beamlets as parents, since their paths enter its length and phase, but no children. +""" +function detached_copy(b::Beam{T, R}, n::Integer = length(rays(b))) where {T, R} + return Beam{T, R}(map(detached_copy, view(rays(b), 1:n)), nothing, Beam{T, R}[]) +end + _chief_beam(b::Beam) = b function translate3d!(::Movable, b::Beam, offset) diff --git a/src/Gaussian.jl b/src/Gaussian.jl index 87377eb90..1a02194c3 100644 --- a/src/Gaussian.jl +++ b/src/Gaussian.jl @@ -107,6 +107,13 @@ end """Return a tuple of the `chief`, `waist` and `divergence` beams of the [`GaussianBeamlet`](@ref).""" _component_beams(g::GaussianBeamlet) = (g.chief, g.waist, g.divergence) +function detached_copy(g::GaussianBeamlet, n::Integer = length(rays(g.chief))) + snapshot = GaussianBeamlet(map(b -> detached_copy(b, n), _component_beams(g))..., + wavelength(g), beam_waist(g), electric_field(g)) + isnothing(g.parent) || parent!(snapshot, detached_copy(g.parent)) + return snapshot +end + first_ray(g::GaussianBeamlet) = first_ray(g.chief) Base.length(gauss::GaussianBeamlet) = length(gauss.chief) diff --git a/src/OpticalComponents/Detectors/Detector.jl b/src/OpticalComponents/Detectors/Detector.jl index 3bd400cf2..12dff3034 100644 --- a/src/OpticalComponents/Detectors/Detector.jl +++ b/src/OpticalComponents/Detectors/Detector.jl @@ -115,16 +115,24 @@ function projection_factor(hit::AbstractRayHit) abs(dot(direction(hit), normal3d(intersection(hit.ray)))) end -"Stores a [`Ray`](@ref) hit" +""" +Stores a [`Ray`](@ref) hit: a copy of the `ray` (see `detached_copy`), such that a new solve of the +beam does not change the hit, and its optical path length `opl`. +""" struct RayHit{T} <: AbstractRayHit{T} ray::Ray{T} opl::T + RayHit(ray::Ray{T}, opl::Real) where {T} = new{T}(detached_copy(ray), opl) end -"Stores a [`PolarizedRay`](@ref) hit" +""" +Stores a [`PolarizedRay`](@ref) hit: a copy of the `ray` (see `detached_copy`), such that a new +solve of the beam does not change the hit, and its optical path length `opl`. +""" struct PolarizedRayHit{T} <: AbstractRayHit{T} ray::PolarizedRay{T} opl::T + PolarizedRayHit(ray::PolarizedRay{T}, opl::Real) where {T} = new{T}(detached_copy(ray), opl) end polarization(hit::PolarizedRayHit) = polarization(hit.ray) @@ -142,7 +150,9 @@ abstract type AbstractBeamletHit{T} <: AbstractDetectorHit end GaussianBeamletHit{T} <: AbstractBeamletHit{T} Stores a [`GaussianBeamlet`], where `l0` represents the length of the parent beam -up until the current beam section, identified by the `id` index. +up until the current beam section, identified by the `id` index. The `gauss` of the hit is a copy +of the traced beamlet (see `detached_copy`), such that a new solve of the beam +does not change the hit. """ struct GaussianBeamletHit{T} <: AbstractBeamletHit{T} gauss::GaussianBeamlet{T} @@ -159,7 +169,9 @@ end AstigmaticGaussianBeamletHit{T} <: AbstractBeamletHit{T} Stores an [`AstigmaticGaussianBeamlet`], where `l0` represents the length of the parent beam -up until the current beam section, identified by the `id` index. +up until the current beam section, identified by the `id` index. The `agb` of the hit is a copy +of the traced beamlet (see `detached_copy`), such that a new solve of the beam +does not change the hit. """ struct AstigmaticGaussianBeamletHit{T} <: AbstractBeamletHit{T} agb::AstigmaticGaussianBeamlet{T} @@ -383,7 +395,9 @@ a beamlet on a plane of one's own. `l0` is the length of the beam (including its up to the start of the segment. The projection factor is `1` if the segment ends without an intersection. """ -function GaussianBeamletHit(g::GaussianBeamlet{R}, id::Integer) where {R} +function GaussianBeamletHit(traced::GaussianBeamlet{R}, id::Integer) where {R} + # a new solve of the traced beamlet must not change the hit + g = detached_copy(traced) ray = g.chief.rays[id] l0 = _length_before(g.chief, id) p0 = position(ray) @@ -405,7 +419,9 @@ path from the source (parents included), the Gouy factor and the reference ampli traced segment, e.g. to sample a beamlet on a plane of one's own. The projection factor is `1` if the segment ends without an intersection. """ -function AstigmaticGaussianBeamletHit(agb::AstigmaticGaussianBeamlet{R}, id::Integer) where {R} +function AstigmaticGaussianBeamletHit(traced::AstigmaticGaussianBeamlet{R}, id::Integer) where {R} + # a new solve of the traced beamlet must not change the hit + agb = detached_copy(traced) # Pre-calculate cache chief = rays(agb.c)[id] p0 = position(chief) diff --git a/src/PolarizedRays.jl b/src/PolarizedRays.jl index 6a926bd11..57ffd3fa6 100644 --- a/src/PolarizedRays.jl +++ b/src/PolarizedRays.jl @@ -112,6 +112,11 @@ function PolarizedRay( ) end +function detached_copy(ray::PolarizedRay{T}) where {T} + return PolarizedRay{T}(position(ray), direction(ray), intersection(ray), + wavelength(ray), refractive_index(ray), polarization(ray)) +end + abstract type AbstractJonesMatrix{T} <: AbstractMatrix{T} end # Required methods for AbstractArray diff --git a/src/Rays.jl b/src/Rays.jl index 1efd2b7ca..d3aebcfd7 100644 --- a/src/Rays.jl +++ b/src/Rays.jl @@ -42,4 +42,20 @@ function Ray(pos::AbstractArray{P}, nothing, F(λ), F(1)) -end \ No newline at end of file +end + +""" + detached_copy(ray) + +Returns a copy of the `ray` that shares no mutable state with it, i.e. a later change of the +`ray`, e.g. by a new solve or a move of its beam, does not change the copy. The copy shares the +[`Intersection`](@ref) of the `ray`: an intersection is not changed after the tracing step that +computes it, a new solve replaces it. + +Detector hits store such copies, since [`solve_system!`](@ref) reuses the beam, its first ray and +its vector of rays in the next solve. See also `detached_copy(beam, n)`. +""" +function detached_copy(ray::Ray{T}) where {T} + return Ray{T}(position(ray), direction(ray), intersection(ray), + wavelength(ray), refractive_index(ray)) +end diff --git a/test/Components/TestDetector.jl b/test/Components/TestDetector.jl index 509d8b839..e109f1e11 100644 --- a/test/Components/TestDetector.jl +++ b/test/Components/TestDetector.jl @@ -330,6 +330,62 @@ end end end +@testset "A new solve does not change the stored hits" begin + # The hits of a solve stay as they were when the same beam is solved again without + # initializing, i.e. the hits keep no reference to the traced, live beam. + E0 = [1.0, 0, 0] + beams = ( + "Beam" => () -> Beam([0.0, 0, 0], [0.0, 1, 0], 1e-6), + "Beam of PolarizedRays" => () -> Beam([0.0, 0, 0], [0.0, 1, 0], 1e-6, E0), + "GaussianBeamlet" => () -> GaussianBeamlet([0.0, 0, 0], [0.0, 1, 0], 1e-6, 1mm), + "AstigmaticGaussianBeamlet" => () -> AstigmaticGaussianBeamlet([0.0, 0, 0], [0.0, 1, 0], 1e-6, 1mm)) + # what a hit holds, also the field of a beamlet hit near its hit point + record(h::BMO.AbstractRayHit) = (BMO.hit_point(h), BMO.position(h), BMO.direction(h), + BMO.projection_factor(h), BMO.optical_path_length(h)) + function record(h::BMO.AbstractBeamletHit) + p = BMO.hit_point(h) + return (p, BMO.position(h), BMO.direction(h), BMO.projection_factor(h), + BMO.beamlet_hit_field(h, p), BMO.beamlet_hit_field(h, p + [0.3mm, 0, 0.2mm])) + end + # the hit is on the first ray, on the second ray behind a mirror, or on a child beam + for (label, beam) in beams, path in (:direct, :mirror, :splitter) + @testset "$label, $path" begin + pd = Detector(20mm) + system = System([pd]) + if path === :mirror + m = RoundPlanoMirror(30mm, 5mm) + zrotate3d!(m, deg2rad(45)) + translate3d!(m, [0, 50mm, 0]) + zrotate3d!(pd, deg2rad(90)) + translate3d!(pd, [100mm, 50mm, 0]) + push!(system, m) + else + translate3d!(pd, [0, 150mm, 0]) + end + if path === :splitter + bs = ThinBeamsplitter(30mm) + zrotate3d!(bs, deg2rad(45)) + translate3d!(bs, [0, 50mm, 0]) + push!(system, bs) + end + b = beam() + solve_system!(system, b) + @test BMO.hit_count(pd) == 1 + before = record(only(BMO.hits(pd))) + # move the source and the mirror or splitter, the beam still hits the detector + translate3d!(b, [0, 0, 0.5mm]) + path === :mirror && translate3d!(m, [5mm, 0, 0]) + path === :splitter && translate3d!(bs, [0, 10mm, 0]) + solve_system!(system, b) + @test BMO.hit_count(pd) == 2 + after = record(first(BMO.hits(pd))) + @test all(map(isequal, before, after)) + # the new hit is where the moved beam is + @test BMO.hit_point(last(BMO.hits(pd)))[3] ≈ 0.5mm + end + end +end + end # TESTSET end # MODULE \ No newline at end of file From b38316c145a0bb693075f6ff2c2276deda420f4c Mon Sep 17 00:00:00 2001 From: Oliver Kliebisch Date: Sat, 10 Oct 2026 22:27:27 +0200 Subject: [PATCH 2/2] Update the guidance on reading detector hits The hits are copies since the previous commit: solving again or moving a beam or another object no longer changes them. What remains is that the hits are stored in world coordinates while `spot_diagram`, `electric_field` and `PlaneField(detector)` evaluate them in the current pose of the detector, hence they are read before the detector itself is moved. Updated: the `Detector` docstring, the `PlaneField(detector)` docstring of the OpticsBase extension and the agent skill (`WORKFLOW.md`). --- ext/BeamletOpticsOpticsBaseExt.jl | 6 ++++-- skills/beamletoptics/WORKFLOW.md | 3 ++- src/OpticalComponents/Detectors/Detector.jl | 8 ++++---- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/ext/BeamletOpticsOpticsBaseExt.jl b/ext/BeamletOpticsOpticsBaseExt.jl index 278cb0eca..1c99dfb54 100644 --- a/ext/BeamletOpticsOpticsBaseExt.jl +++ b/ext/BeamletOpticsOpticsBaseExt.jl @@ -40,8 +40,10 @@ const _PREFIX = "BeamletOptics/OpticsBase extension" origin = BeamletOptics.position(detector), axes = ) Samples the coherent field of the beamlets hitting a BeamletOptics (BMO) `Detector` into -an [`OpticsBase.PlaneField`](https://StackEnjoyer.github.io/OpticsBase.jl/dev/). Call it after `solve_system!` and before moving any object, solving again or -emptying the detector. Requires `using OpticsBase` (package extension). +an [`OpticsBase.PlaneField`](https://StackEnjoyer.github.io/OpticsBase.jl/dev/). Call it after `solve_system!`. The hits are +copies that a later solve does not change, but the default `origin` and `axes` follow the current +pose of the detector: call it before moving the detector. Requires `using OpticsBase` (package +extension). # Arguments diff --git a/skills/beamletoptics/WORKFLOW.md b/skills/beamletoptics/WORKFLOW.md index 53acc58a4..ca05204f1 100644 --- a/skills/beamletoptics/WORKFLOW.md +++ b/skills/beamletoptics/WORKFLOW.md @@ -43,7 +43,8 @@ for y in ys end ``` -- Read everything you need from a detector **before** moving anything or solving again (hits reference beam state). +- Hits are copies: solving again or moving a source or another component does not change the stored hits. + They are evaluated in the current pose of the detector, so read what you need **before** moving the detector itself. - See `templates/01_singlet_spot_diagram.jl` (focus scan) and `templates/04_michelson_scan.jl` (fringes). ## Interferometers and coherent sums diff --git a/src/OpticalComponents/Detectors/Detector.jl b/src/OpticalComponents/Detectors/Detector.jl index 12dff3034..922ec9205 100644 --- a/src/OpticalComponents/Detectors/Detector.jl +++ b/src/OpticalComponents/Detectors/Detector.jl @@ -264,10 +264,10 @@ of a **left-handed** (x, z) surface coordinate system, where incoming beams inte all beams can hit the same detector concurrently. The order of the stored hits is not deterministic. !!! warning "Reading hits" - Read the hits of the detector before moving any object or solving again. - The hits refer to the rays and beams of the current solve, which a new call of - [`solve_system!`](@ref) replaces (child beams and all rays after the first are new objects), - and moving objects afterwards leaves the stored hits inconsistent with the system. + A hit stores a copy of the ray or beamlet that hit the detector: solving again or moving a beam or + another object does not change the stored hits. They are stored in world coordinates, whereas + [`spot_diagram`](@ref), [`electric_field`](@ref) and the functions based on them evaluate the hits + in the current pose of the detector. Evaluate the hits before moving the detector itself. # Fields