Conformance tests

OpticsBase.Conformance

Shared conformance tests for packages that produce or propagate PlaneFields. They compare a package's fields with analytic Gaussian beams and catch convention errors that power and amplitude checks miss: a conjugated field (wrong sign of the time convention), a wrong Gouy phase or curvature, a doubled or missing phase, swapped polarization handedness, a misplaced plane or inconsistent H.

A package takes one or both roles:

• source: check_source(make) with make(beam, origin, axes, size, spacing) returning the package's PlaneField of the GaussianBeam beam on the given plane;
• propagator: check_propagator(propagate) with propagate(f, L) returning the field f propagated by L along its normal through a homogeneous medium of index f.n, on the plane f.origin + L n with the axes of f.

Both return a vector of Results. In the package's test suite:

using OpticsBase: Conformance

@testset "$(r.name)" for r in Conformance.check_source(make)
    @test r.value <= r.limit
end

One test set per check keeps the name of a failing check in the test output. The module has no dependency on Test.

GaussianBeam(; waist, direction, λ, w0, P = 1e-3, n = 1, jones = (1, 0))

Stigmatic, paraxial Gaussian beam used as the reference of the conformance tests.

Arguments

• waist: global position of the waist center in [m].
• direction: propagation direction (normalized).
• λ: vacuum wavelength in [m].
• w0: waist radius (1/e² of the intensity) in [m].
• P: power in [W].
• n: refractive index of the medium.
• jones: Jones vector (normalized) in the basis (u, v) of the plane the beam is evaluated on.

Conventions

With z the distance from the waist along direction, ρ the distance from the axis, k = 2π n/λ and z_R = π w0² n/λ, the field is the exp(−iωt) Gaussian beam

E = E₀ (w0/w) exp(−ρ²/w²) exp(i (k z − atan(z/z_R) + k ρ²/(2R)))

with w = w0 √(1 + (z/z_R)²), 1/R = z/(z² + z_R²) and the real peak amplitude E₀ = √(4 Z₀ P/(n π w0²)). The absolute phase is zero at the waist center.

field(beam::GaussianBeam, origin, axes, size, spacing)

The analytic PlaneField of beam on the plane with origin, axes (columns u, v, n), size = (nx, ny) and spacing, built with the E-only constructor. The plane normal n must be the beam direction to within 1e-6 (the orthonormality tolerance of PlaneField, so axes computed in single precision are accepted); the origin may lie off the axis.

check_source(make; n = 1, geometry_tol = 1e-6, kwargs...)

Runs the source conformance tests: for each standard GaussianBeam case, make(beam, origin, axes, size, spacing) must return the field of beam on that plane as a PlaneField with that origin, axes and sampling. The cases cover the axes +z, +y (the BeamletOptics optical axis) and an oblique one, planes at the waist, before and behind it and off the axis, linear and right-circular polarization (jones = (1, i), positive helicity), in a medium of index n. kwargs are tolerances, see compare. Returns the Results, including a check that the returned plane is the requested one.

geometry_tol is the limit of that check: the largest of the origin error in units of the sample spacing, the error of the axes and the relative error of the spacing. The default is the orthonormality tolerance of PlaneField, so axes computed in single precision pass. A returned plane outside the limit fails this check; it does not throw.

check_propagator(propagate; n = 1, geometry_tol = 1e-6, kwargs...)

Runs the propagator conformance tests: for each standard GaussianBeam case, the analytic field on a plane normal to the beam is passed to propagate(f, L), which must return the field after the distance L along the plane normal in a homogeneous medium of index f.n, on the plane f.origin + L n with the axes of f (sampling is up to the propagator). The cases include propagation through a focus, circular polarization and an oblique, off-axis plane. kwargs are tolerances, see compare. Returns the Results, including a check of the output plane with the limit geometry_tol (origin error in units of the input sample spacing and error of the axes, see check_source).

compare(f::PlaneField, beam::GaussianBeam; name = "", power_rtol = 1e-3,
        field_tol = 1e-4, phase_tol = 1e-3, backward_tol = 1e-6)

Compares f with the analytic field of beam on the plane of f and returns Results for:

• power: |power(f)/P − 1|;
• field: 1 − |c|, with c the normalized complex correlation of the physical tangential fields (shape, position and polarization);
• absolute phase: |arg c| in rad (catches a conjugated field, a wrong Gouy phase or a doubled phase);
• backward light: |power(backward(f))|/P (H consistent with a forward wave).

The reference is the beam at the sample positions of f, with jones taken in the (u, v) of f. The checks are meant for a plane normal to the beam. A field on another plane does not throw: it fails the checks, and check_source and check_propagator report the plane itself.

Result(name, value, limit)

Outcome of one conformance check: the measured error value and its tolerance limit. The check passes if value <= limit.