Reference

bigtrace(xr, yr, zr, Dxr, Dyr, Dzr, nsr)

Composite type holding position, direction, and accumulated optical path for parsing. Each is Type Matrix{Vector{T}} where T<:Real, vector holding information along propagation and the matrix mapping to the chosen input bundle subscripting.

bundle(x, y, angx, angy, zpos)

Composite type representing the origination of a bundle of rays. Input zpos is type T<:Real and is z-plane start position for the rays. Other four arguments are typed in one of the following two patterns:

1. x and y are Type AbstractArray{T,1} where T<:Real, angx and angy are Type T where T<:Real
2. x and y are Type T where T<:Real, angx and angy are Type AbstractArray{T,1} where T<:Real}

When a variable is declared this type with specific parameters and called as a function with no arguments, it returns a tuple (position, direction) each entry of which is an output array of vectors corresponding to the input information.

Examples

julia> eval_bundle = bundle([0., 1.], [0.,1.], 0., 0., 0.)
bundle([0.0, 1.0], [0.0, 1.0], 0.0, 0.0, 0.0)

julia> eval_bundle()
([[0.0, 0.0, 0.0] [0.0, 1.0, 0.0]; [1.0, 0.0, 0.0] [1.0, 1.0, 0.0]], [[0.0, 0.0, 1.0] [0.0, 0.0, 1.0]; [0.0, 0.0, 1.0] [0.0, 0.0, 1.0]])

bundle_as_array(x, y, angx, angy, zpos)

Composite type representing the origination of a set of rays. First four arguments are Type AbstractMatrix{T} where T<:Real; last argument is a scalar for the z position.

When a variable is declared this type with specific parameters and called as a function with no arguments, it returns a tuple (position, direction) each entry of which is an output array of vectors corresponding to the input information.

NOTE if types of entries in inputs are known to all be the same, use bundle_as_array_fast with same syntax for increased speed.

Examples

julia> eval_bundle = bundle_as_array([0.5 1.], [0.5 1.], [0. 0.], [0. 0.], 0.)
bundle_as_array{Float64}([0.5 1.0], [0.5 1.0], [0.0 0.0], [0.0 0.0], 0.0)

julia> eval_bundle()
([[0.5000000000000002, 0.5000000000000002, 2.220446049250313e-16] [1.0000000000000002, 1.0000000000000002, 2.220446049250313e-16]], [[0.0, 0.0, 1.0] [0.0, 0.0, 1.0]])

bundle_as_array_big(x, y, z, Dx, Dy, Dz)

Composite type representing the origination of a set of rays. All arguments are Type AbstractArray{T,2} where T<:Real.

NOTE if all input arrays are guaranteed to have the same type, then use bundle_as_array_big_fast with same syntax for increased speed.

opticalstack_instance = opticalstack( ... )

... = opticalstack_instance( ... )

For surface reflection and refraction use this method to define an instance of the opticalstack type

opticalstack(coeffslist, surfslist, nlist)

For gradient index (and surface reflection and refraction) use this method to define an instance of the opticalstack type

opticalstack(coeffslist, surfslist, nlist, ncoeffslist, grindt)

For grating/hologram/metasurface (and surface reflection and refraction) use this method to define an instance of the opticalstack type

opticalstack(coeffslist, surfslist, nlist, diffractiveslist, diffcoeffslist, diffmlist, wavelength)

To use all features together use this method to define an instance of the opticalstack type

opticalstack(coeffslist, surfslist, nlist, diffractiveslist, diffcoeffslist, diffmlist, wavelength, ncoeffslist, grindt)

Arguments to create an instance of opticalstack are

• coeffslist is a Vector set of coefficients for a corresponding surface; each set of coefficients is itself also a Vector.

• surfslist is a Vector of functions callable on (x, y, coeffs) to return a z-zurface position.

• nlist is a Vector of index values or index functions corresponding to the medium before the corresponding surface.

  • Vector values T<:Real work universally
  • Vector input of mixed type, Real and functions n where n(x, y, z, coeffs) = ..., only works for declarations of opticalstack which define ncoeffslist and grindt as well.

• ncoeffslist::Vector{Vector{T}} where T<:Real is a Vector set of coefficients for a corresponding gradient index; each set of coefficients is itself also a Vector.

• grindt::Real is the Sharma ray increment in the gradient index medium.

  • This step parameter scales the physical quantity $OP/n²$ (optical path length and index of refraction) at every step, and raytracing is by the algorithm of Sharma et al. 1982.

• diffractiveslist is a Vector of zeros and functions. Where a vector entry is not zero, the entry must be a valid phase function, e.g. $ϕ$ where $ϕ(x, y, z, coeffs) = ...$ sampled by the surface at a corresponding position to make the diffractive.

• diffcoeffslist::Vector{Vector{T}} where T<:Real is a Vector set of coefficients for a corresponding diffractive; each set of coefficients is itself also a Vector.

• diffmlist::Vector{Int} must have the integer corresponding to the diffraction order in the vector position corresponding to the position of the diffractive surface.

• wavelength::Real is the wavelength in system units simulated for the definition of the diffractive.

When an instance is declared, opticalstack_instance = opticalstack( ... ), the declared instance is called on a bundle instance bundlething and optional arguments as

opticalstack_instance(bundlething; rend = nothing, color = :red, issurfplot = true, numsurfpoints = 20, halfdomain = nothing, xdom = nothing, ydom = nothing, plobj = nothing, isbigtrace = false, plotplane_at = 0., init_prop_guesses=nothing)

• When rend is nothing and isbigtrace = false the output is a trace type.

• When rend is nothing and isbigtrace = true the output is a bigtrace type.

• When rend is not nothing, rend must be "YZ" or "XZ" or "3Dcirc" or "3Dsq". The output will be a plot object compatible with Plots.jl

• When rend is not nothing and issurfplot = false the surfaces being modeled will not be plotted.

• The domain plot can be scaled globally by entering a vector of desired plot extent into xdom or ydom. This is preferred over using numsurfpoints and halfdomain.

• plotplane_at is the value at which a 2D plot is sliced in the non-plotted dimension.

• init_prop_guesses::Vector{T} where T<:Real is an option to declare a first guess in numerical propagation preceding surface in the corresponding vector entry.

  • Defaults to zero.
  • Not recommended to use a nonzero value when traversing a gradient index function.

Note that the data scaling of the output of gradient index analysis is not only with the number of rays but also with the resolution of propagation. Assuming that propagation occurs over some position difference $Δz$, this data scaling is APPROXIMATELY $Δz$/dt. As expected, dt trades precision for computation time.

Note for gradient index surfaces the output ray coordinates are stacked according to propagation needed for the "longest" gradient index ray. Therefore a returned trace or bigtrace will not be easily indexed according to its surface, but all propagation positions will properly align when entering and exiting the gradient index. Shorter rays will replicate their terminated values until the longest ray terminates. Then all rays will exit the gradient index together at the appropriate surface.

Note for diffractive surfaces, the optical path contribution of the corresponding surface is that due to its preceding propagation PLUS that due to the diffraction phase function.

Note that the index of refraction must be equal on both sides of the diffractive. To work with cases where the diffractive sits on a substrate of different index of refraction, two surfaces should be collocated in sequence, one for reflection/refraction and one for diffraction.

Examples

julia> opticalstack_test = opticalstack([[1., 6.], [2., -6.], [4., 8.]], [spherical, spherical, zernike], [1., 1.5, 1.])
opticalstack{Float64}([[1.0, 6.0], [2.0, -6.0], [4.0, 8.0]], UnionAll[spherical, spherical, zernike], [1.0, 1.5, 1.0])

julia> bundle_test = bundle([0.5, 1.], [0.5, 1.], 0., 0., 0.)
bundle([0.5, 1.0], [0.5, 1.0], 0.0, 0.0, 0.0)

julia> tracething = opticalstack_test(bundle_test)
trace{Float64}([[0.5, 0.5, 0.4742890889441142, -0.024645519233983726] ... ; ...])

trace(xr, yr, zr, nsr)

Composite type holding position and accumulated optical path for parsing. Each is Type Matrix{Vector{T}} where T<:Real, vector holding information along propagation and the matrix mapping to the chosen input bundle subscripting.

aspherical(x, y, coeffs)

Composite type representing aspherical surface as a function of lateral coordinate x,y. Argument coeffs of type Vector{T} where T<:Real has entries coeffs = [zpos, R,κ, A4, A6, ...] where the surface is

$z(x,y) = zpos + r² / R / (1 + √(1 - (1 + κ)r² / R²)) + A₄r⁴ + A₆r⁶ + ...$ where $r² ≡ x² + y²$

Examples

julia> aspherical(0., 2., [1., -10., -4., 0.001])
1.0616649185805458

bigtrace_to_bundle(tracething::bigtrace, pos_prop::Int)

Takes a bigtrace object and integer position pos_prop and returns a bundle object.

rac(tracething::Union{trace, bigtrace}, pos_in, pos_out; pl_rac = nothing, color = :red, axistype = "y", pmajoraxis = 2)

Plots the chosen physical coordinate axistype=y or x at an end position pos_out of a particular trace or bigtrace object as a function of the same coordinate at input position pos_in. If pos===nothing, the last position in the trace is used. The coordinate plots are stitched together in lines based on the chosen matrix subscript in the trace or bigtrace. This matrix subscript is set by the optional argument pmajoraxis = 2 or 1. Can optionally pass in a handle to existing plot pl_rac, and change the plot color from default color=:red to any of the conventional options supported by Plots.jl.

NOTE that when tracing a ray fan (a bundle with one dimension of the array having length 1), the pmajoraxis must be set to the correct number to span the nonunitary length of the array. Else the plot may not appear to show anything.

rms_spot(tracething::Union{trace, bigtrace}; isunsqrt = false, pos = nothing, iszincluded = true)

Evaluates the rms spot size for a trace intersecting a surface.

Pass in the result of a trace, and calcuate the rms spot based on the ray values for the subscript pos. If pos===nothing then the final values of the trace are used (i.e. the final surface is taken to be the evaluation surface). Option isunsqrt removes the square root from the calculation (returns the sum of squared error instead). The z coordinate variation is included in the calculation when iszincluded == true.

Examples

julia> opticalstack_test = opticalstack([[1., 6.], [2., -6.], [4., 8.]], [spherical, spherical, zernike], [1., 1.5, 1.])
opticalstack{Float64}([[1.0, 6.0], [2.0, -6.0], [4.0, 8.0]], UnionAll[spherical, spherical, zernike], [1.0, 1.5, 1.0])

julia> bundle_test = bundle([0.5, 1.], [0.5, 1.], 0., 0., 0.)
bundle([0.5, 1.0], [0.5, 1.0], 0.0, 0.0, 0.0)

julia> tracething = opticalstack_test(bundle_test)
trace{Float64}([[0.5, 0.5, 0.4742890889441142, -0.024645519233983726] [0.5, 0.5, 0.47749522247588994, -0.04245690108918665]; [1.0, 1.0, 0.9549904449517799, -0.0849138021783733] [1.0, 1.0, 0.9616736859140215, -0.1253539680837904]], [[0.5, 0.5, 0.4742890889441142, -0.024645519233983726] [1.0, 1.0, 0.9549904449517799, -0.0849138021783733]; [0.5, 0.5, 0.47749522247588994, -0.04245690108918665] [1.0, 1.0, 0.9616736859140215, -0.1253539680837904]], [[0.0, 1.0418113625438212, 1.9623895629300963, 7.999999280260749] [0.0, 1.105086411777687, 1.904234300100513, 7.999999273328101]; [0.0, 1.105086411777687, 1.904234300100513, 7.999999273328101] [0.0, 1.169047547709123, 1.8438309411610754, 7.999999266127459]], [[0.0, 1.0418113625438212, 2.9446610481344417, 9.023361779810676] [0.0, 1.105086411777687, 2.8587256850369682, 9.064376469832027]; [0.0, 1.105086411777687, 2.8587256850369682, 9.064376469832027] [0.0, 1.169047547709123, 2.7690064459109145, 9.114214613215701]])

julia> rms_spot(tracething)
0.1125476814135891

spherical(x, y, coeffs)

Composite type representing spherical surface with apex at defined point. Argument coeffs of type Vector{T} where T<:Real has entries coeffs = [zpos, signed_radius]. Here zpos is the apex and signed_radius has magnitude equal to the radius of the sphere and sign which sets the direction of curvature of the sphere.

Examples

julia> spherical(0., 2., [1., -10.])
0.7979589711327115

splot(tracething::Union{trace, bigtrace}; pos=nothing, pl_splot = nothing, color = :red, markersize = 2)

Plots the spot of a particular trace or bigtrace object at position pos. If pos === nothing, the last position in the trace is used. Can optionally pass in a handle to existing plot pl_splot, and change the marker size from default markersize = 2 and the plot color from default color = :red to any of the conventional options supported by Plots.jl.

trace_extract_ray(tracething::Union{trace, bigtrace}, i::Int, j::Int; coord = "all")

Takes a trace or bigtrace object and integers i,j and returns the ray at position in the traced bundle array i,j.

Coordinates are x, y, z, direction cosines are Dx, Dy, Dz and accumulated optical path is ns.

Optional argument coord can be set "all" to return all information as Matrices. This will be passed out as

• x, y, z, ns for trace object
• x, y, z, Dx, Dy, Dz, ns for bigtrace object

Or optional argument can be set to a different string to only pass out one matrix of information.

• "x", "y", "z", "ns" for trace object
• "x", "y", "z", "Dx", "Dy", "Dz", "ns" for bigtrace object

trace_extract_terminus(tracething::Union{trace, bigtrace}, pos_prop::Int; coord="all")

Takes a trace or bigtrace object and integer position pos_prop and returns matrices of coordinates according to the bundle.

Coordinates are x,y,z, direction cosines are Dx,Dy,Dz and accumulated optical path is ns.

Optional argument coord can be set "all" to return all information as Type Matrix. This will be passed out as

• x, y, z, ns for trace object
• x, y, z, Dx, Dy, Dz, ns for bigtrace object

Or optional argument can be set to a different string to only pass out one Matrix of information.

• "x", "y", "z", "ns" for trace object
• "x", "y", "z", "Dx", "Dy", "Dz", "ns" for bigtrace object

zernike(x, y, coeffs)

Composite type representing OSA/ANSI type Zernike polynomial surface as a function of lateral coordinate x, y. Argument coeffs of type Vector{T} where T<:Real has entries coeffs = [rad, C0, C1, C2, ...]. The normalization radius is rad and the corresponding Zernike surface is given by the contributions of the Zⱼ with arguments over the cartesian coordinates normalized to the unit disk, i.e.:

$z(x, y) = ∑ⱼCⱼZⱼ(r, θ)$ where $r ≡ √( x² + y² ) / rad$ and $θ ≡ atan(y / x)$

NOTE this function evaluates to NaN outside of the normalization radius.

Examples

julia> zernike(0., 2., [2., 0., 1.])
2.0

zplane(x, y, coeffs)

Composite type representing a plane z(x, y) = zpos. Argument coeffs of type Vector{T} where T<:Real has entries coeffs = [zpos].

Examples

julia> zplane(0., 2., [3.])
3.0