BeamletOptics.jl

Appearance

Beams and sources ​

This page explains how the beams and sources described in the Beams section, including the beam groups, work internally, and what a developer has to provide so that a new beam type, beam group or source sampling works with the solver.

Beam interface ​

A Beam stores a vector of rays, and the beamlets are built from it: a GaussianBeamlet traces a chief, a waist and a divergence Beam side by side, an AstigmaticGaussianBeamlet a chief Beam of PolarizedRays and eight auxiliary ones. The diagram shows the beam types, the beams and rays they are made of, and the interface a new beam type implements. All three beam types are subtypes of AbstractBeam (frame); the beamlets store their rays in Beams, so in the end every beam type holds its rays in the Vector of a Beam:

Tracing a beamlet ​

Components define BeamletOptics.interact3d for a Beam and one of its rays; a beamlet hands this call on to each of its component beams, unless the component defines a method for the beamlet itself. The diagram shows the tracing loop of a GaussianBeamlet and where the methods of a component author are called; an AstigmaticGaussianBeamlet runs the same loop with its nine beams and also checks its complex invariant:

Interface contracts ​

The docstrings of the abstract types list what a subtype implements: fields, getters and functions.

BeamletOptics.AbstractBeam Type
julia
AbstractBeam{T <: Real, R <: AbstractRay{T}}

A generic type for a container type which holds rays, beams etc.

Parametrization

A subtype of AbstractBeam is parameterized by its main data type T <: Real, as well as the underlying ray representation R <: AbstractRay{T}. If a beam is to be compatible with different AbstractRay implementations, it must be parameterized by T and R. However, it can also be set to a fixed type for T and R, i.e. MyBeam <: AbstractBeam{Float32, MyRay}.

Implementation reqs.

Subtypes of AbstractBeam must implement the following:

Fields

  • parent: a Nullable field that holds the same type as the subtype, used for tree navigation

  • children: a vector that holds the same type as the subtype, used for sub-beam tracking, i.e. beamsplitting

Getters/setters

The tree functions parent, children and isroot (from AbstractTrees) work via the parent/children fields.

Functions

  • trace_system!(system, beam; r_max, kwargs...): traces the beam from its last ray through the system until no object is hit or an interaction returns nothing

  • push!(beam, interaction): appends the result of an interaction to the beam

  • _component_beams(beam): returns a tuple of the beams that store the rays of beam, chief beam first. A beam that stores its rays itself (e.g. Beam) returns (beam,)

A beam that stores its rays itself must also implement rays and empty!, otherwise the generic methods recurse. Everything else (rays, first_ray, empty!, position, direction, the lengths and the kinematic API) has generic methods built on _component_beams.

Kinematic

AbstractBeams are BeamletOptics.Movable with a BeamletOptics.Directed frame, see BeamletOptics.AbstractKinematicTrait. A subtype needs no move methods of its own: the generic translate3d!/rotate3d! move the start ray of every component beam. Rotations are applied about the position of the beam, i.e. the start of first_ray. reset_rotation3d! throws an ArgumentError, since a beam has no orientation.

Warning

Only root beams can be moved. Every move resets the beam to its untraced start state via empty!; moving a child beam throws an ArgumentError.

source
BeamletOptics.AbstractBeamGroup Type
julia
AbstractBeamGroup

Provides a generic container type interface for bundles of Beams. This interface assumes that there exists a central beam around which the bundle propagates, e.g. akin to an optical axis.

Implementation reqs.

Subtypes of AbstractBeamGroup must implement the following:

Fields

  • beams: a vector or tuple of root AbstractBeams, e.g. Beams or AstigmaticGaussianBeamlets

  • center: a Point3{T} which is regarded as the source position, i.e. the reference origin (pivot) of the group

  • dir: a SMatrix{3,3,T,9} that describes the local coordinate system of the group

The columns of dir are the local x-, y- and z-axis. They must form a right-handed orthonormal basis, like the dir of an ObjectGroup. The local y-axis (second column) is the central source direction, i.e. the optical axis of the group. The local x-axis (first column) is the reference vector of the azimuthal sampling (the basis of the source constructors). Unlike a direction vector, the orientation therefore also tracks a roll of the group about its own optical axis.

Since the kinematic API modifies center and dir, the subtype must be a mutable struct.

Getters/setters

If the fields above do not exist, the following getters/setters must be dispatched:

  • beams: getter for the beams field or equivalent return type

  • position / position!: gets or sets the source position (pivot)

  • orientation / orientation!: gets or sets the orientation matrix

  • wavelength: getter for the common wavelength of the beam bundle

The central source direction is derived from the orientation via direction.

Functions

None required; the kinematic primitives below are generic.

Kinematic

An AbstractBeamGroup is a container: it takes the kinematic class of its beams, i.e. BeamletOptics.Movable with an BeamletOptics.Oriented frame for movable beams, see BeamletOptics.AbstractKinematicTrait. The constructors check that the beams are either all static or all movable. The following logic is applied to

  • translate3d!: all beams and the group center are translated by the offset vector

  • rotate3d!: all beams are rotated around the center point with respect to their relative position, orientation is rotated

  • reset_translation3d! / reset_rotation3d!: moves the group back to the origin or its standard orientation (identity: the central source direction/optical axis is the global +y-axis and the azimuthal sampling reference vector basis is the global +x-axis); the beams are always reset, even if the group is already at the identity

  • set_pivot3d!: moves the group center (the pivot used above) without moving or resetting the beams

Except for set_pivot3d!, every command resets each beam to its untraced start state.

source
BeamletOptics.AbstractSourceSampling Type
julia
AbstractSourceSampling

How the rays of a CollimatedSource or PointSource are sampled. The source stores its sampling in the field sampling, such that num_rays! can regenerate its rays with another number of rays. A source built from given beams stores BeamletOptics.NoSampling. The generic constructors CollimatedSource(pos, dir, diameter, sampling, λ; num_rays) and PointSource(pos, dir, sampling, λ; num_rays) build a source from any sampling; the catalog constructors call them.

Implementation reqs.

Parameters of the sampling other than the number of rays (e.g. the number of rings or the half spread angle) are fields of the subtype.

Functions

A subtype S <: AbstractSourceSampling implements:

  • source_beams(s::S, pos, dir, b1, args..., λ, num_rays::Int, T) -> Vector{<:Beam}: the beams of the source, see BeamletOptics.source_beams. args are the arguments of the source type, i.e. the diameter [m] for a CollimatedSource and none for a PointSource. The sampling pattern must depend on the pose only via pos, dir and b1, i.e. it must move rigidly with the source. The first beam must be the center ray, which starts at pos along dir. Throws an ArgumentError if num_rays is below min_num_rays(s).

  • min_num_rays(s::S) -> Union{Nothing, Int} (optional): the fewest rays of the sampling, default 1, see BeamletOptics.min_num_rays.

  • numerical_aperture(s::S): the numerical aperture of the half spread angle, required for a sampling of a PointSource. The fallback throws an ErrorException.

Implementations

source

Source sampling ​

A CollimatedSource or PointSource stores how its rays were sampled as a BeamletOptics.AbstractSourceSampling, such that num_rays! can regenerate them with another number of rays in the current pose of the source. The diagram shows how the constructors and num_rays! generate the beams with BeamletOptics.source_beams: dotted arrows are its dispatch branches on the sampling type.

An own sampling is a subtype of BeamletOptics.AbstractSourceSampling with a method of source_beams; the generic constructors and num_rays! then work for it without further code. A sampling for a PointSource also implements numerical_aperture(s). A sampling with a lower bound on the number of rays implements min_num_rays(s), and its source_beams throws an ArgumentError for a num_rays below it, as the samplings of BMO do.

Solving a beam group internally ​

The diagram shows the steps of solve_system!(system, bg). A new BeamletOptics.AbstractBeamGroup subtype provides the getter of its beams, as a beams field or a method.