Modes API

Gaussian1D(w0::Real; norm_constant=nothing)
Gaussian1D(w0::Real, λ::Real, z::Real; constant_phase=true, norm_constant=nothing)

Create a one-dimensional Gaussian mode.

The first form creates a Gaussian at the beam waist, while the second includes propagation effects at distance z from the waist.

Arguments

• w0::Real: Beam waist radius
• λ::Real: Wavelength (for propagated version)
• z::Real: Propagation distance from waist (for propagated version)
• constant_phase=true: Include exp(ikz) phase factor
• norm_constant=nothing: Custom normalization constant - defines the peak intensity (default uses proper Gaussian normalization)

Returns

Gaussian1D mode that can be evaluated at spatial positions.

Examples

julia> g = Gaussian1D(10.0);  # 10 μm waist at focus

julia> nx = 40;  # 40 points

julia> dx = 4.0;  # in µm

julia> x, = spatial_vectors(40, dx);

julia> amplitudes = g(x);

julia> isapprox(sum(abs2, amplitudes) * dx, 1)  # Normalization to 1 by default
true

julia> g_prop = Gaussian1D(10.0, 1.064, 1000.0);  # Propagated 1 mm

julia> amplitudes_prop = g_prop(x);

julia> isapprox(sum(abs2, amplitudes_prop) * dx, 1; atol=1e-5)
true

See also: HermiteGaussian1D, Gaussian, HermiteGaussian, LaguerreGaussian

Gaussian(w0::Real; norm_constant=nothing)
Gaussian(w0x::Real, w0y::Real; norm_constant=nothing)
Gaussian(w0::Real, λ::Real, z::Real; constant_phase=true, norm_constant=nothing)
Gaussian(w0x::Real, w0y::Real, λ::Real, z::Real; constant_phase=true, norm_constant=nothing)

Create a two-dimensional Gaussian mode.

Arguments

• w0::Real: Beam waist radius for circular beam
• w0x::Real, w0y::Real: Beam waist radii in x and y directions for elliptical beam
• λ::Real: Wavelength (for propagated version)
• z::Real: Propagation distance from waist (for propagated version)
• constant_phase=true: Include exp(ikz) phase factor
• norm_constant=nothing: Custom normalization constant - defines the peak intensity (default uses proper Gaussian normalization)

Returns

Gaussian mode that can be evaluated at spatial coordinates.

Examples

julia> g = Gaussian(10.0);  # Circular beam, 50 μm waist

julia> nx, ny = 64, 64;

julia> dx, dy = 4.0, 4.0;

julia> xv, yv = spatial_vectors(nx, ny, dx, dy);

julia> field = zeros(ComplexF64, nx, ny);

julia> g(field, xv, yv);  # Evaluate on grid (in-place)

julia> isapprox(sum(abs2, field) * dx * dy, 1)  # Check normalization
true

julia> g_ellip = Gaussian(10.0, 20.0, 1.064, 1000.0);  # Elliptical beam, wavelength 1.064 µm, propagated 1 mm

julia> field_ellip = g_ellip(xv, yv);  # Direct evaluation (out-of-place)

julia> isapprox(sum(abs2, field_ellip) * dx * dy, 1)
true

See also: HermiteGaussian, LaguerreGaussian

HermiteGaussian1D(w0::Real, n::Integer)
HermiteGaussian1D(w0::Real, n::Integer, λ::Real, z::Real; constant_phase=true)

Create a one-dimensional Hermite-Gaussian mode HG_n.

Arguments

• w0::Real: Beam waist radius
• n::Integer: Mode number (≥ 0)
• λ::Real: Wavelength (for propagated version)
• z::Real: Propagation distance from waist (for propagated version)
• constant_phase=true: Include exp(ikz) phase factor

Returns

HermiteGaussian1D mode that can be evaluated at spatial positions.

Examples

julia> hg0 = HermiteGaussian1D(20.0, 0);  # HG_0 (Gaussian)

julia> hg1 = HermiteGaussian1D(20.0, 1);  # HG_1 (first excited mode)

julia> nx = 64;

julia> dx = 2.0;

julia> x, = spatial_vectors(nx, dx);

julia> field0 = hg0(x);

julia> field1 = hg1(x);

julia> isapprox(sum(abs2, field0) * dx, 1)  # Check normalization
true

julia> isapprox(sum(field0 .* conj.(field1)) * dx, 0; atol = 1e-15)  # Orthogonality check
true

See also: Gaussian1D, Gaussian, HermiteGaussian, LaguerreGaussian

HermiteGaussian(w0::Real, m::Integer, n::Integer)
HermiteGaussian(w0x::Real, w0y::Real, m::Integer, n::Integer)
HermiteGaussian(w0::Real, m::Integer, n::Integer, λ::Real, z::Real; constant_phase=true)
HermiteGaussian(w0x::Real, w0y::Real, m::Integer, n::Integer, λ::Real, z::Real; constant_phase=true)

Create a two-dimensional Hermite-Gaussian mode HG_{m,n}.

Arguments

• w0::Real: Beam waist radius for circular beam
• w0x::Real, w0y::Real: Beam waist radii in x and y directions
• m::Integer, n::Integer: Mode numbers in x and y directions (≥ 0)
• λ::Real: Wavelength (for propagated version)
• z::Real: Propagation distance from waist (for propagated version)
• constant_phase=true: Include exp(ikz) phase factor

Returns

HermiteGaussian mode that can be evaluated at spatial coordinates.

Examples

julia> hg00 = HermiteGaussian(10.0, 0, 0);  # Fundamental mode

julia> hg10 = HermiteGaussian(10.0, 1, 0);  # First excited in x

julia> hg01 = HermiteGaussian(10.0, 0, 1);  # First excited in y

julia> nx, ny = 64, 64;

julia> dx, dy = 2.0, 2.0;

julia> xv, yv = spatial_vectors(nx, ny, dx, dy);

julia> field00 = hg00(xv, yv);

julia> field10 = hg10(xv, yv);

julia> isapprox(sum(abs2, field00) * dx * dy, 1)  # Check normalization
true

julia> isapprox(sum(field00 .* conj.(field10)) * dx * dy, 0; atol = 1e-15)  # Orthogonality
true

See also: Gaussian, LaguerreGaussian

hermite_gaussian_groups(w0, n_groups::Int)

Generate all Hermite-Gaussian modes up to a given group number.

Creates all HGₘₙ modes where m + n < n_groups, ordered by increasing total mode number. This is useful for modal decomposition and beam shaping applications.

Arguments

• w0: Beam waist radius
• n_groups::Int: Number of groups to generate

Returns

Vector of HermiteGaussian modes.

Examples

julia> modes = hermite_gaussian_groups(10.0, 3);

julia> length(modes)  # Modes: HG_00, HG_10, HG_01, HG_20, HG_11, HG_02
6

julia> nx, ny = 64, 64;

julia> dx, dy = 2.0, 2.0;

julia> xv, yv = spatial_vectors(nx, ny, dx, dy);

julia> fields = [mode(xv, yv) for mode in modes];

julia> all(abs(sum(abs2, field) * dx * dy - 1.0) < 1e-10 for field in fields)  # All normalized
true

julia> modes = hermite_gaussian_groups(10.0, 4);

julia> length(modes)  # Groups 0, 1, 2, 3 give 1+2+3+4 = 10 modes
10

See also: Gaussian, HermiteGaussian, LaguerreGaussian

LaguerreGaussian(w0::Real, p::Integer, l::Integer; kind=:vortex)
LaguerreGaussian(w0::Real, p::Integer, l::Integer, λ::Real, z::Real; constant_phase=true, kind=:vortex)

Create a Laguerre-Gaussian mode LGₚₗ.

Arguments

• w0::Real: Beam waist radius
• p::Integer: Radial mode number (≥ 0)
• l::Integer: Azimuthal mode number (any integer)
• λ::Real: Wavelength (for propagated version)
• z::Real: Propagation distance from waist (for propagated version)
• constant_phase=true: Include exp(ikz) phase factor
• kind: Mode type - :vortex (default), :even, or :odd
  • :vortex: exp(ilφ) phase dependence
  • :even: cos(lφ) dependence
  • :odd: sin(lφ) dependence

Returns

LaguerreGaussian mode that can be evaluated at spatial coordinates.

Examples

julia> lg00 = LaguerreGaussian(10.0, 0, 0);  # Fundamental mode (Gaussian)

julia> lg01 = LaguerreGaussian(10.0, 0, 1);  # Vortex beam

julia> nx, ny = 65, 65;

julia> dx, dy = 2.0, 2.0;

julia> xv, yv = spatial_vectors(nx, ny, dx, dy);

julia> field00 = lg00(xv, yv);

julia> field01 = lg01(xv, yv);

julia> isapprox(sum(abs2, field00) * dx * dy, 1)  # Check normalization
true

julia> abs(field01[nx÷2+1, ny÷2+1]) < 1e-10  # LG_01 has zero at center (vortex)
true

julia> lg_even = LaguerreGaussian(10.0, 0, 2; kind=:even);

julia> field_even = lg_even(xv, yv);

julia> all(isreal, field_even)  # Even modes are real-valued
true

See also: Gaussian, HermiteGaussian

PointLayout(n, p=(0,0), t=Id2D())

Create a layout of n identical points.

Arguments

• n: Number of points
• p=(0,0): Position of the point
• t=Id2D(): Coordinate transformation

Returns

PointLayout that can be iterated to get point positions.

Examples

julia> layout = Modes.PointLayout(3, (100.0, 50.0));

julia> positions = collect(layout);

julia> length(positions)
3

julia> all(pos == (100.0, 50.0) for pos in positions)
true

GridLayout(nx, ny, px, py, t=Id2D())

Create a regular rectangular grid layout.

Arguments

• nx, ny: Number of points in x and y directions
• px, py: Spacing between points in x and y
• t=Id2D(): Coordinate transformation

Returns

GridLayout that can be iterated to get point positions.

Examples

julia> layout = Modes.GridLayout(2, 3, 100.0, 50.0);

julia> positions = collect(layout);

julia> length(positions)  # 2×3 = 6 points
6

julia> positions[1]  # First point (centered grid)
(-50.0, -50.0)

julia> positions[end]  # Last point
(50.0, 50.0)

TriangleLayout(np, px, py, t=Id2D())

Create a triangular arrangement of points.

Arguments

• np: Number of points along triangle edge
• px, py: Spacing between points in x and y
• t=Id2D(): Coordinate transformation

Returns

TriangleLayout with np(np+1)/2 total points.

Examples

julia> layout = Modes.TriangleLayout(3, 100.0, 100.0);

julia> length(layout)  # 3×4/2 = 6 points
6

julia> layout = Modes.TriangleLayout(4, 50.0, 50.0);

julia> length(layout)  # 4×5/2 = 10 points
10

CustomLayout(positions, t=Id2D())

Create a layout from custom list of positions.

Arguments

• positions: Vector of (x,y) tuples specifying point positions
• t=Id2D(): Coordinate transformation applied to all positions

Returns

CustomLayout that can be iterated to get transformed positions.

Examples

julia> positions = [(0.0, 0.0), (100.0, 0.0), (50.0, 86.6)];

julia> layout = Modes.CustomLayout(positions);

julia> collect(layout) == positions
true

julia> layout_rot = Modes.CustomLayout(positions, Rot2D(π/2));

julia> rotated = collect(layout_rot);

julia> all(isapprox.(rotated[2], (0.0, 100.0), atol=1e-12))  # Second point rotated 90°
true

generate_mode_stack(layout, nx, ny, dx, dy, mode; t=Id2D(), normalize=true)
generate_mode_stack(layout, nx, ny, dx, dy, mode_vector; t=Id2D(), normalize=true)
generate_mode_stack(nx, ny, dx, dy, mode_vector; t=Id2D(), normalize=true)

Generate arrays of optical modes at specified positions.

The first form replicates the same mode at each layout position. The second form uses different modes from mode_vector at each position. The third form places modes at the origin (single position each).

Arguments

• layout: Spatial layout determining mode positions
• nx, ny: Grid size for each mode field
• dx, dy: Pixel size
• mode: Single mode to replicate at all positions
• mode_vector: Vector of modes (one per position)
• t=Id2D(): Additional transformation applied to all modes
• normalize=true: Normalize each mode to unit power

Returns

3D complex array of size (nx, ny, n_modes) containing mode fields.

Examples

julia> layout = Modes.GridLayout(2, 2, 50.0, 50.0);

julia> gaussian = Gaussian(10.0);

julia> modes = generate_mode_stack(layout, 64, 64, 2.0, 2.0, gaussian);

julia> size(modes)
(64, 64, 4)

julia> sum(abs2, modes[:, :, 1]) * 2.0 * 2.0  # Check first mode normalization
1.0000000000000007

julia> hg_modes = [HermiteGaussian(25.0, m, n) for m in 0:1 for n in 0:1];

julia> modes_hg = generate_mode_stack(layout, 64, 64, 2.0, 2.0, hg_modes);

julia> size(modes_hg)
(64, 64, 4)

julia> lg_modes = [LaguerreGaussian(20.0, 0, l) for l in 0:2];

julia> modes_lg = generate_mode_stack(64, 64, 2.0, 2.0, lg_modes);

julia> size(modes_lg)  # No layout specified, modes at origin
(64, 64, 3)

generate_speckle(ns, ds, λ, NA; envelope=nothing, center=(0,0), t=Id2D(), normalize=true)

Generate random speckle pattern with controlled numerical aperture.

Creates a complex random field with Fourier components limited by the numerical aperture, producing realistic speckle with controlled correlation length.

Arguments

• ns: Grid dimensions - (nx,) for 1D, (nx, ny) for 2D, (nx, ny, nz) for 3D
• ds: Pixel sizes - (dx,), (dx, dy), or (dx, dy, dz)
• λ: Wavelength
• NA: Numerical aperture controlling speckle size
• envelope=nothing: Optional envelope function (Mode type)
• center=(0,0): Center position for envelope
• t=Id2D(): Coordinate transformation for envelope
• normalize=true: Normalize the speckle distribution to unit power

Returns

Complex array with random speckle pattern.

Examples

julia> speckle = generate_speckle((64, 64), (1.0, 1.0), 1.064, 0.1);

julia> isapprox(sum(abs2, speckle), 1)
true

julia> envelope = Gaussian(20.0);

julia> speckle_env = generate_speckle((64, 64), (1.0, 1.0), 1.064, 0.1; envelope=envelope);

julia> isapprox(sum(abs2, speckle_env), 1)
true

julia> speckle_1d = generate_speckle((128,), (0.5,), 1.064, 0.2);

julia> isapprox(sum(abs2, speckle_1d) * 0.5, 1)
true