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

julia

ObjectOrGroup

Union of AbstractObject and AbstractObjectGroup: what a System or a group stores and what render! draws.

source

BeamletOptics.PROGRESS_SINK Constant

julia

PROGRESS_SINK

Scoped ProgressSink of the running code, nothing (terminal bars) by default. Set it with Base.ScopedValues.with(PROGRESS_SINK => sink) do … end.

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.SDF_MISS_DISTANCE Constant

julia

SDF_MISS_DISTANCE

Path length in [m] after which a ray that is marched towards an AbstractSDF counts as a miss. A shape that lies farther away than this from the start of the ray is not hit.

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:

trace_system!(system, beam; r_max, kwargs...): traces the beam from its last ray through the system until no object is hit or an interaction returns nothing
push!(beam, interaction): appends the result of an interaction to the beam
empty!: resets the beam to its unsolved state. solve_system! calls it before tracing
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)
_chief_beam: returns the beam whose rays carry the geometric path, used by path_segments. Defaults to the first of _component_beams; a beam that stores its rays directly returns itself

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.

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

julia

AbstractBeamRenderHandle <: AbstractRenderHandle

Handle of a ray, beam or beam group, returned by live_render!(ax, beam). Implements rendered, render_plots, render_settings and render_settings!. update_render! draws the current rays of the beam, e.g. after solve_system!. Keep the handle on a root beam or a beam group: child beams and all rays after the first are new objects after every solve, so a handle on one of them does not follow the solved beam.

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

julia

AbstractBoundingSphere

Supertype of the results of bounding_sphere_of: a SingleBoundingSphere for a shape, a MultiBoundingSphere for several shapes or objects, or NoBoundingSphere for anything without one. Like a trait, bounding_sphere_of(x) selects by the type of x how x is tested against a ray, see intersect3d(sphere, x, ray); in contrast to a trait, a sphere also holds data of x, its center and radius.

Interface

A subtype that describes a sphere has the fields

pos: the center in world coordinates [m], read via position(sphere)
radius: the radius [m], read via radius(sphere)

The generic methods for an AbstractBoundingSphere, e.g. the test against a ray, use these. They do not apply to a NoBoundingSphere, which has its own methods wherever no sphere is a valid input, and whose position and radius throw an ArgumentError.

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. initialize! calls it for all detectors of a system

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!. A single detector is reset with empty!(detector), all detectors of a System or ObjectGroup with initialize!, which calls empty! on every AbstractDetector. The solver does not reset detectors unless asked to (keyword initialize of solve_system!), since the beams of a beam group and several sources solved one after another are meant to superpose.

Every kinematic function empties a detector, since the stored data belong to the pose of the detector during the solve, see translate3d!(::Movable, ::AbstractDetector, offset). A subtype gets this from its empty! method without further code.

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).

A subtype implements electric_field(hit, p), its field at a global point p, as well as direction(hit) and refractive_index(hit), from which the readouts of the Detector on a grid follow (see intensity).

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
AstigmaticGaussianBeamletHit — single astigmatic Gaussian beamlet with a vector field

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
initialize! (optional): resets the data that the object stores during a solve, e.g. the hits of a detector. By default nothing is reset.

source

BeamletOptics.AbstractObjectGroup Type

julia

AbstractObjectGroup

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.

A ray or beam interacts with the object of the group that it hits. A component whose parts interact as one, e.g. a cemented doublet, is an AbstractObject with the MultiShape trait.

Own assembly types

An assembly of separate parts, e.g. a telescope from its mirrors, can be a subtype of AbstractObjectGroup with named parts and its own constructor: it needs the fields below and no interact3d method, and the kinematic API, set_pivot3d!, systems and rendering work as for an ObjectGroup. See templates/08_custom_group.jl of the agent skill.

Implementation reqs.

Subtypes of AbstractObjectGroup must implement the following:

Fields:

objects: a tuple of AbstractObjects or additional subgroups, allows for hierarchical structures
center: a Point3{T} which is regarded as the reference origin (pivot) of the group
dir: a SMatrix{3,3,T,9} that describes the local coordinate system of the group

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

Functions:

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

objects: getter for the objects field or equivalent return type
position / position!: gets or sets the reference origin (pivot)
orientation / orientation!: gets or sets the orientation matrix

Kinematic

An AbstractObjectGroup is a container: it takes the kinematic class of its objects, i.e. BeamletOptics.Movable with an BeamletOptics.Oriented frame for movable objects, see BeamletOptics.AbstractKinematicTrait. The constructors must check that the objects are either all static or all movable, e.g. with allequal(BeamletOptics.is_static, objects). The primitives translate3d!(::Movable, group, offset) and rotate3d!(::Movable, group, R::AbstractMatrix) move all objects and the pose of the group.

source

BeamletOptics.AbstractObjectRenderHandle Type

julia

AbstractObjectRenderHandle <: AbstractRenderHandle

Handle of one movable thing, returned by live_render!(ax, obj) for an AbstractObject or an object group and by live_render!(draw, ax, x) for anything with a pose. The plots are drawn once; update_render! applies the current pose of rendered(h) as their model matrix (and draws them again if the parts of a MultiShape object moved relative to each other). pick_object returns rendered(h) for the plots of pickable_plots.

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. Currently the following concrete types are implemented:

A hit stores the values of the ray at the moment it hit the detector, not the ray itself: a new solve of the beam or a move of any object does not change it.

Implementation reqs.

Subtypes of AbstractRayHit must implement the following functions:

hit_point: the R³ point of intersection
direction: the direction of the ray
optical_path_length: the optical path length of the beam up to the hit point (incl. its parents)
wavelength: the vacuum wavelength of the ray
wavenumber: the vacuum wavenumber 2π / λ
refractive_index: the refractive index in front of the detector
projection_factor: |d · n| of the ray direction d and the surface normal n; 1 if the ray ended without an intersection

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

julia

AbstractRenderHandle

Supertype of all handles returned by live_render!. A handle references the rendered object, system or beam and its plots, which can be re-synchronized via update_render! and deleted via remove_render!. Concrete handles are implemented by the Makie extension.

Render handle protocol

Every handle implements rendered and render_plots. The subtypes add:

AbstractObjectRenderHandle: one movable thing, e.g. an object or a marker drawn via live_render!(draw, ax, x)
AbstractSystemRenderHandle: the object handles of a system, with its hierarchy of groups
AbstractBeamRenderHandle: a ray, beam or beam group, with render_settings and render_settings!

Code that uses handles, e.g. a GUI, relies on this protocol only, and may add own subtypes, e.g. a system handle that combines the handles of several systems.

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

julia

AbstractSampling

How the rays of a CollimatedSource or PointSource are sampled. The source stores its sampling in the field sampling, such that set_num_rays! can regenerate its rays with another number of rays. The constructors of the sources generate their beams with the same methods.

Implementation reqs.

A subtype S <: AbstractSampling implements:

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

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

Implementations

BeamletOptics.NoSampling: given beams, can not be regenerated
BeamletOptics.DiscRings, BeamletOptics.DiscSunflower, BeamletOptics.DiscLine: CollimatedSource
BeamletOptics.ConeRings, BeamletOptics.ConeSunflower, BeamletOptics.ConeFan: PointSource

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
bounding_sphere_of (optional): computes a sphere that encloses the shape. A solve then skips the shape for every ray that misses the sphere, without a call of intersect3d

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

julia

AbstractSystemRenderHandle <: AbstractRenderHandle

Handle of a system, returned by live_render!(ax, sys): one AbstractObjectRenderHandle per object, object groups rendered per object, such that each object of a group can be moved on its own. A subtype implements

rendered(h): the system
render_children(h): the object handles
render_parent(h, obj): the group that holds obj, or nothing at the top level
push!(h, oh::AbstractObjectRenderHandle): adds the object handle oh at the top level, e.g. of an object added to the scene, and returns h
delete!(h, oh::AbstractObjectRenderHandle): removes oh from h and returns h; its plots stay, see remove_render!

render_plots, update_render!, remove_render! and pick_object of a system handle are defined in terms of these.

A handle that knows its axis, like the one returned by live_render!(ax, sys), also implements live_render!(h, obj; kwargs...), which renders an object (or object group) into h at runtime, and extends remove_render!(h, obj) by the hierarchy of the groups.

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, i.e. the X axis of the beamlet. Must be orthogonal to direction, otherwise an ArgumentError is thrown; has any non-zero length and is normalized internally. Default is nothing, i.e. a vector orthogonal to direction is chosen.
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. Has any non-zero length and is normalized internally. A support that is not orthogonal to the direction (the dot product of the unit vectors exceeds get_orthogonality_threshold(), default 1e-10) throws an ArgumentError. Default is nothing, i.e. a vector orthogonal to direction is chosen.

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 the segment of an AstigmaticGaussianBeamlet that hit the detector as values, without a reference to the beamlet: p0 and d0 are start and direction of the segment, l_seg its length, l0 the length of the beam (including its parents) up to p0, λ the wavelength and E_pol the polarization of the chief ray of the segment.

source

BeamletOptics.AstigmaticGaussianBeamletHit Method

julia

AstigmaticGaussianBeamletHit(agb::AstigmaticGaussianBeamlet, id)

Hit record of the traced segment id of agb: the data that beamlet_hit_field needs to evaluate the field of that segment at any point near it, including the optical path from the source (parents included), the Gouy factor and the amplitude. The amplitude is that of the polarization of the chief ray of the segment, times the change with the beam area within the segments since the start of the root beam; the Gouy phase is followed from there as well, i.e. a child beamlet continues its parent. Detectors store one per beamlet that hits them; it can also be built for any traced segment, e.g. to sample a beamlet on a plane of one's own. The hit keeps no reference to agb: a new solve of agb does not change it.

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 the electric field vector E0, which may be complex, e.g. [1, 0, im] / √2 for circular polarization. The number type of the beam is that of the PolarizedRay, i.e. real also for a complex 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.BoundingSphereTable Type

The table of the bounding spheres of a solve, see bounding_spheres: the sphere of a shape under the shape, the MultiBoundingSphere of a MultiShape object or group under the object. The keys are compared by identity. The values are of these two concrete types, not of the abstract type, such that the lookup per ray needs no dynamic dispatch.

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. The first one is the center beam, which starts at the source position along the central source direction, unless the source wraps given beams.
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
sampling: how the rays were sampled (rings, sunflower, line, or given beams), see set_num_rays!

Functions

diameter: returns the diameter of the source
set_num_rays!: regenerates the rays with another number of rays

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; the number of rings counts the center as the innermost one, i.e. num_rings - 1 rings lie around it
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. The rays of such a source can not be regenerated with set_num_rays!.

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

julia

ConeFan(θ::Float64)

Rays with equidistant angles in the plane fan of a UniformFanSource, i.e. in the plane spanned by the source direction and the sampling reference vector, between -θ and θ [rad] to the source direction. The center ray comes first, followed by the other rays from one edge of the fan to the other, both edges included. An even number of rays has a second ray at the center, see UniformFanSource. Needs at least one ray.

source

BeamletOptics.ConeRings Type

julia

ConeRings(num_rings::Int, θ::Float64)

Concentric cones of rays around a center ray of a PointSource, the center counted as the innermost of the num_rings cones, the outermost with the half spread angle θ [rad]. The rays are distributed over the cones in proportion to the solid angle each cone represents, i.e. to its circumference, but half of it for the outermost cone, which represents only the inner half of its band. Every ray then represents about the same solid angle (trapezoidal rule). Needs at least 20 num_rings rays.

source

BeamletOptics.ConeSunflower Type

julia

ConeSunflower(θ::Float64)

Sunflower (Fibonacci) sampling of the spherical cap with the half spread angle θ [rad] of a UniformPointSource: every ray represents the same solid angle. The spiral starts with the center ray. Needs at least one ray.

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, or a number for a constant refractive index

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

A Detector accumulates hits across calls of solve_system!, on purpose: all beams of a beam group and several sources solved one after another superpose on it. To discard the results of previous solves, e.g. after changing a component in a loop, call initialize!(system) for all detectors of a system (nested groups included), empty!(detector) for a single one, or solve with initialize = true. Otherwise, the current result is added onto the previous result.

Thread safety

Beam groups are solved multithreaded. Pushing hits is guarded by the lock of the detector, so all beams can hit the same detector concurrently. Each task of the solve of a beam group collects its hits and stores them at its end, see with_hit_buffers. The order of the stored hits is not deterministic.

Reading hits

A hit stores the values of the ray or beamlet at the moment of the solve, in world coordinates. Solving again or moving a source or another object does not change the stored hits. Moving the detector itself empties it, since its hits would no longer lie on its surface. The hits of consecutive solves are kept side by side, and it is up to the user when to evaluate them: spot_diagram shows all of them, whereas electric_field, intensity and optical_power superpose all of them coherently, as for beams that exist at the same time.

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

julia

DiscLine()

Equidistant rays on the line of a UniformLineSource, i.e. on the diameter of the disc along the sampling reference vector. The center ray comes first, followed by the other rays from one end of the line to the other, both ends included. An even number of rays has a second ray at the center, see UniformLineSource. Needs at least one ray.

source

BeamletOptics.DiscRings Type

julia

DiscRings(num_rings::Int)

Concentric rings of rays around a center ray on the disc of a CollimatedSource, the center counted as the innermost of the num_rings rings. The outermost ring lies on the edge of the disc; the rays are distributed over the rings in proportion to the area of the disc each ring represents, i.e. to its circumference, but half of it for the outermost ring, which represents only the inner half of its annulus. Every ray then represents about the same area (trapezoidal rule), e.g. for spot sizes or point spread functions, which weight every ray equally. Needs at least 20 num_rings rays.

source

BeamletOptics.DiscSunflower Type

julia

DiscSunflower()

Sunflower (Fibonacci) sampling of the disc of a UniformDiscSource: every ray represents the same area of the disc. The spiral starts with the center ray. Needs at least one ray.

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 and the surface-based constructor DoubletLens(s1, s2, s3, l1, l2, n1, n2).

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.DoubletLens Method

julia

DoubletLens(s1, s2, s3, l1, l2, n1, n2)

Generates a two-component "cemented" DoubletLens from three surface specifications, e.g. SphericalSurface, EvenAsphericalSurface or CircularFlatSurface. The front element is Lens(s1, s2, l1, n1) and the back element is Lens(s2, s3, l2, n2), refer to the surface-based Lens constructor for the construction of the elements. The front vertex lies at the origin and the back element is translated along +y by l1, so that both elements share the cemented surface s2.

Arguments

s1: first surface
s2: second (cemented) surface
s3: third surface
l1: first lens center thickness in m
l2: second lens center thickness in m
n1: first lens RefractiveIndex
n2: second lens RefractiveIndex

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, i.e. at +y. Otherwise it is negative.

Clear apertures

Each surface has its own clear aperture and mechanical diameter, which are leveled per element as for a single Lens.

Supported surfaces

Only rotationally symmetric surfaces are supported, cylindrical surfaces are not. The limitations of the surface-based Lens constructor apply to each element: a meniscus element, whose center thickness does not exceed the sagitta of its convex surface, must consist of spherical surfaces.

Total internal reflection

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

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. Must be orthogonal to direction, has any non-zero length and is normalized internally. Default is nothing, i.e. a vector orthogonal to direction is chosen.

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. The waist and divergence rays start from the chief ray along this vector. A support that is not orthogonal to the direction (the dot product of the unit vectors exceeds get_orthogonality_threshold(), default 1e-10) throws an ArgumentError, since it would give a beamlet with a smaller waist radius and a shifted waist.

source

BeamletOptics.GaussianBeamletHit Type

julia

GaussianBeamletHit{T} <: AbstractBeamletHit{T}

Stores the segment of a GaussianBeamlet that hit the detector as values, without a reference to the beamlet: p0 and d0 are start and direction of the segment, l_seg its length, l0 the length of the beam (including its parents) up to p0, Δl0 the optical minus the geometric path and ψ0 the Gouy phase that the beam has collected up to there. segment holds the waist and divergence rays of the segment (see BeamletOptics.GaussianSegment), from which the field follows as from the beamlet itself, see gauss_parameters. E_amp is the field amplitude times the beam radius, E0 w0 of the source.

source

BeamletOptics.GaussianBeamletHit Method

julia

GaussianBeamletHit(g::GaussianBeamlet, id)

Hit record of the traced segment id of g: the data that beamlet_hit_field needs to evaluate the field of that segment at any point near it. Detectors store one per beamlet that hits them; it can also be built for any traced segment, e.g. to sample a beamlet on a plane of one's own. l0 is the length of the beam (including its parents) up to the start of the segment.

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

julia

GaussianSegment{T}

The waist and divergence rays of one segment of a GaussianBeamlet, as values relative to its chief ray: on the plane normal to the chief ray at the distance l behind its start, an auxiliary ray with direction a crosses at the transverse offset y0 + l * v from the chief ray. Both rays are straight within the segment, hence this holds exactly. n is the refractive index of the segment and λ the vacuum wavelength. gauss_parameters(segment, l) evaluates it, a GaussianBeamletHit stores it.

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 immediately 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.HitBuffers Type

The hits of the current task per Detector, see with_hit_buffers. Pushing detector => hit collects the hit in the buffer of the detector. The buffer of the last detector is kept at hand, since consecutive hits mostly go to the same detector.

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.

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

A meniscus lens, whose center thickness does not exceed the sagitta of its convex surface, must consist of spherical surfaces. An aspherical surface throws an ArgumentError in this case.

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

Stores each pushed detector => hit directly in its detector, guarded by the lock of the detector.

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

julia

MultiBoundingSphere{T} <: AbstractBoundingSphere

A sphere that encloses several bounding spheres, i.e. all parts of a MultiShape object or all objects of an object group, see bounding_sphere_of. A ray that misses it hits none of the parts, hence a solve tests it before the parts. It is tested against a ray like a SingleBoundingSphere and differs only in what it states: the sphere of several things.

Fields

pos: the center in world coordinates [m]
radius: the radius [m]

source

BeamletOptics.MultiBoundingSphere Method

julia

MultiBoundingSphere(a::AbstractBoundingSphere, b::AbstractBoundingSphere)
MultiBoundingSphere(spheres::Tuple)

Returns the smallest sphere that encloses the bounding spheres a and b, or all spheres, e.g. those of the parts of an object. The result is NoBoundingSphere() if one of them is none, since then no sphere encloses all parts, and for no spheres at all.

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

julia

NoBoundingSphere <: AbstractBoundingSphere

States that a shape or object has no bounding sphere. It is then tested against every ray via intersect3d, see bounding_sphere_of.

It has no center and no radius: position and radius throw an ArgumentError. Code that needs them handles NoBoundingSphere by a method of its own, or tests for it first.

source

BeamletOptics.NoSampling Type

julia

NoSampling()

The beams of the source were given to its constructor, e.g. CollimatedSource(beams, diameter, pos, dir). They can not be regenerated: set_num_rays! throws an ArgumentError and min_num_rays returns nothing.

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.NonInteractableObject Method

julia

NonInteractableObject(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.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

Each of its objects is traced and interacts on its own, read them via objects(group).

Kinematic

An ObjectGroup implements the kinematic API, see BeamletOptics.AbstractKinematicTrait. 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.PathSegment Type

julia

PathSegment{T}

Element type of the vector returned by path_segments, a NamedTuple with the fields

start, stop: start and end point of the segment, Point3{T} in [m]
s_start, s_stop: geometric path length from the source to the start and the end of the segment [m]
opl_start, opl_stop: optical path length from the source to the start and the end of the segment [m]
λ: wavelength of the segment in [m]
depth: depth of the beam in the beam tree, 1 for a root beam, 2 for its children, ...
parent: index of the preceding segment in the vector (the previous segment of the same beam or, for the first segment of a child beam, the last segment of its parent beam), 0 for the first segment of a root beam
beam_index: index of the root beam in a beam group, 1 for a single beam
ray_index: index of the ray of the segment in the rays of its beam (of the chief beam of a beamlet), as returned by point_on_beam; starts at 1 for every beam of the tree
final: true if the segment is a final ray without intersection, drawn with the length flen
leaf: true if the segment ends its branch, i.e. no other segment names it as parent: a final ray, or a ray that ends on an object without leaving it (e.g. on a detector)
object: the AbstractObject hit at the end of the segment (the object itself, not its ObjectGroup), nothing for a final segment or if the intersection does not name its object

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. The first one is the center beam, which starts at the source position along the central source direction, unless the source wraps given beams.
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
sampling: how the rays were sampled (rings, sunflower, fan, or given beams), see set_num_rays!

Functions

numerical_aperture: returns the NA of the source
set_num_rays!: regenerates the rays with another number of rays

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; the number of rings counts the center as the innermost one, i.e. num_rings - 1 rings lie around it
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. The rays of such a source can not be regenerated with set_num_rays!.

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

julia

PolarizedRayHit(ray::PolarizedRay, opl)

Stores the hit of a PolarizedRay as values: those of a RayHit and the field vector E of the ray in global coordinates.

source

BeamletOptics.PolygonPrismSDF Type

julia

PolygonPrismSDF <: AbstractSDF

Implements the exact SDF of a right prism, i.e. the extrusion of a convex polygon along the local z-axis. The local origin is the origin of the coordinates given to the constructor, it is not shifted.

Fields

vertices: corners of the cross-section in the local x-y-plane in [m], in counter-clockwise order
normals: outward unit normals of the edges, where edge i runs from vertex i to vertex i + 1
height: extent along the local z-axis in [m], the prism spans z ∈ [-height/2, height/2]

source

BeamletOptics.PolygonPrismSDF Method

julia

PolygonPrismSDF(vertices, height)

Constructs the prism over the convex polygon given by vertices, a vector of 2D points (x, y) in [m], extruded symmetrically by height in [m] along the local z-axis. Both vertex orders are accepted and normalized to counter-clockwise. Throws an ArgumentError for fewer than three vertices, for points that are not 2D, for degenerate (zero area or collinear) corners and for non-convex or self-intersecting polygons.

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.Prism Method

julia

Prism(vertices, height, n)

Creates a Prism with a convex polygonal cross-section, extruded along the local z-axis. The local origin is the origin of the given coordinates, i.e. the prism is placed where the vertices are, and rotations act around it. Like the RightAnglePrism the prism is not aligned with the y-axis, orient it with the kinematic functions. See PolygonPrismSDF for the geometry. See also EquilateralPrism and DovePrism.

Arguments

vertices: corners (x, y) of the cross-section in the local x-y-plane in [m], as a vector of 2D points or tuples. Both vertex orders are accepted. The polygon must be strictly convex.
height: extent along the local z-axis in [m], the prism is centered at z = 0
n: RefractiveIndex of the prism, or a number for a constant refractive index

source

BeamletOptics.ProgressSink Type

julia

ProgressSink()

Receiver of the progress of all progress loops of BeamletOptics (e.g. of solve_system! with progress = true, see _with_progress) that run inside with(PROGRESS_SINK => sink) do … end, including the tasks of Threads.@threads started there. Such loops draw no terminal bar. Part of the developer API, e.g. for a GUI that shows the progress of a solve in the background and cancels it. Another task reads the running loop with progress_state(sink), and cancels the loops by setting sink.cancel[] = true: the next _tick! then throws _ProgressCancelled, i.e. a loop stops after its current item.

Fields

current: the innermost running loop, nothing between loops (atomic)
cancel: cancel request, checked by every tick

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

julia

RayHit(ray::Ray, opl)

Stores the hit of a Ray as values: hit point p, direction d, optical path length opl of the beam up to the hit point, wavelength λ, refractive index n and projection factor proj.

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

julia

SingleBoundingSphere{T} <: AbstractBoundingSphere

A sphere that encloses one shape, see bounding_sphere_of.

Fields

pos: the center in world coordinates [m]
radius: the radius [m]

source

BeamletOptics.SingleBoundingSphere Method

julia

SingleBoundingSphere(sphere::AbstractBoundingSphere)
MultiBoundingSphere(sphere::AbstractBoundingSphere)

The sphere with the same center and radius as a sphere of the other kind, e.g. the sphere around the parts of a composite shape as the sphere of this one shape. NoBoundingSphere() is passed on.

source

BeamletOptics.SingleBoundingSphere Method

julia

SingleBoundingSphere(shape::AbstractShape, center, radius)

The bounding sphere of the shape from a center given in the local frame of the shape, i.e. relative to its position and along the axes of its orientation, and the radius in [m]. The center is converted to world coordinates for the current pose of the shape. This is the constructor for a method of bounding_sphere_of.

source

BeamletOptics.SingleBoundingSphere Method

julia

SingleBoundingSphere(shape::AbstractShape, sphere::AbstractBoundingSphere)

The sphere, whose center is given in the local frame of the shape, in world coordinates, e.g. the sphere around the parts of a shape that are positioned in its local frame. NoBoundingSphere() is passed on.

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 (subtypes of AbstractObject) and object groups (subtypes of AbstractObjectGroup) that are part of the system. The constructor copies the vector it is given, such that push! and delete! of the system do not change it.

source

BeamletOptics.System Method

julia

System()

Creates an empty system, to which objects are added via push!.

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 and the surface-based constructor TripletLens(s1, s2, s3, s4, l1, l2, l3, n1, n2, n3).

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), use the surface-based constructor TripletLens(s1, s2, s3, s4, l1, l2, l3, n1, n2, n3) with e.g. SphericalSurface(r, d) for each surface. 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.TripletLens Method

julia

TripletLens(s1, s2, s3, s4, l1, l2, l3, n1, n2, n3)

Generates a three-component "cemented" TripletLens from four surface specifications, e.g. SphericalSurface, EvenAsphericalSurface or CircularFlatSurface. The front, middle and back elements are Lens(s1, s2, l1, n1), Lens(s2, s3, l2, n2) and Lens(s3, s4, l3, n3), refer to the surface-based Lens constructor for the construction of the elements. The front vertex lies at the origin and the middle and back elements are translated along +y by l1 and l1 + l2, so that neighbouring elements share the cemented surfaces s2 and s3.

Arguments

s1: first surface
s2: second (first cemented) surface
s3: third (second cemented) surface
s4: fourth surface
l1: first lens center thickness in m
l2: second lens center thickness in m
l3: third lens center thickness in m
n1: first lens RefractiveIndex
n2: second lens RefractiveIndex
n3: third lens RefractiveIndex

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, i.e. at +y. Otherwise it is negative.

Clear apertures

Each surface has its own clear aperture and mechanical diameter, which are leveled per element as for a single Lens.

Supported surfaces

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{O}

Thread-safe progress counter for long loops. Where the progress goes depends on the output type O, see _report!:

an IO: a ProgressMeter.Progress bar is drawn only once the loop has run for threshold seconds, see get_progress_threshold,
a ProgressSink: nothing is drawn, the sink exposes the running loop to another task (e.g. the live view) and can cancel it.

_tick! costs one atomic increment plus the report of the output: one time() call for an IO, one atomic load of the cancel flag for a sink. The terminal 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, or the ProgressSink the loop reports 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
t0: time() at which the counter was created, i.e. the loop started
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 reports to the scoped PROGRESS_SINK if one is set, otherwise to stderr. It is enabled only if progress is true and the output can show it: a sink always, stderr only if it 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 reports to output, an IO or a ProgressSink. An IO is drawn to once threshold seconds have passed; a sink ignores threshold and dt.

source

BeamletOptics._ProgressCancelled Type

julia

_ProgressCancelled()

Thrown by _tick! inside a loop whose ProgressSink was cancelled. Check caught exceptions with is_cancelled, which also sees through the wrappers of Threads.@threads.

source

Base.append! Method

julia

append!(d::Detector, new::Vector{<:AbstractDetectorHit})

Stores all hits of new in the detector d at once, guarded by the lock of d. The vector new may become the vector of hits of d, i.e. it must not be used afterwards.

source

Base.delete! Method

julia

delete!(h::AbstractSystemRenderHandle, oh::AbstractObjectRenderHandle) -> h

Removes the object handle oh from the system handle h. Its plots stay in the axis, delete them via remove_render!(oh).

source

Base.delete! Method

julia

delete!(system::System, object::ObjectOrGroup) -> system

Removes the top-level object (or object group) from the system, compared by identity. Nothing happens for an object that is not part of the system. An object within a group can not be removed on its own and throws an ArgumentError: remove the group instead.

Beams and beam groups that were solved before still end on the removed object: solve them again with solve_system!(system, beam). The system must not be changed while it is being solved.

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!(bg::AbstractBeamGroup)

Resets every beam of the group to its untraced start state, e.g. to solve the group again after the objects of a System were changed. The pose of the group is unchanged.

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.pop! Method

julia

pop!(system::System) -> ObjectOrGroup

Removes the last top-level object (or object group) of the system and returns it. Beams that were solved before must be solved again, see delete!(system, object).

source

Base.popat! Method

julia

popat!(system::System, i::Integer) -> ObjectOrGroup

Removes the i-th top-level object (or object group) of the system and returns it. The index counts the objects and groups as they were added, a group counts as one. An index out of bounds throws a BoundsError. Beams that were solved before must be solved again, see delete!(system, object).

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

Base.push! Method

julia

push!(h::AbstractSystemRenderHandle, oh::AbstractObjectRenderHandle) -> h

Adds the object handle oh at the top level of the system handle h, e.g. of an object added to the scene after live_render!, such that update_render! and pick_object of h include it.

source

Base.push! Method

julia

push!(d::Detector, hit::AbstractDetectorHit)

Stores the hit in the detector d, guarded by the lock of d. Within with_hit_buffers, e.g. in the solve of a beam group, the hit is collected in the buffer of the current task instead and reaches d when the buffer is flushed.

source

Base.push! Method

julia

push!(system::System, objects::ObjectOrGroup...) -> system

Adds the objects (or object groups) at the top level of the system, such that they are traced by the following calls of solve_system!. An object that is already part of the system, directly or within a group, throws an ArgumentError; in this case nothing is added.

Beams and beam groups that were solved before do not know the new object: solve them again with solve_system!(system, beam). The system must not be changed while it is being solved.

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, P0)

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.
P0: Total power of the source in [W]. The beamlets overlap and add coherently; their fields are scaled such that the superposition carries P0.

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.DovePrism Method

julia

DovePrism(length, aperture, height, n)

Creates a Prism with an isosceles trapezoid cross-section and 45° end faces, e.g. a Dove prism that inverts an image without deviating a beam along its axis. The long axis is the local y-axis, so that a beam travelling along +y enters the 45° end face. The base face with the normal -x is the one that totally internally reflects. The local origin is the center of the cross-section's bounding box.

Arguments

length: length of the long base face in [m], must be larger than 2 * aperture
aperture: distance between the base face and the parallel short face in [m], must be positive
height: extent along the local z-axis in [m]
n: RefractiveIndex of the prism, or a number for a constant refractive index

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; the number of rings counts the center as the innermost one, i.e. num_rings - 1 rings lie around it.
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]. The beamlets overlap and add coherently in the far field; their fields are scaled such that the superposition carries P0.
E0: Optional Jones vector defining the polarization and phase of the wave; its component transverse to each beamlet is used, its magnitude does not matter, the power is P0.

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.EquilateralPrism Method

julia

EquilateralPrism(side, height, n)

Creates an equilateral triangular Prism, e.g. for dispersion. The local origin is the centroid of the triangle. The apex points along the local +y-axis and the base face has the normal -y. A beam travelling along +x or -x through the faces next to the apex at (approximately) minimum deviation is deflected towards the base.

Arguments

side: edge length of the triangular cross-section in [m], must be positive
height: extent along the local z-axis in [m]
n: RefractiveIndex of the prism, or a number for a constant refractive index

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). The grid spans 4 w0; the sub-waist overlap ⋅ 4 w0 / n_grid of the beamlets must be smaller than w0, i.e. n_grid > 4 overlap, else an ArgumentError is thrown. The superposition of the beamlets is the Gaussian beam of the waist w0 and the power P0: the sampled envelope is deconvolved with the profile of a beamlet.
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; its component transverse to dir is used, its magnitude does not matter, the power is P0. 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.GaussianModeDecomposition Method

julia

GaussianModeDecomposition(x, y, Eu, Ev, dir, λ; basis = nothing, origin = zeros(3), R = Inf)

Fits a single AstigmaticGaussianBeamlet to a transverse complex vector field, given by its components Eu, Ev along the sampling axes e1, e2 of a plane normal to dir. This is the lowest-order Gaussian mode decomposition: the counterpart of WavefrontBeamletDecomposition for fields that are close to one Gaussian mode and too small to be tiled into many beamlets, e.g. the output of a single-mode fiber (beamlets must be much larger than λ).

Arguments

x, y: 1D sample coordinates along e1, e2 in [m], relative to origin.
Eu, Ev: length(x) × length(y) complex field components along e1, e2 in [V/m] (peak amplitude), with the full spatial phase and travelling along dir.
dir: propagation direction, the normal of the sampling plane.
λ: vacuum wavelength in [m]. The plane must lie in vacuum or air (n = 1), where BMO starts beams.
basis: optional tuple (ex, ey) of the sampling axes e1, e2, as in WavefrontBeamletDecomposition. Default: e1 = normal3d(dir), e2 = dir × e1.
origin: global position of the sample x = y = 0 in [m].
R: radius in [m] of a reference sphere that has been removed from Eu, Ev, as in WavefrontBeamletDecomposition(x, y, Eu, Ev, dir, λ). Default Inf: Eu, Ev are the physical field. The sphere enters the fit analytically (tilt at the centroid, curvature 1/R), so the grid only has to resolve the phase of Eu, Ev.

Fit

Polarization: the dominant eigenvector of the coherence matrix Σ E Eᴴ; the field is projected onto it.
Position and waist: centroid and principal axes of the second intensity moments; the beam radius along a principal axis is twice the rms width.
Direction: the mean transverse wave vector, from the intensity-weighted phase step between neighboring samples.
Curvature: the quadratic phase from the moments ⟨rᵢ ∂ⱼφ⟩ of the phase gradient (phase steps between neighbors), taken along the principal axes of the intensity. Twist between curvature and intensity axes (general astigmatism) is not represented.
Amplitude and phase: the projection of the field onto the fitted mode.

The beamlet starts at the centroid on the plane, with waist radii and waist positions along its principal axes that reproduce the fitted radii and curvatures there. The widths are measured in the plane, so the tilt of the fitted direction against dir must be small.

The beamlet carries only the projected part of the field: optical_power(beamlet) divided by the power of the input is the fraction of the power in the fitted Gaussian mode, i.e. the quality of the approximation.

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 NonInteractableObject 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.MoellerTrumboreAlgorithm Method

julia

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

An implementation of the Möller-Trumbore algorithm for ray-triangle-intersection, which hits the face from both sides. 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ϵ: dimensionless tolerance. A ray whose direction is closer than kϵ (in units of the cosine of the angle to the face normal) to the plane of the face misses it, and the barycentric coordinates of a hit may exceed the face by kϵ. Both are independent of the size of the face.
lϵ: the shortest distance in [m] from the start of the ray at which a hit counts, such that a ray that starts on the face does not hit it again.

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 legs are the faces with the normals -x and -y and the hypotenuse passes through the local origin, see RightAnglePrismSDF. The prism is not aligned with the y-axis.

Arguments

leg_length: dimension in x- and y-direction in [m]
height: extent along the local z-axis in [m]
n: RefractiveIndex of the prism, or a number for a constant refractive index

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; the number of rings counts the center as the innermost one, i.e. num_rings - 1 rings lie around it.
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]. The beamlets overlap and add coherently in the far field; their fields are scaled such that the superposition carries P0.
E0: Optional Jones vector defining the polarization and phase of the spherical wave; its component transverse to each beamlet is used, its magnitude does not matter, the power is P0.

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 spiral starts with the center ray at pos (k = 0). The radius of the k-th ray (k = 1 … 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. All rays are equally weighted samples of the pupil: ray k represents the part of the disc between the radii diameter/2 ⋅ √(k/N) and diameter/2 ⋅ √((k + 1)/N). The center ray represents the innermost of these parts, a disc, by its center.

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, must be ≥ 1
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.UniformFanSource Method

julia

UniformFanSource(pos, dir, θ, λ; num_rays=101, basis)

Generates a plane fan of Beams emitted from pos, i.e. a two-dimensional point source: the rays lie in the plane spanned by dir and basis, with equidistant angles between -θ and θ to dir. This is useful for layout sketches and for tracing a single (e.g. meridional or sagittal) section of a system.

The first ray is the center ray along dir. It is followed by h = (N - 1) ÷ 2 rays on each side of it, which enclose the angles φⱼ = j/h ⋅ θ with dir for j = -h … h without j = 0 and point along cos φⱼ ⋅ dir + sin φⱼ ⋅ basis, i.e. from one marginal ray at the edge of the fan to the other. A single ray points along dir.

Use an odd number of rays

A pattern that is symmetric to its center ray has an odd number of rays. An even num_rays yields the pattern of num_rays - 1 rays and a second ray along dir.

Note

This is merely a PointSource constructor which samples one section of the cone instead of concentric rings.

Warning

The rays sample a plane angle, not a solid angle: they are not equal solid angle samples of a cone. For a point spread function or an intensity use UniformPointSource.

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 axis of the fan
θ: half spread angle in rad, must be < π
λ = 1e-6: wavelength in [m], default val. is 1000 nm

Keyword Arguments

num_rays=101: total number of rays in the source, must be ≥ 1
basis: direction (e.g. [1,0,0]) that spans the plane of the fan together with dir, projected into the plane normal to dir. Rays with a positive angle are tilted towards it. Must not be zero or parallel to dir.

Orientation of the fan

If no basis is passed, the plane of the fan is derived from dir deterministically via normal3d, which is rarely the section of interest: pass a basis to choose the plane of the rays. The fan can also be turned about dir afterwards with rotate3d!.

source

BeamletOptics.UniformLineSource Method

julia

UniformLineSource(pos, dir, width, λ; num_rays=101, basis)

Generates a plane sheet of parallel Beams, i.e. a two-dimensional collimated source: the rays start equidistantly on a line of the length width centered at pos and travel along dir. The line lies along basis, such that all rays lie in the plane spanned by dir and basis. This is useful for layout sketches and for tracing a single (e.g. meridional or sagittal) section of a system.

The first ray is the center ray at pos. It is followed by h = (N - 1) ÷ 2 rays on each side of it, at pos + j/h ⋅ width/2 ⋅ basis for j = -h … h without j = 0, i.e. from one marginal ray at the end of the line to the other. A single ray starts at pos.

Use an odd number of rays

A pattern that is symmetric to its center ray has an odd number of rays. An even num_rays yields the pattern of num_rays - 1 rays and a second ray at pos.

Note

This is merely a CollimatedSource constructor which samples one diameter of the disc instead of concentric rings. width is stored as the diameter of the source.

Warning

The rays sample a line, not an area: they are not equal-area samples of a circular pupil. For a point spread function or an intensity use UniformDiscSource.

Arguments

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

Inputs

pos: center of the line, i.e. the source position
dir: starting direction of all beams
width: length of the line in [m], i.e. the distance between the marginal rays
λ = 1e-6: wavelength in [m]

Keyword Arguments

num_rays=101: total number of rays in the source, must be ≥ 1
basis: direction of the line (e.g. [1,0,0]), projected into the plane normal to dir. Must not be zero or parallel to dir.

Orientation of the line

If no basis is passed, the direction of the line is derived from dir deterministically via normal3d, which is rarely the section of interest: pass a basis to choose the plane of the rays. The line can also be turned about dir afterwards with rotate3d!.

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 spiral starts with the center ray along dir (k = 0). The polar angle ϑₖ of the k-th ray (k = 1 … 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. All rays are equally weighted samples of the cap: ray k represents the part of the cap with 1 - (k + 1)/N ⋅ (1 - cos θ) ≤ cos ϑ ≤ 1 - k/N ⋅ (1 - cos θ). The center ray represents the innermost of these parts, a cap, by its center.

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, Eu, Ev, dir, λ; threshold=1e-4)

Vector-field counterpart of WavefrontBeamletDecomposition(x, y, amplitude, phase, dir, λ): decomposes a transverse complex vector field, given as its two components Eu, Ev along the sampling axes e1, e2 (basis, default e1 = normal3d(dir), e2 = dir × e1), into a collection of AstigmaticGaussianBeamlets.

Unlike the scalar method (one amplitude/phase pair plus a single macroscopic polarization E0), this method carries an independent complex amplitude per polarization component and grid point, i.e. an arbitrary, spatially varying polarization state (including elliptical and depolarizing-looking patterns coming from separate Eu, Ev measurements). This is the minimal generic addition needed for BeamletOptics.WavefrontBeamletDecomposition(::OpticsBase.PlaneField) (ext/BeamletOpticsOpticsBaseExt.jl), which hands in the plane's tangential E field directly; it is not extension-specific and works standalone.

Arguments

x, y: 1D spatial coordinates of the field grid, along e1, e2, in [m].
Eu, Ev: length(x) × length(y) complex matrices, the field components along e1, e2 in [V/m] (peak amplitude). Both must have the full spatial phase.
dir: macroscopic reference propagation direction (e.g. [0, 1, 0]).
λ: wavelength in [m].
threshold: relative amplitude (of hypot.(abs.(Eu), abs.(Ev))) below which no beamlet is spawned.
overlap, basis, randomize_axes, rng: as in the scalar method.
R: radius in [m] of a reference sphere that has been removed from Eu, Ev: the physical field is E .* cis(sign(R) k (√(x² + y² + R²) − |R|)) with k = 2π/λ (R > 0: diverging from the point at the distance R behind x = y = 0, R < 0: converging to the point |R| in front of it). Default Inf: Eu, Ev are the physical field. The sphere enters analytically, so the grid only has to resolve the phase of Eu, Ev, not that of the sphere: every beamlet travels along the ray of the sphere through its sample (plus the gradient of the sampled phase) and starts with the wavefront curvature of the sphere.

Local propagation direction and polarization

The local propagation direction at each grid point is found from the Eikonal equation, with the phase difference between neighboring samples taken from the complex vector overlap E(a)ᴴ E(b). This is continuous where the polarization changes and assumes that both components share one local wavevector, i.e. that the field is not the superposition of two waves with genuinely different directions at that point. The phase step between neighbors must stay below π: a field tilted by θ against dir needs dx < λ / (2 sin θ), while the beamlets (waist overlap * dx) must stay much larger than λ, so keep the sampling plane close to normal to the beam.

The beamlet's E0 keeps the given tangential components Eu, Ev and gets the normal component that makes it transverse to the local direction (E·d = 0). Its amplitude is scaled by cos θ = d·dir, because the footprint of a tilted beamlet on the sampling plane is stretched by 1/cos θ. The sum of the beamlets then reproduces the sampled tangential field for oblique beams as well.

Throws an ArgumentError for a field that is zero everywhere and for R = 0.

The grid is placed in the plane normal to dir through the global origin; use translate3d! to move it to its actual position.

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._area_arg Method

julia

_area_arg(agb, i, l)

Continuous argument of the complex beam area of agb at the local distance l along the chief ray segment i (measured from the start of that segment), relative to the start of the root beam: a child continues the last segment of its parent, see _area_from_root.

The area (h1 × h2) ⋅ d is a pseudoscalar: a reflection mirrors the transverse frame against the chief ray and flips its sign, which is no change of the beam. The jump at an interface is therefore taken modulo π, on (−π/2, π/2], and the Gouy phase does not change at a mirror. Physical interface jumps (refraction) are small.

source

BeamletOptics._aspheric_axial_extent Method

julia

_aspheric_axial_extent(s)

Returns the smallest and the largest coordinate along the optical axis of the volume of an aspheric or acylindric surface SDF s, as a tuple. The candidates are the vertex, the edge and the stationary point of the sag (max_sag), which is exact for profiles with at most one stationary point within the aperture.

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._chief_beam Method

julia

_chief_beam(beam::AbstractBeam)

Returns the beam whose rays carry the geometric path of beam: the first of its _component_beams, i.e. the chief beam of a beamlet. A beam that stores its rays directly (e.g. Beam) returns itself.

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._eikonal_direction Function

julia

_eikonal_direction(Δφ, i, j, nx, ny, dx, dy, k, e1, e2, dir_n, ∇φ0 = (0, 0))

Local propagation direction at grid index (i, j) from the Eikonal equation ∇φ = k sin θ. Δφ(a, b) returns the phase difference from grid index a to the neighboring index b (tuples); central differences, one-sided at the grid edges, give the transverse direction cosines sin θx, sin θy along e1, e2. ∇φ0 is a phase gradient along e1, e2 that is known analytically and added to the measured one (e.g. that of a reference sphere, see _sphere_phase). Returns nothing if the gradient is too steep to represent a non-grazing propagation direction (sin²θx + sin²θy ≥ 1) or is NaN. Shared by both WavefrontBeamletDecomposition methods, which differ only in how they measure Δφ (scalar phase or vector overlap).

source

BeamletOptics._enclosing_circle Method

julia

_enclosing_circle(vertices)

Returns the center and the radius of a circle that encloses the 2D points vertices and passes through at least one of them. Of the circles around the mean of the points (exact for regular polygons) and around the center of their bounding box (exact for rectangles and right triangles) the smaller one is returned, which is not the smallest enclosing circle in general.

source

BeamletOptics._fan_coordinates Method

julia

_fan_coordinates(n) -> Vector{Float64}

The positions of the n samples of a line or fan on [-1, 1]: the center 0 first, then (n - 1) ÷ 2 equidistant samples on each side of it from -1 to 1, both ends included. These are n samples for an odd n. An even n leaves one sample, which lies at the center as well, since a pattern that is symmetric to its center sample has an odd number of samples.

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._flat_size Method

julia

_flat_size(s::AbstractShape) -> Vector{Pair{String, Any}}

Returns "Size [m]", the extent of the flat mesh s along its local x and z axes, i.e. the width and height of e.g. a Detector, or nothing for other shapes. Linear in the number of vertices, hence only used for flat components.

source

BeamletOptics._gouy_before Method

julia

_gouy_before(gauss::GaussianBeamlet, index)

Gouy phase that the beam (including its parents) has collected in front of segment index, as the offset between the collected Gouy phase (the ψ of gauss_parameters) and the Gouy phase relative to the waist of the local segment (gauss_parameters(gauss, z, 0)). The collected phase is continuous at a surface, whereas the local waist and with it the local phase changes there, e.g. at a lens. The offset is zero on the first segment of a root beam and collects the steps of the local phase at every surface on the way. A child continues the last segment of its parent.

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._index_properties Method

Returns the refractive index model n (see RefractiveIndex) and its value at the default wavelength λ₀, see get_default_wavelength.

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_leaf_of Method

Returns true if obj is one of the leaves, compared by identity.

source

BeamletOptics._jones_field Method

julia

_jones_field(E0, d, a)

The field of the amplitude a [V/m] along the direction d with the polarization and the phase of the Jones vector E0: its component transverse to d, normalized. Throws an ArgumentError for an E0 along d.

source

BeamletOptics._normalize_coherent_power! Method

julia

_normalize_coherent_power!(beams, vs, width)

Scales the fields of beams, beamlets of equal power that start in phase, such that their coherent superposition carries the sum of their powers. Their profiles are Gaussians of the width (the 1/e² half width of the intensity) about the vectors vs in a common plane: the positions with the waist in the source plane of collimated beamlets, or the directions with the far-field divergence of beamlets from one point. Where the beamlets overlap, their fields add: two beamlets of the power P whose vectors differ by δ contribute P exp(-δ² / (2 width²)) to the power of the superposition per pair, i.e. it carries P Σᵢⱼ exp(-|vᵢ - vⱼ|² / (2 width²)) instead of N P. This holds for all beamlets, also at the edge of the source, where fewer neighbors overlap.

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._path_segments! Method

julia

_path_segments!(segments, beam, beam_index, flen, parent = 0, depth = 1, s = 0, opl = 0)

Appends the segments of beam and, recursively, of its children to segments, see path_segments. parent is the index of the segment the beam continues from, and s, opl are the geometric and optical path length accumulated there.

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(shape::AbstractSDF, pos, dir, t_max=SDF_MISS_DISTANCE, num_iter=10_000, eps=1e-10, h=1e-9)

Perform the ray marching algorithm if the starting pos is inside of shape, or on its surface with dir pointing inside, and return the intersection where the ray leaves shape first. The ray is marched by the distance -sdf, which is not larger than the distance to the surface for an SDF that is exact or a lower bound inside, hence no step passes the exit. A point where the SDF is about 0 is an exit only if the ray leaves the object there, not at an internal seam of a composite SDF. If a step ends outside, e.g. for an SDF that overestimates the distance inside or after a minimum step, the exit within this step is found within the bracket of this step, see _bracketed_exit. The ray is a miss once it has travelled the path length t_max in [m] without leaving shape. A ray that grazes the surface of a thin part from inside takes steps of about its depth, hence the many iterations. A ray that starts on the surface may start up to the surface threshold h outside of it, see intersect3d(object::AbstractSDF, ray).

source

BeamletOptics._raymarch_outside Method

julia

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

Perform the ray marching algorithm if the starting pos is outside of shape. The ray is a miss once it has travelled the path length t_max in [m] without a hit.

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, and scaled for the medium behind the coating: the coating transmits a fraction of the power, and the power of a beam is proportional to n cos(θ) |E|². The refractive index of the child must be set before.

source

BeamletOptics._report! Method

julia

_report!(output::IO, p::_LazyProgress)
_report!(s::ProgressSink, p::_LazyProgress)

Report a tick of p. To an IO, the bar is drawn lazily (threshold and redraw interval of p). To a sink nothing is drawn; if the sink is cancelled, _ProgressCancelled is thrown.

source

BeamletOptics._signed_edge_sag Method

julia

_signed_edge_sag(surface, sd)

Returns the edge sagitta of the surface with sign, such that the edge of a front surface lies at y = s and the edge of a back surface at y = center_thickness + s. edge_sag returns the unsigned sagitta for spherical and cylindrical surfaces, hence the sign of the radius is applied; the sagitta of aspherical and acylindrical surfaces is already signed.

source

BeamletOptics._sphere_exit Function

julia

_sphere_exit(sphere::AbstractBoundingSphere, ray, margin = 0)

Returns the path length in [m] at which the ray leaves the sphere, or nothing if the ray does not pass through it, i.e. if its line misses the sphere or the sphere lies behind its start. The radius is enlarged by the margin in [m] and by the rounding error of the test, such that a ray towards a point on the sphere still passes through it.

source

BeamletOptics._sphere_phase Method

julia

_sphere_phase(x, y, R, k)
_sphere_phase_gradient(x, y, R, k)

Phase sign(R) k (√(ρ² + R²) − |R|) of a reference sphere with radius R about the axis through x = y = 0 (ρ² = x² + y²), written without cancellation for ρ ≪ |R|, and its gradient along x, y. Both are zero for R = Inf.

source

BeamletOptics._splitting_ratio Method

Returns the power "Reflectance" R and "Transmittance" T of the coating, which stores the amplitude factors √R and √T, i.e. R as passed to the constructors of the beamsplitters.

source

BeamletOptics._sunflower_fraction Method

julia

_sunflower_fraction(k, n)

The fraction of the area of a disc (or of the solid angle of a cap) within the radius (or the polar angle) of the k-th of n sunflower samples (k = 0 … n-1). Sample k represents the cell between the fractions k/n and (k + 1)/n. The first cell is the disc (or cap) around the center and is sampled at its center, i.e. at 0, the others at the middle (k + ½)/n of their cell.

source

BeamletOptics._tick! Method

julia

_tick!(p::_LazyProgress)

Count one finished item and report it to the output of p, see _report!. Safe to call from any thread. Throws _ProgressCancelled if p reports to a cancelled ProgressSink.

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._transverse_field Method

julia

_transverse_field(E1, E2, e1, e2, n, d)

3D field vector with the tangential components E1, E2 along e1, e2 of a plane with normal n, completed by the normal component that makes it transverse to the propagation direction d (E·d = 0). Keeps the given tangential field of an oblique beam instead of projecting it, which would scale it by cos²θ.

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.

If p reports to a ProgressSink, p is the sink's current loop while f runs; the previous loop is restored afterwards, also if f throws, so nested loops show the inner loop while it runs.

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.

R is the rotation about the axis normal to both vectors (the smallest rotation). It is exact and orthonormal for all angles, including angles of a few nrad (alignment of optics) and angles close to π. For antiparallel vectors, R is a rotation by π about an axis normal to start.

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_edge Method

julia

aspheric_edge(c, k, α_coeffs, d)

Returns the sag of the asphere at its edge r = d/2 and the norm of the gradient of its 2D distance field there, as a Point2. Both are constant for a surface, hence the SDFs store them instead of evaluating the asphere at the edge for every distance.

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.beamlet_hit_field Method

julia

beamlet_hit_field(hit::AbstractBeamletHit, p::AbstractArray)

Complex scalar field of a single beamlet hit at the global point p [m]. For an AstigmaticGaussianBeamletHit it is the field along the polarization of the hit, see beamlet_hit_polarization for the 3D field vector; for a GaussianBeamletHit it is the field of the scalar model, whose amplitude is √n too large in a medium of index n. The fields that the readouts of a Detector add are those of electric_field(::BeamletOptics.AbstractDetectorHit, ::AbstractVector). It is kept as its own function so that other code that needs the individual hit contributions at a point, e.g. the BeamletOpticsOpticsBaseExt package extension, does not have to duplicate the beamlet field formulas.

source

BeamletOptics.beamlet_hit_polarization Method

julia

beamlet_hit_polarization(hit::AstigmaticGaussianBeamletHit)

Complex 3D vector (global frame) that turns the scalar beamlet_hit_field(hit, p) of an astigmatic beamlet hit into its 3D field vector at p: the polarization of the hit segment's chief ray divided by the complex amplitude E_ref_amp that the scalar field already contains, i.e. a unit vector with the phase of its largest component removed. It is the zero vector if the segment carries no light, e.g. behind a crossed polarizer.

Stigmatic GaussianBeamletHits have no method: the underlying GaussianBeamlet model is scalar and carries no polarization in BMO, so there is no principled 3D direction to return. Callers that need a vector for such a hit (e.g. to build a tangential field on some plane) must supply their own convention, such as the local u axis of that plane (this matches OpticsBase's rule for a purely scalar field: it is placed entirely along u).

source

BeamletOptics.bounding_box Method

julia

bounding_box(sphere::AbstractBoundingSphere)

Returns the limits (xmin, xmax, ymin, ymax, zmin, zmax) of the axis-aligned box around the sphere.

source

BeamletOptics.bounding_box Method

julia

bounding_box(s::AbstractSDF)

Returns the limits (xmin, xmax, ymin, ymax, zmin, zmax) of an axis-aligned box around s in world coordinates, e.g. for the sampling grid of the rendering. The SDF is probed from ±1000 m along the axes, which gives the extent of the shape if the SDF is exact outside of it. A type whose SDF is not exact far away returns the box around its bounding_sphere_of instead.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(shape::AbstractShape)
bounding_sphere_of(object::AbstractObject)
bounding_sphere_of(group::AbstractObjectGroup)

Computes a sphere that encloses the shape, object or group in its current pose and returns it as a SingleBoundingSphere or MultiBoundingSphere, or returns NoBoundingSphere() if there is none.

For a shape, the method is an optional part of the AbstractShape interface. With the default NoBoundingSphere() every ray is tested via intersect3d. With a sphere, a solve tests a ray against the sphere first and skips the shape if it misses, which pays off for shapes with a costly intersect3d. The sphere is computed once per solve_system! and not stored in the shape, hence the method may take some time, e.g. look at all vertices of a mesh.

The sphere must enclose every point of the shape, for all its parameters: a hit outside of the sphere is lost without a warning. It should also be tight, since a ray that hits the sphere is tested as before. A safety margin is not needed, the solver adds its own tolerance. Use render_bounding_sphere! to look at the result.

julia

# a cylinder of the radius `r` and the height `h`, with the origin at the center of its base
function BeamletOptics.bounding_sphere_of(c::MyCylinder)
    return BeamletOptics.SingleBoundingSphere(c, Point3(0, c.h / 2, 0), sqrt(c.r^2 + (c.h / 2)^2))
end

For an object, the result follows from its shapes, see AbstractShapeTrait: the sphere of the shape of a SingleShape object, and for a MultiShape object or an object group the MultiBoundingSphere that encloses the spheres of all its parts, or NoBoundingSphere() if one part has none.

A solve does not call this method per ray. It computes the spheres once into a table and looks them up via bounding_sphere_of(table, x).

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(d::DifferenceSDF)

Returns the bounding_sphere_of of d.base in its current pose: the result of a subtraction is always a subset of the base, so the bounding sphere of the base (or NoBoundingSphere(), if it has none) also bounds d.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(ml::MeniscusLensSDF)

Returns the sphere that encloses the bounding spheres of the convex and the cylindrical part, which are positioned in the local frame of the lens; the concave part only removes volume.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(u::UnionSDF)

Returns the sphere that encloses the bounding spheres of all operands in their current poses, or NoBoundingSphere() if one of the operands has none.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(table::BoundingSphereTable, x)
bounding_sphere_of(::Nothing, x)

Returns the bounding sphere that the table holds for the shape or object x, or NoBoundingSphere() if it holds none. Nothing is computed, in contrast to bounding_sphere_of(x), which fills the table, see bounding_spheres.

The intersection code calls this method per ray with the table of the solve that is running in the current task, current_bounding_spheres(). Outside of a solve this table is nothing and the result is always NoBoundingSphere(), i.e. intersect3d(object, ray) then tests the object without a sphere.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(s::AbstractAcylindricalSurfaceSDF)

Returns the sphere through the corners of the box around the surface volume: the cylinder height along x, the axial extent of the sag along y and the diameter along z.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(s::AbstractAsphericalSurfaceSDF)

Returns the sphere around the cylinder of the lens diameter that spans the axial extent of the surface volume, centered on the axis.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(mesh::AbstractMesh)

Returns the sphere around the center of the axis-aligned box of the vertices that passes through the farthest vertex. All vertices are read, i.e. the cost grows with the size of the mesh.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(box::BoxSDF)

Returns the sphere through the eight corners of the box, centered at the local origin.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(s::ConcaveCylinderSDF)

Returns the sphere through the eight corners of the box that the cylinder is cut out of, which extends from y = 0 to the sagitta, on the side given by the sign of the radius.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(css::ConcaveSphericalSurfaceSDF)

Returns the sphere through both rims of the surface, which lie at y = 0 and y = -sag, centered on the axis in between.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(s::ConicSDF)

Returns the sphere around the cylinder of the segment diameter that extends from the lowest point of the reflecting surface to the back side at y = thickness, centered on the local y-axis.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(s::ConvexCylinderSDF)

Returns the sphere through the four corners of the flat side, centered in that side. In the local frame the cylinder axis is the x-axis and the flat side is normal to the z-axis.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(css::ConvexSphericalSurfaceSDF)

Returns the smallest sphere around the spherical cap, which extends from its vertex at the local origin to its flat side at y = sag: the sphere through the rim, centered in the plane of the rim.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(cs::CutSphereSDF)

Returns the smallest sphere around the spherical cap y ≥ height: the sphere through the rim, centered in the cut plane, for a cap of at most a hemisphere (height ≥ 0), and the full sphere otherwise.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(cylinder::CylinderSDF)

Returns the sphere through both rims of the cylinder, centered at the local origin. Note that the height field stores half of the cylinder height.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(ps::PlanoSurfaceSDF)

Returns the sphere through both rims of the cylinder, centered on the axis at half of the thickness.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(prism::PolygonPrismSDF)

Returns the sphere around the prism over a circle that encloses the cross-section (the smaller one of the circles around the mean of the vertices and around the center of their bounding box), centered in the local plane z = 0. It passes through at least two corners of the prism.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(prism::RightAnglePrismSDF)

Returns the sphere through the four corners of the hypotenuse face, centered at the local origin, which is the center of that face.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(ring::RingSDF)

Returns the sphere through both outer rims of the ring, centered at the local origin. Note that the inner_radius field stores the mean radius of the ring.

source

BeamletOptics.bounding_sphere_of Method

julia

bounding_sphere_of(sphere::SphereSDF)

Returns the sphere itself.

source

BeamletOptics.bounding_spheres Method

julia

bounding_spheres(system::AbstractSystem) -> BoundingSphereTable

Computes the bounding spheres of all objects of the system in their current poses, via bounding_sphere_of: of the shape of every SingleShape object, and of every MultiShape object and object group, which encloses the spheres of its parts. Shapes and objects without a sphere have no entry.

The spheres are stored as Float64, with the radius enlarged by the rounding error of the number type of the shape. A sphere of a number type that is no AbstractFloat is not stored, i.e. this shape is tested without a sphere.

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=3, 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. The box reaches crop_factor beam radii beyond each hit point, divided by the cos θ of the angle of incidence, which stretches the footprint of the beam on the detector.

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}

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

Attaches the child or the children to beam and links beam as their parent, e.g. the transmitted and the reflected beam at a beamsplitter. The children continue beam: its length, optical path and reference plane are counted on, see relaunch! for beams that start their own reference.

A beam is split once, at its end: a beam that already has children throws an ArgumentError.

source

BeamletOptics.convex_aspheric_surface_distance Method

julia

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

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.
max_sag : the extremal sag and its radius, see max_aspheric_value
edge : the sag and the gradient norm at the edge, see aspheric_edge

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.current_bounding_spheres Method

julia

current_bounding_spheres() -> Union{Nothing, BoundingSphereTable}

Returns the BoundingSphereTable of the solve that is running in the current task, or nothing outside of a solve. It is set by with_bounding_spheres, and the intersection code passes it to bounding_sphere_of(table, x).

The table lives in the task-local storage, since the intersection code reads it for every object and ray, and this read is several times cheaper than that of a ScopedValue. A task that is spawned within a solve therefore does not see the table of its parent.

source

BeamletOptics.default_properties Method

julia

default_properties(x) -> Vector{Pair{String, Any}}

Returns the properties that properties lists for any x, see its conventions:

"Type": the name of the type of x
depending on the BeamletOptics.AbstractKinematicTrait of x: "Position [m]" and "Optical axis" (local +y axis) for oriented objects, "Position [m]" and "Direction" for directed ones (beams), only "Position [m]" for static objects
for an AbstractObject, depending on its BeamletOptics.AbstractShapeTrait: the properties of its shape ("Shape" and the stored dimensions, e.g. "Diameter [m]") or the number of its "Parts"
for an object group: the number of its objects as "Parts"

Methods of properties for specific types start from this list, see properties.

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(hits::AbstractVector{<:AbstractDetectorHit}, p::AbstractVector)

Coherent sum of the fields of the detector hits at the global point p [m], see electric_field(::BeamletOptics.AbstractDetectorHit, ::AbstractVector).

source

BeamletOptics.electric_field Method

julia

electric_field(agb, r, z)

Convenience wrapper for parabasal_field.

source

BeamletOptics.electric_field Method

julia

electric_field(hit::AbstractDetectorHit, p::AbstractVector)

Electric field Eⱼ(p) of a single detector hit at the global point p [m], not projected onto the detector: a complex scalar for RayHits and GaussianBeamletHits, a complex 3D vector in global coordinates for PolarizedRayHits and AstigmaticGaussianBeamletHits. It is a phasor with the time dependence exp(-iωt), so that a plane wave in a medium of index n carries the intensity n|E|²/(2Z₀). With the vacuum wavenumber k₀ = 2π/λ, the direction s of the hit, the refractive index n in front of the detector and the optical path length L from the source to the hit point p_hit:

RayHit: a plane wave of amplitude 1,
PolarizedRayHit: the same plane wave times the field vector E₀ of the ray,
GaussianBeamletHit: the TEM₀₀ field of the traced segment, at the distance l along its chief ray and the distance r from it,
with the field E₀ and waist w₀ of the beamlet, the beam radius w, the radius of curvature R and the Gouy phase ψ of the segment (see gauss_parameters), the index n of the segment and the optical path L(l) along the chief ray.
AstigmaticGaussianBeamletHit: the field vector of the chief ray of the segment, E_pol, times the general astigmatic Gaussian beam of its parabasal rays, , with the Gouy factor g, which also holds the change of the amplitude with the beam area, and the complex transverse phase W, whose imaginary part is the Gaussian envelope, see Astigmatic polarized beamlets.

Beamlet hits give the physical field in [V/m]. Ray hits are raw and unscaled: |E|² does not carry the power of the ray, see the note on scaling in electric_field(pd; kwargs...).

A new hit type implements this method, direction(hit) and refractive_index(hit); the readouts of a Detector on a grid (electric_field, intensity, optical_power) then work for it.

source

BeamletOptics.electric_field Method

julia

electric_field(pd::Detector, xs::AbstractVector, zs::AbstractVector; progress = true)

Samples the electric field of the hits of the Detector pd on the grid xs × zs of its local coordinates in [m]: E[i, j] is the field at (xs[i], zs[j]). The type of E and the meaning of its values are those of electric_field(pd; kwargs...), which picks the grid automatically.

source

BeamletOptics.electric_field Method

julia

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

Samples the electric field of the hits of the Detector pd on a regular n×n grid in its local (x, z) plane, in a window around the hits. The field at the local point (x, z) is the coherent sum of the fields Eⱼ of all hits j,

with the position p_d of the detector and its local axes x̂, ẑ, which form a left-handed system with the detector normal. Eⱼ is defined per hit type in electric_field(::BeamletOptics.AbstractDetectorHit, ::AbstractVector). The field is not projected onto the detector: it is the field that is there, for any angle of incidence. The power per detector area follows from intensity, which takes the angle of incidence of each hit into account. To sample on a grid of one's own, use electric_field(::Detector, ::AbstractVector, ::AbstractVector).

Coherent sum

All hits are summed as one monochromatic, mutually coherent field, also hits of different wavelengths or of sources that are mutually incoherent. For those, evaluate the intensity of each wavelength or source on its own and add the intensities.

Resetting detectors

Be sure to call empty!(pd) (or initialize!(system) for all detectors) 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 Scales the width of the sampling window returned by calc_local_lims; values >1 expand, <1 shrink. The default is 1 for ray hits (the box around the hit points) and 3 for beamlet hits (three beam radii around each hit, which holds the power of a Gaussian beam except for a part of 10⁻⁸).
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: a Ray has the amplitude 1, a PolarizedRay its field vector E0, which carries the Fresnel/Jones amplitude factors but not the ray-tube area or the pupil sampling density.

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 is the field at (xs[i], zs[j]): a Matrix{Complex{T}} for Rays and GaussianBeamlets, a Matrix{Point3{Complex{T}}} of 3D vectors in global coordinates for PolarizedRays and AstigmaticGaussianBeamlets, which carry a polarization.

Unpolarized light

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]), evaluate intensity(pd, xs, zs) on the same grid after each trace and add the results.

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. The phase contains the optical_path_length from the start of the beam (parents included) up to z: within a medium of refractive index n it advances with the wavenumber n k₀, along the beam and across it. The Gouy phase is collected along the beam as well, i.e. it is continuous at every surface and from a parent beam to its children, and equals the ψ of gauss_parameters.

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, collected continuously along the beam: it does not jump behind a focus or at a mirror, and a child beam continues its parent
w01, w02: waist radii along the principal axes

source

BeamletOptics.gauss_parameters Method

julia

gauss_parameters(segment::GaussianSegment, l)

Returns (w, R, ψ, w0) of the GaussianSegment at the distance l behind the start of its chief ray, as gauss_parameters(gauss, z) does, but with the Gouy phase ψ relative to the local waist of the segment.

source

BeamletOptics.gauss_parameters Method

julia

gauss_parameters(gauss::GaussianBeamlet, z, ψ0; hint)

As gauss_parameters(gauss, z), but the returned Gouy phase is the one relative to the waist of the local segment plus ψ0. With ψ0 = 0 it is the local Gouy phase, which jumps at every surface, e.g. at a lens; gauss_parameters(gauss, z) passes the Gouy phase that the beam has collected in front of the segment.

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), collected along the beam from the start of the root beam: continuous at every surface and from a parent beam to its children, i.e. the Gouy phase that electric_field contains. The same holds for an AstigmaticGaussianBeamlet.
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.hit_count Method

julia

hit_count(d::Detector) -> Int

The number of hits stored in the detector d, 0 before the first solve.

source

BeamletOptics.hit_point Method

julia

hit_point(ray::AbstractRay)

Returns the point where the ray ends, i.e. where it hits the surface of its Intersection.

source

BeamletOptics.initialize! Method

julia

initialize!(x)

Brings x into the state that a new solve starts from, by discarding the data that its objects have stored during previous calls of solve_system!. x can be a System or StaticSystem, an ObjectGroup (nested groups are included) or a single object. Currently this empties all Detectors. Objects that store no such data are left unchanged. Returns nothing.

solve_system! does not call this function unless its keyword initialize is set: a Detector accumulates the hits of several solves on purpose, such that several sources solved one after another superpose. Initialize before solving again after the setup was changed, e.g. in a parameter scan. The beams are not touched, solve_system! resets them itself.

A new object type that stores data during a solve implements initialize!(object). For an AbstractDetector it calls empty!(detector).

Examples

julia

for shift in shifts
    translate_to3d!(mirror, shift)
    initialize!(system)             # instead of empty!(pd) for every detector
    solve_system!(system, beam)
    P = optical_power(pd)
end

or in one call via solve_system!(system, beam; initialize = true).

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 |E|²/(2Z) in [W/m²] of a plane wave with the complex electric field phasor E in a medium of the wave impedance Z (default: vacuum, use Z₀/n in a medium of index n). It is not projected onto a surface; the irradiance on a Detector is intensity(pd).

source

BeamletOptics.intensity Function

Calculates the intensity |E|²/(2Z) in [W/m²] of a plane wave with the complex electric field vector E (e.g. a PolarizedRay field) in a medium of the wave impedance Z (default: vacuum). It is not projected onto a surface; the irradiance on a Detector is intensity(pd).

source

BeamletOptics.intensity Method

julia

intensity(hits::AbstractVector{<:AbstractDetectorHit}, p::AbstractVector, n̂::AbstractVector)

Irradiance [W/m²] of the coherent sum of the detector hits at the global point p through a plane with the unit normal n̂, see intensity(pd; kwargs...).

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.intensity Method

julia

intensity(pd::Detector, xs::AbstractVector, zs::AbstractVector; progress = true)

Samples the irradiance on the Detector pd in [W/m²] on the grid xs × zs of its local coordinates in [m]: I[i, j] is the irradiance at (xs[i], zs[j]), see intensity(pd; kwargs...).

source

BeamletOptics.intensity Method

julia

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

Samples the irradiance on the Detector pd, the power per detector area in [W/m²], on the grid of electric_field(pd; kwargs...), with the same keyword arguments. Returns a tuple (xs, zs, I). To sample on a grid of one's own, use intensity(::Detector, ::AbstractVector, ::AbstractVector).

I is the flux of the coherent sum of all hits through the detector: the time-averaged Poynting vector along the detector normal n̂, which points along the incoming beams. Hits with a polarization (PolarizedRays, AstigmaticGaussianBeamlets) give

with the field Eⱼ of hit j (see electric_field(hit, p)), its direction sⱼ, the refractive index nⱼ in front of the detector, the vacuum impedance Z₀ and σⱼ = sign(sⱼ ⋅ n̂), i.e. a hit on the back side of the detector counts like one on its front side. Hits without a polarization (Rays, GaussianBeamlets) have no vector H and give the scalar form of the same flux,

A single hit under the angle θ to the normal gives I = n|E|² cos θ / (2Z₀), the power of the beam per detector area, so that optical_power is the power of the beam for any angle of incidence. No projection factor is applied to the field. For two scalar hits, the cross term is Re(E₁* E₂) (n₁ cos θ₁ + n₂ cos θ₂) / (2Z₀), i.e. hits under different angles interfere with the mean of their n cos θ.

I is in [W/m²] for beamlet hits. For ray hits, whose fields are unscaled, it has the same form but no absolute unit.

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.

A MultiShape object receives this call for whichever of its parts was hit. Its method finds that part, e.g. via shape(intersection(ray)), and hands the beam to it, see CubeBeamsplitter. Parts that do not interact as one belong in an ObjectGroup or another AbstractObjectGroup instead, where each part interacts on its own.

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(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 Function

julia

intersect3d(object::AbstractSDF, ray::AbstractRay, t_max = SDF_MISS_DISTANCE)

Intersection algorithm for sdf based shapes. A ray that starts outside of the object is a miss once it has travelled the path length t_max in [m] without a hit. A ray that starts inside, or on the surface pointing inside, hits the surface where it leaves the object first, see _raymarch_inside.

source

BeamletOptics.intersect3d Method

julia

intersect3d(sphere::AbstractBoundingSphere, object::AbstractSDF, ray::AbstractRay)

Tests the ray against the bounding sphere of the object, see intersect3d(sphere, shape, ray). If the ray passes through the sphere, it is marched as in intersect3d(object, ray), but is a miss as soon as it has left the sphere, since the object lies within. A ray that leaves the object is thus a miss after a few steps.

The radius is enlarged by the surface threshold of the marching algorithm (Config.get_sdf_surface_threshold()), below which a ray counts as starting on the surface.

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(group::AbstractObjectGroup, ray::AbstractRay)

Returns the closest intersection of the ray with the objects of the group. In contrast to a MultiShape object, the intersection keeps the object of the group that was hit, since this object, not the group, interacts with the ray. No object is tested if the ray misses the bounding sphere of the group, which the table of a running solve holds, see bounding_sphere_of(table, x).

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(sphere::AbstractBoundingSphere, x::Union{AbstractShape, Tuple, AbstractVector, Leaves}, ray::AbstractRay)

Returns the intersection between x and the ray like intersect3d(x, ray), but tests the ray against the bounding sphere of x first. x is a shape, or the parts of a MultiShape object or of an object group, see intersect3d(parts, ray):

NoBoundingSphere: x is tested via intersect3d(x, ray)
the ray misses the SingleBoundingSphere or MultiBoundingSphere, or the sphere lies behind it: returns nothing without a test of x, i.e. of any of the parts
otherwise x is tested via intersect3d(x, ray)

The intersection code of the objects calls this method with the sphere that the table of the running solve holds for the shape, object or group, e.g. bounding_sphere_of(current_bounding_spheres(), shape). A shape type implements intersect3d(shape, ray) and, optionally, bounding_sphere_of(shape), not this method.

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(parts, ray::AbstractRay)

Returns the closest Intersection of the ray with the parts, or nothing if it hits none of them. The parts are a tuple, a vector or the Leaves of shapes or objects, e.g. the shapes of a MultiShape object, the objects of a group or the objects of a system. Each part is tested via its own intersect3d method, hence parts that consist of parts, e.g. the groups of a system, are tested as a whole. No parts give nothing.

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.is_cancelled Method

julia

is_cancelled(e)

true if the exception e stems from a cancelled ProgressSink, also if it is wrapped in a TaskFailedException or a CompositeException (as thrown by Threads.@threads).

source

BeamletOptics.is_static Method

julia

is_static(x)

Returns true if the kinematic_trait_of x is Static.

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.live_render! Method

julia

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

Renders thing into the axis like render!, but returns an AbstractRenderHandle that can be updated in place via update_render!. Intended for animations and interactive applications, e.g. moving components that require the system to be solved repeatedly.

objects and systems: the geometry is generated once, kinematic changes are applied as a model transformation of the existing plots
rays, beams and beam groups: all segments are bundled into a single plot
GaussianBeamlet: the envelope of all segments is bundled into a single mesh

Keyword arguments are passed on as for render!.

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

source

BeamletOptics.live_render! Method

julia

live_render!(h::AbstractSystemRenderHandle, obj; kwargs...) -> Vector{<:AbstractObjectRenderHandle}

Live-renders obj, an object or object group, into the axis of the system handle h and adds it to h, e.g. an object that was added to the system via push!(system, obj) after h was created. An object group is rendered per object, with its hierarchy known to render_parent, like the groups of live_render!(ax, system). Returns the new object handles, one per rendered object. The system of h is not changed. An obj that h already renders throws an ArgumentError.

Keyword arguments are passed on as for render!. Implemented by the handle returned by live_render!(ax, system). A system handle that does not implement it throws an ArgumentError: render obj via live_render!(ax, obj) and add its handle via push!(h, oh) instead.

source

BeamletOptics.live_render! Method

julia

live_render!(draw, axis, x) -> AbstractObjectRenderHandle

Live-renders x via the function draw: draw() plots x in its current pose into the axis, and the returned handle moves these plots with x like those of an object, see live_render!, e.g. a marker of a thing that render! does not draw. x has a position and an orientation (or a direction), e.g. a source or an own movable type (see kinematic_trait_of):

julia

h = live_render!(ax, src) do
    scatter!(ax, [Point3f(position(src))]; color = :orange)
end

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

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.look_colors Function

julia

look_colors() -> Dict{Symbol, RGBf}

The colors of the material classes (:refractive, :reflective, :coating, :polarizer, :detector, :mechanics, :interface) of the active look, see set_render_look, e.g. to recolor the rendered objects of a class for a dark background.

Needs the Makie extension, i.e. a loaded Makie backend.

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.min_num_rays Method

julia

min_num_rays(src) -> Union{Nothing, Int}

The fewest rays with which set_num_rays! regenerates the source src: 20 num_rings for ring sources, 1 for sunflower, line and fan sources, and nothing if the rays of src can not be regenerated, e.g. a source built from given beams or any other beam or beam group. Also defined for the BeamletOptics.AbstractSampling of a source.

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::AbstractObjectGroup)

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. An empty system exposes no objects.

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 at its start. 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] as the integral of its intensity over the sampling window in the local detector coordinates,

evaluated with the trapezoidal rule on the n×n grid of electric_field(pd; kwargs...), with the same keyword arguments. Since I is the flux through the detector, P is the power of the beams for any angle of incidence.

The integral runs over the sampling window, not over the active area of the detector: the window is not cut at the edges of the detector. The default window of beamlet hits holds the power of each beamlet except for a part of 10⁻⁸, see crop_factor. For ray hits, P has no absolute unit, see intensity.

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)

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

The amplitude is that of the polarization of the chief ray of the segment at z, which holds everything that changed the field at the surfaces on the way (Fresnel coefficients, polarizers, beamsplitters), times the change with the beam area within the segments since the start of the root beam. A child beamlet continues its parent, in amplitude and in Gouy phase.

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: complex field amplitude of the segment (if nothing: the norm of the polarization of its chief ray with the phase of its largest component)

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 and area_ref its value at the start of the segment, continued over all segments in front of it.

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.path_segments Method

julia

path_segments(beam::AbstractBeam; flen = 1.0) -> Vector{PathSegment}
path_segments(group::AbstractBeamGroup; flen = 1.0) -> Vector{PathSegment}

Flattens the traced beam and all of its child beams (e.g. after beam splitting) into a vector of straight segments, one per ray, in depth-first order. For a GaussianBeamlet or an AstigmaticGaussianBeamlet the segments are those of the chief ray. For a beam group the segments of all its beams are concatenated, the beam_index field gives the index of the beam.

Each segment is a BeamletOptics.PathSegment NamedTuple with the start and end point, the accumulated geometric path length s_start, s_stop and optical path length opl_start, opl_stop (refractive index of the medium of the ray times its length), the wavelength λ, the depth in the beam tree, the parent segment index, from which the branches can be rebuilt, and the object hit at the end of the segment. The last segment of a branch is flagged by leaf = true. A child beam continues from the end of its parent beam, i.e. its first segment starts at the path length at which its parent ends. A beam attached with relaunch! (e.g. the output of a fiber) instead starts its own path: its first segment has s_start = 0 and opl_start = 0, like length and optical_path_length of that beam, while its parent still names the segment it was launched from and its depth counts the levels of the beam tree. A final ray without an intersection has no length of its own: it is flen [m] long and flagged by final = true.

Note

The beam must have been traced with solve_system!; an untraced beam consists of a single final segment. The path lengths are those of the ray tracer: length and BeamletOptics.optical_path_length of the beam equal s_stop and opl_stop of the last non-final segments of its branch.

Examples

julia

beam = Beam([0, 0, 0], [0, 1, 0])
solve_system!(system, beam)
segs = path_segments(beam; flen = 0.1)
# position of the beam at the geometric path length s along the first branch
s = 0.25
seg = first(filter(sg -> sg.s_start <= s < sg.s_stop, segs))
point = seg.start + (s - seg.s_start) * (seg.stop - seg.start) / (seg.s_stop - seg.s_start)

source

BeamletOptics.pick_object Method

julia

pick_object(handle, plot)

Returns the object of a live-rendered object or system handle that is visualized by the plot (one of its pickable_plots, or a child plot of one), or nothing if the plot does not belong to the handle. For a system handle, the top-level object, i.e. the outermost group of the picked object, see render_parent.

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

source

BeamletOptics.pickable_plots Method

julia

pickable_plots(x, plots) -> AbstractVector

The plots among the plots of x that select x in pick_object, by default all. Add a method for the type of x to exclude plots, e.g. the outline of a marker, whose clicks should reach what lies behind it.

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.progress_state Method

julia

progress_state(s::ProgressSink)

State of the loop that currently reports to s: nothing between loops, otherwise (; desc, count, n, t0) with desc the description without its trailing ": " (e.g. "Tracing beams"), count finished of n items and t0 the time() at which the loop started. Safe to call from any task while the loop runs.

source

BeamletOptics.projection_factor Method

julia

projection_factor(ray::AbstractRay)

Returns |d · n| of the direction d of the ray and the normal n of the surface it ends on; 1 if the ray ends without an intersection.

source

BeamletOptics.properties Method

julia

properties(x) -> Vector{Pair{String, Any}}

Returns the properties of x (an AbstractObject, shape, beam or source) as a list of name => value pairs for display, e.g. in the inspector of the GUI package BeamletOpticsGUI. Only stored or cheaply derived values are listed, e.g. the reflectance of a beamsplitter (the power ratio R, as passed to its constructor) or the number of hits of a Detector, no design parameters that the object does not store. The list is computed on each call, i.e. it shows the current pose and hits.

Conventions

values are numbers in SI units, vectors of them (e.g. a position), Strings or Bools
the unit of a value is given in brackets at the end of its name, e.g. "Diameter [m]" or "Angle [rad]"; names without brackets are dimensionless, e.g. "Reflectance"
the list starts with default_properties: "Type", the pose and, for objects, the shape

julia

julia> properties(SphericalLens(50e-3, -50e-3, 5e-3, 25.4e-3))
8-element Vector{Pair{String, Any}}:
          "Type" => "Lens"
  "Position [m]" => [0.0, 0.0, 0.0]
  "Optical axis" => [0.0, 1.0, 0.0]
         "Shape" => "UnionSDF"
 "Thickness [m]" => 0.005
   "Index model" => "function of λ"
         "n(λ₀)" => 1.5
        "λ₀ [m]" => 1.0e-6

The refractive index is evaluated at λ₀ = get_default_wavelength(). The radii and the diameter of a lens are not listed, since its shape does not store them.

Custom components

Add a method for your type that extends the default list, e.g.

julia

BeamletOptics.properties(x::MyFilter) =
    [BeamletOptics.default_properties(x); "Optical density" => x.od; "Center wavelength [m]" => x.λc]

Without a method, default_properties is shown.

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.relaunch! Method

julia

relaunch!(beam::B, new_beams::AbstractVector{B}) where {B <: AbstractBeam}

Attaches new_beams as children of beam that start their own optical reference: they are traced and removed together with beam, but their length, optical path and phase are counted from their own start instead of being continued from beam. The new beams carry the full phase in their amplitude.

Use it in the interact3d of a component that re-emits light elsewhere, e.g. the output end of a fiber or a solver coupled through a field: the light leaves at another place than where beam ended, so the geometric continuation of children! (parent length, reference plane of a beamlet) does not apply.

The new_beams replace any children that beam already has. A beam that the component keeps and attaches again is solved from its first ray, like every beam.

source

BeamletOptics.remove_render! Method

julia

remove_render!(handle)

Deletes all plots of the handle from its axis.

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

source

BeamletOptics.remove_render! Method

julia

remove_render!(h::AbstractSystemRenderHandle, obj)

Removes obj, an object or object group, from the system handle h: deletes the plots of obj (of all objects of an object group) from the axis and removes their object handles from h, e.g. after delete!(system, obj). The system of h is not changed. Nothing happens for an obj that h does not render. An object within a group can not be removed on its own and throws an ArgumentError: remove the group instead.

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_bounding_sphere! Method

julia

render_bounding_sphere!(ax, sphere; color = :magenta, linewidth = 1, kwargs...)
render_bounding_sphere!(ax, shape; color = :magenta, linewidth = 1, kwargs...)
render_bounding_sphere!(ax, object; color = :magenta, main_color = :orange, linewidth = 1, kwargs...)
render_bounding_sphere!(ax, system; color = :magenta, main_color = :orange, linewidth = 1, kwargs...)

Draws the bounding sphere of an AbstractShape into ax (an LScene or Axis3), if a suitable backend is loaded: the sphere of BeamletOptics.bounding_sphere_of in world coordinates, for the current position and orientation of the shape, as a wireframe of three great circles (parallel to the xy-, yz- and zx-plane of the world frame) in one lines plot. The solver skips a shape for every ray that misses this sphere, hence the function shows what the solver tests, e.g. to check the bounding_sphere_of method of an own shape type: the sphere must enclose the whole shape and should be tight.

sphere: a SingleBoundingSphere or MultiBoundingSphere is drawn as it is, a NoBoundingSphere gives no plot
shape: one plot, or none if the shape has no bounding sphere
object: the sphere of its shape, or, if it consists of several parts (e.g. a doublet lens, a cube beamsplitter), the sphere of each part, since the solver tests each part on its own, and the main sphere around all parts in main_color. The solver tests a ray against the main sphere first. An object without a main sphere, because a part has none, gets none. An object without a sphere, e.g. a NonInteractableObject, gets no plot.
object group (ObjectGroup): like an object of several parts, the spheres of its objects and then the main sphere of the group
system: the spheres of all its objects

Keyword args

color = :magenta: color of the lines
main_color = :orange: color of the main spheres of objects with several parts and of groups, also those nested in a group. Not passed to the plot.
linewidth = 1: line width in screen units

All other kwargs are passed on to the lines plot of Makie. Returns nothing. The spheres are drawn once and do not follow an object that is moved afterwards. For spheres that follow, use the show_bounding_sphere option of render! for objects with live_render!.

julia

render!(ax, system)
render_bounding_sphere!(ax, system)

# or in one call
render!(ax, system; show_bounding_sphere = true)

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

source

BeamletOptics.render_children Function

julia

render_children(h::AbstractSystemRenderHandle) -> AbstractVector{<:AbstractObjectRenderHandle}

The object handles of the system handle h, one per rendered object (the objects of groups, not the groups). Change them via push! and delete! of h, not via the returned vector.

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 object group (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.render_parent Function

julia

render_parent(h::AbstractSystemRenderHandle, obj)

The object group of the system of h that holds obj (an object or a group), or nothing if obj is at the top level or not in h.

source

BeamletOptics.render_plots Function

julia

render_plots(h::AbstractRenderHandle) -> AbstractVector

The plots of the render handle h; of a system handle, the plots of all its object handles. The plots of an object handle may be replaced by update_render!, hence do not keep them.

source

BeamletOptics.render_settings Function

julia

render_settings(h::AbstractBeamRenderHandle) -> NamedTuple

The settings with which the beam handle h draws its beam, at least flen (length of a final ray without intersection [m]) and render_every (every how many beams of a beam group are drawn, 1 for other beams), e.g. to find the drawn segments of a beam, and color (the color of the rays or of the envelope as it was given, e.g. :blue or :wavelength). The handles of Gaussian beamlets and of beam groups of beamlets also report the resolution of the envelope, r_res and z_res. Change them via render_settings!.

source

BeamletOptics.render_settings! Method

julia

render_settings!(h::AbstractBeamRenderHandle; kwargs...) -> h

Changes the settings of the beam handle h and draws the beam again with them, without creating new plots: the plots of render_plots(h) stay in the axis, with their other attributes (visibility, opacity, line width, clip planes, ...) unchanged. The keywords are among the keys of render_settings(h):

flen: length of a final ray without intersection [m], positive and finite
render_every: every how many beams of a beam group are drawn, a positive integer (no effect on other beams)
r_res, z_res: radial and longitudinal resolution of an envelope mesh, integers of at least 2
color: the color of the rays or of the envelope, a single color that Makie knows (e.g. :red, (:red, 0.3)), or :wavelength or (:wavelength, alpha) for the color of the wavelength of each ray, see wavelength_color

Any other keyword, e.g. r_res for a ray, throws an ArgumentError, and then h is not changed. The beam is drawn as it is, i.e. nothing is solved, like update_render!. The overlays of the handle, e.g. show_beams or show_pos, follow the settings; the generating rays of show_beams and the polarization curve keep their colors.

The plots of a handle that draw the color hold one color per vertex, which the handle sets together with the positions. Change the color via render_settings!, not via the color attribute of the plots, which the next update overwrites. A color that is neither a single color nor the wavelength, e.g. a vector of colors, is passed on to Makie by live_render! and can not be changed here.

julia

h = live_render!(ax, beam; flen = 0.1)
render_settings!(h; flen = 0.5)             # the final ray is now 0.5 m long
render_settings!(h; color = :wavelength)    # each ray in the color of its wavelength
render_settings!(h; color = :orange)        # and all in one color again

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

source

BeamletOptics.rendered Function

julia

rendered(h::AbstractRenderHandle)

The object, system or beam that the render handle h shows, see AbstractRenderHandle.

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.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, detector::AbstractDetector, R::AbstractMatrix)

Empties the detector (see empty!) and rotates it by R about its position, see translate3d!(::Movable, ::AbstractDetector, offset).

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, group::AbstractObjectGroup, R::AbstractMatrix)

Rotates all objects of the group by R about the group center and updates the group orientation to R * orientation(group).

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.sampling_args Method

julia

sampling_args(src)

The arguments of source_beams between b1 and λ for the source src: the diameter of a CollimatedSource, none for a PointSource.

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.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.sdf_convex_polygon Method

julia

sdf_convex_polygon(q, vertices, normals)

Exact signed distance of the 2D point q to the convex polygon with the counter-clockwise vertices and the outward unit normals of its edges, see PolygonPrismSDF.

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_num_rays! Method

julia

set_num_rays!(group, n)

Regenerates the rays of the source group with n rays: a CollimatedSource or PointSource, including UniformDiscSource, UniformPointSource, UniformLineSource and UniformFanSource. The rays are sampled as by the constructor of the source (concentric rings with the same num_rings, the sunflower pattern, or the line or fan), in the current pose of the source and at its wavelength, i.e. the source equals a new one with num_rays = n at its position and orientation. The rays start at the emission point of the current rays, also if set_pivot3d! moved the pivot of the source away from it. The previous beams, including their traced rays, are replaced: solve the system again afterwards.

n must be at least BeamletOptics.min_num_rays of the source, i.e. 20 num_rings for ring sources and 1 for sunflower, line and fan sources, otherwise an ErrorException is thrown, like by the constructors, and the source keeps its rays. A source built from given beams, e.g. CollimatedSource(beams, diameter, pos, dir), can not be regenerated and throws an ArgumentError.

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::AbstractObjectGroup, 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_render_look Method

julia

set_render_look(look::Symbol)

Sets the look of all subsequently rendered objects, :modern (default) or :cad. The :modern look renders clear glass with faint silhouettes, metallic mirrors and neutral mechanics without edge lines, the :cad look saturated materials with feature edge lines. Explicit kwargs of render!, e.g. color, material or edges, override the look.

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

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. 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, initialize=false, 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. Every beam of the group is reset with empty! and solved from its start. The reset happens before the first beam is traced, such that a cancelled or failed solve leaves no beam with an old path.

The hits of all beams accumulate on the same Detectors, and so do the hits of earlier solves unless initialize = true.

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.
initialize = false: if true, initialize!(system) is called once, before the first beam is traced. The beams themselves are solved without initializing, otherwise each beam would discard the hits of the others.

source

BeamletOptics.solve_system! Method

julia

solve_system!(system::AbstractSystem, beam::AbstractBeam; initialize=false, r_max=get_default_r_max(), depth_max=get_default_depth_max(), check_invariant=true, threshold=get_invariant_threshold())

Trace an AbstractBeam and all sub-beams it generates through an optical system. Every call solves the beam from its start: the beam is first reset to its untraced state with empty!, so nothing of an earlier solve is reused. A call after objects were moved, added or removed therefore gives the same result as solving a newly constructed beam. 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.

Between two calls only the beam itself and its first ray keep their identity. The child beams and all later rays are new objects after every call: read children(beam) again instead of keeping a child. The objects of the system are not reset by default: a Detector keeps the hits of earlier solves, such that several sources solved one after another superpose on it. With initialize = true the system is initialized first (see initialize!), i.e. all its detectors are emptied. Otherwise the hits of both solves add up.

Arguments

system::AbstractSystem: The optical system in which the beam will be traced.
beam::AbstractBeam: The beam object to be traced through the system.

Keyword Arguments

initialize = false: if true, initialize!(system) is called before the beam is traced
r_max = get_default_r_max(): Maximum number of tracing iterations for each leaf.
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.source_beams Function

julia

source_beams(sampling::AbstractSampling, pos, dir, b1, args..., λ, num_rays, T) -> Vector{<:Beam}

The beams of a source at pos [m] along the unit vector dir, sampled by sampling with num_rays rays of the wavelength λ [m] and the number type T. b1 is the unit sampling reference vector normal to dir, see BeamletOptics.sampling_basis; it sets the azimuth of the pattern about dir. args depend on the source: the diameter [m] of a CollimatedSource, none for a PointSource. The first beam is the center ray, which starts at pos along dir.

Throws an ErrorException if num_rays is below BeamletOptics.min_num_rays of the sampling, and an ArgumentError for BeamletOptics.NoSampling. Used by the constructors of the sources and by set_num_rays!.

source

BeamletOptics.source_beams Method

julia

source_beams(sampling::Union{ConeRings, ConeSunflower, ConeFan}, pos, dir, b1, λ, num_rays, T)

Beams of a PointSource at pos [m] around the unit vector dir with the wavelength λ [m], sampled by sampling (which holds the half spread angle) with num_rays rays. b1 is the unit sampling reference vector normal to dir, see sampling_basis. For ConeFan, the rays lie in the plane spanned by dir and b1.

source

BeamletOptics.source_beams Method

julia

source_beams(sampling::Union{DiscRings, DiscSunflower, DiscLine}, pos, dir, b1, diameter, λ, num_rays, T)

Beams of a CollimatedSource whose disc with the diameter [m] is centered at pos [m] normal to the unit vector dir, with the wavelength λ [m], sampled by sampling with num_rays rays. b1 is the unit sampling reference vector normal to dir, see sampling_basis. For DiscLine, the rays lie on the diameter of the disc along b1.

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.studio_lighting! Method

julia

studio_lighting!(ax::Union{LScene, Axis3}; preset = :studio)

Sets up a CAD-like lighting rig in the 3D view ax, if a suitable backend is loaded: an ambient light, a key light from the upper right front, a fill light from the left and a rim light from behind, all relative to the camera. Backends with a single directional light (e.g. CairoMakie) get the ambient and the key light only. preset = :none leaves the lights unchanged. The GUI of the package BeamletOpticsGUI applies the rig by default, scenes created via render! call it explicitly.

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

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, detector::AbstractDetector, offset)

Empties the detector (see empty!) and moves it by offset. Its hits lie on the surface where it was during the solve, hence they are discarded when it moves. All kinematic functions are derived from this one and rotate3d!(::Movable, ::AbstractDetector, R), so each of them empties the detector, also when it moves as a member of an ObjectGroup.

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, group::AbstractObjectGroup, offset)

Moves all objects of the group and its center by offset.

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.update_render! Method

julia

update_render!(handle)

Re-synchronizes the plots of the handle with the current state of the rendered object or beam, e.g. after moving components or calling solve_system!. Keep render handles on root beams and groups: child beams and all rays after the first are new objects after every solve.

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

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.wavelength Method

julia

wavelength(x)

The wavelength [m] of the ray x, of a Beam (its first ray), of a GaussianBeamlet, an AstigmaticGaussianBeamlet or of a beam group (its first beam).

source

BeamletOptics.wavelength_color Method

julia

wavelength_color(λ) -> NTuple{3, Float64}

The display color (r, g, b) (each in [0, 1], sRGB) of light of the vacuum wavelength λ [m], e.g. to draw rays in the color of their wavelength, see the color = :wavelength option of render!. Uses the piecewise linear approximation of Dan Bruton (violet at 380 nm over blue, cyan, green, yellow and orange to red at 780 nm) with a gamma of 0.8, and the intensity falls off to 30 % towards both ends of the visible range (380 to 420 nm and 700 to 780 nm).

Outside of 380 to 780 nm there is no visible color: the color of the nearest end of the spectrum is returned, i.e. a dim violet for UV and a dim red for IR, such that rays of an invisible wavelength are still drawn, and the color stays continuous. The result is a perceptual approximation for plots, not a colorimetric conversion.

The function is plain Julia and needs no plotting backend. Throws an ArgumentError unless λ is positive and finite.

julia

wavelength_color(450e-9)   # blue
wavelength_color(650e-9)   # red

source

BeamletOptics.with_bounding_spheres Method

julia

with_bounding_spheres(f, system::AbstractSystem)
with_bounding_spheres(f, table::BoundingSphereTable)

Calls f() with the bounding_spheres of the system, or with the given table, as the table of the current task, such that the intersection code finds them, see current_bounding_spheres. If a table is already set when a system is given, e.g. by the solve of the beam group that a beam belongs to, it is kept and nothing is computed.

The table belongs to the current task only. Code that spawns tasks within f, e.g. via Threads.@threads, passes the table on by calling with_bounding_spheres(g, table) in each task, as the solve of a beam group does.

The system must not be changed while f runs: the spheres are those of the poses at the call.

source

BeamletOptics.with_hit_buffers Method

julia

with_hit_buffers(f)

Calls f() such that the hits that the current task pushes to a Detector are collected in a buffer of the task, and appends them to their detectors when f returns or throws, one append! per detector. The solve of a beam group calls it in each of its tasks, which then do not wait for the lock of a detector at every hit. The hits are stored when with_hit_buffers returns, not while f runs.

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 preference sdf_inside_step, the former fixed step size [m] of the ray marching inside an SDF volume. It is no longer used: a ray inside an SDF is marched by the distance that the SDF returns, see BeamletOptics._raymarch_inside.

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