prysm.propagation#
Numerical optical propagation.
- prysm.propagation.focus(wavefunction, Q)#
Propagate a pupil plane to a PSF plane.
- Parameters
wavefunction (numpy.ndarray) – the pupil wavefunction
Q (float) – oversampling / padding factor
- Returns
psf – point spread function
- Return type
numpy.ndarray
- prysm.propagation.unfocus(wavefunction, Q)#
Propagate a PSF plane to a pupil plane.
- Parameters
wavefunction (numpy.ndarray) – the pupil wavefunction
Q (float) – oversampling / padding factor
- Returns
pupil – field in the pupil plane
- Return type
numpy.ndarray
- prysm.propagation.focus_fixed_sampling(wavefunction, input_dx, prop_dist, wavelength, output_dx, output_samples, shift=(0, 0), method='mdft')#
Propagate a pupil function to the PSF plane with fixed sampling.
- Parameters
wavefunction (numpy.ndarray) – the pupil wavefunction
input_dx (float) – spacing between samples in the pupil plane, millimeters
prop_dist (float) – propagation distance along the z distance
wavelength (float) – wavelength of light
output_dx (float) – sample spacing in the output plane, microns
output_samples (int) – number of samples in the square output array
shift (tuple of float) – shift in (X, Y), same units as output_dx
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
- Returns
data – 2D array of data
- Return type
numpy.ndarray
- prysm.propagation.unfocus_fixed_sampling(wavefunction, input_dx, prop_dist, wavelength, output_dx, output_samples, shift=(0, 0), method='mdft')#
Propagate an image plane field to the pupil plane with fixed sampling.
- Parameters
wavefunction (numpy.ndarray) – the image plane wavefunction
input_dx (float) – spacing between samples in the pupil plane, millimeters
prop_dist (float) – propagation distance along the z distance
wavelength (float) – wavelength of light
output_dx (float) – sample spacing in the output plane, microns
output_samples (int) – number of samples in the square output array
shift (tuple of float) – shift in (X, Y), same units as output_dx
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
- Returns
x (numpy.ndarray) – x axis unit, 1D ndarray
y (numpy.ndarray) – y axis unit, 1D ndarray
data (numpy.ndarray) – 2D array of data
- prysm.propagation.Q_for_sampling(input_diameter, prop_dist, wavelength, output_dx)#
Value of Q for a given output sampling, given input sampling.
- Parameters
input_diameter (float) – diameter of the input array in millimeters
prop_dist (float) – propagation distance along the z distance, millimeters
wavelength (float) – wavelength of light, microns
output_dx (float) – sampling in the output plane, microns
- Returns
requesite Q
- Return type
float
- prysm.propagation.pupil_sample_to_psf_sample(pupil_sample, samples, wavelength, efl)#
Convert pupil sample spacing to PSF sample spacing. fλ/D or Q.
- Parameters
pupil_sample (float) – sample spacing in the pupil plane
samples (int) – number of samples present in both planes (must be equal)
wavelength (float) – wavelength of light, in microns
efl (float) – effective focal length of the optical system in mm
- Returns
the sample spacing in the PSF plane
- Return type
float
- prysm.propagation.psf_sample_to_pupil_sample(psf_sample, samples, wavelength, efl)#
Convert PSF sample spacing to pupil sample spacing.
- Parameters
psf_sample (float) – sample spacing in the PSF plane
samples (int) – number of samples present in both planes (must be equal)
wavelength (float) – wavelength of light, in microns
efl (float) – effective focal length of the optical system in mm
- Returns
the sample spacing in the pupil plane
- Return type
float
- prysm.propagation.fresnel_number(a, L, lambda_)#
Compute the Fresnel number.
Notes
if the fresnel number is << 1, paraxial assumptions hold for propagation
- Parameters
a (float) – characteristic size (“radius”) of an aperture
L (float) – distance of observation
lambda (float) – wavelength of light, same units as a
- Returns
the fresnel number for these parameters
- Return type
float
- prysm.propagation.talbot_distance(a, lambda_)#
Compute the talbot distance.
- Parameters
a (float) – period of the grating, units of microns
lambda (float) – wavelength of light, units of microns
- Returns
talbot distance, units of microns
- Return type
float
- prysm.propagation.angular_spectrum(field, wvl, dx, z, Q=2, tf=None)#
Propagate a field via the angular spectrum method.
- Parameters
field (numpy.ndarray) – 2D array of complex electric field values
wvl (float) – wavelength of light, microns
z (float) – propagation distance, units of millimeters
dx (float) – cartesian sample spacing, units of millimeters
Q (float) – sampling factor used. Q>=2 for Nyquist sampling of incoherent fields
tf (numpy.ndarray) – if not None, clobbers all other arguments transfer function for the propagation
- Returns
2D ndarray of the output field, complex
- Return type
numpy.ndarray
- prysm.propagation.angular_spectrum_transfer_function(samples, wvl, dx, z)#
Precompute the transfer function of free space.
- Parameters
samples (int or tuple) – (y,x) or (r,c) samples in the output array
wvl (float) – wavelength of light, microns
dx (float) – intersample spacing, mm
z (float) – propagation distance, mm
- Returns
ndarray of shape samples containing the complex valued transfer function such that X = fft2(x); xhat = ifft2(X*tf) is signal x after free space propagation
- Return type
numpy.ndarray
- class prysm.propagation.Wavefront(cmplx_field, wavelength, dx, space='pupil')#
Bases:
object
(Complex) representation of a wavefront.
- classmethod from_amp_and_phase(amplitude, phase, wavelength, dx)#
Create a Wavefront from amplitude and phase.
- Parameters
amplitude (numpy.ndarray) – array containing the amplitude
phase (numpy.ndarray, optional) – array containing the optical path error with units of nm if None, assumed zero
wavelength (float) – wavelength of light with units of microns
dx (float) – sample spacing with units of mm
- classmethod thin_lens(f, wavelength, x, y)#
Create a thin lens, used in focusing beams.
Users are encouraged to not use thin lens + free space propagation to take beams to their focus. In nearly all cases, a different propagation scheme is significantly more computational efficient. For example, just using the wf.focus() method. If you have access to the (unwrapped) phase, it is also cheaper to compute the quadratic phase you want and add that before wf.from_amp_and_phase) instead of multiplying by a thin lens.
- Parameters
f (float) – focal length of the lens, millimeters
wavelength (float) – wavelength of light, microns
x (numpy.ndarray) – x coordinates that define the space of the lens, mm
y (numpy.ndarray) – y coordinates that define the space of the beam, mm
- Returns
a wavefront object having quadratic phase which, when multiplied by another wavefront acts as a thin lens
- Return type
- property intensity#
Intensity, abs(w)^2.
- property phase#
Phase, angle(w). Possibly wrapped for large OPD.
- copy()#
Return a (deep) copy of this instance.
- pad2d(Q, value=0, mode='constant', out_shape=None, inplace=True)#
Pad the wavefront.
- Parameters
array (numpy.ndarray) – source array
Q (float, optional) – oversampling factor; ratio of input to output array widths
value (float, optioanl) – value with which to pad the array
mode (str, optional) – mode, passed directly to np.pad
out_shape (tuple) – output shape for the array. Overrides Q if given. in_shape * Q ~= out_shape (up to integer rounding)
inplace (bool, optional) – if True, mutate this wf and return it, else create a new wf with cropped data
- Returns
wavefront with padded data
- Return type
- crop(out_shape, inplace=True)#
Crop the wavefront to the centermost (out_shape).
- Parameters
out_shape (int or tuple of (int, int)) – the output shape (aka number of pixels) to crop to.
inplace (bool, optional) – if True, mutate this wf and return it, else create a new wf with cropped data if out-of-place, will share memory with self via overlap of data
- Returns
cropped wavefront
- Return type
- free_space(dz=nan, Q=1, tf=None)#
Perform a plane-to-plane free space propagation.
Uses angular spectrum and the free space kernel.
- Parameters
dz (float) – inter-plane distance, millimeters
Q (float) – padding factor. Q=1 does no padding, Q=2 pads 1024 to 2048.
tf (numpy.ndarray) – if not None, clobbers all other arguments transfer function for the propagation
- Returns
the wavefront at the new plane
- Return type
- focus(efl, Q=2)#
Perform a “pupil” to “psf” plane propgation.
Uses an FFT with no quadratic phase.
- Parameters
efl (float) – focusing distance, millimeters
Q (float) – padding factor. Q=1 does no padding, Q=2 pads 1024 to 2048. To avoid aliasng, the array must be padded such that Q is at least 2 this may happen organically if your data does not span the array.
- Returns
the wavefront at the focal plane
- Return type
- unfocus(efl, Q=2)#
Perform a “psf” to “pupil” plane propagation.
uses an FFT with no quadratic phase.
- Parameters
efl (float) – un-focusing distance, millimeters
Q (float) – padding factor. Q=1 does no padding, Q=2 pads 1024 to 2048. To avoid aliasng, the array must be padded such that Q is at least 2 this may happen organically if your data does not span the array.
- Returns
the wavefront at the pupil plane
- Return type
- focus_fixed_sampling(efl, dx, samples, shift=(0, 0), method='mdft')#
Perform a “pupil” to “psf” propagation with fixed output sampling.
Uses matrix triple product DFTs to specify the grid directly.
- Parameters
efl (float) – focusing distance, millimeters
dx (float) – output sample spacing, microns
samples (int) – number of samples in the output plane. If int, interpreted as square else interpreted as (x,y), which is the reverse of numpy’s (y, x) row major ordering
shift (tuple of float) – shift in (X, Y), same units as output_dx
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
- Returns
the wavefront at the psf plane
- Return type
- unfocus_fixed_sampling(efl, dx, samples, shift=(0, 0), method='mdft')#
Perform a “psf” to “pupil” propagation with fixed output sampling.
Uses matrix triple product DFTs to specify the grid directly.
- Parameters
efl (float) – un-focusing distance, millimeters
dx (float) – output sample spacing, millimeters
samples (int) – number of samples in the output plane. If int, interpreted as square else interpreted as (x,y), which is the reverse of numpy’s (y, x) row major ordering
shift (tuple of float) – shift in (X, Y), same units as output_dx
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
- Returns
wavefront at the pupil plane
- Return type
- to_fpm_and_back(efl, fpm, fpm_dx=None, method='mdft', return_more=False)#
Propagate to a focal plane mask, apply it, and return.
This routine handles normalization properly for the user.
To invoke babinet’s principle, simply use to_fpm_and_back(fpm=1 - fpm).
- Parameters
efl (float) – focal length for the propagation
fpm (Wavefront or numpy.ndarray) – the focal plane mask
fpm_dx (float) – sampling increment in the focal plane, microns; do not need to pass if fpm is a Wavefront
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
return_more (bool) – if True, return (new_wavefront, field_at_fpm, field_after_fpm) else return new_wavefront
- Returns
new wavefront, [field at fpm, field after fpm]
- Return type
- babinet(efl, lyot, fpm, fpm_dx=None, method='mdft', return_more=False)#
Propagate through a Lyot-style coronagraph using Babinet’s principle.
This routine handles normalization properly for the user.
To invoke babinet’s principle, simply use to_fpm_and_back(fpm=1 - fpm).
- Parameters
efl (float) – focal length for the propagation
lyot (Wavefront or numpy.ndarray) – the Lyot stop; if None, equivalent to ones_like(self.data)
fpm (Wavefront or numpy.ndarray) – 1 - fpm one minus the focal plane mask (see Soummer et al 2007)
fpm_dx (float) – sampling increment in the focal plane, microns; do not need to pass if fpm is a Wavefront
method (str, {'mdft', 'czt'}) – how to propagate the field, matrix DFT or Chirp Z transform CZT is usually faster single-threaded and has less memory consumption MDFT is usually faster multi-threaded and has more memory consumption
return_more (bool) – if True, return each plane in the propagation else return new_wavefront
- Returns
field after lyot, [field at fpm, field after fpm, field at lyot]
- Return type