ptyrad.params.constraint_params

Contents

ptyrad.params.constraint_params#

Defines available options and validation rules for the constraint_params dictionary.

pydantic model ptyrad.params.constraint_params.ConstraintParams[source]#

Bases: BaseModel

Generally, these constraint functions are applied after each (or a couple) iteration(s) to stabilize the optimization trajectories When applied, the target tensor is passed through the constraint function, and the tensor get directly modified by the constraint function Set ‘start_iter’ to a positive integer to specify when do we want to apply such constraint, and setting ‘start_iter’ to ‘null’ would disable that constraint. ‘step’ can be set to specify the interval of applying those constraints when (niter - start_iter) % step == 0. ‘end_iter’ can be used to specify when to stop applying such constraint. Note that end_iter is exclusive, so if end_iter: 20, the constraint would not be applied at the end of Iter: 20. Most constraints are designed specifically for an optimizable tensor to make sure they’re following some arbitrary preference In other words, we typically choose the constraints according to our optimizable tensors. For example, we need ‘ortho_pmode’ if we’re optimizing mixed-state probe. Similarly, we need either ‘obj_zblur’ or ‘kz_filter’ to stabilize the multislice ptychography reconstruciton along z-direction. A common combination of constrains for mixed-state probe multislice ptychography would be ‘ortho_pmode’, ‘fix_probe_int’, ‘kz_filter’, and ‘objp_postiv’

Fields:
param ortho_pmode: OrthoPmode [Optional]#

Apply a SVD decomposition and orthogonalization of the mixed-state probe similar to the PtychoShelves implementation (except it’s vectorized in PtyRAD). Turn this on when optimizing with mixed-state probe

param probe_mask_k: ProbeMaskK [Optional]#

Apply a k-space sigmoid (similar to a top-hat) probe mask that cut off spatial frequencies beyond the probe-forming aperture. This prevents the probe from absorbing the object structure in k-space. It might cause high-frequency oscillations in the real-space object, if you have strong diffuse background in the diffraction pattern and did not provide mixed-object to properly reproduce it. Recommend setting it to ‘null’ unless you’re pursuing mixed-object with more physical probes. k-radius should be larger than 2*rbf/Npix to avoid cutting out the BF disk. ‘radius’ and ‘width’ are used to define the sigmoid funciton in relative unit with kMax. See ‘utils/make_sigmoid_mask’ for more details. ‘power_thresh’ is used to specify how far into the pmode should be masked. If ‘power_thresh’: 0.95, the k-space mask would be applied from strongest probe modes to the one that adds uo to 95% total intensity. This promotes a more physical mixed-probe while keeping a small fraction of probe modes to absorb unexpected errors.

param probe_mask_r: ProbeMaskR [Optional]#

Apply a real-space super-Gaussian (similar to a top-hat) probe mask that apodize (i.e., windowing) the real space probe. This is useful for mitigating the real space corner / edge artifact, or the checkerboard artifact in k-space probe amplitude that comes from resampling model DP when simu_Npix > meas_Npix. Use ‘radius’ and ‘order’ to adjust the shape of the super-Gaussian mask. To prevent cutting off probe when it’s defocused, we roll the probe back to focal plane and apply the mask there, and then propagate the probe back to its original defocus. ‘z_range’ and ‘z_steps’ are used to assign the search space for focal plane, typically a +-50 nm with 1 nm step (i.e., 101 steps) is enough. ‘power_thresh’ is used to specify how far into the pmode should be masked. If ‘power_thresh’: 0.95, the k-space mask would be applied from strongest probe modes to the one that adds uo to 95% total intensity. This promotes a more physical mixed-probe while keeping a small fraction of probe modes to absorb unexpected errors. Because windowing in real-space is equivalent to blurring in the k-space, this mitigates the corner and edge artifact intensities in probe window, while also simultaneously blur the k-space probe slightly. A signal can not be perfectly bounded in both real and Fourier domains, since probe is physically bounded by probe-forming-aperture in k-space, the real-space probe is mathematically infinitely wide and probe tails never decays to 0. Therefore, this constraint will ALWAYS cut off some probe tails and may inadvertently cause more artifacts, use it with caution.

param fix_probe_int: FixProbeInt [Optional]#

Rescale the probe intensity to make it consistent with the total diffraction pattern intensity (so every probe electron hits on the detector). This is needed to stabilize the object amplitude update because the probe update could potentially change the total intensity. This removes the scaling constant ambiguity between probe and object, and should be applied if you’re simultaneously optimizing the probe and object amplitude

param obj_rblur: ObjRblur [Optional]#

Apply a “lateral” 2D Gaussian blur to the object. This removes some high frequency noise in the reconstructed object and make the apperance smoother. ‘obj_type’ can be either ‘amplitude’, ‘phase’, or ‘both’ with a specified ‘std’ and ‘kernel_size’ in unit of real-space px. Ideally kernel size is odd (like 5) and larger than 6std+1 so it decays to 0. This is usually not needed if your dataset contains sufficient dose and the kMax is not insanely high (extremely high kMax would gives very fine dx which makes feature appear sharper and probably more seemingly noisy)

param obj_zblur: ObjZblur [Optional]#

Apply a “z-direction” 1D Gaussian blur to the object. This is a real-space alternative to the typical kz_filter (or so called missing-wedge regularization that applies Fourier filtering to the object) designed for multislice ptychography. Similar to ‘obj_rblur’, ‘obj_type’ can be either ‘amplitude’, ‘phase’, or ‘both’ with a specified ‘std’ and ‘kernel_size’ in unit of real-space px. Note that the ‘ptycho/engines/GPU_MS/private/regulation_multilayers.m’ from PtychoShelves (fold_slice) is a combination of ‘obja_thresh’, ‘kr_filter’, and ‘kz_filter’, so you may want to activate all these constraints altogether in PtyRAD to get the most similar effect

param kr_filter: KrFilter [Optional]#

Apply a “lateral” Fourier low-pass filtering to the object. This is similar to the band-pass filter in Digital Micrograph that the k-space filter has a sigmoid-like profile, essentially a cut-off spatial frequency. Typically we’re reconstucting object all the way to kMax (Nyquist frequency), so there’s not much room for us to filter out hence it’s recommended to keep this off unless you want to exclude certain spatial frequencies. ‘radius’ and ‘width’ are used to define the sigmoid funciton in relative unit with kMax. See ‘utils/make_sigmoid_mask’ for more details

param kz_filter: KzFilter [Optional]#

Apply the arctan kz filter just like the ‘regulation_multilayers.m’ in PtychoShelves. ‘beta’ controls the strength of the arctan function and is the same as ‘eng. regularize_layers’ in PtychoShelves. Typical value of ‘beta’ ranges from 0 to 1. ‘alpha’ is the implicit constant controls the lateral Fourier filtering that has similar effect as ‘kr_filter’, usually set as 1 to be consistent with PtychoShelves. Note that ‘kz_filter’ is designed to be a PtyRAD equivalence of the ‘regulation_multilayers.m’ so it also includes the arctan Fourier filer, lateral Fourier filter, and the soft object amplitude thresholding if you set ‘obj_type’ to ‘both’. See ‘optimization/kz_filter’ for more details. While this ‘kz_filter’ works very well for most multislice reconstructions of crystals, you might prefer ‘obj_zblur’ if you have an object that has distinct top and bottom layer like twisted bilayer or tilted systems, because ‘kz_filter’ would introduce intermixing between the top and bottom layer due to the periodic boundary condition of Fourier transform. Another solution to the intermixing is to pad vacuum layers to your object and remove them later, although padding extensive vacuum layers tend to make object phase bleed into the vacuum layers and it’s very hard to set the interface

param kr_thresh: KrThresh [Optional]#

Apply a thresholding to supress weak spatial frequency coefficients of the object along “lateral” (i.e., x, y) directions. ‘thresh’ is the ratio of spatial frequencies to keep and thresh is within (0,1]. Typical ‘thresh’ value is 0.1, meaning keeping 10% of the strongest spatial frequencies and set the others to 0. Smaller ‘thresh’ value will promote sparsity in frequency domain (implemented with DCT) and produce a smoother object with reduced noise. Note that this constraint would also reduce / remove the disorder in periodic objects like strain and atomic defects as it only keep the strong spatial frequencies, so it’s advised to only use it for purely amorphous specimen, low dose reconstructions, or as an initial stabilizing constraint. The DCT is applied to the last 2 dimensions for object array shaped (…,H,W), hence the regularization effect is only within 2D and is sequentially repeated for each depth slice. See https://doi.org/10.1364/OE.551986 for example on low dose biological samples.

param complex_ratio: ComplexRatio [Optional]#

Apply a complex constraint between object amplitude and phase based on https://doi.org/10.1016/j.ultramic.2024.114068 and https://doi.org/10.1364/OE.18.001981. This will constrain the amplitude to as A’ = exp(-C*phase), C is an estimated (adaptive) positive constant, so the amplitude would look similar to phase and strongest phase shift would correspond to less than 1 amplitude. Default value of phase object is alpha1 = 1, alpha2 = 0. Note that the implementation considers the negative correlation between amplitude and phase for electctron ptychography, hence it’s not the exact same formula as in the papers.

param mirrored_amp: MirroredAmp [Optional]#

Apply a more flexible, ad hoc constraint for constraining amplitude using 1-scale*phase**power, which provide more arbitrary parameters to tune the constrained amplitude based on the phase.

param obj_z_recenter: ObjZRecenter [Optional]#

Apply the z-recentering of object based on CoM to keep the object centered within the depth dimension. The probe defocus is adjusted accordingly. thresh is the threshold value in percentile to exclude weaker signals while calculating center-of-mass along depth. The value of thresh should be around 90-95 to target values that are 2-3 sigma away from mean. scale is a multplication scaling factor applied on the measured shift, keep it <= 1 to slowly approach the ideal center. max_shift sets a hard limit on the applied shift, which should be less than half the number of z-slices. The shift is in unit of slices, so shift=1 would re-center the object by 1 slice.

param obja_thresh: ObjaThresh [Optional]#

Apply a thresholding of object amplitude around 1. The threshold is defined by ‘thresh’ and the value is determined by the min and max. Note that wave amplitude is multiplicative when propagating through multislice object, so even an objective amplitude of 0.95 can become 0.6 after 10 layers. The thresholding can be relaxed by the relax param that is a weighted sum betwen the pre-threshold and post-threshold values.

param objp_postiv: ObjpPostiv [Optional]#

Apply a positivity constraint of the object phase, make it non-negative. This clips the negative values (anything below 0) so the object is visually darker but with stronger constrast, it’s suggested to keep it on so that you can interpret, compare, and process your object phase with a simple baseline. Besides, the positivity constraint makes it easier to compare with atomic potential ground truth after correct scaling for the scattering factor. The clipping can be relaxed by the relax param that is a weighted sum betwen the pre-threshold and post-threshold values.

param pos_recenter: PosRecenter [Optional]#

Recenter the probe position shifts by making mean(probe_pos_shifts) = 0 so there’s no global offset from the cropping position. This would keep the probe, probe position, and object relatively fixed in place even with large position learning rates.

param tilt_smooth: TiltSmooth [Optional]#

Apply a lateral Gaussian blur of the local object tilts in unit of “scan positions”. This smoothens the local tilts so that you don’t have drastic changes of object tilts between scan positions.

pydantic model ptyrad.params.constraint_params.OrthoPmode[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = 1#
param step: int | None = 1#
param end_iter: int | None = None#
pydantic model ptyrad.params.constraint_params.ProbeMaskK[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param radius: float = 0.22#
param width: float = 0.05#
param power_thresh: float = 0.95#
pydantic model ptyrad.params.constraint_params.FixProbeInt[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = 1#
param step: int | None = 1#
param end_iter: int | None = None#
pydantic model ptyrad.params.constraint_params.ObjRblur[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = 1#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param kernel_size: int = 5#
param std: float = 0.4#
pydantic model ptyrad.params.constraint_params.ObjZblur[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = 1#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param kernel_size: int = 5#
param std: float = 1.0#
pydantic model ptyrad.params.constraint_params.KrFilter[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param radius: float = 0.15#
param width: float = 0.05#
pydantic model ptyrad.params.constraint_params.KzFilter[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param beta: float = 1.0#
param alpha: float = 1.0#
pydantic model ptyrad.params.constraint_params.KrThresh[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param thresh: float = 0.05#
pydantic model ptyrad.params.constraint_params.ComplexRatio[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param obj_type: Literal['amplitude', 'phase', 'both'] = 'both'#
param alpha1: float = 1.0#
param alpha2: float = 0.0#
pydantic model ptyrad.params.constraint_params.MirroredAmp[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param relax: float = 0.1#
param scale: float = 0.03#
param power: float = 4.0#
pydantic model ptyrad.params.constraint_params.ObjZRecenter[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param thresh: float | None = 95#
param scale: float | None = 1#
param max_shift: float | None = 10#
pydantic model ptyrad.params.constraint_params.ObjaThresh[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param relax: float = 0.0#
param thresh: List[float] = [0.96, 1.04]#
pydantic model ptyrad.params.constraint_params.ObjpPostiv[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param relax: float = 0.0#
pydantic model ptyrad.params.constraint_params.PosRecenter[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = 1#
param step: int | None = 1#
param end_iter: int | None = None#
param relax: float = 0.0#
pydantic model ptyrad.params.constraint_params.TiltSmooth[source]#

Bases: BaseModel

Fields:
param start_iter: int | None = None#
param step: int | None = 1#
param end_iter: int | None = None#
param std: float = 2.0#
Contents