Physical Optics#
Boundary occupancy diagnostic#
Angular-spectrum propagation uses a periodic FFT grid. To report the fraction of the current field intensity in a boundary band, call the optional diagnostic after propagation:
from optiland.physical_optics import boundary_diagnostic, gaussian_field
field = gaussian_field((128, 192), dx=0.01, wavelength=0.0005,
waist_radius=0.1)
propagated = field.propagate(10.0)
diagnostic = boundary_diagnostic(propagated, edge_width=4,
threshold=0.01, warn=True)
fraction = diagnostic.boundary_fraction
edge_width is the number of samples at each edge, at most half the smaller
grid dimension.
The boundary is the union of these bands, with each corner counted once.
threshold must be finite and positive; the flag and optional warning use
a strict greater-than comparison.
A zero field returns a zero fraction.
Nonfinite amplitudes are rejected.
The diagnostic never modifies, pads, or filters the field.
The fraction retains PyTorch gradients, dtype, and device for nonzero fields. Validation and the Python threshold decision synchronize device execution, including when warnings are disabled. The zero-field gradient is defined as zero; the normalized fraction has no direction-independent limit there. A small boundary fraction does not prove alias-free propagation: content may already have wrapped into the interior, and frequency sampling is not tested. Choose the band width and threshold for the field and propagation distances being studied, and check grid convergence separately.
Paraxial Gaussian beams#
GaussianBeam describes a rotationally
symmetric Gaussian beam at one plane by its complex beam parameter q.
The real part of q is the distance from the waist to the plane (negative
before the waist), and the imaginary part is the Rayleigh range.
Lengths are in millimeters and wavelengths in micrometers, as in Optic, and
beam radii are 1/e² intensity radii.
GaussianBeamAnalysis (see analysis.gaussian_beam) carries a
beam through an optical system with its ray-transfer (ABCD) matrices, including
systems folded by plane mirrors. Because the beam is rotationally symmetric,
surfaces with different radii in x and y (toroidal, biconic) raise an error:
from optiland.analysis import GaussianBeamAnalysis
from optiland.physical_optics import GaussianBeam
from optiland.samples.objectives import CookeTriplet
lens = CookeTriplet()
beam = GaussianBeam.from_waist(1.0, wavelength=0.55) # 1 mm waist on surface 1
analysis = GaussianBeamAnalysis(lens, beam)
focus = analysis.beam_at(-1, "before") # arriving at the image plane
print(focus)
# GaussianBeam(w=0.00965934 mm, w0=0.0087533 mm, waist at +0.204216 mm,
# wavelength=0.55 µm, m2=1.0)
GaussianBeam.from_round_trip gives the eigenmode of a stable resonator, and
GaussianBeam.overlap the mode-matching efficiency between two beams.
Tutorial 1f: Paraxial Gaussian Beams and Resonators shows both, including the
arm cavity of ETpathfinder.
Scalar physical-optics field models and propagation algorithms.
- class BoundaryDiagnostic(boundary_fraction: ScalarOrArray, edge_width: int, threshold: float, exceeds_threshold: bool)[source]#
Bases:
objectIntensity fraction in the boundary band of a rectangular field.
- Variables:
boundary_fraction (ScalarOrArray) – Dimensionless boundary intensity divided by total intensity. Zero for a zero field. A NumPy scalar or a differentiable Torch scalar with the field’s real dtype and device.
edge_width (int) – Width of the band at each edge, in samples.
threshold (float) – Finite positive reporting threshold.
exceeds_threshold (bool) – Whether
boundary_fraction > threshold.
The record is frozen; its Torch scalar remains a tensor, not a deeply immutable value. A low fraction does not establish alias-free propagation.
- boundary_fraction: ScalarOrArray#
- class GaussianBeam(q_real, q_imag, wavelength: float, refractive_index=1.0, m2: float = 1.0)[source]#
Bases:
objectA paraxial, rotationally symmetric Gaussian beam at one plane.
- Parameters:
q_real – Distance in mm from the waist to this plane, negative when the waist lies downstream.
q_imag – Rayleigh range in mm. Must be positive.
wavelength – Vacuum wavelength in µm.
refractive_index – Refractive index of the medium. Defaults to 1.0.
m2 – Beam quality factor M². Defaults to 1.0, a TEM00 beam.
- Raises:
ValueError – If q_imag, wavelength or refractive_index is not positive, or if m2 is below 1.
- property beam_radius#
Beam radius in mm at this plane.
- property curvature#
Wavefront curvature (one over the radius) in 1/mm, zero at the waist.
The curvature is returned instead of the radius because the radius is infinite at the waist.
- property divergence#
Far-field half-angle divergence in radians, in this medium.
- classmethod from_round_trip(matrix, *, wavelength: float, refractive_index=1.0, m2: float = 1.0) GaussianBeam[source]#
Create the eigenmode of a stable resonator.
The eigenmode is the beam that comes back unchanged after one round trip (Siegman, chapter 21).
- Parameters:
matrix – 2x2 round-trip matrix that starts and ends at the same plane, in the same direction and medium. For a linear cavity modeled from a forward-going plane, this is
optic.paraxial.ray_transfer_matrix(1, k).wavelength – Vacuum wavelength in µm.
refractive_index – Refractive index at the starting plane.
m2 – Beam quality factor M².
- Returns:
The eigenmode at the starting plane.
- Raises:
ValueError – If the round trip does not start and end in the same medium, or if the resonator is not stable.
- classmethod from_waist(waist_radius, waist_position=0.0, *, wavelength: float, refractive_index=1.0, m2: float = 1.0) GaussianBeam[source]#
Create a beam from its waist.
- Parameters:
waist_radius – Waist radius in mm.
waist_position – Distance in mm from this plane to the waist, positive when the waist lies downstream. Defaults to 0.0, a waist on this plane.
wavelength – Vacuum wavelength in µm.
refractive_index – Refractive index of the medium.
m2 – Beam quality factor M².
- Returns:
The beam at this plane.
- overlap(other: GaussianBeam)[source]#
Fraction of power that couples from this beam into another.
- Parameters:
other – The beam to couple into, at the same plane, wavelength and refractive index.
- Returns:
The coupled power fraction, from 0 to 1.
- Raises:
ValueError – If either beam has M² above 1, or if the wavelengths or refractive indices differ.
- propagate(distance) GaussianBeam[source]#
Return the beam after
distancemm of free space.
- property rayleigh_range#
Rayleigh range in mm.
- transform(matrix, refractive_index=None) GaussianBeam[source]#
Apply a ray-transfer (ABCD) matrix to the beam.
- Parameters:
matrix – 2x2 matrix acting on ray height and physical slope, such as one returned by
optic.paraxial.ray_transfer_matrix.refractive_index – Refractive index after the matrix. Defaults to the current index.
- Returns:
The transformed beam.
- property waist_position#
Distance in mm from this plane to the waist, positive downstream.
- property waist_radius#
Waist radius in mm.
- with_refractive_index(refractive_index) GaussianBeam[source]#
Return a beam with the same waist in a medium of another index.
- class ScalarField(data: BEArrayT, dx: float, wavelength: float, dy: float | None = None, refractive_index: float = 1.0)[source]#
Bases:
Generic[BEArrayT]A sampled two-dimensional complex scalar optical field.
The last array dimension is the x-axis and the first is the y-axis. All spatial quantities, including
dx,dy, andwavelength, must use the same unit.- Parameters:
data – Two-dimensional NumPy array or PyTorch tensor containing the sampled complex amplitude. Real arrays are promoted to complex without changing their device or floating-point precision.
dx – Sample spacing along x.
wavelength – Vacuum wavelength in the same unit as
dx.dy – Sample spacing along y. Defaults to
dx.refractive_index – Homogeneous-medium refractive index. Defaults to 1.
- Raises:
TypeError – If
datadoes not belong to the active backend.ValueError – If the field or physical parameters are invalid.
- coordinates() tuple[BEArrayT, BEArrayT][source]#
Return centered one-dimensional x and y coordinate arrays.
- property intensity: BEArrayT#
Return sampled intensity,
abs(data) ** 2.
- property power: ScalarOrArrayT#
Return the sampled intensity integral over the field plane.
- propagate(distance: float | ScalarOrArrayT, evanescent: Literal['discard', 'decay'] = 'discard') ScalarField[BEArrayT][source]#
Propagate the field through a homogeneous medium.
- Parameters:
distance – Signed propagation distance in the field’s spatial unit.
evanescent –
"discard"filters evanescent content even at zero distance."decay"preserves the complete field at zero, up to FFT roundoff. Seeangular_spectrum()for distance-gradient behavior.
- Returns:
Propagated field on the same sampling grid.
- Return type:
- angular_spectrum(field: ScalarField[BEArrayT], distance: float | ScalarOrArrayT, evanescent: EvanescentPolicy = 'discard') ScalarField[BEArrayT][source]#
Propagate a scalar field with the angular spectrum method.
The input and output use the same rectangular sampling grid. Consequently, the usual discrete-Fourier periodic-boundary assumption applies; callers should provide enough zero padding to prevent wraparound for expanding fields.
The longitudinal phase is evaluated as a uniform carrier plus the stable difference
kz - k = -kt**2 / (kz + k). Transfer calculations use float64 on NumPy and non-MPS Torch devices, then return to the field’s dtype. This avoids spurious float32 diffraction halos without widening the field or its FFT. MPS uses the same formula in native precision; large relative phases and tensor-distance carrier phases remain limited by that precision. Tensor distances stay on the field’s device and retain their autograd graph. A float32 distance’s already-rounded physical value cannot be recovered by phase evaluation.- Parameters:
field – Input scalar field.
distance – Signed propagation distance. It must use the same unit as the field spacing and wavelength. A backend scalar is accepted so that PyTorch can differentiate with respect to distance, including at zero for propagating components.
evanescent – Handling of spatial frequencies above the propagating cutoff.
"discard"removes them at every distance, including zero, so zero-distance propagation is an identity only for fields without evanescent content."decay"attenuates them exponentially withabs(distance)and preserves the complete field at zero, up to FFT roundoff. With evanescent content, this absolute-value decay has no two-sided distance derivative at zero; PyTorch uses a zero subgradient for the absolute-value factor there.
- Returns:
Propagated field on the original sampling grid.
- Return type:
- Raises:
TypeError – If
distanceis not scalar.ValueError – If the distance or evanescent policy is invalid.
- boundary_diagnostic(field: ScalarField, *, edge_width: int, threshold: float, warn: bool = False) BoundaryDiagnostic[source]#
Report intensity reaching the periodic FFT grid boundary.
Call this on a propagated field to check its current boundary occupancy. The band is the union of the outer
edge_widthrows and columns; corners are counted once. Uniform pixel area cancels from the power ratio, even whendx != dy. Amplitudes are scaled before squaring to avoid intensity overflow or underflow. Neither the field nor its sampling is modified.This is a wraparound-risk indicator, not a proof of alias-free propagation: it cannot detect content that has already wrapped back into the interior or assess spatial-frequency sampling. It never pads or filters the field.
The metric retains Torch gradients for nonzero fields. Validation and the Python threshold flag synchronize Torch device execution, even when
warn=False; warning formatting also reads the scalar on the host. The zero-field convention has a zero gradient, not a directional limit.- Parameters:
field – Scalar field on the active backend, with finite amplitudes.
edge_width – Positive integer band width in samples, no greater than half the smaller grid dimension (rounded down).
threshold – Finite positive dimensionless fraction threshold. Equality does not trigger the flag or warning.
warn – Emit a
RuntimeWarningwhen the threshold is exceeded.
- Returns:
- Frozen record containing the backend metric and
the threshold decision.
- Return type:
- Raises:
TypeError – If the field or reporting parameters have invalid types.
ValueError – If the width, threshold, or field amplitudes are invalid.
RuntimeError – If the field’s backend is no longer active.
- gaussian_field(shape: tuple[int, int], dx: float, wavelength: float, waist_radius: float, dy: float | None = None, refractive_index: float = 1.0, amplitude: complex | ScalarOrArrayT = 1.0) ScalarField[source]#
Create a fundamental Gaussian beam sampled at its waist.
waist_radiusis the conventional 1/e field-amplitude radius, or equivalently the 1/e-squared intensity radius.- Parameters:
shape – Number of samples as
(ny, nx).dx – Sample spacing along x.
wavelength – Vacuum wavelength.
waist_radius – Gaussian beam waist radius.
dy – Sample spacing along y. Defaults to
dx.refractive_index – Homogeneous-medium refractive index. Defaults to 1.
amplitude – On-axis complex-field amplitude. Defaults to 1.
- Returns:
Gaussian field at its waist plane.
- Return type: