pado.light.Light

class Light(dim, pitch, wvl, field=None, device='cpu')[source]

Light wave with complex field wavefront.

Represent a light wave with complex field wavefront that can be manipulated through various optical operations.

Parameters:
__init__(dim, pitch, wvl, field=None, device='cpu')[source]

Create light wave instance with complex field wavefront.

Parameters:
  • dim (tuple) – Field dimensions (B, Ch, R, C) for batch, channels, rows, cols

  • pitch (float) – Pixel pitch in meters

  • wvl (float or list) – Wavelength in meters. Can be single value or list for multi-wavelength

  • field (torch.Tensor, optional) – Initial complex field [B, Ch, R, C]

  • device (str) – Device for computation (‘cpu’, ‘cuda:0’, etc.)

Examples

>>> light = Light(dim=(1, 1, 1024, 1024), pitch=6.4e-6, wvl=633e-9)
>>> light = Light(dim=(2, 3, 512, 512), pitch=2e-6, wvl=[450e-9, 550e-9, 650e-9])
crop(crop_width)[source]

Crop light wavefront.

Parameters:

crop_width (tuple) – Crop dimensions (left, right, top, bottom)

Return type:

None

Examples

>>> light.crop((32, 32, 32, 32))
clone()[source]

Create deep copy of light instance.

Returns:

New light instance with copied attributes

Return type:

Light

Examples

>>> light_copy = light.clone()
pad(pad_width, padval=0)[source]

Pad light field with constant value.

Parameters:
  • pad_width (tuple) – Padding dimensions (left, right, top, bottom)

  • padval (int) – Padding value (only 0 supported)

Return type:

None

Examples

>>> light.pad((16, 16, 16, 16))  # Add 16 pixels padding on all sides
set_real(real, c=None)[source]

Set real part of light wavefront.

Parameters:
  • real (torch.Tensor) – Real part in rectangular representation. If c is None: Expected shape is (B,Ch,R,C) matching self.field.real.shape If c is provided: Expected shape is (B,R,C) matching self.field[:, c, …].real.shape where B=batch size, Ch=channels, R=rows, C=columns

  • c (int, optional) – Channel index to modify. If provided, only that specific channel will be updated.

Return type:

None

Examples

>>> # Set real part for all channels (B=1, Ch=1, R=1024, C=1024)
>>> real_part = torch.ones((1, 1, 1024, 1024))  # (B,Ch,R,C)
>>> light.set_real(real_part)
>>>
>>> # Set real part for only channel 0 (B=1, R=1024, C=1024)
>>> real_part_channel0 = torch.ones((1, 1024, 1024))  # (B,R,C)
>>> light.set_real(real_part_channel0, c=0)
set_imag(imag, c=None)[source]

Set imaginary part of light wavefront.

Parameters:
  • imag (torch.Tensor) – Imaginary part in rectangular representation. If c is None: Expected shape is (B,Ch,R,C) matching self.field.imag.shape If c is provided: Expected shape is (B,R,C) matching self.field[:, c, …].imag.shape where B=batch size, Ch=channels, R=rows, C=columns

  • c (int, optional) – Channel index to modify. If provided, only that specific channel will be updated.

Return type:

None

Examples

>>> # Set imaginary part for all channels (B=1, Ch=1, R=1024, C=1024)
>>> imag_part = torch.ones((1, 1, 1024, 1024))  # (B,Ch,R,C)
>>> light.set_imag(imag_part)
>>>
>>> # Set imaginary part for only channel 0 (B=1, R=1024, C=1024)
>>> imag_part_channel0 = torch.ones((1, 1024, 1024))  # (B,R,C)
>>> light.set_imag(imag_part_channel0, c=0)
set_amplitude(amplitude, c=None)[source]

Set amplitude of light wavefront (keeps phase unchanged) without maintaining computation graph.

Parameters:
  • amplitude (torch.Tensor) – Amplitude in polar representation.

  • c (int, optional) – Channel index to modify.

Return type:

None

set_phase(phase, c=None)[source]

Set phase of light wavefront (keeps amplitude unchanged).

Parameters:
  • phase (torch.Tensor) – Phase in polar representation (in radians). If c is None: Expected shape is (B,Ch,R,C) matching self.field.shape If c is provided: Expected shape is (B,R,C) matching self.field[:, c, …].shape where B=batch size, Ch=channels, R=rows, C=columns

  • c (int, optional) – Channel index to modify. If provided, only that specific channel will be updated.

Return type:

None

Examples

>>> # Set phase for all channels (B=1, Ch=1, R=1024, C=1024)
>>> phase = torch.zeros((1, 1, 1024, 1024))  # (B,Ch,R,C)
>>> light.set_phase(phase)
>>>
>>> # Set phase for only channel 0 (B=1, R=1024, C=1024)
>>> phase_channel0 = torch.zeros((1, 1024, 1024))  # (B,R,C)
>>> light.set_phase(phase_channel0, c=0)
set_field(field, c=None)[source]

Set complex field of light wavefront.

Channel replacement copies the containing field, so a borrowed tensor or autograd leaf is not modified. Untouched channels retain their graph.

Parameters:
  • field (torch.Tensor) – Complex field tensor. If c is None: Expected shape is (B,Ch,R,C) matching self.field.shape If c is provided: Expected shape is (B,R,C) matching self.field[:, c, …].shape where B=batch size, Ch=channels, R=rows, C=columns

  • c (int, optional) – Channel index to modify. If provided, only that specific channel will be updated.

Return type:

None

Examples

>>> # Set field for all channels (B=1, Ch=1, R=1024, C=1024)
>>> field = torch.ones((1, 1, 1024, 1024), dtype=torch.complex64)  # (B,Ch,R,C)
>>> light.set_field(field)
>>>
>>> # Set field for only channel 0 (B=1, R=1024, C=1024)
>>> field_channel0 = torch.ones((1, 1024, 1024), dtype=torch.complex64)  # (B,R,C)
>>> light.set_field(field_channel0, c=0)
set_pitch(pitch)[source]

Set pixel pitch of light field.

Parameters:

pitch (float) – New pixel pitch in meters

Return type:

None

Examples

>>> light.set_pitch(6.4e-6)  # Set 6.4μm pitch
get_channel()[source]

Return number of channels in light field.

Returns:

Number of channels

Return type:

int

Examples

>>> channels = light.get_channel()
get_amplitude(c=None)[source]

Get amplitude of light wavefront.

Parameters:

c (int, optional) – Channel index to retrieve. If provided, only that specific channel will be returned.

Returns:

Amplitude in polar representation.

If c is None: Shape is (B,Ch,R,C) If c is provided: Shape is (B,R,C) where B=batch size, Ch=channels, R=rows, C=columns

Return type:

torch.Tensor

Examples

>>> # Get amplitude for all channels (B=1, Ch=1, R=1024, C=1024)
>>> amp = light.get_amplitude()  # Shape: (1, 1, 1024, 1024)
>>>
>>> # Get amplitude for only channel 0 (B=1, R=1024, C=1024)
>>> amp_channel0 = light.get_amplitude(c=0)  # Shape: (1, 1024, 1024)
get_phase(c=None)[source]

Get phase of light wavefront.

Parameters:

c (int, optional) – Channel index to retrieve. If provided, only that specific channel will be returned.

Returns:

Phase in polar representation (in radians).

If c is None: Shape is (B,Ch,R,C) If c is provided: Shape is (B,R,C) where B=batch size, Ch=channels, R=rows, C=columns

Return type:

torch.Tensor

Examples

>>> # Get phase for all channels (B=1, Ch=1, R=1024, C=1024)
>>> phase = light.get_phase()  # Shape: (1, 1, 1024, 1024)
>>>
>>> # Get phase for only channel 0 (B=1, R=1024, C=1024)
>>> phase_channel0 = light.get_phase(c=0)  # Shape: (1, 1024, 1024)
get_intensity(c=None)[source]

Get intensity (amplitude squared) of light wavefront.

Parameters:

c (int, optional) – Channel index to retrieve. If provided, only that specific channel will be returned.

Returns:

Intensity values.

If c is None: Shape is (B,Ch,R,C) If c is provided: Shape is (B,R,C) where B=batch size, Ch=channels, R=rows, C=columns

Return type:

torch.Tensor

Examples

>>> # Get intensity for all channels (B=1, Ch=1, R=1024, C=1024)
>>> intensity = light.get_intensity()  # Shape: (1, 1, 1024, 1024)
>>>
>>> # Get intensity for only channel 0 (B=1, R=1024, C=1024)
>>> intensity_channel0 = light.get_intensity(c=0)  # Shape: (1, 1024, 1024)
get_field(c=None)[source]

Get complex field of light wavefront.

Parameters:

c (int, optional) – Channel index to retrieve. If provided, only that specific channel will be returned.

Returns:

Complex field tensor.

If c is None: Shape is (B,Ch,R,C) If c is provided: Shape is (B,R,C) where B=batch size, Ch=channels, R=rows, C=columns

Return type:

torch.Tensor

Examples

>>> # Get field for all channels (B=1, Ch=1, R=1024, C=1024)
>>> field = light.get_field()  # Shape: (1, 1, 1024, 1024), dtype=torch.complex64
>>>
>>> # Get field for only channel 0 (B=1, R=1024, C=1024)
>>> field_channel0 = light.get_field(c=0)  # Shape: (1, 1024, 1024), dtype=torch.complex64
get_device()[source]

Return device of light field.

Returns:

Device name (‘cpu’, ‘cuda:0’, etc.)

Return type:

str

Examples

>>> device = light.get_device()
get_bandwidth()[source]

Return spatial bandwidth of light wavefront.

Returns:

Spatial height and width of wavefront in meters

Return type:

tuple

Examples

>>> height, width = light.get_bandwidth()
get_ideal_angle_limit()[source]

Return ideal angle limit of light wavefront based on optical axis.

Calculate the maximum diffraction angle supported by the current sampling, based on the Nyquist sampling criterion: sin(θ_max) = λ/(2·pitch). Use the shortest wavelength for multi-wavelength cases.

Returns:

Ideal angle limit in degrees. Tensor wavelength

inputs retain their device, dtype and gradient.

Return type:

float or torch.Tensor

Examples

>>> angle_limit = light.get_ideal_angle_limit()
magnify(scale_factor, interp_mode='nearest', c=None)[source]

Change wavefront resolution without changing pixel pitch.

Parameters:
  • scale_factor (float) – Scale factor for interpolation

  • interp_mode (str) – Interpolation method (‘bilinear’ or ‘nearest’)

  • c (int, optional) – Channel index to modify

Return type:

None

Examples

>>> light.magnify(2.0)  # Double resolution
>>> light.magnify(0.5, interp_mode='bilinear')  # Half resolution
resize(target_pitch, interp_mode='nearest')[source]

Resize wavefront by changing pixel pitch.

Parameters:
  • target_pitch (float) – New pixel pitch in meters

  • interp_mode (str) – Interpolation method (‘bilinear’ or ‘nearest’)

Return type:

None

Examples

>>> light.resize(4e-6)  # Change pitch to 4μm
set_spherical_light(z, dx=0.0, dy=0.0)[source]

Set a unit-amplitude spherical phase front from a point source.

Coordinates are (index - size//2)*pitch. dx offsets columns and dy offsets rows, in meters. This initializer retains the absolute optical carrier phase; it does not apply geometric 1/r amplitude decay. Scalar or channel wavelengths and scalar tensor parameters retain gradients. Phase is evaluated in float64 before final field storage.

Return type:

None

Parameters:
set_plane_light(theta=0)[source]

Set a unit-amplitude plane wave with angle theta in degrees.

The historical tilt axis is rows. Coordinates are now spaced by the declared pitch: (index - rows//2)*pitch, including odd-sized fields. This intentionally replaces endpoint-inclusive linspace, whose actual spacing was rows/(rows-1)*pitch. Optical phase is evaluated in float64 before casting the complex field to its original storage dtype.

Return type:

None

Parameters:

theta (float)

set_amplitude_ones()[source]

Set amplitude to ones. :rtype: None

Examples

>>> light.set_amplitude_ones()
Return type:

None

set_amplitude_zeros()[source]

Set amplitude to zeros. :rtype: None

Examples

>>> light.set_amplitude_zeros()
Return type:

None

set_phase_zeros()[source]

Set phase to zeros. :rtype: None

Examples

>>> light.set_phase_zeros()
Return type:

None

set_phase_random(std=1.5707963267948966, distribution='gaussian', c=None)[source]

Set random phase with specified distribution.

Parameters:
  • std (float, optional) – Standard deviation for phase randomness. - For gaussian: Standard deviation in radians - For uniform: Half-width of uniform distribution in radians - For von_mises: Inverse of concentration parameter (1/κ) Defaults to π/2.

  • distribution (str, optional) – Type of random distribution. Must be one of [‘gaussian’, ‘uniform’, ‘von_mises’]. Defaults to ‘gaussian’.

  • c (int, optional) – Channel index to modify. If None, all channels are modified.

Return type:

None

Notes

All-channel mode draws one complete phase tensor. For more than one channel, seeded outputs and the subsequent RNG stream differ from versions that redundantly redrew the full tensor per channel. The von Mises sampler now uses an unbiased independent sign draw; its seeded outputs also change. Selected-channel scope is unchanged.

Raises:

ValueError – If distribution is not one of the supported types.

Parameters:
Return type:

None

Examples

>>> light.set_phase_random()  # Default gaussian with π/2 std for all channels
>>> light.set_phase_random(std=torch.pi/4)  # Reduced randomness
>>> light.set_phase_random(distribution='uniform')  # Uniform distribution
>>> light.set_phase_random(std=0.25, distribution='von_mises')  # von Mises with κ=4
>>> light.set_phase_random(c=0)  # Only modify first channel
save(fn)[source]

Save light field to file.

Parameters:

fn (str) – Filename (.pt, .pth, .npy or .mat)

Return type:

None

Examples

>>> light.save("field.pt")  # Save as PyTorch format
>>> light.save("field.npy")  # Save as NumPy format
>>> light.save("field.mat")  # Save as MATLAB format
adjust_amplitude_to_other_light(other_light)[source]

Scale amplitude to match average of another light field.

Parameters:

other_light (Light) – Reference light field

Return type:

None

Examples

>>> target = Light(dim=(1,1,1024,1024), pitch=6.4e-6, wvl=633e-9)
>>> light.adjust_amplitude_to_other_light(target)
load_image(image_path, random_phase=False, std=3.141592653589793, distribution='uniform', batch_idx=None)[source]

Load image as amplitude pattern with optional random phase.

Parameters:
  • image_path (str) – Path to image file.

  • random_phase (bool, optional) – Whether to apply random phase. Defaults to False.

  • std (float, optional) – Standard deviation for phase randomness. For gaussian: Standard deviation in radians For uniform: Half-width of uniform distribution in radians For von_mises: Inverse of concentration parameter (1/κ) Defaults to π.

  • distribution (str, optional) – Type of random distribution. Must be one of [‘gaussian’, ‘uniform’, ‘von_mises’]. Defaults to ‘uniform’.

  • batch_idx (int, optional) – Specific batch index to load the image into. If None, loads the image into all batches. Defaults to None.

Return type:

None

Examples

>>> light.load_image("target.png")  # No random phase, all batches
>>> light.load_image("target.png", random_phase=True)  # Default uniform, all batches
>>> light.load_image("target.png", random_phase=True, std=torch.pi/4)
>>> light.load_image("target.png", random_phase=True, distribution='gaussian')
>>> light.load_image("target.png", batch_idx=0)  # Load only into first batch
visualize(b=0, c=None, uniform_scale=False, vmin=None, vmax=None, fix_noise=True, amp_threshold=1e-05)[source]

Visualize amplitude, phase, and intensity of light field with improved noise handling.

Parameters:
  • b (int) – Batch index

  • c (int, optional) – Channel index

  • uniform_scale (bool) – Use same scale for all channels

  • vmin (float, optional) – Intensity plot range

  • vmax (float, optional) – Intensity plot range

  • fix_noise (bool) – Whether to fix numerical noise in amplitude visualization

  • amp_threshold (float) – Threshold for detecting uniform amplitude with noise

Return type:

None

Examples

>>> light.visualize()  # Show all channels
>>> light.visualize(c=0)  # Show only first channel
>>> light.visualize(uniform_scale=True)  # Use uniform scaling
>>> light.visualize(fix_noise=False)  # Don't fix numerical noise
>>> light.visualize(b=1)  # Visualize the second batch
visualize_image(b=0)[source]

Visualize amplitude, phase, and intensity as RGB images.

Parameters:

b (int) – Batch index to visualize

Return type:

None

Examples

>>> light.visualize_image()
>>> light.visualize_image(b=1)  # Visualize the second batch
shape()[source]

Return shape of light wavefront.

Returns:

Shape of the field tensor

Return type:

tuple

Examples

>>> shape = light.shape()
load(fn)[source]

Load light field from file.

Parameters:

fn (str) – Filename (.pt, .pth, .npy or .mat)

Return type:

None

Examples

>>> light.load("field.pt")  # Load PyTorch format
>>> light.load("field.npy")  # Load NumPy format
>>> light.load("field.mat")  # Load MATLAB format