pado.propagator.Propagator

class Propagator(mode, polar='non', *, backend='torch')[source]
Parameters:
__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.

Return type:

Callable

Parameters:
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:

Light

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:

KSpaceLight

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:

Light

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.

Return type:

Light

Parameters:
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.

Return type:

Light

Parameters:
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.

Parameters:
  • light (Light) – Input light field

  • z (float, optional) – Not used in this method

Returns:

FFT of input field

Return type:

Light

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:
  • light (Light) – Input light field

  • z (float) – Propagation distance in meters

  • offset (tuple) – Lateral shift (y, x) in meters

  • linear (bool) – If True, use linear convolution

  • band_limit (bool) – If True, apply band-limiting

  • b (float) – Scaling factor (b>1: expansion, b<1: focusing)

Returns:

Propagated light field using selected ASM method

Return type:

Light

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.

Return type:

Light

Parameters:
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.

Return type:

Light

Parameters:
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.

Return type:

Light

Parameters:
forward_ScASM_focusing(light, z, b, linear=True)[source]

Focusing variant of the same physically normalized scaled operator.

Return type:

Light

Parameters:
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.

Return type:

Light

Parameters:
_forward_RayleighSommerfeld_vectorized(light, z, target_plane=None, steps=100)[source]

Compatibility wrapper for chunked RS quadrature.

Return type:

Light

Parameters: