pado.propagator.Propagator¶
- class Propagator(mode, polar='non', *, backend='torch')[source]¶
-
- __init__(mode, polar='non', *, backend='torch')[source]¶
Light propagator for simulating wave propagation through free space.
Implement common diffraction methods including Fraunhofer, Fresnel, ASM and RS. Support complex field calculations.
- Parameters:
mode (str) – Propagation method to use: - “Fraunhofer”: Far-field diffraction - “Fresnel”: Near-field diffraction - “ASM”: Angular Spectrum Method - “RS”: Rayleigh-Sommerfeld Method
polar (str) – Polarization mode (‘non’: scalar, ‘polar’: vector)
backend (str) – ‘torch’ uses native PyTorch on the field device. ‘fused’ opts ASM into an experimental NVRTC transfer kernel for fixed CUDA geometry. CPU and differentiable geometry use PyTorch; input-field gradients remain supported in both paths. First CUDA use compiles the kernel through PyTorch’s Jiterator.
Examples
>>> # Create ASM propagator for scalar field >>> prop = Propagator(mode="ASM", polar="non")
>>> # Create Fresnel propagator for vector field >>> prop = Propagator(mode="Fresnel", polar="polar")
>>> # Create Fraunhofer propagator >>> prop = Propagator(mode="ASM") >>> field = torch.ones((1, 1, 1000, 1000)) >>> light = Light(field, pitch=2e-6, wvl=660e-9) >>> light_prop = prop.forward(light, z=0.05)
- prepare(light, z, *, offset=(0, 0), linear=True, band_limit=True)[source]¶
Prepare scalar, unscaled ASM for repeated Tensor -> Tensor calls.
Optical conditions are fixed at preparation. The callable accepts new fields with the same channels, spatial shape, dtype and device; batch size may vary. Only H and layout metadata persist, not the input Light, field or geometry tensors. Changing conditions requires a new prepare. H occupies one complex tensor per wavelength at the padded FFT size.
Field gradients remain supported across repeated backward calls. Differentiable geometry is rejected, even inside no_grad; use forward to optimize wavelength, pitch, distance or offset. Preparation inside torch.func transforms is unsupported; applying an existing operator to transformed fields uses ordinary Torch operations. Fixed zero distance and zero offset return the input field itself, including Tensor zeros. The selected backend is used only to prepare H, never during reuse.
- forward(light, z, offset=(0, 0), linear=True, band_limit=True, b=1, target_plane=None, sampling_ratio=1, vectorized=False, steps=100)[source]¶
Propagate incident light through the propagator.
- Parameters:
light (Light) – Incident light field
z (float) – Propagation distance in meters
offset (tuple) – Lateral shift (y, x) in meters for off-axis propagation
linear (bool) – Flag for linear convolution (with padding) or circular convolution (no padding)
band_limit (bool) – If True, apply band-limiting for unscaled ASM (b=1)
b (float) – Scaling factor for observation plane (b>1: expansion, b<1: focusing)
target_plane (tuple, optional) – (x, y, z) coordinates for RS diffraction
sampling_ratio (int) – Spatial sampling ratio for RS computation
vectorized (bool) – If True, use vectorized implementation for RS (better performance but higher memory usage)
steps (int) – Number of chunks for vectorized RS. More chunks reduce temporary kernel storage, but not total autograd saved tensors.
- Returns:
Propagated light field
- Return type:
Examples
>>> # Basic propagation >>> prop = Propagator(mode="ASM") >>> light_prop = prop.forward(light, z=0.1)
>>> # Propagation with padding >>> light_prop = prop.forward(light, z=0.1, linear=True)
>>> # Vector field propagation >>> prop = Propagator(mode="Fresnel", polar="polar") >>> light_prop = prop.forward(light, z=0.05) >>> # Access x,y components >>> x_component = light_prop.get_lightX() >>> y_component = light_prop.get_lightY()
>>> # Vectorized RS propagation for better performance >>> prop = Propagator(mode="RS") >>> light_prop = prop.forward(light, z=0.1, vectorized=True, steps=50)
- forward_180(light)[source]¶
Convert a spatial-domain Light into a k-space KSpaceLight.
Perform a centered 2D FFT of the input spatial field and represent the result on a wave-vector (kx, ky) grid derived from the input’s spatial pitch and field size. This is the entry point for wide-angle / 180-degree propagation: (kx, ky) maps naturally to propagation direction (theta, phi).
No propagation distance is applied: this mode performs only spatial complex field -> centered FFT -> KSpaceLight. Autograd is preserved through the FFT (the field is never detached).
Only scalar Light with polar=’non’ is supported. PolarizedLight and other polarization modes raise NotImplementedError; no polarization components are silently combined. Angular sampling supports the forward hemisphere, not backward propagation.
- Parameters:
light (Light) – Input spatial-domain light field
- Returns:
k-space field on a centered (kx, ky) grid
- Return type:
- forward_non_polar(light, z, offset=(0, 0), linear=True, band_limit=True, b=1, target_plane=None, sampling_ratio=1, vectorized=False, steps=100)[source]¶
Propagate non-polarized light field using selected propagation method.
- Parameters:
light (Light) – Input light field
z (float) – Propagation distance in meters
offset (tuple) – Lateral shift (y, x) in meters for off-axis propagation
linear (bool) – If True, use linear convolution with zero-padding
band_limit (bool) – If True, apply band-limiting for ASM
b (float) – Scaling factor for observation plane (b>1: expansion, b<1: focusing)
target_plane (tuple, optional) – (x, y, z) coordinates for RS diffraction
sampling_ratio (int) – Spatial sampling ratio for RS computation
vectorized (bool) – If True, use vectorized implementation for RS
steps (int) – Number of computation steps for vectorized RS
- Returns:
Propagated light field
- Return type:
- forward_Fraunhofer(light, z, linear=True)[source]¶
Physical Fraunhofer integral on a common isotropic output grid.
The returned shape is unchanged. Padding doubles Fourier sampling; output pitch and field coordinates depend on wavelength and distance. Includes pixel area, carrier, amplitude and output quadratic phase. Tensor distance/wavelength gradients include the moving output grid.
- forward_Fresnel(light, z, linear)[source]¶
Sampled paraxial propagation with unchanged pixel pitch.
Uses H=exp(i*2*pi*z/wavelength-i*pi*wavelength*z*(fx**2+fy**2)). This replaces the formerly amplitude-normalized impulse convolution. Optional zero padding reduces circular wrap-around before cropping.
- forward_FFT(light, z=None)[source]¶
Propagate light using simple FFT-based propagation.
Apply exp(1j * phase) before FFT without considering propagation distance z or padding. Used for basic Fourier transform of the input field.
- forward_ASM(light, z, offset=(0, 0), linear=True, band_limit=True, b=1)[source]¶
Select appropriate ASM propagation method based on parameters.
Automatically choose between standard ASM, band-limited ASM, and scaled ASM depending on the scaling factor b and offset requirements.
- Parameters:
- Returns:
Propagated light field using selected ASM method
- Return type:
- forward_standard_ASM(light, z, offset=(0, 0), linear=True)[source]¶
Scalar ASM with double-precision geometry and evanescent decay.
Complex field dtype is preserved. Negative z applies the stable adjoint: propagating phases reverse, while evanescent components still decay. It is not the unstable inverse of a decaying evanescent field.
- forward_shifted_BL_ASM(light, z, offset=(0, 0), linear=True)[source]¶
Shifted ASM with a mask derived from sampled phase-gradient limits.
offset is (y, x) in metres. The Nyquist bound uses half of the actual FFT period, including padding. Evanescent bins are suppressed at nonzero distance. Hard support changes are nondifferentiable; parameter gradients describe the transfer within the locally fixed support.
- forward_ScASM(light, z, b, linear=True)[source]¶
Scaled angular spectrum on an isotropic output pitch b*input_pitch.
Preserves field precision and supports odd rectangular arrays. Uses physical forward/inverse quadrature normalization and the same scaled inverse operator for expansion and focusing. Negative z is the stable adjoint for evanescent components, rather than their unstable inverse.
- forward_ScASM_focusing(light, z, b, linear=True)[source]¶
Focusing variant of the same physically normalized scaled operator.
- forward_RayleighSommerfeld(light, z, target_plane=None, sampling_ratio=1, vectorized=False, steps=100)[source]¶
Evaluate the scalar Rayleigh-Sommerfeld integral by pixel quadrature.
Source coordinates are (index - size//2)*pitch, in metres. Batch and wavelength channels are independent. The returned field preserves the input complex dtype and device. This finite-grid quadrature is not an exact continuous diffraction solution; sampling convergence is required.
target_plane is an optional tuple of finite, equally shaped 2D (x,y,z) tensors, with nonzero z. Output target coordinates are retained as result.target_plane. For explicit targets, result.pitch remains the input pitch as a fallback: the coordinate tensors are authoritative and must be used for nonuniform/tilted grids, rather than feeding the result directly to a uniform-grid propagator.
sampling_ratio evaluates every nth target row/column and replicates the samples with nearest-neighbour blocks, including partial edge blocks. It does not subsample the source integral. vectorized selects chunked rather than one-target-at-a-time evaluation; steps is the requested number of chunks, bounded by the sampled target count. Both execution paths implement the same quadrature and sampling rule.