Reference

This page contains the full source code documentation and the literature referenced througout this website.

Literature

B. A. Madruga, C. C. Dorian, M. Sehgal, A. J. Silva, M. Shtrahman, D. Aharoni and P. Golshani. Open-source, high performance miniature multiphoton microscopy systems for freely behaving animals, bioRxiv (2024).
A. Manny. Simulation of the contrast mechanisms of a heterodyne two-color interferometer. Master's thesis, Faculty of Aerospace Engineering and Geodesy, University of Stuttgart (Dec 2024).
L. Boussemaere. OpenRAMAN: a low-cost, high-performance open-source Raman spectrometer, https://www.open-raman.org/. Hardware licensed under CERN-OHL-W-v2. Accessed 2026-07-31.
B. Richards and E. Wolf. Electromagnetic diffraction in optical systems, II. Structure of the image field in an aplanatic system. Proc. R. Soc. Lond. A 253, 358–379 (1959).
G. Yun, K. Crabtree and R. A. Chipman. Three-dimensional polarization ray-tracing calculus I: definition and diattenuation. Appl. Opt. 50, 2855–2865 (2011).
G. Yun, S. C. McClain and R. A. Chipman. Three-dimensional polarization ray-tracing calculus II: retardance. Appl. Opt. 50, 2866–2874 (2011).
G. Fowles. Introduction to Modern Optics. Dover Books on Physics Series (Dover Publications, 1989).
M. Ware and J. Peatross. Physics of Light and Optics (Black & White) (Brigham Young University, Department of Physics, 2015).
B. Saleh and M. Teich. Fundamentals of Photonics. Wiley Series in Pure and Applied Optics (Wiley, 2019).
J. Arnaud. Representation of Gaussian beams by complex rays. Appl. Opt. 24, 538–543 (1985).
J. Ashcraft, poke v0.1.0, https://zenodo.org/10.5281/zenodo.7117214 (Sep 2022).
G. Wanner, E. Kochkina, C. Mahrdt, V. Müller, S. Schuster, G. Heinzel and K. Danzmann. Simulating laser interferometers for missions such as (E)Lisa, Lisa pathfinder and Grace follow-on. In: International Conference on Space Optics — ICSO 2014, Vol. 10563, edited by Z. Sodnik, B. Cugny and N. Karafolas (International Society for Optics and Photonics, SPIE, 2017); p. 105632G.
R. Herloski, S. Marshall and R. Antos. Gaussian beam ray-equivalent modeling and optical design. Appl. Opt. 22, 1168–1174 (1983).
D. DeJager and M. Noethen. Gaussian beam parameters that use Coddington-based Y–NU paraprincipal ray tracing. Appl. Opt. 31, 2199–2205 (1992).
A. W. Greynolds. Propagation Of Generally Astigmatic Gaussian Beams Along Skew Ray Paths. In: Diffraction Phenomena in Optical Engineering Applications, Vol. 0560, edited by D. M. Byrne and J. E. Harvey (International Society for Optics and Photonics, SPIE, 1986); pp. 33–51.
A. W. Greynolds. Vector Formulation Of The Ray-Equivalent Method For General Gaussian Beam Propagation. In: Current Developments in Optical Engineering and Diffraction Phenomena, Vol. 0679, edited by R. E. Fischer, J. E. Harvey and W. J. Smith (International Society for Optics and Photonics, SPIE, 1986); pp. 129–133.
R. Wilhelm. Comparing geometrical and wave-optical algorithms of a novel propagation code applied to the VLTI. In: Wave-Optical Systems Engineering, Vol. 4436, edited by F. Wyrowski (International Society for Optics and Photonics, SPIE, 2001); pp. 89–100.
A. W. Greynolds. Fat Rays Revisited: A Synthesis of Physical and Geometrical Optics with Gaußlets. In: Classical Optics 2014 (Optica Publishing Group, 2014); p. ITu1A.3.
N. Worku and H. Gross. Vectorial field propagation through high NA objectives using polarized Gaussian beam decomposition. In: Optical Trapping and Optical Micromanipulation XIV, Vol. 10347, edited by K. Dholakia and G. C. Spalding (International Society for Optics and Photonics, SPIE, 2017); p. 103470W.
E. Kochkina. Stigmatic and astigmatic Gaussian beams in fundamental mode : impact of beam model choice on interferometric pathlength signal estimates. Ph.D. Thesis, Leibniz U., Hannover (2013).
J. N. Ashcraft, E. S. Douglas, R. Anche, B. D. Dube, K. Z. Derby, L. Furenlid, M. Kautz, D. Kim, K. Milani and A. J. Riggs. A generalized expression for accelerating beamlet decomposition simulations. Opt. Express 32, 18068–18086 (2024).
E. Kochkina, G. Wanner, D. Schmelzer, M. Tröbs and G. Heinzel. Modeling of the general astigmatic Gaussian beam and its propagation through 3D optical systems. Appl. Opt. 52, 6030–6040 (2013).
International Organization for Standardization. ISO 10110-12:2019 Optics and photonics – Preparation of drawings for optical elements and systems – Part 12: Aspheric surfaces (2019).
J. Sasián. Aspheric Surfaces. In: Introduction to Lens Design (Cambridge University Press, 2019); pp. 21–29.
J. Korger, T. Kolb, P. Banzer, A. Aiello, C. Wittmann, C. Marquardt and G. Leuchs. The polarization properties of a tilted polarizer. Opt. Express 21, 27032–27042 (2013).
E. Hecht. Optik (De Gruyter, Berlin, Boston, 2018).
P. Hanrahan. A survey of ray-surface intersection algorithms. In: An Introduction to Ray Tracing (Academic Press Ltd., GBR, 1989); pp. 79–119.
T. Möller and B. Trumbore. Fast, minimum storage ray/triangle intersection. In: ACM SIGGRAPH 2005 Courses, SIGGRAPH '05 (Association for Computing Machinery, New York, NY, USA, 2005); p. 7–es.
S. Osher and R. Fedkiw. Signed Distance Functions. In: Level Set Methods and Dynamic Implicit Surfaces (Springer New York, New York, NY, 2003); pp. 17–22.
L. McMillan, G. D. Bruce and K. Dholakia. Meshless Monte Carlo radiation transfer method for curved geometries using signed distance functions. Journal of Biomedical Optics 27, 083003 (2022).

Index

julia

BeamletOptics

Non-sequential 3D ray and Gaussian beamlet tracing for optical setups ("BMO"). Documentation: https://juliaphysics.github.io/BeamletOptics.jl/stable/

AI coding assistants

The package ships an agent skill that teaches assistants such as Claude Code how to use BMO. Install the copy matching this package version into a project with BeamletOptics.install_agent_skill.

source

BeamletOptics.Nullable Type

julia

Nullable{T}

An alias which results in Union{T, Nothing} to provide a shorter notation for struct fields which can containing nothing.

source

BeamletOptics.NullableVector Type

julia

NullableVector{T}

An alias which results in Union{Vector{T}, Nothing} to provide a shorter notation for struct fields which can containing nothing.

source

BeamletOptics.RefractiveIndex Type

julia

RefractiveIndex

Union type that represents valid means to pass a refractive index n to e.g. AbstractObjects. The core assumption is that:

the refractive index is callable with a single Number argument λ to represent the wavelength in [m]
the return value is a single Number value for the refractive index

Refer to e.g. DiscreteRefractiveIndex.

source

BeamletOptics._GOLDEN_ANGLE Constant

julia

_GOLDEN_ANGLE

The golden angle π(3 - √5) ≈ 2.39996 rad, i.e. the azimuthal increment of the sunflower (Fibonacci) sampling shared by UniformDiscSource and UniformPointSource.

source

BeamletOptics._RenderTypes Type

A collection of all types from BMO which might be renderable in principle.

source

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

Functions:

_modify_beam_head!: modifies the beam path for retracing purposes
_last_beam_intersection: returns the last Beam intersection
empty!: resets the beam to its unsolved state
first_ray: returns the start ray on the optical axis of the beam; for beamlets the first chief ray. Defines the generic position/direction of the beam (the pivot for rotations)

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

Kinematic API:

AbstractBeams are BeamletOptics.Movable with a BeamletOptics.Directed frame, see BeamletOptics.AbstractKinematicTrait. 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. 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.

To support the kinematic API, a subtype additionally implements one of the following:

_component_beams: for beams made up of component Beams (e.g. GaussianBeamlet), returns a tuple of these beams. The generic translate3d!/rotate3d! then delegate to them.
translate3d!(::Movable, beam, offset) and rotate3d!(::Movable, beam, R::AbstractMatrix): for beams that store rays directly (e.g. Beam), move the start ray(s) via the ray verbs.

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.

AbstractBeamGroup 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
orientation: a SMatrix{3,3,T,9} that describes the local coordinate system of the group

The columns of orientation are the local x-, y- and z-axis. They must form a right-handed orthonormal basis, like the orientation 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 orientation, the subtype must be a mutable struct.

Functions:

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.

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.AbstractBeamletHit Type

julia

AbstractBeamletHit

Stores beamlet hits. Currently implemented:

GaussianBeamletHit

source

BeamletOptics.AbstractBeamsplitter Type

julia

AbstractBeamsplitter <: AbstractObject

A generic type to represent an AbstractObject that splits incoming beams by reflection and transmission.

Implementation reqs.

Subtypes of AbstractBeamsplitter should implement all supertype requirements.

Interaction logic

After intersection with the AbstractShape at which the beam splitting occurs, the interact3d function should appended the transmitted and reflected sub-beams to the parent beam via the children! function. The interact3d function should then return nothing in order to stop the tracing of the parent beam.

Appending convention

As a convention, when splitting an incoming beam, the order of children appended to the parent beam should be

transmitted beam
reflected beam

Functions

interact3d: see above
_beamsplitter_transmitted_beam: optional helper function
_beamsplitter_reflected_beam: optical helper function

source

BeamletOptics.AbstractCompositeSDF Type

julia

AbstractCompositeSDF{T} <: AbstractSDF{T}

Generic supertype for boolean composite SDFs, i.e. SDFs that combine two or more AbstractSDF operands into a single shape. Owns the field layout and pivot-aware kinematics shared by all boolean composites; concrete subtypes only need to define the boolean combination semantics (sdf, normal3d, thickness).

Implementation reqs.

Subtypes of AbstractCompositeSDF should implement all reqs. of AbstractSDF as well as the following:

Fields

dir::SMatrix{3, 3, T, 9}: the composite's own orientation matrix
transposed_dir::SMatrix{3, 3, T, 9}: transpose of dir
pos::Point3{T}: the composite's own position, in that field order, and the struct must be mutable since every setter in AbstractShape.jl/AbstractSDF.jl assigns fields directly

Functions

operands: returns a Tuple of every child AbstractSDF, in any order
sdf, normal3d and thickness specific to the boolean combination

source

BeamletOptics.AbstractCylindricalSurfaceSDF Type

julia

AbstractCylindricalSurfaceSDF <: AbstractLensSDF{T}

A class of AbstractSDFs that can be used to represent cylindric non-rotationally symmetric lens surfaces. It is implicity assumed that all surfaces are represented by closed volumes for ray-tracing correctness.

Implementation reqs.

Subtypes of AbstractCylindricalSurfaceSDF must implement the following additional methods.

Functions:

height: this function returns the height of the cylinder part of the surface
radius: this function returns the radius of the cylinder surface curvature

source

BeamletOptics.AbstractDetector Type

julia

AbstractDetector <: AbstractObject

A generic representation of a detector that evaluates AbstractBeam data during and/or after interaction. Refer to e.g. Detector for more information.

Implementation reqs.

Subtypes of AbstractDetector should implement all supertype requirements as well as:

Functions

interact3d: see e.g. Detector for reference
empty!: resets data stored in the detector, see below

Additional information

The information provided below applies to the standard functional implementation of this type and may be overwritten by specialized subtypes.

Data mutability

In order to model field superposition effects, the concrete implementation of an AbstractDetector should be a mutable struct with a constant shape field. This is necessary, since (sub-)beams will interact sequentially with the detector during solve_system!. Only if the data can be accumulated sequentially, multiple beam interactions can be captured for a complex system, e.g. an interferometer.

Data reset

Since e.g. E-field data is supposed to be accumulated by mutability of the detector data, the burden of resetting the data for a new solver call is placed on the user. This function should be called empty!.

source

BeamletOptics.AbstractDetectorHit Type

julia

AbstractDetectorHit

Abstract supertype for all Detector hit records.

A hit of this type encapsulates the interaction of a ray or beamlet with the Detector surface. Instead of directly accumulating values (e.g. optical power), the hit object stores all relevant information about the incident field for a posteriori evaluation (such as plotting, power integration, or polarization analysis).

Info

Note that new subtypes of AbstractDetectorHit must be manually added to the Detector definition to be eligible.

Concrete subtypes include:

RayHit — unpolarized geometric ray
PolarizedRayHit — ray carrying a polarization state
GaussianBeamletHit — single Gaussian beamlet

source

BeamletOptics.AbstractInteraction Type

julia

AbstractInteraction

Describes how an AbstractBeam and an AbstractObject interact with each other. This data type stores information from the interact3d function and provides it to the solver. The solver can use this data to extend the AbstractBeam.

Implementation reqs.

Subtypes of AbstractInteraction must implement the following:

Fields

hint: a nullable Hint for the solver (optional but recommended)

Beam data

It is required that concrete implementations of this type provide some form of data on how to extend the beam. For instance, refer to theBeamInteraction and GaussianBeamletInteraction.

source

BeamletOptics.AbstractJonesPolarizer Type

julia

AbstractJonesPolarizer <: AbstractObject

Represents infinitesimally thin components that change the polarization state of incoming PolarizedRays via global Jones matrix calculus. Rather than using the generic Yun ray tracing scheme as referred to in the PolarizedRay docs, this element interacts with the global E-field vector E0 by using a GlobalJonesBasis and projecting the entries into the transverse plane defined by the incoming ray direction and orthogonal E-field vector. This approach is partially inspired by the publication:

Jan Korger et al., "The polarization properties of a tilted polarizer," Opt. Express 21, 27032-27042 (2013)

Warning

It is assumed that the ray direction of propagation is not changed during the interaction.

Implementation reqs.

Subtypes of AbstractJonesPolarizer should implement all supertype requirements.

Interaction logic

The GlobalJonesBasis tracks the rotation in 3D-space via the orientation of the attached AbstractShape. The polarization matrix P is calculated by projecting the previous matrix into the incoming orthogonal plane of polarization. Refer to the _calculate_global_E0 implementation for more information.

Info

The validity of this approach is still under consideration for non-normal incidence.

source

BeamletOptics.AbstractKinematicFrame Type

julia

AbstractKinematicFrame

Reference frame of a Movable value, either Oriented or Directed.

source

BeamletOptics.AbstractKinematicTrait Type

julia

AbstractKinematicTrait

The kinematic trait defines whether an entity can be moved by the kinematic API (translate3d!, rotate3d!, ...). It is returned by kinematic_trait_of and follows the same dispatch pattern as AbstractShapeTrait: every public function e.g. translate3d!(x, args...) forwards to translate3d!(kinematic_trait_of(x), x, args...).

Two traits are defined:

Static: x cannot be moved, every kin. function throws an ArgumentError
Movable: x can be moved; its frame (Oriented or Directed) selects orientation- or direction-based behaviour

A subtype of a movable abstract type can opt out of the kinematic API by declaring its own kinematic_trait_of method, e.g.

julia

struct FixedMirror{T, S <: AbstractShape{T}} <: AbstractObject{T}
    shape::S
end

kinematic_trait_of(::FixedMirror) = Static()

Every kinematic function on a FixedMirror now throws an ArgumentError; its getters (position, orientation, ...) stay available.

Containers

All members of a container (ObjectGroup, UnionSDF/DifferenceSDF, AbstractBeamGroup) must be either all Static or all Movable. Frames can still be mixed. This must be checked in the respective constructors; nesting is then covered because a nested container already has a uniform class from its own constructor. The container then takes that class: Static if all members are Static, else Movable(Oriented()). All shapes returned by shape(object) of a MultiShape object must be movable, since MultiShape objects (e.g. a CubeBeamsplitter) have no shared constructor to enforce this.

source

BeamletOptics.AbstractLensSDF Type

julia

AbstractLensSDF

A class of AbstractSDFs that can be used to represent rotationally symmetric lens surfaces. It is implicity assumed that all surfaces are represented by closed volumes for ray-tracing correctness.

Implementation reqs.

Subtypes of AbstractLensSDF must implement the following:

Functions:

thickness: this function returns the material thickness of the element along its symmetry axis
diameter: this function returns the outer diameter of the element

Shape orientation

For easy compatibility between subtypes, the follwing requirements should be fulfilled:

Symmetry axis aligned onto the y-axis
Surface contour aligned towards negative y-values
Surface point with min(y) should satisfy min(y) = 0 on the symmetry axis

source

BeamletOptics.AbstractMesh Type

julia

AbstractMesh <: AbstractShape

A generic type for an shape whose volume can be described by a mesh. Must have a field mesh of type Mesh. See also Mesh{T}.

source

BeamletOptics.AbstractObject Type

julia

AbstractObject

A generic type for 2D/3D objects that can be used to model optical elements. The geometry of the object is represented via an AbstractShape. The optical effect that occurs between the object and an incoming ray/beam of light is modeled via its interact3d method.

Implementation reqs.

Subtypes of AbstractObject must implement the following:

Shape trait

An AbstractObject can consist of a single AbstractShape, e.g. a lens element, or a collection of functionally dependant shapes, e.g. a cube beamsplitter. In order to model this, the API implementation of an AbstractObject requires the definition of the shape trait. This trait allows the dispatch onto specialized methods to handle the kinematic interface and tracing methods for objects consisting of one or more shapes.

shape_trait_of: defines the shape type of the AbstractObject, refer to AbstractShapeTrait for more information

Default shape trait

Unless specified otherwise, the shape_trait_of an AbstractObject is defined as SingleShape. This requires object.shape as a dedicated field. For MultiShapes the getter function shape(object) must return a tuple of all shapes that make up the object.

Getters/setters

All kinematic functions defined for the AbstractShape can also be called for a AbstractObject. In this case, the shape trait will define how the specific movement function is dispatched.

Kinematic

AbstractObjects are BeamletOptics.Movable with an BeamletOptics.Oriented frame, see BeamletOptics.AbstractKinematicTrait. The primitives translate3d!(::Movable, object, offset) and rotate3d!(::Movable, object, R::AbstractMatrix) forward to the shape trait. A subtype can opt out of the kinematic API via BeamletOptics.kinematic_trait_of(::Foo) = BeamletOptics.Static().

Functions:

interact3d: defines the optical interaction, the return type must be Nothing or an AbstractInteraction

source

BeamletOptics.AbstractObjectGroup Type

julia

AbstractObjectGroup <: AbstractObject

Container type for groups of optical elements, based on a tree-like data structure. Intended for easier kinematic handling of connected elements. See also ObjectGroup for a concrete implementation.

Implementation reqs.

Subtypes of AbstractObjectGroup must implement the following:

Fields:

objects: stores objects or additional subgroups of objects, allows for hierarchical structures

Functions:

for the kinematic API, all corresponding functions of AbstractObject must be implemented

source

BeamletOptics.AbstractPlateBeamsplitter Type

julia

AbstractPlateBeamsplitter <: AbstractBeamsplitter

A generic type to represent an AbstractBeamsplitter that consists of a substrate with a single coated face at which a beam splitting interaction occurs.

Implementation reqs.

Subtypes of AbstractPlateBeamsplitter should implement all supertype reqs. as well as:

Fields

coating: a ThinBeamsplitter that represents the splitter coating
substrate: a Prism that represents the substrate

Getters/setters

If the concrete implementation does not define the above fields, the following getters must be defined:

coating: returns a ThinBeamsplitter
substrate: returns a Prism

Additional information

Object orientation

This interact3d method of this type strongly assumes that the coating is positioned directly upon a single face of the substrate with a 100% fill factor.

Interaction logic

This type uses the Hint-API in order to ensure that the splitting interaction is correctly triggered at the coating.

source

BeamletOptics.AbstractRay Type

julia

AbstractRay{T<:Real}

An implementation for a geometrical optics ray in R³. In general, a AbstractRay is described by with . AbstractRays are intended to model the propagation of light between optical interactions according to the laws of geometrical optics. To store the result of a ray tracing solution, refer to AbstractBeam.

Intersections:

Since the length of a ray can not be known before solving an optical system, the Intersection-type is used. This Nullable type can represent the intersection with an optical element, or lack thereof.

Implementation reqs.

Subtypes of AbstractRay must implement the following:

Fields:

pos: a R³-vector that stores the current position
dir: a R³-vector that stores the current direction
intersection: a Nullable field that stores the current [Intersection] or nothing
λ: wavelength in [m]
n: refractive index along the ray path

Functions:

empty!: resets the ray to its initial, unsolved state
intersect3d: calculates the Intersection between a ray and a shape
rotate3d!(::Movable, ray, R::AbstractMatrix): only required for subtypes carrying direction-dependent data (e.g. field vectors); must rotate this data together with the ray direction and clear the intersection

Kinematic API:

AbstractRays are BeamletOptics.Movable with a BeamletOptics.Directed frame, see BeamletOptics.AbstractKinematicTrait. Every verb clears the ray Intersection, i.e. resets the ray to its unsolved state. Rotations are applied about the ray start position. reset_rotation3d! throws an ArgumentError, since a ray has no orientation.

Additional information

Ray length

Base.length: this function is used to return the length of the AbstractRay (if no intersection exists, the ray length is Inf). The opl keyword can be used to obtain the optical path length instead.

Ray direction

Many functions assume that the direction vector has unit length (i.e. ). Violating this assumption might lead to spurious results.

source

BeamletOptics.AbstractRayHit Type

julia

AbstractRayHit{T} <: AbstractDetectorHit

Abstract supertype for detector hits produced by AbstractRays. Provides a common interface for extracting positional and optical path information from rays stored in a detector hit. Currently the following concrete types are implemented:

Implementation reqs.

Subtypes of AbstractRayHit must implement the following:

Fields

ray: stores the AbstractRay that has intersected the detector
opl: stores the optical_path_length of the parent beam (incl. the ray)

Functions

The interface provides the following functions for the fields above:

position: returns the ray position
direction: returns the ray direction
length: returns the ray length
optical_path_length: returns the opl
wavenumber: returns the ray wavenumber
hit_point: returns the R³ point of intersection
projection_factor: returns the scalar projection between the surface normal and ray dir.

source

BeamletOptics.AbstractReflectiveOptic Type

julia

AbstractReflectiveOptic <: AbstractObject

A generic type to represent an [AbstractObject] which reflects incoming rays.

Implementation reqs.

Subtypes of AbstractReflectiveOptic should implement all supertype reqs. as well as:

Fields

no specific fields required

Getters/setters

none required

Functions

interact3d: the interaction logic should be akin to reflection3d for each surface crossing

Additional information

The information provided below applies to the standard functional implementation of this type and may be overwritten by specialized subtypes.

Polarization ray tracing

Fresnel coefficients during reflection are set such that no reflection losses occur (i.e. |rₚ| = |rₛ| = 1).

source

BeamletOptics.AbstractRefractiveOptic Type

julia

AbstractRefractiveOptic <: AbstractObject

A generic type to represent an AbstractObject that refracts incoming rays.

Implementation reqs.

Subtypes of AbstractRefractiveOptic should implement all supertype reqs. as well as:

Fields

n: a callable field which returns the RefractiveIndex for a wavelength λ

Getters/setters

refractive_index: gets the ref. index data of the optic

Functions

interact3d: the interaction logic should be akin to refraction3d for each surface crossing

Additional information

The information provided below applies to the standard functional implementation of this type and may be overwritten by specialized subtypes.

Uniform ref. index

It is assumed that the optic consists of a single transparent material with a homogeneous refractive index n. It does not consider coated surfaces.

Polarization ray tracing

Fresnel coefficients at the point of refraction are calculated via the fresnel_coefficients function with the refractive index data of the substrate and the previous medium.

source

BeamletOptics.AbstractRotationallySymmetricSurface Type

julia

AbstractRotationallySymmetricSurface{T} <: AbstractSurface{T}

A surface type which is rotationally symmetric around one axis.

Implementation reqs.

Subtypes of AbstractShape should implement the following:

Getters/setters

radius : Returns the radius of curvature of the AbstractRotationallySymmetricSurface
diameter : Returns the clear optical diameter of the AbstractRotationallySymmetricSurface
mechanical_diameter : Returns the mechanical diameter of the AbstractRotationallySymmetricSurface
edge_sag : Returns the edge sagitta of the AbstractRotationallySymmetricSurface

Functions:

sdf(::AbstractRotationallySymmetricSurface, ::Union{Nothing, AbstractOrientationType}) : Converts the surface specification of AbstractRotationallySymmetricSurface into an AbstractSDF

source

BeamletOptics.AbstractSDF Type

julia

AbstractSDF <: AbstractShape

Provides a shape function based on signed distance functions. See https://iquilezles.org/articles/distfunctions/ for more information.

Implementation reqs.

Subtypes of AbstractSDF should implement all reqs. of AbstractShape as well as the following:

Functions

sdf(::AbstractSDF, point): a function that returns the signed distance for a point in 3D space

source

BeamletOptics.AbstractShape Type

julia

AbstractShape{T<:Real}

A generic type for a shape that exists in 3D-space. Must have a position and orientation. Types used to describe the geometry of a shape should be subtypes of Real.

Implementation reqs.

Subtypes of AbstractShape should implement the following:

Fields:

pos: a 3D-vector that stores the current position of the object-specific coordinate system
dir: a 3x3-matrix that represents the orthonormal basis of the object and therefore, the orientation

Getters/setters

position / position!: gets or sets the position vector of the AbstractShape
orientation / orientation!: gets or sets the orientation matrix of the AbstractShape

Kinematic:

AbstractShapes are BeamletOptics.Movable with an BeamletOptics.Oriented frame, see BeamletOptics.AbstractKinematicTrait. The default primitives translate3d!(::Movable, shape, offset) and rotate3d!(::Movable, shape, R::AbstractMatrix) act on position/orientation; subtypes with additional geometry data (e.g. mesh vertices) dispatch their own.

Ray Tracing:

intersect3d: returns the intersection between an AbstractShape and AbstractRay, or lack thereof. See also Intersection

Rendering (with Makie):

Refer to the render! documentation.

source

BeamletOptics.AbstractShapeTrait Type

julia

AbstractShapeTrait

The shape trait defines how many shapes an AbstractObject consists of. Two different traits are defined:

SingleShape: the AbstractObject consists of a single AbstractShape
MultiShape: the AbstractObject consists of two or more AbstractShapes

Refer to the respective documentation for more information

source

BeamletOptics.AbstractSphericalSurfaceSDF Type

julia

AbstractSphericalSurfaceSDF{T} <: AbstractSDF{T}

An abstract type for SDF-based volumes which represent spherical lens surfaces, i.e. ConvexSphericalSurfaceSDF or ConcaveSphericalSurfaceSDF.

Implementation reqs.

Subtypes of AbstractSphericalSurfaceSDF should implement all supertype reqs. as well as the following:

Fields:

radius: the radius of curvature
diameter: the lens outer diameter
sag: the lens sagitta

Lens construction

It is intended that practical lens shapes are constructed from AbstractSphericalSurfaceSDFs using the UnionSDF type.

source

BeamletOptics.AbstractSurface Type

julia

AbstractSurface{T}

A generic type for a surface which is basically an information storage type in order to build shapes (volumes) from a combination of surfaces.

source

BeamletOptics.AbstractSystem Type

julia

AbstractSystem

A generic representation of a system of optical elements.

Implementation reqs.

Subtypes of AbstractSystem must implement the following:

Fields:

objects: a vector or tuple of AbstractObjects that make up the system
n: (optional) RefractiveIndex of the surrounding medium, default value is 1.0

Functions:

refractive_index: returns the RefractiveIndex n of the system medium, see above

source

BeamletOptics.AconcaveCylinderSDF Type

julia

AconcaveCylinderSDF{T} <: AbstractAcylindricalSurfaceSDF{T}

Implements the SDF of a concave cylinder with radius r, diameter d and height h.

source

BeamletOptics.AconcaveCylinderSDF Method

julia

AconcaveCylinderSDF(radius, diameter, height)

Constructs an aconcave cylinder cutout with radius r, diameter d and height h in [m]. The acylindric shape is defined by its conic_constant and the coefficients for the even aspheric polynomoial.

source

BeamletOptics.AconvexCylinderSDF Type

julia

AconvexCylinderSDF{T} <: AbstractAcylindricalSurfaceSDF{T}

Implements the SDF of a cut cylinder with radius r, diameter d and height h.

source

BeamletOptics.AconvexCylinderSDF Method

julia

AconvexCylinderSDF(radius, diameter, height)

Constructs an aconvex cylinder with radius r, diameter d and height h in [m]. The acylindric shape is defined by its conic_constant and the coefficients for the even aspheric polynomoial.

source

BeamletOptics.AcylindricalSurface Type

julia

AcylindricalSurface{T} <: AbstractAcylindricalSurface{T}

A type representing an acylindric optical surface defined by its radius of curvature, diameter, height, mechanical diameter, conic constant and even aspheric coefficients. It is therefore a cylindric surface with a deviation from the perfect cylindric shape.

Fields

radius::T: The radius of curvature of the curved surface.
diameter::T: The clear (optical) aperture of the surface.
height::T : The height/length of the uncurved surface direction
conic_constant::T : The conic_constant of the curved surface
coefficients::Vector{T} : The coefficients of the even aspherical equation for the curved surface.
mechanical_diameter::T: The overall mechanical diameter of the surface. In many cases, this is equal to the optical diameter, but it can be set independently if the mechanical mount requires a larger dimension.

source

BeamletOptics.AcylindricalSurface Method

julia

AcylindricalSurface(radius, diameter, height, conic_constant, coefficients)

Construct a CylindricalSurface given the radius of curvature, optical diameter and height. This constructor automatically sets the mechanical diameter equal to the optical diameter.

Arguments

radius: The radius of curvature of the curved surface.
diameter: The clear (optical) diameter of the surface.
height: The height/length of the uncurved surface direction.
conic_constant::T : The conic_constant of the curved surface
coefficients::Vector{T} : The coefficients of the even aspherical equation for the curved surface.

source

BeamletOptics.AstigmaticBeamGroup Type

julia

AstigmaticBeamGroup{T, R} <: AbstractBeamGroup{T, R}

A generic container for groups of AstigmaticGaussianBeamlets.

Fields

beams: vector of all beamlets
center: source position, pivot for rotations
orientation: right-handed orthonormal matrix, columns are the sampling reference vector, the central source direction and their cross product, see AbstractBeamGroup

source

BeamletOptics.AstigmaticBeamGroup Method

julia

AstigmaticBeamGroup(beams, pos, dir::AbstractVector)
AstigmaticBeamGroup(beams, pos, orientation::AbstractMatrix)

Wraps existing beams into an AstigmaticBeamGroup with the source position pos. The group orientation is either derived from the central direction dir (the sampling reference vector is then picked deterministically via normal3d), or passed explicitly as a right-handed orthonormal 3x3 orientation matrix whose second column is the central direction. An invalid orientation throws an ArgumentError.

source

BeamletOptics.AstigmaticGaussianBeamlet Type

julia

AstigmaticGaussianBeamlet(position, direction, λ, w0; kwargs...)

Constructs an astigmatic Gaussian beamlet at its waist with the specified beam parameters. In the 4-argument version, the beam has circular symmetry with waist radius w0. In the 5-argument version, independent waists w0_x and w0_y can be specified.

Arguments

Inputs

position: origin of the beamlet
direction: direction of the beamlet
λ: wavelength of the beamlet in [m]. Default value is 1000 nm.
w0: beam waist (radius) in [m]. Default value is 1 mm.
w0_x, w0_y: independent beam waists in [m].

Keyword Arguments

M2, M2_x, M2_y: beam quality factors. Default is 1
P0: beam total power in [W]. Default is 1 mW.
E0: electric field vector in [V/m]. Default is nothing (aligned with support axes, scaled by P0).
support: optional support vector for basis construction
z0: beam waist offset in [m]. Default is 0 m

Additional information

Optical invariant check

When using the solve_system! function, the beamlet invariant will be checked for each interaction. If the invariant is violated, tracing will be stopped.

source

BeamletOptics.AstigmaticGaussianBeamlet Type

julia

AstigmaticGaussianBeamlet{T} <: AbstractBeam{T, PolarizedRay{T}}

Complex ray representation of a general astigmatic Gaussian beam as per the formalism described by A. Greynolds (1986) and N. Worku (2017). The beam is described by a chief PolarizedRay and 8 auxiliary Rays that encode the waist radius and divergence in two orthogonal transverse axes. The beam quality M2 is considered via the divergence angle. All equations are based on the following publications:

Alan Greynolds, "Vector formulation of the ray-equivalent method for general Gaussian beam propagation." Curr. Dev. Opt. Eng. Diffraction Phenom. Vol. 679. SPIE, 1986

and

Norman Worku and Herbert Gross, "Vectorial field propagation through high NA objectives using polarized Gaussian beam decomposition." OTOM XIV. Vol. 10347. SPIE, 2017

Fields

c: chief Beam of PolarizedRays
wxp: waist x-positive Beam of Rays
wxm: waist x-negative Beam of Rays
wyp: waist y-positive Beam of Rays
wym: waist y-negative Beam of Rays
dxp: divergence x-positive Beam of Rays
dxm: divergence x-negative Beam of Rays
dyp: divergence y-positive Beam of Rays
dym: divergence y-negative Beam of Rays
parent: reference to the parent beam (or nothing)
children: vector of child beams (e.g. after beam-splitting)

Additional information

Waist and field calculation

For a given beamlet the Gaussian beam parameters can be obtained via the gauss_parameters function.

source

BeamletOptics.AstigmaticGaussianBeamlet Method

julia

AstigmaticGaussianBeamlet(position, direction, λ, w0_x, w0_y; kwargs...)

Constructs an astigmatic Gaussian beamlet with independent waists w0_x and w0_y. This constructor supports modeling astigmatic sources where the waists in X and Y are at different locations along the beam axis.

Arguments

position: Global reference point of the beamlet.
direction: Propagation direction vector.
λ: Wavelength.
w0_x: Waist radius in the X direction (defined by the support vector).
w0_y: Waist radius in the Y direction.

Keyword Arguments

z0_x: Position of the X waist relative to position along the propagation axis. Defaults to z0.
z0_y: Position of the Y waist relative to position along the propagation axis. Defaults to z0.
z0: Default waist position if z0_x and z0_y are not specified. Also defines the starting point of the chief ray as position + z0 * direction.
M2_x, M2_y: Beam quality factors. Default is 1.
P0: Total power in [W].
E0: Optional Jones vector for polarization.
support: Optional vector orthogonal to direction to define the X axis.

Additional information

Optical invariant check

When using the solve_system! function, the beamlet invariant will be checked for each interaction. If the invariant is violated, tracing will be stopped.

source

BeamletOptics.AstigmaticGaussianBeamletHit Type

julia

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.

source

BeamletOptics.AstigmaticGaussianBeamletInteraction Type

julia

AstigmaticGaussianBeamletInteraction <: AbstractInteraction

Stores the interaction result for all 9 component beams of an AstigmaticGaussianBeamlet. Uses the hint from the chief beam interaction.

Fields

chief: BeamInteraction for the chief ray
wxp, wxm, wyp, wym: waist beam interactions
dxp, dxm, dyp, dym: divergence beam interactions

source

BeamletOptics.Beam Type

julia

Beam{T, R <: AbstractRay{T}} <: AbstractBeam{T, R}

Stores the rays that are calculated from geometric optics when propagating through an optical system. The Beam type is parametrically defined by the AbstractRay subtype that it stores.

Fields

rays: vector of AbstractRay objects, representing the rays that make up the beam
parent: reference to the parent beam, if any (Nullable to account for the root beam which has no parent)
children: vector of child beams, each child beam represents a branching or bifurcation of the original beam, i.e. beam-splitting

source

BeamletOptics.Beam Method

julia

Beam(pos, dir, λ, E0)

Spawns a Beam of PolarizedRays at the start position in the specified direction with the wavelength λ and electric field vector E0

source

BeamletOptics.Beam Method

julia

Beam(pos, dir, λ, E0)

Spawns a Beam at the start position in the specified direction with the wavelength λ and field vector E0.

source

BeamletOptics.Beam Method

julia

Beam(pos, dir, λ=1e-6)

Spawns a Beam at the start position in the specified direction with the wavelength λ = 1000 nm.

source

BeamletOptics.BeamInteraction Type

julia

BeamInteraction <: AbstractInteraction

This type is used to store the new AbstractRay resulting from on optical interaction between a Beam and some AbstractObject.

Fields

hint: optional Hint for the solver
ray: new AbstractRay resulting from the interaction

source

BeamletOptics.BoxSDF Type

julia

BoxSDF <: AbstractSDF

Implements the box SDF with edge lengths x, y, and z. Note that these values are stored in the dimensions field as:

dimensions::Point3 = ( len_in_x/2, len_in_y/2, len_in_z/2,

)

source

BeamletOptics.BoxSDF Method

julia

BoxSDF(x, y, z)

Creates a BoxSDF with:

x: x-dir. edge length in [m]
y: y-dir. edge length in [m]
z: z-dir. edge length in [m]

source

BeamletOptics.CircularFlatSurface Type

julia

CircularFlatSurface{T} <: AbstractRotationallySurface{T}

A type representing a planar circular surface, which is only parametrized by its diameter.

Fields

diameter::T: The diameter of the planar surface

source

BeamletOptics.CollimatedSource Type

julia

CollimatedSource <: AbstractBeamGroup

Represents a parallel bundle of Beams being emitted from a disk in space.

Fields

beams: a vector of all Beams originating from the source
diameter: the diameter of the outermost beam ring
center: source position, pivot for rotations
orientation: right-handed orthonormal matrix, columns are the sampling reference vector, the central source direction and their cross product, see AbstractBeamGroup

Functions

diameter: returns the diameter of the source

source

BeamletOptics.CollimatedSource Method

julia

CollimatedSource(pos, dir, diameter, λ; num_rings, num_rays, basis)

Spawns a bundle of collimated Beams at the specified position and direction. The source is modelled as a ring of concentric beam rings around the center beam. The amount of beam rings between the center ray and outer diameter can be specified via num_rings.

Info

Note that for correct sampling, the number of rays should be atleast 20x the number of rings.

Arguments

The following inputs and arguments can be used to configure the CollimatedSource:

Inputs

pos: center beam starting position
dir: center beam starting direction
diameter: outer beam bundle diameter in [m]
λ = 1e-6: wavelength in [m], default val. is 1000 nm

Keyword Arguments

num_rings: number of concentric beam rings, default is 10
num_rays: total number of rays in the source, default is 100x num_rings
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle for the beam rings.

Reproducible sampling

If no basis is passed, the orthogonal basis vectors spanning the pupil plane are derived from dir deterministically, so two sources sharing the same dir, diameter, num_rings and num_rays sample exactly the same ray positions. Pass a basis to rotate the azimuthal sampling of a source about its own axis, e.g. to interleave several otherwise identical sources.

source

BeamletOptics.CollimatedSource Method

julia

CollimatedSource(beams, diameter, pos, dir::AbstractVector)
CollimatedSource(beams, diameter, pos, orientation::AbstractMatrix)

Wraps existing beams into a CollimatedSource with the given diameter and the source position pos. The group orientation is either derived from the central direction dir (the sampling reference vector is then picked deterministically via normal3d), or passed explicitly as a right-handed orthonormal 3x3 orientation matrix whose second column is the central direction. An invalid orientation throws an ArgumentError.

source

BeamletOptics.ConcaveAsphericalSurfaceSDF Type

julia

ConcaveAsphericalSurfaceSDF

Constructs an aspheric lens with a concave-like surface according to ISO10110.

Note

Currently, it is assumed that the aspheric surface is concave if the radius is negative. There might be unexpected effects for complex shapes which do not show a generally concave behavior.

coefficients : (even) coefficients of the asphere.
radius : radius of the lens (negative!)
conic_constant : conic constant of the lens surface
diameter: lens diameter
mechanical_diameter: mechanical lens diameter, defaults to be identical to the lens diameter, Otherwise an outer ring section will be added to the lens, if mechanical_diameter > diameter.

source

BeamletOptics.ConcaveCylinderSDF Type

julia

ConcaveCylinderSDF <: AbstractSDF

Implements the SDF of a concave cylinder with radius r, diameter d and height h.

source

BeamletOptics.ConcaveCylinderSDF Method

julia

ConcaveCylinderSDF(radius, diameter, height)

Constructs a concave cylinder with radius r, diameter d and height h in [m].

source

BeamletOptics.ConcaveSphericalSurfaceSDF Type

julia

ConcaveSphericalSurfaceSDF

AbstractSDF-based representation of a concave spherical lens surface. When constructed, it is assumed that the plano-surface lies at the origin and the optical axis is aligned with the y-axis. The concave surface is orientated towards negative y-values for R > 0 and vice versa.

Fields:

radius: the radius of curvature of the convex spherical surface.
diameter: the outer diameter of the lens surface
sag: the sagitta of the opposing convex shape

source

BeamletOptics.ConcaveSphericalSurfaceSDF Method

julia

ConcaveSphericalSurfaceSDF(radius, diameter)

Constructs a ConcaveSphericalSurfaceSDF with a specific radius of curvature and lens outer diameter.

source

BeamletOptics.ConicSDF Type

julia

ConicSDF{T} <: AbstractSDF{T}

Signed distance function representation of a segment of a conic of revolution (sphere, paraboloid, prolate/oblate ellipsoid or hyperboloid), used as the substrate of ParabolicMirror, ConicMirror, EllipsoidalMirror, HyperbolicMirror and their OffAxis* twins.

Frame convention

The origin is the segment centre, lying on the reflecting surface.
The parent optical axis is parallel to the local y-axis, offset by x_off along the negative x-axis; there is no tilt between the segment and its parent axis.
A concave surface (R > 0) opens towards the negative y-axis; a convex surface (R < 0) opens towards the positive y-axis.
The parent vertex lies at (-x_off, +Z(x_off), 0), where Z is the sag function of the parent conic.
For x_off = 0 and k = -1, R = 2f: the vertex lies at the origin and the (real) focus lies at (0, -f, 0). This on-axis case needs no separate type: x_off = 0 is an ordinary argument value, not a different ConicSDF variant.

Fields

f: paraxial focal length of the parent conic, R/2 [m]
k: conic constant (k = -1 paraboloid, k = 0 sphere, -1 < k < 0 prolate ellipsoid, k > 0 oblate ellipsoid, k < -1 hyperboloid)
x_off: off-axis distance from the parent vertex to the segment centre [m]
diameter: segment aperture diameter [m]
thickness: substrate thickness in y-direction [m]
pos: position point in world coordinates [m]
dir: rotation matrix in world coordinates
transposed_dir: transposed rotation matrix

Surface equation

With r_p = sqrt((x + x_off)^2 + z^2) the parent radius and

the reflecting surface is y_surf(x, z) = -(Z(r_p) - Z(x_off)). The substrate is the solid {y_surf <= y <= thickness, sqrt(x^2 + z^2) <= diameter/2}.

source

BeamletOptics.ConicSDF Method

julia

ConicSDF(R, k, x_off, diameter, thickness)

Constructs a ConicSDF representing a segment of a conic of revolution.

Inputs

R: radius of curvature at the parent vertex [m]; R > 0 is concave (opens towards -y), R < 0 is convex (opens towards +y). Must be non-zero.
k: conic constant. k = -1 is a paraboloid, k = 0 a sphere, -1 < k <= 0 a prolate ellipsoid, k > 0 an oblate ellipsoid, k < -1 a hyperboloid.
x_off: off-axis distance from the parent vertex to the segment centre [m]
diameter: segment aperture diameter [m]. Must be positive.
thickness: substrate thickness in y-direction [m]

For k > -1 the parent conic is only defined for r < abs(R)/sqrt(1+k); the constructor throws an ArgumentError if the aperture (abs(x_off) + diameter/2) reaches or exceeds this limit. For k <= -1 the surface is defined for all r, so no such limit applies.

source

BeamletOptics.ConvexAsphericalSurfaceSDF Type

julia

ConvexAsphericalSurfaceSDF

Constructs an aspheric lens with a convex-like surface according to ISO10110.

Note

Currently, it is assumed that the aspheric surface is convex if the radius is positive. There might be unexpected effects for complex shapes which do not show a generally convex behavior.

coefficients : (even) coefficients of the asphere.
radius : radius of the lens
conic_constant : conic constant of the lens surface
diameter: lens diameter

source

BeamletOptics.ConvexCylinderSDF Type

julia

ConvexCylinderSDF <: AbstractSDF

Implements the SDF of a cut cylinder with radius r, diameter d and height h.

source

BeamletOptics.ConvexCylinderSDF Method

julia

ConvexCylinderSDF(radius, diameter, height)

Constructs a cut cylinder with radius r, diameter d and height h in [m].

source

BeamletOptics.ConvexSphericalSurfaceSDF Type

julia

ConvexSphericalSurfaceSDF

AbstractSDF-based representation of a convex spherical lens surface. When constructed, it is assumed that the plano-surface lies at the origin and the optical axis is aligned with the y-axis. The convex surface is orientated towards negative y-values for R > 0 and vice versa.

Fields:

radius: the radius of curvature of the concave spherical surface.
diameter: the outer diameter of the lens surface
sag: the sagitta of the convex shape
height: the sphere cutoff height, see also CutSphereSDF

source

BeamletOptics.ConvexSphericalSurfaceSDF Method

julia

ConvexSphericalSurfaceSDF(radius, diameter)

Constructs a ConvexSphericalSurfaceSDF with a specific radius of curvature and lens outer diameter.

source

BeamletOptics.CubeBeamsplitter Type

julia

CubeBeamsplitter <: AbstractBeamsplitter

A cuboid beamsplitter where the splitting interaction occurs between two RightAnglePrisms. For more information refer to the AbstractPlateBeamsplitter docs.

Fields

front: the forward facing substrate, represented by a RightAnglePrism
back: the backward facing substrate, represented by a RightAnglePrism
coating: a rectangular ThinBeamsplitter that represents the splitting interface

Additional information

Hints and interaction logic

In order to model gap-free beam propagation, the interact3d model relies heavily on the Hint-API. If the front or back substrate is hit, the Hint will ensure that the beam intersects the coating.

source

BeamletOptics.CubeBeamsplitter Method

julia

CubeBeamsplitter(leg_length, n; reflectance=0.5)

Creates a CubeBeamsplitter. The cuboid is centered at the origin. The splitter coating is orientated at a 45° angle with respect to the y-axis.

Inputs

leg_length: the x-, y- and z-edge length in [m]
n: the RefractiveIndex of the front and back prism

Keywords

reflectance: defines the splitting ratio in [-], i.e. R = 0 ... 1.0

source

BeamletOptics.CubeBeamsplitterShape Type

Placeholder type for the shape of a CubeBeamsplitter

source

BeamletOptics.CutSphereSDF Type

julia

CutSphereSDF <: AbstractSDF

Implements SDF of a sphere which is cut off in the x-z-plane at some point along the y-axis.

source

BeamletOptics.CutSphereSDF Method

julia

CutSphereSDF(pos, radius, height)

Constructs a sphere with radius which is cut off along the y-axis at height.

source

BeamletOptics.CylinderSDF Type

julia

CylinderSDF <: AbstractSDF

Implements cylinder SDF. Cylinder is initially orientated along the y-axis and symmetrical in x-z.

source

BeamletOptics.CylindricalSurface Type

julia

CylindricalSurface{T} <: AbstractCylindricalSurface{T}

A type representing a cylindric optical surface defined by its radius of curvature, diameter, height and mechanical diameter

Fields

radius::T: The radius of curvature of the curved surface.
diameter::T: The clear (optical) aperture of the surface.
height::T : The height/length of the uncurved surface direction
mechanical_diameter::T: The overall mechanical diameter of the surface. In many cases, this is equal to the optical diameter, but it can be set independently if the mechanical mount requires a larger dimension.

source

BeamletOptics.CylindricalSurface Method

julia

CylindricalSurface(radius::T, diameter::T, height::T) where T

Construct a CylindricalSurface given the radius of curvature, optical diameter and height. This constructor automatically sets the mechanical diameter equal to the optical diameter.

Arguments

radius::T: The radius of curvature of the curved surface.
diameter::T: The clear (optical) diameter of the surface.
height::T: The height/length of the uncurved surface direction.

source

BeamletOptics.Detector Type

julia

Detector(edge_length, stop)

Spawns a quadratic Detector surface that is aligned with the neg. y-axis. The detector edge length can be configured via edge_length. Additionally, continued tracing can be configured via the stop flag where

false indicates continued tracing
true stops the incoming beams as with any hard target

source

BeamletOptics.Detector Type

julia

Detector <: AbstractDetector

Represents a flat rectangular or quadratic, infinitesimally thin surface in R³. The detector surface is a detection screen that captures incoming ray or beamlet data. The active surface is discretized in the local R² x-y-coordinate system. If configured, beams or beamlets can continue tracing after hitting the detector.

Hits

Hits are represented via the AbstractDetectorHit interface. An empty detector is able to detect any kind of incoming hit, but as soon as the initial hit type has been determined, all following hits must share the same type, i.e. no cross-interaction between hit types is allowed.

Functions

The following functions allow a posteriori evaluation of hit contributions via e.g. f(detector). Refer to the respective function documentation.

Additional information

In general, the detection surface is represented by a flat Mesh that has been rotated such that the surface normals point towards the negative y-axis for the initial positioning. This allows for the definition of a left-handed (x, z) surface coordinate system, where incoming beams intersect against the detector surface normal.

Reset behavior

The Detector must be reset between each call of solve_system! in order to overwrite previous results using the empty! function. Otherwise, the current result will be added onto the previous result.

Moving after solving

Do not move the detector before calculating all parameters of interest for the current system configuration. Since the detector stores pointers to the current system and beam states, silent errors might occur.

Fields

shape: geometry of the active surface, must represent 2D-field in x any y dimensions, normal vector direction must adhere to definition above
hits: a union of Nothing and all implemented AbstractDetectorHits, resettable via empty! (note that only one type is allowed at any time)
stop: a boolean value that allows for continued tracing after "passing through" the detector
lock: locks the Detector for multithreading-safe push!ing to the hits vector

source

BeamletOptics.DifferenceSDF Type

julia

DifferenceSDF{T, S, TT <: Tuple} <: AbstractCompositeSDF{T}

Represents the boolean subtraction of one or more tools from a base AbstractSDF, i.e. base \ (tool_1 ∪ tool_2 ∪ …). Unlike UnionSDF, the constituent SDFs are required to overlap: the tools must intersect the base for anything to be removed.

The intended way to construct these is not explicitly but by subtracting AbstractSDFs using the regular - operator:

julia

s1 = SphereSDF(1.0)
s2 = SphereSDF(0.5)
translate3d!(s2, Point3(0.5, 0.0, 0.0))

# will result in a sphere with a smaller, off-center sphere carved out of it
s_diff = s1 - s2

Non-commutativity and evaluation order

Subtraction is neither commutative nor associative, so a - b and b - a differ, and a chain like a + b - c + d must keep track of when each operand was combined. Repeated subtraction is flattened along its own chain via the identity

so a - b - c produces a single DifferenceSDF with one base and a flat tools tuple, rather than deepening the type on every chained -. Mixed +/- chains still nest (e.g. a + b - c is (a + b) - c, and ... + d afterwards wraps the whole difference in a UnionSDF) — this is what keeps their meaning, since material added after a subtraction must not be carved away by it.

Exactness

Per iquilezles.org/articles/distfunctions, opSubtraction = max(-a, b) is only a bound, not an exact SDF: it under-estimates the true distance near the seam between base and tool. This is the safe direction for sphere tracing — an under-estimate never causes tunneling, it only costs a few extra ray marching iterations near concave creases. Correctness of ray marching hinges on normal3d being resolved by explicit operand selection (as implemented here) rather than by automatic differentiation, which picks the wrong sub-shape at the seam.

source

BeamletOptics.Directed Type

julia

Directed <: AbstractKinematicFrame

Reference frame of a movable value that only has a direction but no orientation, e.g. rays and beams.

Implementation reqs.

position
direction: the direction getter of the type

reset_rotation3d! throws an ArgumentError, use align3d! instead.

source

BeamletOptics.DiscreteRefractiveIndex Type

julia

DiscreteRefractiveIndex{T}

Represents a incomplete set of dispersion data where for each exact wavelength one refractive index value is stored in the data field. Can be called like a function n = n(λ). Does not interpolate between data points. Refer to RefractiveIndex for more information.

source

BeamletOptics.DiscreteRefractiveIndex Method

julia

DiscreteRefractiveIndex(λs, n)

Creates a DiscreteRefractiveIndex dictionary where each wavelength in λs is mapped onto an exact exact refractive index in ns.

Inputs

λs: array of wavelengths
ns: array of refractive indices

source

BeamletOptics.DoubletLens Type

julia

DoubletLens

Represents a two-component cemented doublet lens with two respective refractive indices n = n(λ). See also SphericalDoubletLens.

Fields

front: front Lens component
back: back Lens component

Additional information

Air gap

This component type strongly assumes that both lenses are mounted fully flush with respect to each other. Gaps between the components might lead to incorrect results.

source

BeamletOptics.EvenAsphericalSurface Type

julia

EvenAsphericalSurface{T} <: AbstractRotationallySymmetricSurface{T}

A type representing an aspherical optical surface defined by its radius of curvature, clear (optical) diameter, conic constant, aspheric coefficients and mechanical diameter. This surface is rotationally symmetric about its optical axis.

Fields

spherical::SphericalSurface{T}: The base spherical surface portion of the asphere.
conic_constant::T: The conic constant defining the deviation from a spherical shape.
coefficients::AbstractVector{T}: A vector of even aspheric coefficients for higher-order corrections.

source

BeamletOptics.EvenAsphericalSurface Method

julia

EvenAsphericalSurface(radius, diameter, conic_constant, coefficients::AbstractVector, mechanical_diameter = diameter)

Construct a EvenAsphericalSurface given the radius of curvature, the optical diameter, conic constant, the aspheric coefficients and optionally the mechanical diameter. This constructor automatically sets the mechanical diameter equal to the optical diameter.

Arguments

radius: The radius of curvature of the base spherical surface.
diameter: The clear (optical) diameter of the surface.
conic_constant: The conic constant defining the deviation from a spherical shape.
coefficients::AbstractVector: A vector of even aspheric coefficients for higher-order corrections.
mechanical_diameter: The mechanical diameter of the surface; if not provided, it defaults to diameter.

source

BeamletOptics.GaussianBeamlet Type

julia

GaussianBeamlet{T} <: AbstractBeam{T, Ray{T}}

Ray representation of the stigmatic Gaussian beam as per J. Arnaud (1985). The beam quality M2 is fully considered via the divergence angle. The formalism for the beam parameter calculation is based on the following publications:

Jacques Arnaud, "Representation of Gaussian beams by complex rays." Appl. Opt. 24, 538-543 (1985)

and

Donald DeJager and Mark Noethen, "Gaussian beam parameters that use Coddington-based Y-NU paraprincipal ray tracing," Appl. Opt. 31, 2199-2205 (1992)

Fields

chief: a Beam of Rays to store the chief ray
waist: a Beam of Rays to store the waist ray
divergence: a Beam of Rays to store the divergence ray
λ: beam wavelength in [m]
w0: local beam waist radius in [m]
E0: complex field value in [V/m]
parent: reference to the parent beam, if any (Nullable to account for the root beam which has no parent)
children: vector of child beams, each child beam represents a branching or bifurcation of the original beam, i.e. beam-splitting

Additional information

Beam parameters

Parameters of the beam, e.g. or , can be obtained through the gauss_parameters function.

Astigmatism and abberations

It is assumed, but not forbidden, that the optical system contains non-flat or non-parabolic beam-surface-interactions that cause the beam to obtain astigmatism or higher-order abberations. These can not be represented by the GaussianBeamlet.

source

BeamletOptics.GaussianBeamlet Method

julia

GaussianBeamlet(position, direction, λ, w0; kwargs...)

Constructs a Gaussian beamlet at its waist with the specified beam parameters.

Arguments

The following inputs and arguments can be used to configure the beamlet:

Inputs

position: origin of the beamlet
direction: direction of the beamlet
λ: wavelength of the beamlet in [m]. Default value is 1000 nm.
w0: beam waist (radius) in [m]. Default value is 1 mm.

Keyword Arguments

M2: beam quality factor. Default is 1
P0: beam total power in [W]. Default is 1 mW
z0: beam waist offset in [m]. Default is 0 m
support: Nullable support vector for the construction of the waist and div rays

Additional information

Waist offset

The z0 keyword arg. can be used in order to spawn a beam where the waist is not located at the specified position, but rather at an offset z0 in [m] along the chief ray axis.

Support vector

In order to calculate the basis vectors required for the beamlet construction, a random orthogonal vector is chosen. If results fluctuate due to the randomness of this vector, make sure to specify a fixed orthogonal support vector.

source

BeamletOptics.GaussianBeamletHit Type

julia

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.

source

BeamletOptics.GaussianBeamletInteraction Type

julia

GaussianBeamletInteraction <: AbstractInteraction

This type is used to store the new beamlet section resulting from on optical interaction between a GaussianBeamlet and some AbstractObject. Uses the hint of the chief beam.

Fields

chief: Beam interaction
waist: Beam interaction
divergence: Beam interaction

source

BeamletOptics.GlobalJonesBasis Type

julia

GlobalJonesBasis <: AbstractJonesMatrix

Stores the Jones matrix entries for a polarizing optical element that is aligned with the global y-axis as the optical axis.

source

BeamletOptics.Hint Type

julia

Hint

A Hint can be passed as part of an AbstractInteraction and will inform the tracing algorithm about which AbstractObject in the AbstractSystem will be hit next.

Info

The Hint does not need to result in a guaranteed Intersection. However, if the hinted shape is intersected, it will be immediatly assumed as the correct global intersection.

Fields

object: the object that might or will be intersected next
shape: the underlying shape that will be intersected next, i.e. shape(object), relevant for multi-shape objects

source

BeamletOptics.IntersectableObject Type

julia

IntersectableObject

A passive AbstractObject which can be hit by a beam. In this case, the object acts like a hard target and blocks the beam path.

Fields

shape: an AbstractShape

source

BeamletOptics.Intersection Type

julia

Intersection{T}

Stores data calculated by the intersect3d method. This information can be reused, i.e. for retracing.

Fields:

object: a Nullable reference to the AbstractObject that has been hit (optional but recommended)
shape: a Nullable reference to the AbstractShape of the object that has been hit (optional but recommended)
t: length of the ray parametrization in [m]
n: normal vector at the point of intersection

source

BeamletOptics.Lens Type

julia

Lens{T, S <: AbstractShape{T}, N <: RefractiveIndex} <: AbstractRefractiveOptic{T, N}

Represents an uncoated Lens with a homogeneous RefractiveIndex n = n(λ). Refer to the Lens and SphericalLens constructors for more information on how to generate lenses.

Fields

shape: geometry of the lens, refer to AbstractShape for more information
n: RefractiveIndex function that returns n(λ)

Additional information

Refractive index

The chromatic dispersion of the lens is represented by a λ-dependent function for n and must be provided by the user. For testing purposes, an anonymous function, e.g. λ -> 1.5 can be passed such that the lens has the same refractive index for all wavelengths.

source

BeamletOptics.Lens Method

julia

 Lens(front_surface::AbstractCylindricalSurface, back_surface::AbstractCylindricalSurface, center_thickness::Real, n::RefractiveIndex)

Constructs a new Lens object using the cylindric surface specifications front_surface and back_surface and the center_thickness. These inputs are used to construct a UnionSDF that consists of the appropriate sub-SDFs to represent the shape of the lens.

This method of Lens is specific for cylindric lenses and has some limitations: - The cylinder height of both surfaces has to be identical - No mixture with non-cylindric surfaces is supported at the moment

The material properties are supplied via the n parameter.

Additional information

Radius of curvature (ROC) sign definition

The ROC is defined to be positive if the center is to the right of the surface. Otherwise it is negative.

source

BeamletOptics.Lens Method

julia

 Lens(front_surface::AbstractRotationallySymmetricSurface, back_surface::AbstractRotationallySymmetricSurface, center_thickness::Real, n::RefractiveIndex)

Constructs a new Lens object using the surface specifications front_surface and back_surface and the center_thickness. These inputs are used to construct a UnionSDF that consists of the appropriate sub-SDFs to represent the shape of the lens.

The material properties are supplied via the n parameter.

Additional information

Radius of curvature (ROC) sign definition

The ROC is defined to be positive if the center is to the right of the surface. Otherwise it is negative.

Meniscus

If your specification results in a meniscus lens, only spherical meniscus lenses are supported at the moment.

source

BeamletOptics.LinearPolarizer Type

julia

LinearPolarizer{T, N <: RefractiveIndex} <: AbstractObject{T}

Represents a real, round linear polarizing film laminated between two uncoated glass plates (e.g. Thorlabs LPNIRE100-B), modeled as a thin PolarizationFilter cemented between two Prism substrates that sit flush against the film. Refer to RoundLinearPolarizer for the constructor.

Fields

filter: the thin PolarizationFilter that models the polarizing film
front: front glass substrate Prism
back: back glass substrate Prism

Additional information

Kinematic center

The center of kinematics of this component lies at the center of the film.

Uncoated surfaces

Since the glass substrates are uncoated, a PolarizedRay loses approx. 4 % of its intensity per outer surface at n ≈ 1.5 due to Fresnel reflection, unlike the anti-reflection coated real-world part.

Crossed orientation

When the film orientation is crossed (transmission axis perpendicular to the incident polarization), the beam is terminated at the cemented film interface once the norm of the transmitted electric field falls to or below the cutoff_strength of the underlying PolarizationFilter.

source

BeamletOptics.LocalJonesBasis Type

julia

LocalJonesBasis

Stores the s-p-basis Jones matrix coefficients. Must be defined for x-y-aligned elements where z is the optical axis.

source

BeamletOptics.MeniscusLensSDF Type

julia

MeniscusLensSDF

AbstractSDF-based representation of a positive or negative meniscus lens. When constructed, it is assumed that the lens lies at the origin and the optical axis is aligned with the y-axis. Parameters that lead to a sharp lens edge will cause an error.

Notes

Radius of curvature sign convention

The ROC is defined to be positive if the center is to the right of the surface. Otherwise it is negative.

Fields:

convex: the convex part of the lens composite SDF
cylinder: the cylindrical part of the lens composite SDF
concave: the concave part of the lens composite SDF
thickness: lens thickness on the optical axis

source

BeamletOptics.MeniscusLensSDF Method

julia

MeniscusLensSDF(r1::R1, r2::R2, l::L, d::D, md::MD)

Constructs a positive or negative MeniscusLensSDF with:

r1: front surface radis or curvature
r2: back surface radis or curvature
l: lens thickness
d: lens diameter, default value is one inch
md: mechanical lens diameter, must be > d

source

BeamletOptics.Mesh Type

julia

Mesh <: AbstractMesh

Contains the STL mesh information for an arbitrary shape, that is the vertices that make up the mesh and a matrix of faces, i.e. the connectivity matrix of the mesh. The data is read in using the FileIO.jl and MeshIO.jl packages. Translations and rotations of the mesh are directly saved in absolute coordinates in the vertex matrix. For orientation and translation tracking, a positional and directional matrix are stored.

Fields

vertices: (m x 3)-matrix that stores the edge points of all triangles
faces: (n x 3)-matrix that stores the connectivity data for all faces
dir: (3 x 3)-matrix that represents the current orientation of the mesh
pos: 3-element vector that is used as the mesh location reference
scale: scalar value that represents the current scale of the original mesh

source

BeamletOptics.Mesh Method

julia

Mesh(mesh)

Parametric type constructor for struct Mesh. Takes data of type GeometryBasics.Mesh and extracts the vertices and faces. The mesh is initialized at the global origin. Data type of Mesh is variably selected based on type of vertex data (i.e Float32).

Tip

Mesh vertex data is scaled by factor 1e-3, assuming [m] scale. Ensure that the export program is adjusted accordingly when scaling issues occur.

source

BeamletOptics.Mirror Type

julia

Mirror{S <: AbstractShape} <: AbstractReflectiveOptic

Concrete implementation of a perfect mirror (R = 1) with arbitrary shape.

Reflecting surfaces

It is important to consider that all surfaces of this mirror type are reflecting!

source

BeamletOptics.MissingBackendError Type

julia

MissingBackendError

Custom Exception type that indicates that the Makie extension of BeamletOptics has not been loaded correctly.

source

BeamletOptics.Movable Type

julia

Movable{F <: AbstractKinematicFrame} <: AbstractKinematicTrait

Represents a value that can be moved by the kinematic API. The frame field (Oriented or Directed) selects orientation- or direction-based behaviour of the derived functions.

Rotations are applied about the own position of the value unless a pivot is passed explicitly. A rotation axis can have any non-zero length (it is normalized internally).

Kinematic functions

translate3d!: moves x by an offset vector (primitive, implemented per type)
rotate3d!: rotates x by a rotation matrix R about position(x), or about a given pivot if one is passed (the R-only form is the primitive, implemented per type; the axis/angle and pivot forms are derived from it)
translate_to3d!: moves x so that position(x) coincides with a target point
xrotate3d! / yrotate3d! / zrotate3d!: rotate x by an angle θ [rad] about the global x-, y- or z-axis through position(x)
align3d!: rotates x about position(x) so that direction(x) is aligned with a target vector
reset_translation3d!: moves x so that position(x) is the global origin; available for every Movable, including rays, beams and beam groups
reset_rotation3d!: only available for Oriented values, where it rotates x back to identity orientation; for Directed values (rays, beams) it throws an ArgumentError, use align3d! instead
direction: for Oriented values this is the local y-axis, orientation(x)[:, 2]; Directed values provide their own getter

Sources (rays, beams and beam groups) are additionally reset to their untraced start state by every one of the functions above: a moved but already-traced source would otherwise keep rays or child beams belonging to the old, now geometrically wrong, light path. Moving a beam that is not the root of its beam tree (e.g. one created by a beamsplitter interaction) throws an ArgumentError; move its root beam instead.

Implementation reqs.

If kinematic_trait_of(::Foo) = Movable(...) is declared, Foo must implement the following:

position
translate3d!(::Movable, x::Foo, offset): moves x by offset
rotate3d!(::Movable, x::Foo, R::AbstractMatrix): rotates x by R about position(x)

All other kin. functions listed above are derived from these two primitives.

source

BeamletOptics.MultiShape Type

julia

MultiShape <: AbstractShapeTrait

Represents that the AbstractObject consists of a two or more AbstractShapes.

AbstractObject implementation reqs.

If shape_trait_of(::Foo) = MultiShape() is defined, Foo must implement the following:

Functions

shape(::Foo): a getter function that returns a Tuple of all relevant shapes, e.g. (foo.front, foo.middle, foo.back)

All shapes returned by shape(::Foo) must be movable, see BeamletOptics.AbstractKinematicTrait.

Additional information

Kinematic center

Unless specified otherwise by dispatching position / position! and orientation / orientation! onto custom pos and dir data fields, the position and orientation of the first element returned by shape(object) will be used as the kinematic center for e.g. translate3d!.

source

BeamletOptics.NonInteractableObject Type

julia

NonInteractableObject

A passive AbstractObject which does not interact with the ray tracing simulation but can be moved via the kinematic API.

Fields

shape: an AbstractShape

Usage

This type is intended mainly for visualization purposes, e.g. kinematic mount Meshs, or similar applications. In essence, this object behaves fully transparent. The intersect3d and interact3d methods default to nothing.

source

BeamletOptics.ObjectGroup Type

julia

ObjectGroup <: AbstractObjectGroup

A tree-like storage container for groups of objects. Can store individual objects and subgroups. Main purpose is handling of, i.e., groups of lenses.

Fields

center: a point in 3D space which is regarded as the reference origin of the group
dir: a 3x3 matrix that describes the common orientation of the group
objects: stores AbstractObject, can also store subgroups of type AbstractObjectGroup

Kinematic

A ObjectGroup implements the kinematic functions of AbstractObject. The following logic is applied to

translate3d!: all objects in the group are translated by the offset vector
translate_to3d!: all objects are moved in parallel such that the group center is equal to the target position
rotate3d!: all objects are rotated around the center point with respect to their relative position
set_pivot3d!: moves the group center (the pivot used above) without moving any of its objects

The objects must be either all static or all movable, otherwise the constructor throws an ArgumentError. The group takes that kinematic class, see BeamletOptics.AbstractKinematicTrait.

source

BeamletOptics.Oriented Type

julia

Oriented <: AbstractKinematicFrame

Reference frame of a movable value with a full local coordinate system, e.g. shapes, objects and beam groups.

Implementation reqs.

position / position!
orientation / orientation!: a right-handed orthonormal 3x3 matrix

direction returns the local y-axis, i.e. orientation(x)[:, 2]. reset_rotation3d! rotates x by transpose(orientation(x)) about its position and then sets the orientation to the identity.

source

BeamletOptics.PlanoSurfaceSDF Type

julia

PlanoSurfaceSDF

AbstractSDF-based representation of two flat optical surfaces, i.e. equivalent to the CylinderSDF. When constructed, it is assumed that the first flat surface lies at the origin and the optical axis is aligned with the positive y-axis.

Fields:

diameter: the outer diameter of the circular flat lens surface
thickness: the distance between the flat surfaces

source

BeamletOptics.PointSource Type

julia

PointSource <: AbstractBeamGroup

Represents a cone of Beams being emitted from a single point in space.

Fields

beams: a vector of all Beams originating from the source
NA: the numerical_aperture of the point source spread angle
center: source position, pivot for rotations
orientation: right-handed orthonormal matrix, columns are the sampling reference vector, the central source direction and their cross product, see AbstractBeamGroup

Functions

numerical_aperture: returns the NA of the source

source

BeamletOptics.PointSource Method

julia

PointSource(pos, dir, θ, λ; num_rings, num_rays, basis)

Spawns a point source of Beams at the specified position and direction. The point source is modelled as a collection of concentric beam fans centered around the center beam. The amount of beam rings between the center ray and half-spread-angle θ can be specified via num_rings.

Info

Note that for correct sampling, the number of rays should be atleast 20x the number of rings.

Arguments

The following inputs and arguments can be used to configure the PointSource:

Inputs

pos: center beam starting position
dir: center beam starting direction
θ: half spread angle in rad, must be < π
λ = 1e-6: wavelength in [m], default val. is 1000 nm

Keyword Arguments

num_rings: number of concentric beam rings, default is 10
num_rays: total number of rays in the source, default is 100x num_rings
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle for the source rings.

Reproducible sampling

If no basis is passed, the orthogonal basis vectors are derived from dir deterministically, so two sources sharing the same dir, θ, num_rings and num_rays sample exactly the same ray directions. Pass a basis to rotate the azimuthal sampling of a source about its own axis, e.g. to interleave several otherwise identical sources.

source

BeamletOptics.PointSource Method

julia

PointSource(beams, NA, pos, dir::AbstractVector)
PointSource(beams, NA, pos, orientation::AbstractMatrix)

Wraps existing beams into a PointSource with the numerical aperture NA and the source position pos. The group orientation is either derived from the central direction dir (the sampling reference vector is then picked deterministically via normal3d), or passed explicitly as a right-handed orthonormal 3x3 orientation matrix whose second column is the central direction. An invalid orientation throws an ArgumentError.

source

BeamletOptics.PolarizationFilter Type

julia

PolarizationFilter <: AbstractJonesPolarizer

Represents a zero-thickness, ideal polarization filter.

source

BeamletOptics.PolarizationFilter Method

julia

PolarizationFilter(edge_length; cutoff_strength)

Spawns a thin, rectangular PolarizationFilter. The edge_length has to be specified in [m]. The filter is aligned with the global y-axis and transmits along the x-axis, while blocking polarization components along the global z-axis.

source

BeamletOptics.PolarizedRay Type

julia

PolarizedRay{T} <: AbstractRay{T}

A ray type to model the propagation of an electric field vector based on the publication:

Yun, Garam, Karlton Crabtree, and Russell A. Chipman. "Three-dimensional polarization ray-tracing calculus I: definition and diattenuation." Applied Optics 50.18 (2011): 2855-2865.

The geometrical ray description is identical to the standard Ray. The polarization interaction can be described in local s-p-coordinates but must be transformed into global coordinates using the method described in the publication above, see also _calculate_global_E0.

Fields

pos: a point in R³ that describes the Ray origin
dir: a normalized vector in R³ that describes the Ray direction
intersection: refer to Intersection
λ: wavelength in [m]
n: refractive index along the beam path
E0: complex-valued 3-tuple to represent the electric field in global coordinates

Jones matrices

In local coordinates the Jones matrices in the case of reflection/refraction are defined as

reflection: [-rₛ 0; 0 rₚ]
transmission: [tₛ 0; 0 tₚ]

where r and t are the complex-valued Fresnel coefficients (see also fresnel_coefficients).

Additional information

Field vector

It is assumed that the electric field vector stays orthogonal to the direction of propagation throughout the optical system.

Intensity

E0 can not be converted into an intensity value, since a single PolarizedRay can not directly model the change in intensity during imaging by an optical system.

source

BeamletOptics.PolarizedRay Method

julia

PolarizedRay(pos, dir, λ = 1000e-9, E0 = [1, 0, 0])

1 V/m in x-dir.

source

BeamletOptics.PolarizedRayHit Type

Stores a PolarizedRay hit

source

BeamletOptics.Prism Type

julia

Prism{T, S <: AbstractShape{T}, N <: RefractiveIndex} <: AbstractRefractiveOptic{T, N}

Essentially represents the same functionality as Lens. Refer to its documentation.

source

BeamletOptics.Ray Type

julia

Ray{T} <: AbstractRay{T}

Mutable struct to store ray information.

Fields

pos: a point in R³ that describes the Ray origin
dir: a normalized vector in R³ that describes the Ray direction
intersection: refer to Intersection
λ: wavelength in [m]
n: refractive index along the beam path

source

BeamletOptics.Ray Method

julia

Ray(pos, dir, λ=1000e-9)

Constructs a Ray where:

pos: is the Ray origin
dir: is the Ray direction of propagation, normalized to unit length

Optionally, a wavelength λ can be specified. The start refractive index is assumed to be in vacuum (n = 1).

source

BeamletOptics.RayHit Type

Stores a Ray hit

source

BeamletOptics.RectangularFlatSurface Type

julia

RectangularFlatSurface{T} <: AbstracCylindricalSurface{T}

A type representing a planar rectangular surface, which is only parametrized by its size.

Fields

size::T: The size of the planar surface

source

BeamletOptics.RectangularPlateBeamsplitter Type

julia

RectangularPlateBeamsplitter <: AbstractPlateBeamsplitter

A plate beamsplitter with rectangular substrate and a single coated face. For more information refer to the AbstractPlateBeamsplitter docs.

Fields

substrate: a rectangular Prism that acts as the substrate
coating: a ThinBeamsplitter that acts as the coating

Additional information

Kinematic center

The center of kinematics of this splitter lies at the center of the coating.

source

BeamletOptics.RectangularPlateBeamsplitter Method

julia

RectangularPlateBeamsplitter(width, height, thickness, n; reflectance=0.5)

Creates a RectangularPlateBeamsplitter. The splitter is aligned with the negative y-axis. The splitter coating is centered at the origin. See also RoundPlateBeamsplitter.

Inputs

width: substrate width along the x-axis in [m]
height: substrate height along the z-axis in [m]
thickness: substrate thickness along the y-axis in [m]
n: the RefractiveIndex of the substrate

Keywords

reflectance: defines the splitting ratio in [-], i.e. R = 0 ... 1.0

source

BeamletOptics.Retroreflector Type

julia

Retroreflector

A Retroreflector reflects incoming rays back toward their source, independent of the incident angle. The shape is represented by a tetrahedral Mesh.

Fields

mesh: shape of the Retroreflector

source

BeamletOptics.Retroreflector Method

julia

Retroreflector(scale)

Spawns a Retroreflector.

Inputs

scale: a scaling factor for the size of the retroreflector, e.g. 1e-3 for 1 mm

source

BeamletOptics.RightAnglePrismSDF Type

julia

RightAnglePrismSDF <: AbstractSDF

Implements the SDF of a right angle prism with symmetric leg length l and height h. Note that these values are stored in the dimensions field as:

dimensions::Point3 = ( leg_length, # dim in x leg_length, # dim in y height, # dim in z )

Alignment

Note that the prism is not aligned with the positive y-axis!

source

BeamletOptics.RightAnglePrismSDF Method

julia

RightAnglePrismSDF(leg_length, height)

Constructs a symmetric right angle prism with leg_length in x and y and height z in [m].

source

BeamletOptics.RingSDF Type

julia

RingSDF <: AbstractSDF

Implements the SDF of a ring in the x-z-plane for some distance in the y axis. This allows to add planar outer sections to any SDF which fits inside of the ring.

source

BeamletOptics.RingSDF Method

julia

RingSDF(inner_radius, width, thickness)

Constructs a ring with inner_radius with a width and some thickness.

source

BeamletOptics.RoundPlateBeamsplitter Type

julia

RoundPlateBeamsplitter <: AbstractPlateBeamsplitter

A plate beamsplitter with cylindrical substrate and a single coated face. For more information refer to the AbstractPlateBeamsplitter docs.

Fields

substrate: a cylindrical Prism that acts as the substrate
coating: a RoundThinBeamsplitter that acts as the coating

Additional information

Kinematic center

The center of kinematics of this splitter lies at the center of the coating.

source

BeamletOptics.RoundPlateBeamsplitter Method

julia

RoundPlateBeamsplitter(diameter, thickness, n; reflectance=0.5)

Creates a RoundPlateBeamsplitter. The splitter is aligned with the negative y-axis. The coating is centered at the origin. See also RectangularPlateBeamsplitter.

Inputs

diameter: x-z-plane substrate diameter in [m]
thickness: substrate thickness along the z-axis in [m]
n: the RefractiveIndex of the substrate

Keywords

reflectance: defines the splitting ratio in [-], i.e. R = 0 ... 1.0

source

BeamletOptics.SellmeierEquation Type

julia

SellmeierEquation

A parametric type representing the six-coefficient Sellmeier equation for a transparent dielectric material. The Sellmeier equation models the wavelength dependence of the refractive index n(λ) in the material's transparency window. This type can provide n(λ) via a functor call, e.g.:

julia

NBK7 = SellmeierEquation(...)
n_532 = NBK7(532e-9)

Info

When initializing this type, the data should be provided with the classic μm-based coefficients. However, when calling the function, use SI-units, e.g. 532e-9 for 532 nm.

Fields

B1, B2, B3 : dimensionless Sellmeier coefficients.
C1, C2, C3 : squared resonance wavelengths in μm².

source

BeamletOptics.SellmeierEquation Method

Returns the ref. index n(λ) for the six coefficient Sellmeier equation.

source

BeamletOptics.SingleShape Type

julia

SingleShape <: AbstractShapeTrait

Represents that the AbstractObject consists of a single underlying shape.

AbstractObject implementation reqs.

If shape_trait_of(::Foo) = SingleShape() is defined, Foo must implement the following:

Fields

shape: a single concrete AbstractShape, e.g. a CylinderSDF

source

BeamletOptics.SphereSDF Type

julia

SphereSDF

Implements the SDF of a perfect sphere. Orientation is fixed to unity matrix.

source

BeamletOptics.SphericalSurface Type

julia

SphericalSurface{T} <: AbstractRotationallySymmetricSurface{T}

A type representing a spherical optical surface defined by its radius of curvature, clear (optical) diameter, and mechanical diameter. This surface is rotationally symmetric about its optical axis.

Fields

radius::T: The radius of curvature of the spherical surface. A positive value indicates that the center of curvature lies to the right of the vertex (following ISO 10110).
diameter::T: The clear (optical) aperture of the surface.
mechanical_diameter::T: The overall mechanical diameter of the surface. In many cases, this is equal to the optical diameter, but it can be set independently if the mechanical mount requires a larger dimension.

source

BeamletOptics.SphericalSurface Method

julia

SphericalSurface(radius, diameter)

Construct a SphericalSurface given the radius of curvature and the optical diameter. This constructor automatically sets the mechanical diameter equal to the optical diameter.

Arguments

radius: The radius of curvature of the surface.
diameter: The clear (optical) diameter of the surface.

source

BeamletOptics.Static Type

julia

Static <: AbstractKinematicTrait

Represents a value that cannot be moved. Every kinematic function throws an ArgumentError; the getters (e.g. position, orientation) stay available. This is the fallback of kinematic_trait_of.

source

BeamletOptics.StaticSystem Type

julia

StaticSystem <: AbstractSystem

A static container storing the optical elements of, i.e. a camera lens or lab setup. Compared to System this way defining the system is less flexible, i.e. no elements can be added or removed after construction but it allows for more performant ray-tracing.

Warning

This type uses long tuples for storing the elements. This container should not be used for very large optical systems as it puts a lot of stress onto the compiler.

Fields

objects: vector containing the different objects that are part of the system (subtypes of AbstractObject)

source

BeamletOptics.System Type

julia

System <: AbstractSystem

A container storing the optical elements of, i.e. a camera lens or lab setup.

Fields

objects: vector containing the different objects that are part of the system (subtypes of AbstractObject)

source

BeamletOptics.ThinBeamsplitter Type

julia

ThinBeamsplitter <: AbstractBeamsplitter

Represents a 2D beam-splitting device.

Fields

shape: 2D AbstractShape at which the splitting process occurs (e.g. a 2D-Mesh)
reflectance: scalar reflection factor
transmittance: scalar transmission factor

Warning

Note that the transmittance should be calculated from an input reflectance in order to ensure that R² + T² = 1.

source

BeamletOptics.ThinBeamsplitter Method

julia

ThinBeamsplitter(width, height; reflectance=0.5)

Creates a zero-thickness, lossless, non-polarizing 2D rectangular ThinBeamsplitter where

width: is the x-dir. edge length in [m]
height: is the z-dir. edge length in [m]
reflectance: kw-arg that determines how much light is reflected, i.e. 0.7 for a 70:30 splitter

Additional information

Reflectance

The input value for the reflectance R is normed such that R² + T² = 1, where T is the transmittance. The transmittance is calculated via T = √(1 - R²).

Reflection phase jump

Note that the reflection phase jump θᵣ is implemented by the individual interact3d-methods. Refer to them for more information.

source

BeamletOptics.TripletLens Type

julia

TripletLens

Represents a three-component cemented triplet lens with three respective refractive indices n = n(λ). See also SphericalTripletLens.

Fields

front: front Lens component
middle: middle Lens component
back: back Lens component

Additional information

Clear apertures

If the surfaces need different clear apertures (e.g. a steep last surface), build the elements via Lens(SphericalSurface(r1, d1), SphericalSurface(r2, d2), l, n) and pass them to TripletLens. SphericalTripletLens uses one diameter for all surfaces.

Air gap

This component type strongly assumes that all three lenses are mounted fully flush with respect to each other. Gaps between the components might lead to incorrect results.

Total internal reflection

Total internal reflection at a cemented interface between two elements is not modeled correctly.

source

BeamletOptics.UnionSDF Type

julia

UnionSDF{T, TT <: Tuple} <: AbstractSDF{T}

This SDF represents the merging of two or more SDFs. If the constituent SDFs do not overlap (they can and should touch) the resulting SDF should be still exact if the constituent SDFs are exact.

The intended way to construct these is not explicitely but by just adding two AbstractSDFs using the regular + operator.

julia

s1 = SphereSDF(1.0)
translate3d!(s1, Point3(0, 1.0, 0.0))

s2 = SphereSDF(1.0)

# will result in a SDF with two spheres touching each other.
s_merged = s1 + s2

source

BeamletOptics._LazyProgress Type

julia

_LazyProgress

Thread-safe progress counter for long loops. It draws a ProgressMeter.Progress bar only once the loop has run for threshold seconds, see get_progress_threshold.

_tick! costs one atomic increment and one time() call per item. The bar is created lazily and redrawn at most every dt seconds by one thread at a time (trylock), so an invisible bar never contends for a lock. Use it through _with_progress, which finishes the bar, or cancels it if the loop throws.

Fields

n: total number of items
desc: description printed in front of the bar
enabled: if false, _tick! returns after a single branch
output: stream the bar is drawn to
count: number of finished items
tnext: earliest time() at which the bar is created or redrawn, Inf stops drawing
dt: minimum interval in s between redraws
lock: serializes creating, redrawing and stopping the bar
bar: the ProgressMeter bar, nothing until it is first drawn

source

BeamletOptics._LazyProgress Method

julia

_LazyProgress(progress::Bool, n, desc)

Progress counter for the progress keyword of a public function. It is enabled only if progress is true and stderr is a terminal (Base.TTY), so documentation builds, CI logs and piped output stay clean.

source

BeamletOptics._LazyProgress Method

julia

_LazyProgress(n, desc; enabled = true, output = stderr, threshold = get_progress_threshold(), dt = 0.2)

Progress counter for n items that draws to output once threshold seconds have passed.

source

Base.empty! Method

julia

empty!(agb::AstigmaticGaussianBeamlet)

Resets the beamlet to its untraced start state, i.e. resets all 9 component beams and drops all child beamlets.

source

Base.empty! Method

julia

empty!(beam::Beam)

Resets the beam to its untraced start state: all rays but the first are removed, the intersection of the start ray is cleared and all child beams are dropped.

source

Base.empty! Method

julia

empty!(detector)

Resets the field data of the detector. Must be implemented for each concrete subtype of AbstractDetector.

source

Base.empty! Method

julia

empty!(gauss::GaussianBeamlet)

Resets the beamlet to its untraced start state, i.e. resets the chief, waist and divergence beams and drops all child beamlets.

source

Base.length Method

julia

Base.length(ray::AbstractRay)

Returns the geometric length of a ray between its start and intersection point. If no intersection exists, Inf is returned.

Tip

Use optical_path_length to get the optical path length instead.

source

Base.length Method

julia

Base.length(beam::Beam)

Calculate the length of a beam up to the point of the last intersection.

Tip

Use optical_path_length to get the optical path length instead.

source

Base.position Method

julia

position(object) -> Point3

Returns the current position of the object in R³ as a Point3 where (x, y, z) in a right-hand coordinate system.

In general, position(object) returns position(shape(object)) unless specified otherwise.

source

Base.position Method

Enforces that shape has to have the field pos or implement position().

source

BeamletOptics.BiConcaveLensSDF Method

julia

BiConcaveLensSDF(r1, r2, l, d=1inch)

Constructs a bi-concave lens SDF with:

r1 > 0: radius of concave front
r2 > 0: radius of convex back
l: lens thickness
d: lens diameter, default value is one inch
md: mechanical lens diameter, adds an outer ring section to the lens, if md > d.

The spherical surfaces are constructed flush with the cylinder surface.

source

BeamletOptics.BiConvexLensSDF Method

julia

BiConvexLensSDF(r1, r2, l, d=1inch)

Constructs a cylindrical bi-convex lens SDF with:

r1 > 0: radius of convex front
r2 > 0: radius of convex back
l: lens thickness
d: lens diameter, default value is one inch

The spherical surfaces are constructed flush with the cylinder surface.

source

BeamletOptics.CircularFlatMesh Method

julia

CircularFlatMesh(radius, n)

Creates a 2D rectangular Mesh that is centered around the origin and aligned with respect to the negative y-axis.

Inputs

radius: of the mesh in [m]
n: slice discretization factor (higher equals better resolution)

source

BeamletOptics.CollimatedGaussianBeamletSource Method

julia

CollimatedGaussianBeamletSource(pos, dir, D, λ, w0s; n_grid=20)

Generates an n_grid × n_grid square array of AstigmaticGaussianBeamlets, all pointing in the same direction and having the same uniform amplitude. This is used to model macroscopic plane waves or flat-top beams passing through hard apertures (e.g., for Fraunhofer or Fresnel diffraction).

Arguments

pos: Center position of the source plane.
dir: Propagation direction.
D: Total width/height of the square aperture.
λ: Wavelength.
w0s: Sub-waist of each individual beamlet. For smooth overlap, w0s ≈ D / n_grid.
n_grid: Number of beamlets along one axis (default 20 yields 400 total beamlets).
basis: Optional tuple (ex, ey) of the macroscopic sampling grid axes, i.e. the 3D directions corresponding to the x and y grid axes. ex must not be zero or parallel to dir; its component normal to dir becomes the local x-axis of the group orientation.
randomize_axes: If true, the internal principal axes of each individual beamlet are randomly rotated. This averages out numerical grid-alignment biases and is essential for preserving rotational symmetry in focused spots (e.g. Airy disks).
rng: Random number generator to use for randomize_axes.

source

BeamletOptics.ConicMirror Method

julia

ConicMirror(R, k, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an on-axis segment of a general conic-of-revolution Mirror (sphere, paraboloid, ellipsoid or hyperboloid). The vertex lies at the origin and the mirror opens towards the negative y-axis for R > 0. See OffAxisConicMirror for the off-axis case and the full sign/domain conventions.

If hole_diameter is given, a cylindrical bore centred on the optical axis (the local +y-axis) is subtracted from the substrate, piercing it completely (e.g. Cassegrain, Ritchey-Chrétien, or Dall-Kirkham primary).

Inputs

R: Radius of curvature at the vertex [m]; R > 0 concave, R < 0 convex
k: Conic constant; k = -1 is a paraboloid (see ParabolicMirror), k = 0 a sphere (see SphericalMirror)
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter.

source

BeamletOptics.CubeMesh Method

Refer to CuboidMesh.

source

BeamletOptics.CuboidMesh Method

julia

CuboidMesh(x, y, z, θ=π/2)

Constructs the Mesh of a rectangular cuboid as per the dimensions specified by x, y and z. In addition, one side of the mesh can be tilted by an angle θ in order to generate the mesh of a rhomb. The mesh is initialized such that one corner of the cuboid lies at the origin.

Arguments

x, y, z: dimensions for the cube in [m]
θ: parallel tilt angle

source

BeamletOptics.EllipsoidalMirror Method

julia

EllipsoidalMirror(s, s′, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an on-axis segment of an ellipsoidal Mirror whose two real conjugate foci lie at (0, -s, 0) and (0, -s′, 0); the vertex lies at the origin. See OffAxisEllipsoidalMirror for the off-axis case and the sign convention for s, s′.

If hole_diameter is given, a cylindrical bore centred on the optical axis (the local +y-axis) is subtracted from the substrate, piercing it completely (e.g. Dall-Kirkham primary).

Inputs

s, s′: Conjugate object/image distances from the vertex [m], same sign
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter.

source

BeamletOptics.EllipticalGaussianBeamletSource Method

julia

EllipticalGaussianBeamletSource(pos, dir, θ_x, θ_y, λ; num_rings=10, num_rays=100*num_rings, ...)

Spawns a coherent array of AstigmaticGaussianBeamlets distributed on an elliptical cap. This is ideal for modelling sources with different divergences in the fast and slow axes, such as tapered amplifiers or edge-emitting laser diodes.

Arguments

pos: Origin point of the spherical wave.
dir: Central propagation direction.
θ_x, θ_y: Half spread angles in radians for the two principal axes.
λ: Wavelength.
num_rings: Number of concentric angular rings.
num_rays: Total number of beamlets to generate.
overlap: Scaling factor for the sub-waist divergence (default 1.2 ensures smooth overlap).
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle for the source rings.
randomize_axes: If true, the internal principal axes of each individual beamlet are randomly rotated.
rng: Random number generator to use for randomize_axes.
P0: Total power of the source in [W].
E0: Optional Jones vector defining the polarization and phase of the wave.

Reproducible sampling

If no basis is passed, the orthogonal basis vectors are derived from dir deterministically, so two sources sharing the same arguments sample exactly the same beamlet directions. Pass a basis to rotate the azimuthal sampling of a source about its own axis. A basis that is zero or parallel to dir throws.

source

BeamletOptics.GaussianBeamletDecomposition Method

julia

GaussianBeamletDecomposition(pos, dir, λ, w0; n_grid=20)

Decomposes a macroscopic Gaussian beam of waist w0 into an n_grid × n_grid array of microscopic AstigmaticGaussianBeamlets. This allows the accurate tracing of large Gaussian beams through highly aberrative or non-paraxial optical systems, perfectly preserving higher-order phase aberrations via the coherent superposition of the sub-beamlets.

Arguments

pos: Waist center position of the macroscopic beam.
dir: Propagation direction.
λ: Wavelength.
w0: Macroscopic beam waist.
n_grid: Number of beamlets along one axis (default 20 yields 400 total beamlets).
overlap: Scaling factor for the sub-waist relative to grid spacing (default 1.2 ensures smooth overlap).
basis: Optional tuple (ex, ey) of the macroscopic sampling grid axes, i.e. the 3D directions corresponding to the x and y grid axes. ex must not be zero or parallel to dir; its component normal to dir becomes the local x-axis of the group orientation.
randomize_axes: If true, the internal principal axes of each individual beamlet are randomly rotated. This averages out numerical grid-alignment biases and is essential for preserving rotational symmetry in focused spots.
rng: Random number generator to use for randomize_axes.
P0: Total power of the macroscopic Gaussian beam in [W].
E0: Optional Jones vector defining the polarization and initial phase of the beam. If nothing, defaults to linear polarization along the first grid axis.
threshold: Relative amplitude below which beamlets are not spawned (default 1e-4).

source

BeamletOptics.HyperbolicMirror Method

julia

HyperbolicMirror(s, s′, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an on-axis segment of a hyperboloidal Mirror (e.g. a Cassegrain/Gregory secondary, or a Ritchey-Chrétien primary) whose conjugate foci lie at (0, -s, 0) and (0, -s′, 0); the vertex lies at the origin. See OffAxisHyperbolicMirror for the off-axis case and the sign convention.

If hole_diameter is given, a cylindrical bore centred on the optical axis (the local +y-axis) is subtracted from the substrate, piercing it completely (e.g. Ritchey-Chrétien primary).

Cassegrain secondary

The secondary of a Cassegrain/Gregory telescope sees the prime focus behind itself, so pass it as a negative s.

Inputs

s, s′: Conjugate object/image distances from the vertex [m], opposite signs
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter.

source

BeamletOptics.KM100CPMount Method

julia

KM100CPMount()

Returns a MeshDummy of a Thorlabs KM100CP/M kinematic mount for Ø1" optics on a post. The origin lies at the center of a mounted Ø1" mirror, i.e. a RoundPlanoMirror spawned at the origin sits in the mount, and the post base is 81.8 mm below it.

The mesh is loaded from the documentation assets that ship with the package. Combine it with a mirror via ObjectGroup to move both together.

source

BeamletOptics.MeshDummy Method

julia

MeshDummy(loadpath::String)

Creates a NonInteractableObject with a Mesh loaded from the specified file path. Useful for rendering background objects or geometry that does not interact with rays.

source

BeamletOptics.MoellerTrumboreAlgorithm Method

julia

MoellerTrumboreAlgorithm(face::Matrix, ray::Ray)

A culling implementation of the Möller-Trumbore algorithm for ray-triangle-intersection. This algorithm evaluates the possible intersection between a ray and a face that is defined by three vertices. If no intersection occurs, Inf is returned. kϵ is the abort threshold for backfacing and non-intersecting triangles. lϵ is the threshold for negative values of t. This algorithm is fast due to multiple breakout conditions.

source

BeamletOptics.OffAxisConicMirror Method

julia

OffAxisConicMirror(R, k, x_off, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an off-axis segment of a general conic-of-revolution Mirror (sphere, paraboloid, ellipsoid or hyperboloid), offset by x_off from the parent vertex. See ConicSDF for the frame convention (origin, parent axis, opening direction, vertex location).

Inputs

R: Radius of curvature at the parent vertex [m]; R > 0 is concave (opens towards -y), R < 0 is convex (opens towards +y). Must be non-zero.
k: Conic constant. k = -1 is a paraboloid, k = 0 a sphere, -1 < k <= 0 a prolate ellipsoid, k > 0 an oblate ellipsoid, k < -1 a hyperboloid.
x_off: Off-axis distance from the parent vertex to the aperture center [m]
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter. The bore is parallel to the local +y axis through the aperture centre.

For k > -1 the aperture must stay within the domain of the parent conic (abs(x_off) + diameter/2 < abs(R)/sqrt(1+k)), otherwise an ArgumentError is thrown; for k <= -1 there is no such limit. See also ConicMirror for the on-axis case.

Note that hole_axis (collimated/focused bore) exists only for OffAxisParabolicMirror.

source

BeamletOptics.OffAxisEllipsoidalMirror Method

julia

OffAxisEllipsoidalMirror(s, s′, x_off, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an off-axis segment of an ellipsoidal Mirror whose two real conjugate foci lie at object/image distances s, s′ from the parent vertex, offset by x_off. Both foci lie on the same side (the -y, i.e. reflecting, side) of the parent vertex for positive s, s′.

Inputs

s, s′: Conjugate object/image distances from the parent vertex [m], measured positive towards -y (in front of the mirror). Must have the same sign.
x_off: Off-axis distance from the parent vertex to the aperture center [m]
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter. The bore is parallel to the local +y axis through the aperture centre.

The vertex radius of curvature and conic constant are derived via R = 2ss′/(s+s′), k = -((s′-s)/(s′+s))^2. See also EllipsoidalMirror for the on-axis case.

Note that hole_axis (collimated/focused bore) exists only for OffAxisParabolicMirror.

source

BeamletOptics.OffAxisHyperbolicMirror Method

julia

OffAxisHyperbolicMirror(s, s′, x_off, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an off-axis segment of a hyperboloidal Mirror whose conjugate foci lie at object/image distances s, s′ from the parent vertex, offset by x_off. Exactly one focus is virtual, i.e. s and s′ have opposite signs.

Inputs

s, s′: Conjugate object/image distances from the parent vertex [m], measured positive towards -y (real focus, in front of the mirror) and negative towards +y (virtual focus, behind the mirror). Must have opposite signs.
x_off: Off-axis distance from the parent vertex to the aperture center [m]
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter. The bore is parallel to the local +y axis through the aperture centre.

Cassegrain secondary

The secondary of a Cassegrain/Gregory telescope sees the prime focus behind itself, so pass it as a negative s.

The vertex radius of curvature and conic constant are derived via R = 2ss′/(s+s′), k = -((s′-s)/(s′+s))^2. See also HyperbolicMirror for the on-axis case.

Note that hole_axis (collimated/focused bore) exists only for OffAxisParabolicMirror.

source

BeamletOptics.OffAxisParabolicMirror Method

julia

OffAxisParabolicMirror(rfl, diameter; angle=90, thickness=nothing, hole_diameter=nothing, hole_axis=:collimated)

Constructs an Off-Axis Parabolic (OAP) Mirror from:

Inputs

rfl: Reflected Focal Length (distance from aperture center to focus) [m]
diameter: Mirror aperture diameter [m]
angle: Deflection angle in degrees (default: 90°)
thickness: Substrate thickness [m], calculated automatically to ensure solid backing if nothing (default)
hole_diameter: Diameter of the through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter.
hole_axis: Orientation of the through-hole. Options: - :collimated (default): parallel to the collimated beam (local y-axis / substrate normal), centered at the aperture center (0, 0, 0). - :focused: angled towards the parent paraboloid focus (-x_off, x_off^2/(4f) - f, 0) in the segment frame, equivalently (-rfl*sind(angle), -rfl*cosd(angle), 0) with angle in degrees, passing through the aperture center (0, 0, 0) (e.g. for collinear pump-probe beams).

source

BeamletOptics.OffAxisParaboloidSDF Method

julia

OffAxisParaboloidSDF(f, x_off, diameter, thickness)

Constructs a ConicSDF with R = 2f and k = -1, i.e. a segment of a paraboloid of revolution. Kept for backwards compatibility; prefer ConicSDF.

source

BeamletOptics.ParabolicMirror Method

julia

ParabolicMirror(f, diameter; thickness=nothing, hole_diameter=nothing)

Constructs an on-axis parabolic Mirror with focal length f. The vertex of the concave reflecting surface lies at the origin, the mirror opens towards the negative y-axis and its focus lies at (0, -f, 0). The shape is an OffAxisParaboloidSDF without off-axis offset.

If hole_diameter is given, a cylindrical bore centred on the optical axis (the local +y-axis) is subtracted from the substrate, piercing it completely (a Cassegrain primary).

Reflective bore wall

Rays that graze into the hole will reflect off its wall rather than being absorbed.

Inputs

f: Focal length [m]
diameter: Mirror aperture diameter [m]
thickness: Substrate thickness [m], rim sag + 10 mm if nothing (default)
hole_diameter: Diameter of the central through-hole [m], no hole if nothing (default). Must satisfy 0 < hole_diameter < diameter.

source

BeamletOptics.PlanoConcaveAsphericalLensSDF Method

julia

PlanoConcaveAsphericalLensSDF(r, l, d=1inch)

Constructs a plano-concave aspheric lens SDF with:

r > 0: front radius
l: lens thickness
d: lens diameter
cz: aspheric surface chip zone
k : The conic constant of the surface
α_coeffs : The (even) aspheric coefficients, starting with A4.
md: lens mechanical diameter (default: md = d)

The spherical surface is constructed flush with the cylinder surface.

source

BeamletOptics.PlanoConcaveLensSDF Method

julia

PlanoConcaveLensSDF(r, l, d=1inch)

Constructs a plano-concave lens SDF with:

r > 0: front radius
l: lens thickness
d: lens diameter, default value is one inch
md: mechanical lens diameter, must be > d

The spherical surface is constructed flush with the cylinder surface.

source

BeamletOptics.PlanoConvexAsphericalLensSDF Method

julia

PlanoConvexAsphericalLensSDF(r, l, d=1inch)

Constructs a plano-convex aspheric lens SDF with:

r > 0: front radius
l: lens thickness
d: lens diameter
k : The conic constant of the surface
α_coeffs : The (even) aspheric coefficients, starting with A4.

The spherical surface is constructed flush with the cylinder surface.

source

BeamletOptics.PlanoConvexLensSDF Method

julia

PlanoConvexLensSDF(r, l, d=1inch)

Constructs a plano-convex lens SDF with:

r > 0: front radius
l: lens thickness
d: lens diameter, default value is one inch

The spherical surface is constructed flush with the cylinder surface.

source

BeamletOptics.QuadraticFlatMesh Method

julia

QuadraticFlatMesh(width)

Creates a 2D quadratic Mesh. Refer to RectangularFlatMesh for more information.

source

BeamletOptics.RectangularCompensatorPlate Method

julia

RectangularCompensatorPlate(width, height, thickness, n)

Creates a compensator plate (modeled as a Prism) that can be used to remove parallel beam offsets created by e.g. the RectangularPlateBeamsplitter. The compensator is aligned with the positive y-axis. The first surface lies at the origin.

Inputs

width: compensator width along the x-axis in [m]
height: compensator height along the z-axis in [m]
thickness: compensator thickness along the y-axis in [m]
n: the RefractiveIndex of the substrate

source

BeamletOptics.RectangularFlatMesh Method

julia

RectangularFlatMesh(width, height)

Creates a 2D rectangular Mesh that is centered around the origin and aligned with respect to the y-axis. Vertex normals are parallel to the positive y-axis.

Inputs

width: width along the x-axis in [m]
height: height along the z-axis in [m]

source

BeamletOptics.RectangularPlanoMirror Method

julia

RectangularPlanoMirror(width, height, thickness)

Constructs a rectangular plano Mirror based on the input dimensions. The front reflecting surface is normal to the y-axis and lies at the origin.

Inputs

width: of the mirror in x-direction [m]
height: of the mirror in z-direction [m]
thickness: of the mirror in y-direction [m]

source

BeamletOptics.RetroMesh Method

julia

RetroMesh(scale::Real; T = Float64)

Creates an open tetrahedral Mesh with edges derived from the vertices of a unit cube. Can be scaled with a scale factor. The data type for the vertices and internal computations can be adjusted using T (default: Float64).

source

BeamletOptics.RightAnglePrism Method

julia

RightAnglePrism(leg_length, height, n)

Creates a right angle symmetric Prism. The prism is not aligned with the y-axis.

Inputs

leg_length: dimension in x- and y-direction in [m]
height: in [m]
n: RefractiveIndex of the prism

source

BeamletOptics.RightAnglePrismMirror Method

julia

RightAnglePrismMirror(leg_length, height)

Constructs a right-angle prism Mirror with perfect reflectivity (R = 1). The reflecting surface is modeled using a BeamletOptics.RightAnglePrismSDF.

Inputs

leg_length: edge length in x and y [m]
height: height in z-axis [m]

source

BeamletOptics.RoundLinearPolarizer Method

julia

RoundLinearPolarizer(diameter, front_thickness, back_thickness, n; cutoff_strength=eps())

Creates a LinearPolarizer: a round polarizing film cemented between two round glass plates of the given diameter, flush against the film on both sides.

Inputs

diameter: outer diameter of the film and substrates in [m]
front_thickness: thickness of the front glass substrate in [m]
back_thickness: thickness of the back glass substrate in [m]
n: RefractiveIndex of both glass substrates

Keywords

cutoff_strength: passed to RoundPolarizationFilter

Additional information

The component is centered on the film (local origin); the front substrate extends from y = -front_thickness to y = 0, the back substrate from y = 0 to y = back_thickness, along local +y. The film transmits along local x and blocks local z.

source

BeamletOptics.RoundPlanoMirror Method

julia

RoundPlanoMirror(diameter, thickness; hole_diameter=nothing)

Constructs a round plano Mirror with a flat reflecting surface and perfect reflectivity (R = 1). The reflecting surface is modeled using a BeamletOptics.PlanoSurfaceSDF.

Inputs

diameter: mirror diameter [m]
thickness: mirror substrate thickness [m]
hole_diameter: diameter of the central through-hole [m], no hole if nothing (default)

source

BeamletOptics.RoundPolarizationFilter Method

julia

RoundPolarizationFilter(diameter; cutoff_strength)

Spawns a thin, round PolarizationFilter with the given diameter in [m]. The filter is centered at the origin, aligned with the global y-axis and transmits along the x-axis, while blocking polarization components along the global z-axis.

source

BeamletOptics.RoundThinBeamsplitter Method

julia

RoundThinBeamsplitter(diameter; reflectance=0.5)

Creates a zero-thickness, 2D round ThinBeamsplitter with the specified diameter in [m]. For more information, refer to the ThinBeamsplitter constructor.

source

BeamletOptics.SphericalDoubletLens Method

julia

SphericalDoubletLens(r1, r2, r3, l1, l2, d, n1, n2)

Generates a two-component "cemented" doublet lens consisting of two spherical lenses. For radii sign definition, refer to the SphericalLens constructor.

Arguments

r1: radius of curvature for first surface
r2: radius of curvature for second (cemented) surface
r3: radius of curvature for third surface
l1: first lens thickness
l2: second lens thickness
d: lens diameter
n1: first lens RefractiveIndex
n1: second lens RefractiveIndex

source

BeamletOptics.SphericalGaussianBeamletSource Method

julia

SphericalGaussianBeamletSource(pos, dir, θ, λ; num_rings=10, num_rays=100*num_rings)

Decomposes a macroscopic spherical wave (or a highly divergent/focused beam) into a cone of AstigmaticGaussianBeamlets originating from a single point pos.

The angular spread of the beamlets is bounded by the half-angle θ. To ensure a smooth far-field interference pattern without speckle, the sub-waist w0s of each beamlet is automatically calculated such that their far-field divergence perfectly overlaps with adjacent beamlets in the grid.

Arguments

pos: Origin point of the spherical wave.
dir: Central propagation direction.
θ: Half spread angle in radians.
λ: Wavelength.
num_rings: Number of concentric angular rings.
num_rays: Total number of beamlets to generate.
overlap: Scaling factor for the sub-waist divergence (default 1.2 ensures smooth overlap).
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle for the source rings.
randomize_axes: If true, the internal principal axes of each individual beamlet are randomly rotated. This averages out numerical artifacts in the far-field focus.
rng: Random number generator to use for randomize_axes.
P0: Total power of the spherical source in [W].
E0: Optional Jones vector defining the polarization and phase of the spherical wave.

Reproducible sampling

source

BeamletOptics.SphericalLens Function

julia

SphericalLens(r1, r2, l, d=1inch, n=λ->1.5)

Creates a spherical Lens based on:

r1: front radius
r2: back radius
l: lens thickness
d: lens diameter, default is one inch
n: RefractiveIndex as a function of λ, i.e. n = n(λ)

Notes

Radius of curvature (ROC) sign

The ROC is defined to be positive if the center is to the right of the surface. Otherwise it is negative.

Thin lenses

If l is set to zero, a ThinLens will be created. However, note that the actual lens thickness will be different from zero.

source

BeamletOptics.SphericalMirror Method

julia

SphericalMirror(radius, thickness, diameter; hole_diameter=nothing)

Constructs a concave spherical Mirror with perfect reflectivity (R = 1). The reflecting surface is modeled as a BeamletOptics.UnionSDF of a concave spherical surface and a plano substrate, combining BeamletOptics.ConcaveSphericalSurfaceSDF and BeamletOptics.PlanoSurfaceSDF.

Inputs

radius: spherical surface radius of curvature [m]
thickness: substrate thickness [m]
diameter: mirror outer diameter [m]
hole_diameter: diameter of the central through-hole [m], no hole if nothing (default)

source

BeamletOptics.SphericalTripletLens Method

julia

SphericalTripletLens(r1, r2, r3, r4, l1, l2, l3, d, n1, n2, n3)

Generates a three-component "cemented" triplet lens consisting of three spherical lenses. The middle and back lens are translated along +y so that they sit flush. For radii sign definition, refer to the SphericalLens constructor.

Arguments

r1: radius of curvature for first surface
r2: radius of curvature for second (first cemented) surface
r3: radius of curvature for third (second cemented) surface
r4: radius of curvature for fourth surface
l1: first lens thickness
l2: second lens thickness
l3: third lens thickness
d: lens diameter
n1: first lens RefractiveIndex
n2: second lens RefractiveIndex
n3: third lens RefractiveIndex

Additional information

Inf gives a plano surface.

source

BeamletOptics.SquarePlanoMirror Method

julia

SquarePlanoMirror(width, thickness)

Constructs a square plano Mirror with equal width and height. The front reflecting surface is normal to the y-axis and lies at the origin. See also RectangularPlanoMirror.

Inputs

width: the side length of the square mirror in x- and y-direction [m]
thickness: of the mirror in [m]

source

BeamletOptics.SquarePlanoMirror2D Method

julia

SquarePlanoMirror2D(edge_length)

Constructs a 2D square plano Mirror with a given edge_length. The reflecting surface is normal to the y-axis.

Inputs

edge_length: the edge length of the square mirror in [m]

source

BeamletOptics.ThinLens Method

julia

ThinLens(R1::Real, R2::Real, d::Real, n::Function)

Directly creates an ideal spherical thin Lens with radii of curvature R1 and R2 and diameter d and RefractiveIndex n.

source

BeamletOptics.ThinLensSDF Method

julia

ThinLensSDF(r1, r2, d=1inch)

Constructs a bi-convex thin lens SDF-based shape with:

r1 > 0: radius of convex front
r2 > 0: radius of convex back
d: lens diameter, default value is one inch

The spherical surfaces are constructed flush.

source

BeamletOptics.UniformDiscSource Method

julia

UniformDiscSource(pos, dir, diameter, λ; num_rays=1_000, basis)

Generates a ray fan with equal area per ray across a circular pupil using the deterministic sunflower (Fibonacci) pattern.

The radius of the k-th ray (k = 0 … N-1) is ρₖ = diameter/2 ⋅ √((k + ½)/N), its azimuth is k times the golden angle π(3 - √5).

Note

This is merely a CollimatedSource constructor which uses Fibonacci sampling instead of concentric rings. Unlike CollimatedSource, there is no dedicated center beam at pos, i.e. all rays are equally weighted samples of the pupil.

Arguments

The following inputs and arguments can be used to configure the underlying CollimatedSource:

Inputs

pos: center of the pupil disc, i.e. the source position
dir: starting direction of all beams
diameter: outer beam bundle diameter in [m]
λ = 1e-6: wavelength in [m]

Keyword Arguments

num_rays=1000: total number of rays in the source
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle of the sunflower pattern.

Reproducible sampling

If no basis is passed, the orthogonal basis vectors spanning the pupil plane are derived from dir deterministically, so two sources sharing the same dir, diameter and num_rays sample exactly the same ray positions. Pass a basis to rotate the sunflower pattern about its own axis, e.g. to interleave several otherwise identical sources.

source

BeamletOptics.UniformPointSource Method

julia

UniformPointSource(pos, dir, θ, λ; num_rays=1_000, basis)

Generates a cone of Beams emitted from pos with equal solid angle per ray across the spherical cap 0 ≤ ϑ ≤ θ around dir, using the deterministic sunflower (Fibonacci) pattern. The polar angle ϑₖ of the k-th ray (k = 0 … N-1) follows from cos ϑₖ = 1 - (k + ½)/N ⋅ (1 - cos θ), its azimuth is k times the golden angle π(3 - √5).

Note

This is merely a PointSource constructor which uses Fibonacci sampling instead of concentric rings. Unlike PointSource, there is no dedicated center beam along dir, i.e. all rays are equally weighted samples of the cap.

Arguments

The following inputs and arguments can be used to configure the underlying PointSource:

Inputs

pos: starting position of all beams
dir: central source direction, i.e. the cone axis
θ: half spread angle in rad, must be < π
λ = 1e-6: wavelength in [m], default val. is 1000 nm

Keyword Arguments

num_rays=1000: total number of rays in the source, must be ≥ 1
basis: Optional reference vector (e.g. [1,0,0]) to define the starting azimuthal angle of the sunflower pattern. Must not be zero or parallel to dir.

Reproducible sampling

If no basis is passed, the orthogonal basis vectors are derived from dir deterministically, so two sources sharing the same dir, θ and num_rays sample exactly the same ray directions. Pass a basis to rotate the sunflower pattern about its own axis, e.g. to interleave several otherwise identical sources.

source

BeamletOptics.WavefrontBeamletDecomposition Method

julia

WavefrontBeamletDecomposition(x, y, amplitude, phase, dir, λ; threshold=1e-4)

Decomposes an arbitrary complex scalar field (defined by a spatial amplitude and phase distribution on a 2D grid x and y) into a collection of AstigmaticGaussianBeamlets.

This function uses the Eikonal approximation to map the local phase gradient into a local propagation direction for each beamlet. It allows users to import arbitrary, aberrated, or custom beam profiles (e.g. from a camera or a wavefront sensor) and propagate them through a BeamletOptics system.

The grid is placed in the plane normal to dir through the global origin, i.e. the group center is (0, 0, 0). Use translate3d! to move the decomposed field to its actual position.

Arguments

x, y: Vectors defining the 1D spatial coordinates of the 2D field grid.
amplitude: 2D array of field amplitudes (length(x) × length(y)).
phase: 2D array of phase values in radians.
dir: The macroscopic reference propagation direction (e.g., [0, 1, 0]).
λ: Wavelength.
threshold: Relative amplitude threshold below which beamlets are not spawned (saves computation).
overlap: Scaling factor for the sub-waist relative to grid spacing (default 1.2 ensures smooth overlap).
basis: Optional tuple (ex, ey) of the macroscopic sampling grid axes, i.e. the 3D directions corresponding to the x and y input axes. ex must not be zero or parallel to dir; its component normal to dir becomes the local x-axis of the group orientation.
randomize_axes: If true, the internal principal axes of each individual beamlet are randomly rotated. This averages out numerical grid-alignment biases and helps preserve rotational symmetry in focused patterns.
rng: Random number generator to use for randomize_axes.
E0: Optional reference polarization vector or Jones vector. If nothing, defaults to linear polarization along the first grid axis.

source

BeamletOptics._aux_beams Method

Return a tuple of the 8 auxiliary (parabasal) beams.

source

BeamletOptics._beams_hits_same_shape Method

julia

_beams_hits_same_shape(agb, id)

Tests if all 9 component rays at section id hit the same object shape.

source

BeamletOptics._beams_hits_same_shape Method

julia

_beams_hits_same_shape(gauss, id)

Tests if all rays at section id of gauss hit the same object shape. Returns true or false.

source

BeamletOptics._calculate_global_E0 Method

julia

_calculate_global_E0(in_dir, out_dir, normal, J)

Calculates the resulting polarization matrix as per the publication by Yun et al. for each surface interaction. If the normal- vector and the in- and out-directions of propagation are in parallel, an arbitrary basis is chosen for the s- and p-components.

Arguments

in_dir: propagation direction before surface interaction
out_dir: propagation direction after surface interaction
normal: surface normal at the point of intersection
J: Jones matrix extended to 3x3, e.g. [-rₛ 0 0; 0 rₚ 0; 0 0 1] for reflection

source

BeamletOptics._check_kinematic_members Method

julia

_check_kinematic_members(members)

Throws an ArgumentError if some members of a container are Static and some are Movable. Empty collections pass.

source

BeamletOptics._check_orientation Method

julia

_check_orientation(M, T) -> SMatrix{3,3,T,9}

Validates that M is a right-handed orthonormal 3x3 matrix, i.e. MᵀM ≈ I and det M ≈ 1 within √eps(T), and converts it into an SMatrix{3,3,T,9}. Throws an ArgumentError otherwise.

source

BeamletOptics._component_beams Method

Return a tuple of all 9 component beams of the AstigmaticGaussianBeamlet.

source

BeamletOptics._component_beams Method

julia

_component_beams(beam::AbstractBeam)

Returns a tuple of the component Beams of a composite beam (e.g. a GaussianBeamlet), chief beam first. Required for the kinematic API of composite beams.

source

BeamletOptics._component_beams Method

Return a tuple of the chief, waist and divergence beams of the GaussianBeamlet.

source

BeamletOptics._container_trait Method

julia

_container_trait(members)

Returns the kinematic trait of a container with homogeneous members (see _check_kinematic_members): Static() if the members are static, else Movable(Oriented()).

source

BeamletOptics._film_interface Method

julia

_film_interface(system, lp::LinearPolarizer, from, to, beam, ray::PolarizedRay)

Handles the cemented from → to glass interface for a PolarizedRay. The polarizing film acts on the incident field (still expressed in from) before the ray crosses into to. In case of total internal reflection at the cemented interface, the ray is reflected back into from and the film is not applied.

source

BeamletOptics._film_interface Method

julia

_film_interface(system, lp::LinearPolarizer, from, to, beam, ray::Ray)

Handles the cemented from → to glass interface for an unpolarized Ray: the film has no effect, only glass-to-glass refraction (with total internal reflection handling) occurs.

source

BeamletOptics._group_orientation Method

julia

_group_orientation(dir, e1, T) -> SMatrix{3,3,T,9}

Returns the orientation matrix of a beam group with the columns (e1, dir, e1 × dir), i.e. local x = sampling reference vector e1, local y = optical axis dir. Both inputs are normalized, e1 must be normal to dir.

source

BeamletOptics._is_film_interface Method

julia

_is_film_interface(lp::LinearPolarizer, from, ray::AbstractRay)::Bool

Tests whether ray, having just crossed a prism (from is lp.front or lp.back), is exiting through the flat inner face that is cemented to the polarizing film (as opposed to exiting the outer face or the cylindrical edge close to the film).

source

BeamletOptics._is_static Method

julia

_is_static(x)

Returns true if the kinematic_trait_of x is Static.

source

BeamletOptics._modify_beam_head! Method

Used mainly for retracing. Updates beam children data.

source

BeamletOptics._modify_beam_head! Method

Used mainly for retracing. Updates beam children data.

source

BeamletOptics._orthogonal_basis_vector Method

julia

normal3d(input)

Returns a vector with unit length that is perpendicular to the input vector. The orientation is chosen deterministically to guarantee reproducible bases.

source

BeamletOptics._pseudo_cross2d Method

julia

_pseudo_cross2d(a, b, c)

Calculates the triple product (a × b) ⋅ c using a non-conjugating dot product.

source

BeamletOptics._pseudo_dot Method

julia

_pseudo_dot(a, b)

Calculates the non-conjugating dot product a ⋅ b = Σ aᵢbᵢ.

source

BeamletOptics._ray_to_plane_projection Method

julia

_ray_to_plane_projection(plane_pos, plane_normal, ray)

Projects a ray onto a plane defined by plane_pos and plane_normal. Returns the offset vector h (from plane_pos to projected point) and the projected ray slope u.

source

BeamletOptics._raymarch_inside Method

julia

_raymarch_inside(object::AbstractSDF, pos, dir; num_iter=1000, dl=0.1)

Perform the ray marching algorithm if the starting pos is inside of object.

source

BeamletOptics._raymarch_outside Method

julia

_raymarch_outside(shape::AbstractSDF, pos, dir; num_iter=1000, eps=1e-10)

Perform the ray marching algorithm if the starting pos is outside of shape.

source

BeamletOptics._refract_transmitted! Method

julia

_refract_transmitted!(child, ray, dir)

Sets the direction of the transmitted child ray of the coating to the refracted direction dir. For a PolarizedRay, the field is transformed into the new direction as well.

source

BeamletOptics._sampling_basis Method

julia

_sampling_basis(dir, basis, T)

Returns the unit-length reference vector that seeds the azimuthal sampling of a beam group. dir must already be normalized.

If basis is nothing, a vector normal to dir is picked deterministically via normal3d. Otherwise basis is projected into the plane normal to dir, which lets a caller rotate the sampling pattern of a source about its own axis.

Throws if basis has no significant component in that plane, i.e. if it is zero or parallel to dir. The test is relative to norm(basis) because projecting an unnormalized vector leaves a residual that scales with its length; an absolute tolerance would let a parallel basis through and yield NaN sampling.

source

BeamletOptics._tick! Method

julia

_tick!(p::_LazyProgress)

Count one finished item. Safe to call from any thread.

source

BeamletOptics._transverse Method

julia

_transverse(E0, dir)

Removes the component of the field E0 along dir. For nearly parallel in- and out-directions, the s-p basis of _calculate_global_E0 is ill-conditioned and E0 would otherwise keep a small component along the direction of propagation.

source

BeamletOptics._with_progress Method

julia

_with_progress(f, p::_LazyProgress)
_with_progress(f, progress::Bool, n, desc)

Run f(p), which calls _tick!(p) once per finished item, and return its result. Afterwards the bar is completed. If f throws, e.g. an InterruptException from Ctrl-C, the bar is cancelled before the exception is rethrown, so no half-drawn bar is left behind. In both cases later ticks draw nothing.

source

BeamletOptics._world_to_sdf Method

julia

_world_to_sdf(sdf, point)

Transforms the coordinates of point into a reference frame where the sdf lies at the origin. Useful to represent translation and rotation. If rotations are applied, the rotation is applied around the local sdf coordinate system.

source

BeamletOptics.align3d! Method

julia

align3d!(x, target)

Rotates x about its position such that its direction is aligned with target. See BeamletOptics.Movable.

source

BeamletOptics.align3d Method

julia

align3d(start::AbstractVector, target::AbstractVector)

Returns the rotation matrix R that will align the start vector to be parallel to the target vector. Based on 'Avoiding Trigonometry' by Íñigo Quílez. The resulting matrix was transposed due to column/row major issues. Vector length is maintained. This function is very fast.

source

BeamletOptics.angle3d Function

julia

angle3d(ray::AbstractRay, intersect::Intersection=intersection(ray))

Calculates the angle between a ray and its or some other intersection.

source

BeamletOptics.angle3d Method

julia

angle3d(target::AbstractArray, start::AbstractArray, reference::AbstractArray)

Returns the angle between the target and start vector in rad. In addition, a reference axis must be specified. This axis is used in order to determine the angle sign of rotation according to the right hand rule.

source

BeamletOptics.angle3d Method

julia

angle3d(target::AbstractVector, start::AbstractVector)

Returns the angle between the target and start vector in rad.

source

BeamletOptics.arrow! Method

julia

arrow!(ax, pos, dir; scale=1, kwargs...)

Draws a single 3D arrow from pos pointing along dir into ax, if a suitable backend is loaded, scaled to a fixed on-screen length (independent of dir's own norm) so it stays legible next to CAD geometry. If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.aspheric_equation Method

aspheric_equation(r, c, k, α_coeffs)

The aspheric surface equation. The asphere is defined by:

c : The curvature (1/radius) of the surface
k : The conic constant of the surface
α_coeffs : The (even) aspheric coefficients, starting with A4.

This function returns NaN if the square root argument becomes negative.

Note

Only even aspheres are implemented at the moment. This will change soon.

source

BeamletOptics.base_transform Function

julia

base_transform(base, base2=I(3))

Return the base transformation matrix for transforming from vectors given relative to base2 into base.

source

BeamletOptics.bounding_sphere Method

julia

bounding_sphere(sdf)

Returns nothing or a center point and the radius of a sphere which encloses the shape of the SDF. This function is currently only used for rendering SDFs but might be used in the future to optimize the raymarching algorithm, by tracing against the bounding sphere of and SDF first, instead of calling the more costly complex SDF.

source

BeamletOptics.bounding_sphere Method

julia

bounding_sphere(d::DifferenceSDF)

Returns the bounding_sphere of d.base — the result of a subtraction is always a subset of the base, so the base's bounding sphere (or nothing, if it has none) also bounds d.

source

BeamletOptics.calc_center_point Method

julia

calc_center_point(::AbstractCenterAlgorithm, xs::Vector{T}, zs::Vector{T}, projection_factor::Vector{T}) where T

Calculates a central 2D point based on a distribution of points, specified by xs and zs. The algorithm can be selected by specifying a concrete AbstractCenterAlgorithm. In addition, projection factors for each hit point can be passed.

Returns (x0, z0).

source

BeamletOptics.calc_local_lims Method

julia

calc_local_lims(pd::Detector; kwargs...)

Calculates the limiting values for the flat E-field evaluation grid based on the detector data.

source

BeamletOptics.calc_local_lims Method

julia

calc_local_lims(pd::Detector, hits::Vector{GaussianBeamletHit}; crop_factor=1, num_spots=50, kwargs...)

Computes a 2D bounding box around the circular or elliptical waist of GaussianBeamlet hits. Assumes that the beamlet is approximately cylindrical around its optical axis at the point of intersection.

Keyword arguments

For available keyword args., refer to the corresponding calc_local_pos function.

source

BeamletOptics.calc_local_lims Method

julia

calc_local_lims(pd::Detector, hits::Vector{<:AbstractRayHit}; crop_factor=1, center=Centroid())

Compute a symmetric [x_min,x_max]×[z_min,z_max] box around the hit positions weighted centroid for ray-based spot diagrams.

• If center==Centroid() (the default), uses x0 = ∑ wᵢ·xᵢ / ∑ wᵢ, z0 = ∑ wᵢ·yᵢ / ∑ wᵢ with wᵢ = projection_factor. • If center==MinMax(), falls back to the midpoint of [min,max].

Returns (x_min, x_max, z_min, z_max).

source

BeamletOptics.calc_local_pos Method

julia

calc_local_pos(pd::Detector; kwargs...)

Calculates the hit position of all registered hits in local detector coordinates.

source

BeamletOptics.calc_local_pos Method

julia

calc_local_pos(pd::Detector, hits::Vector{AstigmaticGaussianBeamletHit}; crop_factor=1, num_spots=50)

Calculates a projected ellipse of 2D hit spots for each hit of an AstigmaticGaussianBeamlet on the Detector.

source

BeamletOptics.calc_local_pos Method

julia

calc_local_pos(pd::Detector, hits::Vector{GaussianBeamletHit}; crop_factor=1, num_spots=50)

Calculates a projected circle or ellipse of 2D hit spots for each hit of a GaussianBeamlet on the Detector. The spot coordinates are returned in a left-handed (x, z) coordinate system where the detector surface normal points towards the incoming beamlets.

Keyword arguments

crop_factor=1: scales the beam waist radius used to determine the bounding box
num_spots=50: determines the number of 2D hits used to determine the bounding circle/ellipse

source

BeamletOptics.check_optical_invariant Method

julia

check_optical_invariant(agb, i; threshold = get_invariant_threshold())

Evaluate the complex optical invariant h1 . u2 - h2 . u1 = 0 at segment i. Returns true if the invariant holds (within threshold), and false otherwise.

source

BeamletOptics.children! Method

julia

children!(beam::B, child::B) where {B<:AbstractBeam}

Handles the inclusion of adding a single child to an existing beam. The function behaves as follows:

If no previous children exist, add child
If beam already has a single child, modify child beam starting ray (retracing)
Else throw error

source

BeamletOptics.convex_aspheric_surface_distance Method

julia

convex_aspheric_surface_distance(r, z, c, k, d, α_coeffs)

Calculates the 2D distance field for an aspheric surface at radius r away from the optical axis position z. The asphere is defined by:

c : The curvature (1/radius) of the surface
k : The conic constant of the surface
d : The diameter of the asphere
α_coeffs : The (even) aspheric coefficients, starting with A2.

Note that this is not just an infinite aspheric surface and also not a surface segment but a closed 2D perimeter.

It is intended to pair the SDF derived from this distance field with a cylinder SDF to build a real lens.

source

BeamletOptics.countlines_in_dir Function

julia

countlines_in_dir(dir, ext=[".jl", ".md"])

Counts the number of lines and files of all files in dir that have the specified file extension.

source

BeamletOptics.diameter Method

Returns the outer bounding diameter of the AbstractLensSDF

source

BeamletOptics.diameter Method

julia

diameter(s::AbstractRotationallySymmetricSurface)

Returns the clear optical diameter of the surface.

source

BeamletOptics.direction Method

julia

direction(x)

Returns the direction of x. For BeamletOptics.Oriented values this is the local y-axis, i.e. orientation(x)[:, 2]; rays and beams return their own direction.

source

BeamletOptics.direction Method

julia

direction(ray::AbstractRay)

Returns the direction vector of the ray.

source

BeamletOptics.edge_sag Method

Returns the sagitta of the surface at it edge, i.e. at diameter(s)

source

BeamletOptics.electric_field Function

julia

electric_field(I::Real, Z=Z_vacuum, ϕ=0)

Calculates the E-field phasor in [V/m] for a given intensity I and phase ϕ. Vacuum wave impedance is assumed.

source

BeamletOptics.electric_field Method

julia

electric_field(agb, r, z)

Convenience wrapper for parabasal_field using the beamlet's starting position (z=0) as the reference normalization.

source

BeamletOptics.electric_field Method

julia

electric_field(pd::Detector; kwargs...)

Compute a two‐dimensional electric field based on incoming rays or beams as captured by a Detector. The returned E-field map is sampled on a regular n×n grid in the detector's local (x,z)-plane. Note that the pd local coordinates are given in a (x, z) basis where the normal vector forms a left-handed system.

Resetting detectors

Be sure to call empty!(pd) before each new measurement if reusing the same detector.

Keyword Arguments

The following generic kwargs can be used for all hit types:

n::Int=100 Number of sample points per axis.
crop_factor::Real=1 Scales the width of the sampling window returned by calc_local_lims; values >1 expand, <1 shrink.
x_min, x_max, z_min, z_max Manually override the sampling bounds in the local x or z directions. If left as Inf, the bounds from calc_local_lims are used.
x0_shift::Real=0, z0_shift::Real=0 Applies a constant offset to the entire x or z coordinate arrays, useful for recentring or testing alignment.
progress::Bool=true Shows a progress bar once the calculation has run for get_progress_threshold() seconds (default 5 s). It is only drawn if stderr is a terminal.

Ray specific keyword arguments

center::AbstractCenterAlgorithm=Centroid() How the sampling window is centred. Centroid() uses the projection‑weighted centroid, MinMax() uses the geometric mid‑point of the bounding box.

Scaling

The returned values for ray hits correspond to the E-field of the point spread function. The values are raw/unscaled and not equal to a Strehl ratio. This feature is not yet added. In future versions a pupil finder along with a Strehl estimator will be added.

Beamlet specific keyword arguments

num_spots::Int=50 Number of hit spots used to determine bounding box

Returns

A tuple (xs, zs, E) where

xs::LinRange{T} and zs::LinRange{T} are the sampled coordinates in the detector's local x and z axes,
E::Matrix{Complex{T}} is the corresponding raw/unscaled intensity map, except for PolarizedRayHits, see below.

PolarizedRayHit hits

For PolarizedRays, the per-ray E0 field vectors are added coherently as 3D vectors in global coordinates (not projected onto the detector plane), so E::Matrix{Point3{Complex{T}}}. No obliquity/projection factor is applied: unlike the scalar ray case, the relative projection between rays is already encoded in their vector directions. As with the scalar case, the result is raw/unscaled (E0 carries Fresnel/Jones amplitude factors but not ray-tube area or pupil-sampling density).

Unpolarized light

Since polarization states with orthogonal E0 do not interfere, an unpolarized PSF is not obtained from a single coherent trace. Instead, trace twice with orthogonal input polarizations (e.g. E0 = [1,0,0] and E0 = [0,0,1]) and incoherently add the resulting intensities, i.e. I_total = intensity(E_x) .+ intensity(E_z).

source

BeamletOptics.electric_field Method

julia

electric_field(gauss::GaussianBeamlet, r, z)

Calculates the electric field phasor [V/m] of the GaussianBeamlet at the radial and longitudinal positions r and z. This function also considers phase changes due to changes in the optical_path_length of the beamlet.

Warning

Note that z and r must be specified as cartesian distances. Using the optical path length for z can lead to false results.

source

BeamletOptics.electric_field Method

julia

electric_field(r, z, E0, w0, w, k, ψ, R) -> ComplexF64

Computes the analytical complex electric field distribution of a stigmatic TEM₀₀ Gaussian beam which is described by:

Arguments

r: radial distance from beam origin
z: axial distance from beam origin
E0: peak electric field amplitude
w0: waist radius
w: local beam radius
k: wave number, equal to 2π/λ
ψ: Gouy phase shift (defined as !)
R: wavefront curvature, i.e. 1/r (radius of curvature)

source

BeamletOptics.ellipse Method

julia

ellipse(t, a, b, c)

Returns a point in Rⁿ that lies on an n-dim. ellipse that is parametrized by

t: circumference control variable ∈ [0, 2π]
a: center point
b, c: conjugate diameter vectors

source

BeamletOptics.find_zero_bisection Method

julia

find_zero_bisection(f, a, b; tol=1e-10, max_iter=1000)

Finds a root of the scalar function f on [a, b] using the bisection method. Requires sign(f(a)) ≠ sign(f(b)). Stops when abs(f(mid)) < tol or after max_iter iterations, returning the current midpoint.

Arguments

f: function Real -> Real
a: lower interval bound
b: upper interval bound
tol: absolute function tolerance (default 1e-10)
max_iter: maximum iterations (default 1000)

Errors

Throws if there is no sign change on [a, b] or if convergence is not reached within max_iter.

source

BeamletOptics.first_ray Method

julia

first_ray(beam::AbstractBeam)

Returns the start ray on the optical axis of the beam; for beamlets the first chief ray. Defines the generic position and direction of the beam, which are used as the pivot for rotations.

source

BeamletOptics.fresnel_coefficients Method

fresnel_coefficients(θ, n)

Calculates the complex Fresnel coefficients for reflection and transmission based on the incident angle θ in [rad] and the refractive index ratio n = n₂ / n₁. Returns rₛ, rₚ, tₛ and tₚ.

Signs

Info

The signs of rₛ, rₚ are based on the definition by Fowles (1975, 2nd Ed. p. 44) and Peatross (2015, 2023 Ed. p. 78)

source

BeamletOptics.gauss_parameters Method

julia

gauss_parameters(agb::AstigmaticGaussianBeamlet, z::Real)

Compute the scalar Gaussian beam parameters at distance z. Returns a tuple (w1, w2, R1, R2, ψ, w01, w02) where:

w1, w2: beam radii along the principal axes
R1, R2: radii of curvature along the principal axes
ψ: total Gouy phase shift
w01, w02: waist radii along the principal axes

source

BeamletOptics.gauss_parameters Method

julia

gauss_parameters(gauss::GaussianBeamlet, z; hint::Union{Nothing, Tuple{Int, Vector{<:Real}}}=nothing)

Calculate the local waist radius and Gouy phase of an unastigmatic Gaussian beamlet at a specific cartesian distance z based on the method of J. Arnaud (1985) and D. DeJager (1992).

Arguments

gauss: the GaussianBeamlet object for which parameters are to be calculated.
z: the position along the beam at which to calculate the parameters.
hint: an optional hint parameter for the relevant point/index of the appropriate beam segment. If not provided, the function will automatically select the ray.

Returns

w: local radius
R: curvature, i.e. 1/r where r is the radius of curvature
ψ: Gouy phase (note that -atan definition is used)
w0: local beam waist radius

source

BeamletOptics.gauss_parameters Method

julia

gauss_parameters(gauss::GaussianBeamlet, zs::AbstractArray)

Return the parameters of the GaussianBeamlet along the specified positions in zs.

source

BeamletOptics.get_view Method

julia

get_view(ls)

Returns the current camera view matrix of an LScene ls, if a suitable backend is loaded.

Handy at the REPL to freeze a view found interactively: rotate the scene by hand, call get_view(ax), and paste the printed matrix into the script as a literal passed to set_view.

If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.height Method

Returns the cylindric height of the AbstractCylindricalSurfaceSDF

source

BeamletOptics.hide_axis Method

julia

hide_axis(ls, hide::Bool=true)

Hides the axis markers of an LScene ls, if a suitable backend is loaded. Can be toggled via hide. If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.install_agent_skill Function

julia

install_agent_skill(dest = joinpath(pwd(), ".claude", "skills"))

Copies the agent skill that ships with the installed BeamletOptics version into joinpath(dest, "beamletoptics") and returns that path. The skill teaches AI coding assistants (e.g. Claude Code) how to write BeamletOptics simulations.

The default dest is the project-level skill directory of Claude Code in the current working directory. Use e.g. joinpath(homedir(), ".claude", "skills") for a personal installation.

An existing beamletoptics skill in dest is replaced, so calling this function again after Pkg.update keeps the skill in sync with the installed package version. Local edits to the copy are lost.

File permissions

Pkg installs packages read-only. The copied files are made writable so that the copy can be edited and replaced later.

source

BeamletOptics.intensity Function

Calculates the intensity in [W/m²] for a given complex electric field vector E (e.g. a PolarizedRay field). Vacuum wave impedance is assumed.

source

BeamletOptics.intensity Function

julia

intensity(pd::Detector, Z::Number = Z_vacuum; kwargs...)

Calculates the intensity distribution on the Detector via

where E is the electric field value and Z is the wave impedance. In general, vacuum wave impedance is assumed. This function returns a tuple (x, y, I). For more information on the available keyword arguments, refer to the electric_field documentation.

source

BeamletOptics.intensity Function

Calculates the intensity in [W/m²] for a given complex electric field phasor E. Vacuum wave impedance is assumed.

source

BeamletOptics.intensity Method

julia

intensity(agb::AstigmaticGaussianBeamlet, r, z)

Compute the optical intensity [W/m²] of the beamlet at position (r, z).

source

BeamletOptics.interact3d Method

julia

interact3d(::AbstractSystem, bs::ThinBeamsplitter, agb::AstigmaticGaussianBeamlet, ray_id::Int)

Models the interaction between a ThinBeamsplitter and an AstigmaticGaussianBeamlet. The reflection phase jump θᵣ = π is applied to the reflected child beam.

source

BeamletOptics.interact3d Method

julia

interact3d(::AbstractSystem, bs::ThinBeamsplitter, gauss::GaussianBeamlet, ray_id::Int)

Models the interaction between a ThinBeamsplitter and a GaussianBeamlet.

Reflection phase jump

The reflection phase jump is modeled here as θᵣ = π for simplicity. This is since in practice it will have only a relative effect on the signal at the detector for interferometric setups. The phase jump is applied to the reflected portion of any incoming beam that faces the ThinBeamsplitter normal vector, which assumes that the splitter has an unambigous normal, i.e. a 2D mesh. This is intended to model the effect of the Fresnel equations without full polarization calculus.

source

BeamletOptics.interact3d Method

julia

interact3d(::AbstractSystem, object::AbstractObject, ::AbstractBeam, ::AbstractRay)

Defines the optical interaction between an incoming/outgoing beam/ray of light and an optical element, must return an AbstractInteraction or nothing. The default behavior is that no interaction occurs, i.e. return of nothing, which should stop the system tracing procedure. Refer to the AbstractInteraction typedocs for more information on the return type value.

source

BeamletOptics.interact3d Method

julia

interact3d(system, object, agb::AstigmaticGaussianBeamlet, ray_id)

Generic dispatch: traces each component beam's ray through object independently. Returns nothing if any interaction fails; otherwise returns an AstigmaticGaussianBeamletInteraction.

source

BeamletOptics.interact3d Method

julia

interact3d(system::AbstractSystem, object::AbstractObject, gauss::GaussianBeamlet{R}, ray_id::Int)

Generic dispatch for the interact3d method of a GaussianBeamlet with an AbstractObject. Unless a more concrete implementation exists, the interaction of the Gaussian is assumed to be the interaction of the chief, waist and divergence rays with an object.

Returns

The interact3d method for the GaussianBeamlet must return a GaussianBeamletInteraction.

source

BeamletOptics.interact3d Method

julia

interact3d(AbstractReflectiveOptic, PolarizedRay)

Implements the ideal reflection of a PolarizedRay via the normal at the intersection point on an optical surface. A Jones matrix of [-1 0 0; 0 1 0] is assumed as per Peatross (2015, 2023 Ed. p. 154) and Yun et al. (see PolarizedRay for more information).

source

BeamletOptics.interact3d Method

julia

interact3d(AbstractReflectiveOptic, Ray)

Implements the reflection of a Ray via the normal at the intersection point on an optical surface.

source

BeamletOptics.interact3d Method

julia

interact3d(AbstractSystem, AbstractRefractiveOptic, Beam, PolarizedRay)

Implements the refraction of a PolarizedRay at an uncoated optical surface. The "outside" ref. index is obtained from the system unless specified otherwise. Reflection and transmission values are calculated via the fresnel_coefficients. Stray light is not tracked. In the case of total internal reflection, only the reflected light is traced.

source

BeamletOptics.interact3d Method

julia

interact3d(AbstractSystem, AbstractRefractiveOptic, Beam, Ray)

Implements the refraction of a Ray at an optical surface. The "outside" ref. index is obtained from the system unless specified otherwise. At the critical angle, total internal reflection occurs (see refraction3d).

source

BeamletOptics.interact3d Method

julia

interact3d(system::AbstractSystem, lp::LinearPolarizer, beam::Beam, ray::AbstractRay)

Dispatches the optical interaction between a Beam/AbstractRay and a LinearPolarizer depending on which sub-shape (front, filter or back) was intersected.

Additional information

Cemented interface

The front and back substrates sit flush against the film. Refraction at the outer, uncoated surfaces is handled by the standard AbstractRefractiveOptic interaction logic. When a ray reaches the flat inner face cemented to the film, the film's Jones matrix is applied to the field before it is refracted (or, in case of total internal reflection, reflected without crossing the film) directly from the current substrate's refractive index into the other substrate's.

source

BeamletOptics.intersect3d Method

julia

intersect3d(object::AbstractObject, ray::AbstractRay)

In general, the intersection logic between an AbstractObject and an AbstractRay depends on the AbstractShapeTrait. Refer to the respective documentation.

source

BeamletOptics.intersect3d Method

julia

intersect3d(sphere::AbstractSphere, ray::Ray)

Intersection algorithm for sdf based shapes.

source

BeamletOptics.intersect3d Method

julia

intersect3d(shape::AbstractShape, ::AbstractRay)

Defines the intersection between an AbstractShape and an AbstractRay, must return an Intersection or nothing. The default behavior for concrete shapes and rays is to indicate no intersection, that is nothing, which will inform the tracing algorithm to stop. Refer to the Intersection documentation for more information on the return type value.

source

BeamletOptics.intersect3d Method

julia

intersect3d(mesh::Mesh, ray::Ray)

This function is a generic implementation to check if a ray intersects the mesh.

source

BeamletOptics.intersect3d Method

julia

intersect3d(plane_position, plane_normal, ray)

Returns the intersection between a ray and an infinitely large plane which is characterized by its position and normal.

source

BeamletOptics.iscircular Method

julia

iscircular

Tests if the polarization state is circular. Refer to Yun paper.

source

BeamletOptics.iselliptical Method

julia

iselliptical

Tests if the polarization state is elliptical.

source

BeamletOptics.isentering Method

julia

isentering(ray)

Tests whether the ray is entering a shape based on the orientation of the ray direction and surface normal. If no intersection is present, default behavior is to return false.

source

BeamletOptics.isinfrontof Method

julia

isinfrontof(point::AbstractVector, pos::AbstractVector, dir::AbstractVector)

Tests if a point is in front of the plane defined by the position and direction vectors.

source

BeamletOptics.isinfrontof Method

julia

isinfrontof(shape::AbstractShape, ray::AbstractRay)

A simple test to check if a shape lies "in front of" a ray. The forward direction is here defined as the ray orientation. Only works well if ray is outside of the volume of shape. Can be dispatched to return more accurate results for subtypes of AbstractShape.

source

BeamletOptics.islinear Method

julia

islinear

Tests if the polarization state is linear. Refer to Yun paper.

source

BeamletOptics.isorthogonal3d Method

julia

isorthogonal3d(v1, v2; atol=eps())

Tests if v1 and v2 are orthogonal. Additional abs. tolerance can be passed via atol

source

BeamletOptics.isparallel3d Method

julia

isparallel3d(v1, v2; atol = √eps)

Tests if v1 is parallel (or anti-parallel) to v2, i.e. if the sine of the angle between both vectors, norm(cross(v1, v2)) of the normalized vectors, is at most atol.

source

BeamletOptics.isparaxial Function

julia

isparaxial(system, gb::GaussianBeamlet, threshold=π/4)

Tests the angle between the waist and divergence beams and refractive surfaces. A target threshold of π/4 or 45° is assumed before abberations become dominant.

source

BeamletOptics.isparaxial Function

julia

isparaxial(system, beam, threshold=π/4)

Tests the angle between the beam direction and surface normal at each intersection. Mainly intended as a check for GaussianBeamlet.

source

BeamletOptics.isparaxial Method

From Wilhelm (2001)

source

BeamletOptics.isparentbeam Method

julia

isparentbeam(beam, ray)

Tests if the given beam contains the ray as a part of its solution.

source

BeamletOptics.istilted Method

julia

istilted(system::System, gb::GaussianBeamlet)

Tests if refractive elements are tilted with respect to the beamlet optical axis, i.e. introduce simple astigmatism.

source

BeamletOptics.kinematic_trait_of Method

julia

kinematic_trait_of(x) -> AbstractKinematicTrait

Returns the AbstractKinematicTrait of x. Defaults to Static(). Movable types declare Movable(Oriented()) or Movable(Directed()).

source

BeamletOptics.kinematic_trait_of Method

julia

kinematic_trait_of(c::AbstractCompositeSDF)

A composite takes the kinematic class of its operands, which the constructor ensures to be either all static or all movable, see BeamletOptics.AbstractKinematicTrait.

source

BeamletOptics.lensmakers_eq Method

julia

lensmakers_eq(R1, R2, n)

Calculates the thin lens focal length based on the radius of curvature R1/R2 and the lens refractive index n. If center of sphere is on left then R < 0. If center of sphere is on right then R > 0.

source

BeamletOptics.line_plane_distance3d Method

julia

line_plane_distance3d(plane_position, plane_normal, line_position, line_direction)

Returns the distance between a line and an infinitely large plane which are characterized by their position and normal/direction.

source

BeamletOptics.line_point_distance3d Method

julia

line_point_distance3d(pos, dir, point)

Computes the shortes distance between a line described by pos+t*dir and a point in 3D. This function is slow and should be used only for debugging purposes.

source

BeamletOptics.line_point_distance3d Method

julia

line_point_distance3d(ray, point)

Returns value for the shortest distance between the ray (extended to ∞) and point.

source

BeamletOptics.list_subtypes Function

julia

list_subtypes(T::Type; max_depth::Int=5)

Prints a tree of all subtypes, e.g. list_subtypes(AbstractObject). Maximum exploration depth can be limited by passing max_depth. Returns the total number of types encountered.

source

BeamletOptics.look_at! Method

julia

look_at!(ax, target, offset; up = [0, 0, 1])

Aims the camera of ax at target from target + offset, if a suitable backend is loaded. A deterministic replacement for manually orbiting the scene to find a viewpoint, handy for reproducible close-up figures. If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.mechanical_diameter Method

julia

mechanical_diameter(s::AbstractRotationallySymmetricSurface)

Returns the mechanical diameter of the surface.

Note

It is assumed that mechanical_diameter(s) >= diameter(s) always holds.

source

BeamletOptics.normal3d Method

julia

normal3d(target, reference)

Returns a vector with unit length that is perpendicular to the target and an additional reference vector. Vector orientation is determined according to right-hand rule.

source

BeamletOptics.normal3d Method

julia

normal3d(s::AbstractSDF, pos)

Computes the normal vector of s at pos.

source

BeamletOptics.normal3d Method

julia

normal3d(mesh::AbstractMesh, fID::Int)

Returns a vector with unit length that is perpendicular to the target `face`` according to the right-hand rule. The vertices must be listed row-wise within the face matrix.

source

BeamletOptics.numerical_aperture Function

julia

numerical_aperture(θ, n=1)

Returns the NA for a opening half-angle θ and scalar ref. index n. For more information refer to this website.

source

BeamletOptics.objects Method

julia

objects(group::ObjectGroup)

Exposes all objects/subgroups stored within the group.

source

BeamletOptics.objects Method

julia

objects(system::System)

Exposes all objects stored within the system. By exposing the Leaves of the tree only, it is ensured that AbstractObjectGroups are flattened into a regular vector.

source

BeamletOptics.op_extrude_x Method

julia

op_extrude_x(p, sdf2d::Function, height)

Calculates the SDF at point p for the given 2D-SDF function and extrudes the shape to height along the x-axis.

source

BeamletOptics.op_extrude_z Method

julia

op_extrude_z(p, sdf2d::Function, height)

Calculates the SDF at point p for the given 2D-SDF function and extrudes the shape to height along the z-axis.

source

BeamletOptics.op_revolve_y Method

julia

op_revolve_y(p, sdf2d::Function, offset)

Calculates the SDF at point p for the given 2D-SDF function with offset by revolving the 2D shape around the y-axis.

source

BeamletOptics.op_revolve_z Method

julia

op_revolve_z(p, sdf2d::Function, offset)

Calculates the SDF at point p for the given 2D-SDF function with offset by revolving the 2D shape around the z-axis.

source

BeamletOptics.operands Function

julia

operands(c::AbstractCompositeSDF)

Returns a Tuple of every child AbstractSDF that the composite c combines, in any order. This is the accessor the shared kinematics of AbstractCompositeSDF iterate over, so every concrete composite must implement it; the order carries no meaning and must not be relied upon to identify an operand's role in the boolean expression.

source

BeamletOptics.optical_path_length Method

julia

optical_path_length(ray::AbstractRay{T}) where {T}

Calculate the optical path length of the ray, i.e. .

source

BeamletOptics.optical_path_length Method

julia

optical_path_length(beam::Beam)

Calculate the optical path length of the beam, i.e. .

source

BeamletOptics.optical_power Method

julia

optical_power(agb)

Compute the total integrated optical power of the beamlet. For a Gaussian beamlet, this is typically constant through lossless propagation.

source

BeamletOptics.optical_power Method

julia

optical_power(pd::Detector; kwargs...)

Calculates the total optical power on pd in [W] by integration over the local intensity. For more information on keyword argument options, refer to the electric_field docs.

source

BeamletOptics.orientation! Method

julia

orientation!(bg::AbstractBeamGroup, M)

Overwrites the orientation matrix of the beam group bg with M, see orientation.

Warning

This only sets the bookkeeping of the group, the beams are not moved. Use rotate3d! to rotate a group including its beams. M is not validated and must be a right-handed orthonormal matrix.

source

BeamletOptics.orientation Method

julia

orientation(bg::AbstractBeamGroup) -> SMatrix{3,3}

Returns the orientation matrix of the beam group bg. Its columns are the local x-axis (the azimuthal sampling reference vector), the local y-axis (the central source direction, see direction) and the local z-axis, forming a right-handed orthonormal basis.

The orientation tracks the full rotational state of the group, including a roll about its own optical axis. It is updated by rotate3d! and returned to the identity by reset_rotation3d!.

source

BeamletOptics.orientation Method

julia

orientation(object) -> Matrix

Returns the current orientation of the object in R³ as a matrix. The matrix represents the local fixed-body coordinate system.

In general, orientation(object) returns orientation(shape(object)) unless specified otherwise.

source

BeamletOptics.orientation Method

Enforces that shape has to have the field dir or implement orientation().

source

BeamletOptics.parabasal_field Method

julia

parabasal_field(agb, r, z; E_ref_amp, area_ref, z_norm)

Compute the complex scalar electric field of the AstigmaticGaussianBeamlet at a transverse offset r (a 3D vector in the plane perpendicular to the chief ray) and longitudinal position z.

Uses the built-in normalization √(area_ref / area(z)) so that the result is physical [V/m] when E_ref_amp matches the initial polarization amplitude.

Arguments

agb: the astigmatic Gaussian beamlet
r: transverse offset vector (must be orthogonal to the chief ray direction at z)
z: distance along the beam
E_ref_amp: reference field amplitude (auto-computed from z_norm if nothing)
area_ref: reference area (auto-computed from z_norm if nothing).
z_norm: longitudinal position for reference normalization (default: 0).

Formalism

The field is computed using the Parabasal Gaussian Beamlet formalism: ψ(r, z) = √(area_ref / area(z)) * exp(i * k * [z + 1/2 * rᵀ * Q(z) * r]) where area(z) = (h1 × h2) · dir is the complex beam area.

source

BeamletOptics.parabasal_ray_parameters Method

julia

parabasal_ray_parameters(agb, p0, i)

Compute the complex parabasal ray parameters (h1, u1, h2, u2) at the transverse plane defined by the chief ray's position p0 and direction at segment i.

The real parts of h and u come from the divergence rays (dxp, dyp), while the imaginary parts come from the waist rays (wxp, wyp).

source

BeamletOptics.parabasal_ray_parameters Method

julia

parabasal_ray_parameters(agb, z)

Compute the parabasal ray parameters at distance z along the beam.

source

BeamletOptics.parent! Method

julia

parent!(child::AstigmaticGaussianBeamlet, parent::AstigmaticGaussianBeamlet)

Links parent for tree navigation and ensures the chief beam parent is also linked.

source

BeamletOptics.parent! Method

julia

parent!(beam::GaussianBeamlet, parent::GaussianBeamlet)

Ensures that the GaussianBeamlet knows about its parent beam. In addition, links the chief beams of child and parent. Important for correct functioning of point_on_beam and length.

source

BeamletOptics.point_on_beam Method

julia

point_on_beam(beam::Beam, t::Real)

Function to find a point given a specific distance t along the beam. Return the ray index aswell. For negative distances, assume first ray backwards.

source

BeamletOptics.polarized_field Method

julia

polarized_field(agb, r, z)

Compute the complex vector electric field [V/m] of the AstigmaticGaussianBeamlet at position (r, z). Returns a 3D vector.

source

BeamletOptics.radius Method

Returns the radius of the AbstractCylindricalSurfaceSDF

source

BeamletOptics.radius Method

julia

radius(s::AbstractRotationallySymmetricSurface)

Returns the radius of curvature of the surface. This might return Inf for planar surfaces or surfaces which cannot be described by just one curvature radius.

source

BeamletOptics.radius Method

Returns the radius of curvature of the AbstractSphericalSurfaceSDF

source

BeamletOptics.radius Method

julia

radius(s::ConicSDF)

Returns the radius of curvature R = 2f of the parent conic at its vertex [m].

source

BeamletOptics.rayleigh_range Method

julia

rayleigh_range(agb::AstigmaticGaussianBeamlet)

Returns the Rayleigh range for the x and y axes of the beamlet as a tuple (z_rx, z_ry).

source

BeamletOptics.rayleigh_range Method

julia

rayleigh_range(g::GaussianBeamlet; M2=1)

Returns the Rayleigh range for the first beam section of the GaussianBeamlet g. Note: M2 is not stored in g during construction and must be specified by the user.

source

BeamletOptics.rays Method

julia

rays(beam::Beam)

Returns the vector of rays that make up the beam.

source

BeamletOptics.reflection3d Method

julia

reflection3d(dir, normal)

Calculates the reflection between an input vector dir and surface normal vector in R³. Vectors dir and normal must have unit length!

source

BeamletOptics.refraction3d Method

julia

refraction3d(dir, normal, n1, n2)

Calculates the refraction between an input vector dir and surface normal vector in R³. n1 is the "outside" refractive index and n2 is the "inside" refractive index. The function returns the new direction of propagation and a boolean flag to indicate if internal refraction has occured.

Vectors dir and normal must have unit length!

Total internal reflection

If the critical angle for n1, n2 and the incident angle is reached, the ray is reflected internally instead!

Arguments

dir: direction vector of incoming ray
normal: surface normal at point of intersection
n1: index of ref. before refraction
n2: index of ref. after refraction

source

BeamletOptics.refraction3d Method

julia

refraction3d(ray, n2)

Calculates the new direction of a ray entering into a new medium with ref. index n2.

source

BeamletOptics.render! Method

julia

render!(axis, thing; kwargs...)

The render! function allows for the visualization of optical system and beams under the condition that a suitable backend is loaded. This means that either one of the following packages must be loaded in combination with BeamletOptics via using:

GLMakie
- preferred for 3D viewing
- use LScene or Axis3 environments
CairoMakie
- preferred for the generation of high-quality .pngs
- only Axis3 is supported

If no suitable backend is loaded, a MissingBackendError will be thrown.

Implementations reqs.

All concrete implementations of render! must adhere to the following minimal interface:

render!(axis, thing; kwargs...)

axis: an axis type of the union of LScene or Axis3
thing: an abstract or concrete object or beam type
kwargs: custom or Makie keyword arguments that are passed to the underlying backend

Refer to the BeamletOptics extension docs for Makie for more information.

source

BeamletOptics.render_lcs! Function

julia

render_lcs!(ax, pos, lcs; scale = 10, show_labels = false)
render_lcs!(ax, object; scale = 10, show_labels = false)

Draws the local coordinate system of an object (or of an explicit pos/orientation pair) into ax as a red/green/yellow arrow triad, if a suitable backend is loaded. Useful to make the reference frame of an imported CAD mesh visible in the scene. If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.reset_rotation3d! Method

julia

reset_rotation3d!(x)

Rotates x about its position such that its orientation is the identity. Only available for BeamletOptics.Oriented values, see BeamletOptics.Movable.

source

BeamletOptics.reset_translation3d! Method

julia

reset_translation3d!(x)

Moves x such that its position is the global origin. See BeamletOptics.Movable.

source

BeamletOptics.retrace_system! Method

julia

retrace_system!(system, beam)

This function tries to reuse data from a previously solved beam in order to solve the system againg using a sequential approach.

Retracing

The retracing logic for an already solved beam loops over the rays and children and is as follows:

Begin

Test if current ray has a valid intersection
- If not, mark beam tail for cleanup and go to End
Recalculate the intersection
- If a hint was provided by a previous interaction, use hinted object
- Else, test against previous intersection
Test if the ray still has a valid intersection after recalculation
- If no object is hit, mark beam tail for cleanup and go to End

Interact

Recalculate the optical interaction
- Catch hints provided for next ray
- If no interaction occurs, mark beam tail for conditional cleanup and go to End
Add the interaction to the current beam
- If another ray follows, modify the next starting position - Go to Begin
- Else mark children for cleanup, push new ray to beam tail - Go to End

End

If cleanup is required, do conditionally
- remove all beam tail rays after current ray
- remove all beam children
- reset beam tail ray intersection to nothing

Retracing blocked beam paths

The implemented standard retracing procedure can handle beam path invalidations under certain conditions. However, one case that will lead to a silent error is if an element in the system is moved such that it blocks the beam path between two other elements. The retracer will not be able to detect this, since the testing of the previous intersection will return a valid intersection.

If this kind of situation must be modeled, e.g. in the case of an optical chopper wheel, retracing should be disabled.

source

BeamletOptics.retrace_system! Method

julia

retrace_system!(system, agb::AstigmaticGaussianBeamlet; check_invariant=true, threshold = get_invariant_threshold())

Retrace the beam stored in AstigmaticGaussianBeamlet through the optical system. All 9 component ray intersections and interactions are recalculated. All rays must hit the same object, or the retracing step is aborted.

source

BeamletOptics.retrace_system! Method

julia

retrace_system!(system::System, gauss::GaussianBeamlet{T}) where {T <: Real}

Retrace the beam stored in GaussianBeamlet through the optical system. Chief, waist and divergence ray intersections and interactions are recalculated. All rays must hit the same object, or the retracing step is aborted. If retracing is stopped before the end of the beam is reached, further rays are dropped.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(x, R::AbstractMatrix)
rotate3d!(x, axis::AbstractVector, θ::Real)
rotate3d!(x, R::AbstractMatrix, pivot::AbstractVector)
rotate3d!(x, axis::AbstractVector, θ::Real, pivot::AbstractVector)

Rotates x by the rotation matrix R (or by the angle θ [rad] about axis) about its own position, or about pivot if given. See BeamletOptics.Movable.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, beam::AbstractBeam, R::AbstractMatrix)

Resets the root beam to its untraced start state and rotates it by R about its position (the chief ray start for beamlets). Composite beams delegate to their component beams. Throws an ArgumentError for child beams.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, bg::AbstractBeamGroup, R::AbstractMatrix)

Rotates all beams of the group by R about the group center and updates the group orientation to R * orientation(bg). Every beam is reset to its untraced start state.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, c::AbstractCompositeSDF, R::AbstractMatrix)

Rotates c and all of its operands around c's own origin (pivot), by the rotation matrix R.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, mesh::AbstractMesh, R::AbstractMatrix)

Rotate the mesh vertices and orientation around its current position using R.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, shape::AbstractShape, R::AbstractMatrix)

Rotates the dir-matrix of shape by the rotation matrix R.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::MultiShape, object, R::AbstractMatrix)

All parts of the MultiShape object are rotated around the pivot center via the rotation matrix R.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, ray::AbstractRay, R::AbstractMatrix)

Rotates the direction of the ray by R about its own start position and clears its intersection. Subtypes carrying direction-dependent data (e.g. the field vector of a PolarizedRay) dispatch their own method that also rotates this data.

source

BeamletOptics.rotate3d! Method

julia

rotate3d!(::Movable, ray::PolarizedRay, R::AbstractMatrix)

Rotates the direction and the field vector E0 of the ray by R about its start position and clears its intersection. E0 stays orthogonal to the direction and is not renormalized, i.e. its amplitude is kept.

source

BeamletOptics.rotate3d Method

julia

rotate3d(reference::Vector, θ)

Returns the rotation matrix that will rotate a vector around the reference axis at an angle θ in radians. Vector length is maintained. Counter-clockwise rotation in a right-hand coord. system. The reference axis is normalized internally, i.e. it can have any non-zero length.

source

BeamletOptics.sag Method

Returns the sagitta of the AbstractSphericalSurfaceSDF

source

BeamletOptics.sag Method

julia

sag(r::Real, l::Real)

Calculates the sag of a cut circle with radius r and chord length l

source

BeamletOptics.scale3d! Method

julia

scale3d!(mesh::AbstractMesh, scale)

Allows rescaling of mesh data around "center of gravity".

source

BeamletOptics.sd_line_segment Method

julia

sd_line_segment(p, a, b)

Returns the signed distance from point p to the line segment described by the points a and b.

source

BeamletOptics.sdf Method

julia

sdf(::AbstractRotationallySymmetricSurface, ::Union{Nothing, AbstractOrientationType})

Takes the surface specification and an optional AbstractOrientationType as trait parameter and returns a corresponding AbstractSDF type.

Surface vs. volume based tracing

This function is a mere convenience provider for users coming from other optic simulations frameworks which are surface oriented. The goal of this function is to return the best matching closed volume SDF which posesses a surface with the given specs on one side and most often a boundary and planar surface on the other side.

Info

Always keep in mind that this package performs closed-volume baced ray tracing using either SDFs or meshes.

source

BeamletOptics.set_new_origin3d! Method

julia

set_new_origin3d!(mesh::AbstractMesh)

Resets the mesh directional matrix and position vector to their initial values.

Warning: this operation is non-reversible!

source

BeamletOptics.set_orthographic Method

julia

set_orthographic(ls)

Switches the camera of an LScene ls to an orthographic projection, if a suitable backend is loaded. If not, a MissingBackendError will be thrown.

source

BeamletOptics.set_pivot3d! Method

julia

set_pivot3d!(bg::AbstractBeamGroup, pivot)

Moves the kinematic pivot (center) of the beam group bg to pivot, without moving or resetting any of its beams. The pivot is the reference point used by rotate3d! and reset_translation3d!; the group orientation is unchanged.

Unlike translate3d! or rotate3d!, this only changes bookkeeping and does not reset already traced beams.

source

BeamletOptics.set_pivot3d! Method

julia

set_pivot3d!(group::ObjectGroup, pivot)

Moves the kinematic pivot (center) of group to pivot, without moving any of its objects. The pivot is the reference point used by rotate3d!, translate_to3d! and reset_translation3d!; the group orientation is unchanged.

Example

Rotate a lens group about its first surface instead of the group's default center:

julia

group = ObjectGroup([lens1, lens2])
set_pivot3d!(group, position(lens1))
rotate3d!(group, [0, 0, 1], deg2rad(5))   # rotates about lens1's position, not the old center

source

BeamletOptics.set_view Method

julia

set_view(ls, view::AbstractMatrix)
set_view(ls, eye, lookat, up)

Sets the camera of an LScene ls, if a suitable backend is loaded, either directly from a view matrix (e.g. one obtained via get_view) or from an eye/lookat/up triple. See also look_at! to aim the camera at a known point instead of specifying the triple directly.

If no suitable backend is loaded, a MissingBackendError will be thrown.

source

BeamletOptics.shape Method

julia

shape(::AbstractObject)

Returns all component shapes of the object for a MultiShape or a single shape for a SingleShape. E.g. for a custom multi-shape object the user of this API needs to define:

BeamletOptics.shape(obj::MyObject) = (obj.front, obj.back)

Warning

Whenever your object consists of nested structures (e.g. ObjectGroups or other MultiShapes) it is the responsibility of the user to ensure that each atomic shape, i.e. SingleShape, is only listed once. Failure to ensure this can lead to spurious behaviour when using the kinematic API.

source

BeamletOptics.shape_trait_of Method

Default trait

source

BeamletOptics.shift_phase! Method

julia

shift_phase!(agb, Δϕ)

Apply a global phase shift Δϕ to the AstigmaticGaussianBeamlet by rotating the chief ray's polarization.

source

BeamletOptics.solve_system! Method

julia

solve_system!(system::AbstractSystem, bg::AbstractBeamGroup; progress=true, kwargs...)

Trace every beam of the beam group bg through the system, multithreaded over the member beams. All other kwargs are passed on to solve_system! for each beam.

Keyword Arguments

progress = true: show a progress bar once tracing has run for get_progress_threshold() seconds (default 5 s). It is only drawn if stderr is a terminal, so documentation builds, CI logs and piped output stay clean.

source

BeamletOptics.solve_system! Method

julia

solve_system!(system::System, beam::AbstractBeam; r_max=get_default_r_max(), retrace=true, depth_max=get_default_depth_max(), check_invariant=true, threshold=get_invariant_threshold())

Manage the tracing of an AbstractBeam through an optical system. The function retraces the beam if possible and then proceeds to trace each leaf of the beam tree through the system. The condition to stop ray tracing is that the last beam intersection is nothing or the beam interaction is nothing. Then, the system is considered to be solved. A maximum number of rays per beam (r_max) can be specified in order to avoid infinite calculations under resonant conditions, i.e. two facing mirrors. Likewise, depth_max limits how many branching levels are explored when new sub-beams are generated (for example, by beamsplitters) so that the tree cannot grow without bound. Sub-beams beyond the depth limit are dropped from the tree.

Arguments

system::System: The optical system in which the beam will be traced.
beam::AbstractBeam: The beam object to be traced through the system.

Keyword Arguments

r_max = get_default_r_max(): Maximum number of tracing iterations for each leaf.
retrace = true: Flag to indicate if the system should be retraced. Default is true.
depth_max = get_default_depth_max(): Maximum number of branching levels explored from the root beam
check_invariant = true: enables or disables optical invariant checks where applicable
threshold = get_invariant_threshold(): threshold for paraxial invariant checks

source

BeamletOptics.spot_diagram Method

julia

spot_diagram(d::Detector)

Returns an array of 2D points in local detector coordinates that represent the points of intersection for incoming beams.

Beams

For Beams, the point of intersection on the screen surface is stored.

Beamlets

For GaussianBeamlets, the projected 1/e² waist is returned. The number of points and radius can be adjusted via the num_spots and crop_factor keyword arguments.

source

BeamletOptics.static_data Method

Getter fct. for the static array in the AbstractJonesMatrix

source

BeamletOptics.stop Method

Allows continued tracing if set to false

source

BeamletOptics.test_refractive_index_function Method

julia

test_refractive_index_function(input)

Tests if input is callable with a single Real argument for the wavelength λ and returns a single Real value for the refractive index n.

source

BeamletOptics.test_refractive_index_function Method

DiscreteRefractiveIndex passes test by default

source

BeamletOptics.thickness Method

Returns the on-axis thickness of the AbstractLensSDF

source

BeamletOptics.thickness Method

julia

thickness(difference)

Calculates the thickness of a DifferenceSDF as the thickness of its base — removing material cannot increase the axial extent.

source

BeamletOptics.thickness Method

julia

thickness(union)

Calculates the thickness of a union of AbstractLensSDFs.

source

BeamletOptics.trace_system! Method

julia

trace_system!(system::AbstractSystem, beam::Beam{T}; r_max = get_default_r_max()) where {T <: Real}

Trace a Beam through an optical system. Maximum number of tracing steps can be capped by r_max.

Tracing logic

The intersection of the last ray of the beam with any objects contained within the system is tested. If an object is hit, the optical interaction is calculated. If no interaction occurs or no further objects are hit, the tracing procedure is stopped.

Arguments

system:: The optical system through which the Beam is traced.
beam: The Beam object to be traced.
r_max: Maximum number of tracing iterations.

source

BeamletOptics.trace_system! Method

julia

trace_system!(system, agb::AstigmaticGaussianBeamlet; r_max = get_default_r_max(), check_invariant = true, threshold = get_invariant_threshold())

Trace an AstigmaticGaussianBeamlet through an optical system. All 9 component beams (chief + 8 parabasal) are traced in lockstep: the chief ray is traced first for each intersection, followed by the auxiliary rays. All rays must hit the same shape; otherwise tracing stops.

source

BeamletOptics.trace_system! Method

julia

trace_system!(system::System, gauss::GaussianBeamlet{T}; r_max = get_default_r_max()) where {T <: Real}

Trace a GaussianBeamlet through an optical system. Maximum number of tracing steps can be capped by r_max.

Tracing logic

The chief, waist and divergence beams are traced step-by-step through the system. For each intersection after a tracing_step!, the intersections are compared. If all rays hit the same target, the optical interaction is analyzed, else the tracing stops.

Arguments

system: The optical system through which the GaussianBeamlet is traced.
gauss: The GaussianBeamlet object to be traced.
r_max: Maximum number of tracing iterations.

source

BeamletOptics.tracing_step! Method

julia

tracing_step!(system::AbstractSystem, ray::AbstractRay{R}, hint::Hint)

Tests if the ray intersects an object in the optical system. Returns the closest intersection.

Hint

An optional Hint can be provided to test against a specific object (and shape) in the system first.

Warning

If a hint is provided and the object intersection is valid, the intersection will be returned immediately. However, it is not guaranteed that this is the true closest intersection.

source

BeamletOptics.translate3d! Method

julia

translate3d!(x, offset)

Moves x by the offset vector. See BeamletOptics.Movable.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, beam::AbstractBeam, offset)

Resets the root beam to its untraced start state and moves it by offset. Composite beams delegate to their component beams. Throws an ArgumentError for child beams.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, bg::AbstractBeamGroup, offset)

Moves all beams of the group and its center by offset. Every beam is reset to its untraced start state.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, c::AbstractCompositeSDF, offset)

Translates c and all of its operands by offset.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, mesh::AbstractMesh, offset)

Mutating function that translates the vertices of an mesh in relation to the offset vector. In addition, the mesh position vector is overwritten to reflect the new "center of gravity".

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, shape::AbstractShape, offset)

Translates the position of shape by the offset-vector.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::MultiShape, object, offset)

Moves all parts of the MultiShape object along the specified offset vector.

source

BeamletOptics.translate3d! Method

julia

translate3d!(::Movable, ray::AbstractRay, offset)

Moves the start position of the ray by offset and clears its intersection.

source

BeamletOptics.translate_to3d! Method

julia

translate_to3d!(x, target)

Moves x such that its position coincides with target. See BeamletOptics.Movable.

source

BeamletOptics.transmission_axis Method

julia

transmission_axis(lp::LinearPolarizer)

Returns the unit vector (in global coordinates) along which LinearPolarizer lp transmits polarization. Refer to transmission_axis(::PolarizationFilter) for details.

source

BeamletOptics.transmission_axis Method

julia

transmission_axis(pf::PolarizationFilter)

Returns the unit vector (in global coordinates) along which PolarizationFilter pf transmits polarization, derived from its Jones matrix so that it stays correct for any filter orientation or custom GlobalJonesBasis. The sign of the returned vector is arbitrary, since it represents an axis rather than a direction.

source

BeamletOptics.visibility Method

julia

visibility(opt_pwr)

Calculates e.g. the interferometric contrast from a series of optical power measurements. For more information go here.

source

BeamletOptics.waist_parameters Method

julia

waist_parameters(agb, z)

Compute the position and elliptical waist axes at distance z along the beam. Returns (p0, w1, w2, w01, w02) where w1 and w2 are 3D vectors describing the semi-axes of the beam cross-section ellipse.

source

BeamletOptics.waist_parameters Method

julia

waist_parameters(gb, z)

Compute the position and cross-section axes at distance z along the beam. For a stigmatic GaussianBeamlet, the cross-section is circular, and the axes are determined by the orientation of the auxiliary waist ray. Returns the vectors (p0, w1, w2) and scalar waist radii (w0, w0).

source

BeamletOptics.xrotate3d! Method

julia

xrotate3d!(x, θ)

Rotates x by the angle θ [rad] about the global x-axis through its position. See BeamletOptics.Movable.

source

BeamletOptics.yrotate3d! Method

julia

yrotate3d!(x, θ)

Rotates x by the angle θ [rad] about the global y-axis through its position. See BeamletOptics.Movable.

source

BeamletOptics.zrotate3d! Method

julia

zrotate3d!(x, θ)

Rotates x by the angle θ [rad] about the global z-axis through its position. See BeamletOptics.Movable.

source

BeamletOptics.Config Module

julia

Config

Global configuration settings for the BeamletOptics package using Preferences.jl.

source

BeamletOptics.Config.get_default_depth_max Method

julia

get_default_depth_max()

Returns the default maximum depth for recursive ray tracing (e.g., reflections/refractions). Defaults to 100 (configurable via the default_depth_max preference).

source

BeamletOptics.Config.get_default_power Method

julia

get_default_power()

Returns the default beam total power in Watts.

source

BeamletOptics.Config.get_default_r_max Method

julia

get_default_r_max()

Returns the default maximum number of segments for ray tracing.

source

BeamletOptics.Config.get_default_waist Method

julia

get_default_waist()

Returns the default beam waist radius in meters.

source

BeamletOptics.Config.get_default_wavelength Method

julia

get_default_wavelength()

Returns the default wavelength in meters.

source

BeamletOptics.Config.get_internal_reflection_threshold Method

julia

get_internal_reflection_threshold()

Returns the global configuration threshold for total internal reflection detection.

source

BeamletOptics.Config.get_invariant_threshold Method

julia

get_invariant_threshold()

Returns the global configuration threshold for the paraxial optical invariant check.

source

BeamletOptics.Config.get_line_plane_intersection_threshold Method

julia

get_line_plane_intersection_threshold()

Returns the global configuration threshold for line-plane intersection calculations.

source

BeamletOptics.Config.get_orthogonality_threshold Method

julia

get_orthogonality_threshold()

Returns the global configuration threshold for orthogonality checks (e.g., beam support axes).

source

BeamletOptics.Config.get_progress_threshold Method

julia

get_progress_threshold()

Returns the runtime in seconds after which long-running calls (solve_system! on a beam group, electric_field, intensity and optical_power on a detector) show a progress bar in the terminal. Defaults to 5 s (configurable via the progress_threshold preference, see set_progress_threshold!). Inf disables all progress bars.

source

BeamletOptics.Config.get_sdf_inside_step Method

julia

get_sdf_inside_step()

Returns the global configuration step size when inside an SDF volume.

source

BeamletOptics.Config.get_sdf_raymarch_eps Method

julia

get_sdf_raymarch_eps()

Returns the global configuration epsilon for the SDF ray marching algorithm.

source

BeamletOptics.Config.get_sdf_surface_threshold Method

julia

get_sdf_surface_threshold()

Returns the global configuration threshold for the Signed Distance Field (SDF) surface detection.

source

BeamletOptics.Config.set_invariant_threshold! Method

julia

set_invariant_threshold!(val::Real)

Sets the global configuration threshold for the paraxial optical invariant check. This preference is persistent. Please restart Julia for this to take effect.

source

BeamletOptics.Config.set_preference! Method

julia

set_preference!(key::String, val; persistent=true)

Helper to set preferences. Default is persistent.

source

BeamletOptics.Config.set_progress_threshold! Method

julia

set_progress_threshold!(val::Real)

Sets the runtime in seconds after which long-running calls show a progress bar, see get_progress_threshold. Use Inf to disable progress bars globally. This preference is persistent. Please restart Julia for this to take effect.

source

Reference ​

Literature ​

Index ​

Reference

Literature

Index