torchoptics.propagation#

Field propagation functions.

Functions#

calculate_critical_propagation_distance(field, ...)

Calculate the critical propagation distance for determining the propagation method.

get_propagation_plane(field, output_plane)

Create a propagation plane that is equal to or slightly larger than the specified output plane.

is_angular_spectrum_method(field, propagation_plane, ...)

Return whether propagation using ASM should be used.

propagator(field, shape, z, spacing, offset, ...)

Propagate the field through free-space to a plane defined by the input parameters.

Package Contents#

torchoptics.propagation.calculate_critical_propagation_distance(field, propagation_plane)#

Calculate the critical propagation distance for determining the propagation method.

The minimum distance is calculated using the criteria in Eq. A.17 from D. Voelz’s textbook “Computational Fourier Optics: A MATLAB Tutorial” (2011):

\[z_c = \frac{2 |x_\mathrm{max}| \Delta}{\lambda},\]

where:

  • \(z_c\) is the critical propagation distance.

  • \(x_\mathrm{max}\) is the maximum distance between grid points of the field and propagation planes.

  • \(\Delta\) is the spacing of the field.

  • \(\lambda\) is the wavelength of the field.

The returned value is a tensor of shape (2,) containing the critical distances in both planar dimensions.

Parameters:

  • field (torchoptics.fields.Field)

  • propagation_plane (torchoptics.planar_grid.PlanarGrid)

Return type:

torch.Tensor

torchoptics.propagation.get_propagation_plane(field, output_plane)#

Create a propagation plane that is equal to or slightly larger than the specified output plane.

The propagation plane adopts the same spacing as the field, and retains the same z and offset values as the output_plane.

The length of the propagation plane must satisfy the inequality:

\[\text{propagation plane length} \geq \text{output plane length}.\]

This can be expressed as:

\[(N_{{\text{prop}}} - 1) \cdot \Delta_{{\text{prop}}} \geq (N_{{\text{out}}} - 1) \cdot \Delta_{{\text{out}}}.\]

Therefore, the number of grid points in the propagation plane, \(N_{{\text{prop}}}\), must be:

\[N_{{\text{prop}}} \geq \left [ \frac{{(N_{{\text{out}}} - 1) \cdot \Delta_{{\text{out}}}}}{{\Delta_{{\text{prop}}}}} \right ] + 1,\]

where:

  • \(N_{{\text{prop}}}\) is the number of grid points (shape) in the propagation plane.

  • \(N_{{\text{out}}}\) is the number of grid points (shape) in the output plane.

  • \(\Delta_{{\text{prop}}}\) is the spacing in the propagation plane.

  • \(\Delta_{{\text{out}}}\) is the spacing in the output plane.

Parameters:

  • field (torchoptics.fields.Field)

  • output_plane (torchoptics.planar_grid.PlanarGrid)

Return type:

torchoptics.planar_grid.PlanarGrid

torchoptics.propagation.is_angular_spectrum_method(field, propagation_plane, propagation_method)#

Return whether propagation using ASM should be used.

Returns True if propagation_method is “ASM” or “ASM_FRESNEL”.

Returns False if propagation_method is “DIM” or “DIM_FRESNEL”.

If propagation_method is “AUTO” or “AUTO_FRESNEL”, the propagation family is determined based on the condition set in calculate_critical_propagation_distance(). Returns True if at least one of the two planar dimensions meets the condition; otherwise, returns False.

Parameters:

  • field (torchoptics.fields.Field)

  • propagation_plane (torchoptics.planar_grid.PlanarGrid)

  • propagation_method (str)

Return type:

bool

torchoptics.propagation.propagator(field, shape, z, spacing, offset, propagation_method, asm_pad, interpolation_mode)#

Propagate the field through free-space to a plane defined by the input parameters.

First, the field is propagated to the plane determined by get_propagation_plane(). This propagated field is then interpolated using torchoptics.functional.plane_sample() to match the geometry of the output plane.

Parameters:

  • field (Field) – Input field.

  • shape (Vector2) – Number of grid points along the planar dimensions.

  • z (Scalar) – Position along the z-axis.

  • spacing (Vector2 | None) – Distance between grid points along planar dimensions. Default: if None, uses a global default (see torchoptics.set_default_spacing()).

  • offset (Vector2 | None) – Center coordinates of the plane. Default: (0, 0).

  • propagation_method (str) – Propagation method to use.

  • asm_pad (Vector2 | None) – Padding size for ASM propagation.

  • interpolation_mode (str) – Interpolation mode for resampling.

Returns:

Output field after propagating to the plane.

Return type:

Field