Initializers

Contains functions to sensibly initialize reconstructions

The functions in this module both do the geometric calculations needed to initialize the reconstrucions, and the heuristic calculations for geierating sensible initializations for the probe guess.

cdtools.tools.initializers.exit_wave_geometry(det_basis, det_shape, wavelength, distance, oversampling=1)

Returns an exit wave basis and shape, as well as a detector slice for the given detector geometry

It takes in the parameters for a given detector - the basis defining the pixel pitch and the shape, as well as the wavelength and propagation distance. Optionally, it accepts a defined “center”, the zero-frequency pixel’s location. It then will automatically define a larger detector if necessary, define the exit wave basis associated with a far-field diffraction experiment, and return that basis, shape, and detector slice

Parameters:

  • det_basis (torch.Tensor) – The detector basis, as defined elsewhere

  • det_shape (torch.Size) – The (i,j) shape of the detector

  • wavelength (float)) – The wavelength of light for the experiment, in m

  • distance (float) – The sample-detector distance, in m

  • oversampling (int) – Default is 1, the amount to multiply the exit wave shape by.

Returns:

basis – The exit wave basis

Return type:

torch.Tensor

cdtools.tools.initializers.calc_object_setup(probe_shape, translations, padding=0)

Returns an object shape and minimum pixel translation

Based on the given pixel-space translations, it will calculate the required size for an object array and calculate the pixel translation that corresponds to a shift by (0,0) of the probe.

Optionally a small extra border can be defined via the padding attribute. If this is done, the calculated pixel translation will correspond to (padding,padding)

Parameters:

  • probe_shape (torch.Size) – The size of the probe array

  • translations (torch.Tensor) – A Jx2 stack of pixel-valued (i,j) translations

  • padding (int) – Optional, the size of an extra border to include

Returns:

  • obj_shape (torch.Size) – The minimum required size of the object array

  • min_translation (torch.Tensor) – The minimum pixel-valued translation

cdtools.tools.initializers.gaussian(shape, sigma, amplitude=1, center=None, curvature=[0, 0])

Returns an array with a centered Gaussian

Takes in the shape and standard deviation of a gaussian and returns a complex torch tensor (trailing dimension is 2) with values corresponding to a two-dimensional gaussian function

Note that [0, 0] is taken to be at the upper left corner of the array. Default is centered at ((shape[0]-1)/2, (shape[1]-1)/2)) because x and y are zero-indexed. By default, the phase is uniformly 0, however a curvature can be specified to simulate a probe that has been propagated a known distance from it’s focal point. The curvature is implemented by adding a quadratic phase phi = exp(i*curvature/2 r^2) to the Gaussian

Parameters:

  • shape (array) – A 1x2 array specifying the dimensions of the output array in the form (i shape, j shape)

  • sigma (array) – A 1x2 array specifying the i- and j- standard deviation of the gaussian in the form (i stdev, j stdev)

  • amplitude (float) – Default 1, the amplitude the gaussian to simulate

  • center (array) – Optional, a 1x2 array specifying the location of the center of the gaussian (i center, j center)

  • curvature (array) – Optional, a complex part to add to the gaussian coefficient

Returns:

The complex-style tensor storing the Gaussian

Return type:

torch.Tensor

cdtools.tools.initializers.gaussian_probe(dataset, basis, shape, sigma, propagation_distance=0, polarized=False, left_polarized=True)

Initializes a gaussian probe based on experimental parameters

This function generates a gaussian probe initialization which has a total fluence matching the order of magnitude of the intensity in the observed dataset, provided the object function is of order 1.

The initialization is done using parameters defined in physical units, such as sigma (in meters) and the propagation distance (in meters). The internal conversion to pixel space is done with a provided probe basis and probe shape.

TODO: Should be updated to accept a mask

Sigma can be provided either as a scalar for a uniform beam, or as an iterable of length 2 with [sigma_i, sigma_j] being the components of sigma in the directions parallel to the i and j basis vectors of the probe basis

Parameters:

  • dataset (Ptycho_2D_Dataset) – The dataset whose intensity we want to match

  • basis (array) – The real space basis for exit waves in our experiment

  • shape (array) – The shape of the simulated real space arrays

  • sigma (array) – The standard deviation of the probe at it’s focus

  • propagation_distance (float) – Default 0, a distance to propagate the gaussian from it’s focus

Returns:

The complex-style tensor storing the Gaussian

Return type:

torch.Tensor

cdtools.tools.initializers.SHARP_style_probe(dataset, propagation_distance=None, oversampling=1)

Generates a SHARP style probe guess from a dataset

What we call the “SHARP” style probe guess is to take a mean of all the diffraction patterns and use that as an initial guess of the Fourier space distribution of the probe. We set all the phases to zero, which would for many simple beams (like a zone plate) generate a first guess of the probe that is very close to the focal spot of the probe beam.

If the probe is simulated in higher resolution than the detector, a common occurence, these undefined pixels are set to zero for the purposes of defining the guess

We make a small tweak to this procedure to lower the central pixel of the probe generated this way, which can often overwhelm the rest of the probe if there is significant noise on the detector

Parameters:

  • dataset (Ptycho_2D_Dataset) – The dataset to work from

  • propagation_distance (float) – Default is no propagation, an amount to propagate the guessed probe from it’s focal point

  • oversampling (int) – Default 1, the width of the region of pixels in the wavefield to bin into a single detector pixel

Returns:

The complex-style tensor storing the probe guess

Return type:

torch.Tensor

cdtools.tools.initializers.STEM_style_probe(dataset, shape, det_slice, convergence_semiangle, propagation_distance=None, oversampling=1)

Generates a STEM style probe guess from a dataset

What we call the “STEM” style probe guess is a probe generated by a uniform aperture in Fourier space, with no optical aberrations. This is the kind of probe than an ideal, aberration-corrected STEM with perfect coherence would produce, so it is a good starting guess for STEM datasets.

We set the initial intensity of the probe with relation to the diffraction patterns so that a typical object will have an intensity of around 1. We also set the initial phase ramp of the probe such that the undiffracted probe has a centroid on the detector which matches the centroid of the diffraction patterns

Parameters:

  • dataset (Ptycho_2D_Dataset) – The dataset to work from

  • shape (torch.Size) – The size of the probe array to simulate

  • det_slice (slice) – A slice or tuple of slices corresponding to the detector region in Fourier space

  • convergence_angle (float) – The convergence angle of the probe, in mrad.

  • propagation_distance (float) – Default is no propagation, an amount to propagate the guessed probe from it’s focal point

  • oversampling (int) – Default 1, the width of the region of pixels in the wavefield to bin into a single detector pixel

Returns:

The complex-style tensor storing the probe guess

Return type:

torch.Tensor

cdtools.tools.initializers.generate_subdominant_modes(dominant_mode, n_modes, circular=True)

Generates guesses of subdominant modes based on spatial derivatives

The idea here is that vibration is an extremely common cause of spatial incoherence. This typically presents as subdominant modes that look like the derivative of the dominant mode along various axes.

Therefore, it is a good starting guess if the guess of the dominant mode is reasonable. The output probes will all be normalized to have the same intensity as the input dominant probe

Parameters:

  • dominant_mode (array) – The complex-valued dominant mode to work from

  • n_modes (int) – The number of additional modes to create

  • circular (bool) – Default True, whether to use circular modes (x+iy) or linear (x,y)

Returns:

The complex-style tensor storing the probe guesses

Return type:

torch.Tensor