Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions ext/BeamletOpticsOpticsBaseExt.jl
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,10 @@ const _PREFIX = "BeamletOptics/OpticsBase extension"
origin = BeamletOptics.position(detector), axes = <default detector frame, see below>)

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

Expand Down
3 changes: 2 additions & 1 deletion skills/beamletoptics/WORKFLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions src/AstigmaticGaussian.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)))
Expand Down
12 changes: 12 additions & 0 deletions src/Beam.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions src/Gaussian.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
36 changes: 26 additions & 10 deletions src/OpticalComponents/Detectors/Detector.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Update detector-hit lifecycle guidance

The snapshotting introduced here makes the statement in skills/beamletoptics/WORKFLOW.md:46 that detector hits “reference beam state” and must be read before solving again false; the Detector docstring retains the same obsolete warning. Update that user-facing guidance to distinguish safe re-solves from the remaining caveat about evaluating old hits after moving the detector, otherwise the version-matched agent skill teaches behavior this commit intentionally removed.

AGENTS.md reference: AGENTS.md:L103-L112

Useful? React with 👍 / 👎.

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)
Expand All @@ -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}
Expand All @@ -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}
Expand Down Expand Up @@ -252,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

Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down
5 changes: 5 additions & 0 deletions src/PolarizedRays.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 17 additions & 1 deletion src/Rays.jl
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,20 @@ function Ray(pos::AbstractArray{P},
nothing,
F(λ),
F(1))
end
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
56 changes: 56 additions & 0 deletions test/Components/TestDetector.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading