hologradpy.torch_functions¶

Module containing PyTorch-specific functions to perform conjugate gradient minimisation.

Classes¶

`ASM`	This class models the propagation of light from the SLM to the Fourier lens and from the Fourier lens to the image
`VirtualSlm`	This class models pixel crosstalk on the SLM and the propagation of light from the SLM to the camera.
`PhaseRetrieval`	This function calculates the SLM phase pattern for a given target light potential in the image plane using conjugate

Functions¶

`check_device`([verbose])	Check if GPU is available.
`gpu_to_numpy`(gpu_tensor)
`fft`(e_in[, shift, norm])	Performs the FFT.
`ifft`(e_in[, shift, norm])	Performs the IFFT.
`asm`(e_in, e_lens, theta1[, theta2, shift])	Performs the angular spectrum method (ASM) twice, from the SLM to the Fourier lens and from the Fourier lens to the
`rms`(signal, i_target, i_out, frac)	Calculate normalised root-mean-squared error between two images inside a region of interest. Only pixels which are
`eff`(signal, i_out)	Calculates the predicted efficiency of a light potential by dividing the pixel sum in the signal region by
`loss_fn_fid`(e_out, i_tar, phi_tar, signal)	Phase and amplitude cost function from https://doi.org/10.1364/OE.25.011692.
`loss_fn_amp`(e_out, i_tar, signal)	Amplitude-only cost function from https://doi.org/10.1364/OE.22.026548.
`camera_calibration`(slm_obj, slm_disp_obj, cam_obj, pms_obj)	This function performs the camera calibration to obtain the coordinate transform between
`camera_feedback`(phase_retrieval_obj, slm_disp_obj, ...)	This function implements a camera feedback algorithm to reduce experimental errors in the light potentials

Module Contents¶

hologradpy.torch_functions.check_device(verbose=None)¶

Check if GPU is available.

Parameters:: verbose (bool) – Verbose output?
Returns:: ‘cuda’ if GPU available, otherwise ‘cpu’.

hologradpy.torch_functions.gpu_to_numpy(gpu_tensor)¶

hologradpy.torch_functions.fft(e_in, shift=True, norm=None)¶

Performs the FFT.

Parameters:

e_in – Input electric field.
shift (bool) – Perform FFT shift?
norm – Normalisation of FFT.

Returns:

FFT of e_in.

hologradpy.torch_functions.ifft(e_in, shift=True, norm=None)¶

Performs the IFFT.

Parameters:

e_in – Input electric field.
shift (bool) – Perform IFFT shift?
norm – Normalisation of IFFT.

Returns:

IFFT of e_in.

hologradpy.torch_functions.asm(e_in, e_lens, theta1, theta2=None, shift=True)¶

Performs the angular spectrum method (ASM) twice, from the SLM to the Fourier lens and from the Fourier lens to the camera.

Parameters:

e_in – Electric field at the SLM.
e_lens – Electric field of the lens (phase and aperture).
theta1 – Propagation phase from SLM to lens.
theta2 – Propagation phase from lens to camera. If not provided it is assumed theta2 = theta1.
shift (bool) – Perform FFT shift?

Returns:

Electric field at the camera.

class hologradpy.torch_functions.ASM(slm_disp_obj, pms_obj, pix_res, npix_tot, pd1, pd2, extent_lens, xf, shift=False, precision='single', device='cuda')¶

This class models the propagation of light from the SLM to the Fourier lens and from the Fourier lens to the image plane using the angular spectrum method. The lens is modelled as a doublet. The ASM wavefront correction is also calculated in this class.

theta1¶

theta2¶

shift = False¶

e_lens¶

phi_corr_native¶

phi_corr¶

forward(e_in)¶

This function performs the simulation.

Parameters:: e_in – Electric field at the SLM plane.
Returns:: Electric field at the image plane.

class hologradpy.torch_functions.VirtualSlm(slm_disp_obj, pms_obj, phi, npix_pad, npix=None, e_slm=None, kernel_ct=None, pix_res=None, propagation_type='fft', extent_lens=None, pd1=None, pd2=None, xf=None, device='cpu', slm_mask=None, precision=None, fft_shift=True)¶

Bases: torch.nn.Module

This class models pixel crosstalk on the SLM and the propagation of light from the SLM to the camera.

slm_disp_obj¶

pms_obj¶

precision = None¶

dtype_r¶

dtype_c¶

fft_shift = True¶

device = 'cpu'¶

npix_pad¶

pix_res = None¶

npix_full¶

propagation_type = 'fft'¶

npix = None¶

e_slm¶

slm_mask¶

pad¶

counter = 0¶

phi_disp¶

set_phi(new_phi)¶

Set SLM phase from numpy array.

Parameters:: new_phi (ndarray) – SLM phase [rad].

forward()¶

Model the SLM and simulate the propagation of light from the SLM plane to the image plane. This method is used by gradient-based optimizers.

Returns:: Electric field in the image plane.

hologradpy.torch_functions.rms(signal, i_target, i_out, frac)¶

Calculate normalised root-mean-squared error between two images inside a region of interest. Only pixels which are brighter than frac * np.max(i_target_norm) are taken into account, where i_target_norm is the normalised target intensity pattern.

Parameters:

signal – Binary mask containing region of interest (signal region).
i_target – Target intensity pattern.
i_out – Intensity pattern of light potential.
frac – Threshold as explained above.

Returns:

Normalised rms error.

hologradpy.torch_functions.eff(signal, i_out)¶

Calculates the predicted efficiency of a light potential by dividing the pixel sum in the signal region by the pixel sum in the entire pattern.

Parameters:

signal – Binary mask containing the signal region.
i_out – Intensity pattern of the light potential.

Returns:

Predicted efficiency.

hologradpy.torch_functions.loss_fn_fid(e_out, i_tar, phi_tar, signal)¶

Phase and amplitude cost function from https://doi.org/10.1364/OE.25.011692.

Parameters:

e_out – Electric field at the image plane.
i_tar – Target intensity pattern.
phi_tar – Target phase pattern.
signal – Binary mask containing signal region.

Returns:

Cost.

hologradpy.torch_functions.loss_fn_amp(e_out, i_tar, signal)¶

Amplitude-only cost function from https://doi.org/10.1364/OE.22.026548.

Parameters:

e_out – Electric field at the image plane.
i_tar – Target intensity pattern.
signal – Binary mask containing signal region.

Returns:

Cost.

class hologradpy.torch_functions.PhaseRetrieval(slm_obj, n_iter=10, i_tar=None, phi_tar=None, signal_region=None, save=False, n_save=10, loss_type='amp', optim_type='cg')¶

This function calculates the SLM phase pattern for a given target light potential in the image plane using conjugate gradient minimisation or stochastic gradient descent (Adam).

slm_obj¶

signal = None¶

i_tar = None¶

fft_shift¶

phi_tar = None¶

phi_tar_t¶

signal_t¶

i_tar_t¶

save = False¶

n_save = 10¶

n_iter = 10¶

loss = 0¶

closure_counter = 0¶

callback_counter = 0¶

phi = []¶

eta_pred = []¶

eff_pred = []¶

loss_type = 'amp'¶

optim_type = 'cg'¶

optimizer = None¶

set_target(target)¶

Sets the target light potential.

Parameters:: target – Target light potential.

set_optimizer()¶: Sets the optimisation algorithm based on self.optim_type.

loss_fn(e_out)¶

Defines the loss function based on self.loss_type.

Parameters:: e_out – Electric field at the image plane.
Returns:: Loss value.

callback(x)¶: This function is called after every iteration of the optimisation. It saves intermediate SLM phase patterns and the electric field in the image plane if save=True. The progress of the optimisation is printed after every iteration.

retrieve_phase()¶

Performs phase retrieval algorithm.

Returns:: Optimised SLM phase(s), (RMS error and efficiency if save=True)

hologradpy.torch_functions.camera_calibration(slm_obj, slm_disp_obj, cam_obj, pms_obj, save=None, exp_time=None, checkerboard_rows=None, checkerboard_columns=None, checkerboard_square_size=None, linear_phase=None)¶

This function performs the camera calibration to obtain the coordinate transform between the camera image and the computational image plane. To do this, an SLM phase pattern is calculated for a checkerboard-shaped target light potential using CG minimisation and displayed on the SLM. The corners of the checkerboard in the resulting camera image are detected and fitted to the corners of the checkerboard in the computational image plane using an affine transformation.

Parameters:

slm_obj – Virtual SLM object created by VirtualSlm.
slm_disp_obj – Object created by a subclass of hardware.SlmBase.
cam_obj – Object created by a subclass of hardware.CameraBase.
pms_obj – Object created by a subclass of hardware.ParamsBase.
save (bool) – Save data?
exp_time – Exposure time.
checkerboard_rows –
checkerboard_columns –
checkerboard_square_size –
linear_phase –

Returns:

hologradpy.torch_functions.camera_feedback(phase_retrieval_obj, slm_disp_obj, cam_obj, tf, itf, iter_fb=1, iter_cg=None, detect_vortices=False, threshold_vtx=0.2, n_save=10, n_avg=10, exp_time=1000, fb_blur=0, alpha=None, convergence=False, iter_convergence=None, path=None)¶

This function implements a camera feedback algorithm to reduce experimental errors in the light potentials (see https://dx.doi.org/10.1088/0953-4075/48/11/115303). Before applying any camera feedback, optical vortices in the light potential are detected using the patterns.detect_vortices() function and removed if required.

After vortices are removed, the optimised phase pattern is displayed on the SLM and a camera image, M, is recorded. To create the target light potential for the next feedback iteration, T[…, i + 1], a discrepancy, D, between the camera image and the original target light potential, T[…, 0], is calculated and added to the previous light potential, T[…, i].

At the end of each feedback iteration, the root-mean-squared error (RMSE) and the peak signal-to-noise ratio (PSNR) of the camera image are calculated and saved. To find the experimental convergence of the CG minimisation, intermediate SLM phase patterns are saved and displayed on the SLM. A camera image is taken for each pattern and the RMSE is calculated.

Parameters:

phase_retrieval_obj – Instance of the class PhaseRetrieval.
slm_disp_obj – Object created by a subclass of hardware.SlmBase.
cam_obj – Object created by a subclass of hardware.CameraBase.
tf – Affine transform matrix.
itf – Inverse affine transform matrix.
iter_fb – Number of feedback iterations.
iter_cg – Number of conjugate gradient iterations per feedback iteration.
detect_vortices (bool) – Detect vortices?
threshold_vtx – See patterns.detect_vortices()
n_save – Save data for every n_save th CG iteration.
n_avg – Number of camera frames to capture and average per feedback iteration.
exp_time – Exposure time.
fb_blur – Width of blurring kernel for camera image [px].
alpha – Feedback gain parameter for each feedback iteration.
convergence (bool) – Save intermediate phase patterns during CG minimisation?
iter_convergence – During which feedback iterations to save intermediate phase patterns.
path – Save path.

Returns:

See code.