pypty.objective¶
loss_and_direction
¶
Compute the total loss and gradients for ptychographic reconstruction.
This is the core function of PyPty that performs forward and backward propagation, calculates the loss between measured and simulated patterns, and computes the gradients of all active reconstruction parameters (object, probe, positions, tilts, etc.).
| PARAMETER | DESCRIPTION |
|---|---|
this_obj
|
Complex 4D object (current estimate)
TYPE:
|
full_probe
|
Complex probe (y,x,modes) optionally 4D (y,x,modes, scenatios)
TYPE:
|
this_pos_array
|
Integer beam postions in pixels [[y0,x0],.. [yn, xn]]. Note: units are pixels, not angstrom!
TYPE:
|
this_pos_correction
|
Float sub-pixel postions for more precise beam shift. Note: units are pixels, not angstrom!
TYPE:
|
this_tilt_array
|
Beam tilts in radians, shape should be (N_measurements, 6), where first two tilts are applied before the sample, second and third are applied inside (tilted propagator) and two last are applied after the sample
TYPE:
|
this_tilts_correction
|
legacy paramter, actually is not really required. It is a correction that is added to the tilts array.
TYPE:
|
this_distances
|
either just one value for a common slice spacing or list of values for each slice. If object has N slices, it should have N-1 entries.
TYPE:
|
measured_array
|
array or h5-dataset with diffraction patterns. Should be 3D, [N_measurements, y,x]
TYPE:
|
algorithm_type
|
string indicating the loss function (error metric)
|
this_wavelength
|
Electron wavelength in Angstrom
TYPE:
|
this_step_probe
|
do you refine the beam?
TYPE:
|
this_step_obj
|
do you refine the object?
TYPE:
|
this_step_pos_correction
|
do you refine the positions?
|
this_step_tilts
|
do you refine the tilts?
TYPE:
|
masks
|
optional, if the data is compressed, you should provide the 3D array with virtual detectors [N_detectors, y,x].
TYPE:
|
pixel_size_x_A
|
real-space pixel size in x-direction (Angstrom).
TYPE:
|
pixel_size_y_A
|
real-space pixel size in y-direction (Angstrom).
TYPE:
|
recon_type
|
"far_field" or "near_field". Changes the exit-wave propagation regime.
TYPE:
|
Cs
|
Spherical aberration (Angstrom). Only needed for near-field propagation.
TYPE:
|
defocus_array
|
Array of exit-wave defocus values (Angstrom). Only needed for near-field propagation.
TYPE:
|
alpha_near_field
|
Flux-preserving correction for near-field propagation.
TYPE:
|
damping_cutoff_multislice
|
Cutoff (fraction smaller than 1) beyond which the Fouirer-space is cleaned.
TYPE:
|
smooth_rolloff
|
Smooth rolloff for Fourier masking
TYPE:
|
propmethod
|
string indicating the method for split-step integration
TYPE:
|
this_chopped_sequence
|
sequence of measruement indices used for loss and grad calculation (should be sorted)
TYPE:
|
load_one_by_one
|
boolean flag. should be True for lazy loading.
TYPE:
|
data_multiplier
|
multiplicative factor applied to data on the fly.
TYPE:
|
data_pad
|
padding factor applied to data on the fly.
TYPE:
|
phase_plate_in_h5
|
path to h5 dataset containing phase plates for each measurement.
TYPE:
|
this_loss_weight
|
weight applied to the main part of the loss
TYPE:
|
data_bin
|
binning factor applied to data on the fly
TYPE:
|
data_shift_vector
|
shift vector in pixels (y,x) applied to data on the fly
TYPE:
|
upsample_pattern
|
virtual "decompression" of the data used to enlarge the probe window
TYPE:
|
static_background
|
real-valued array descripting the square root of the static offset on the diffraction patterns.
TYPE:
|
this_step_static_background
|
do you refine the static background?
TYPE:
|
tilt_mode
|
flag for tilting
TYPE:
|
aberration_marker
|
TYPE:
|
probe_marker
|
TYPE:
|
aberrations_array
|
TYPE:
|
compute_batch
|
TYPE:
|
phase_only_obj
|
TYPE:
|
beam_current
|
TYPE:
|
this_beam_current_step
|
TYPE:
|
this_step_aberrations_array
|
TYPE:
|
default_float
|
TYPE:
|
default_complex
|
TYPE:
|
xp
|
TYPE:
|
is_first_epoch
|
TYPE:
|
scan_size
|
TYPE:
|
fast_axis_reg_weight_positions
|
TYPE:
|
slow_axis_reg_weight_positions
|
TYPE:
|
slow_axis_reg_weight_tilts
|
TYPE:
|
current_deformation_reg_weight_positions
|
TYPE:
|
current_deformation_reg_weight_tilts
|
TYPE:
|
fast_axis_reg_weight_tilts
|
TYPE:
|
aperture_mask
|
TYPE:
|
probe_reg_weight
|
TYPE:
|
current_window_weight
|
TYPE:
|
current_window
|
TYPE:
|
phase_norm_weight
|
TYPE:
|
abs_norm_weight
|
TYPE:
|
atv_weight
|
TYPE:
|
atv_q
|
TYPE:
|
atv_p
|
TYPE:
|
mixed_variance_weight
|
TYPE:
|
mixed_variance_sigma
|
TYPE:
|
smart_memory
|
do you want to prevent memory fragmentation? Makes the reconstrcution slightly slower
TYPE:
|
print_flag
|
verbodity level
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
loss
|
Total loss value.
TYPE:
|
sse
|
Sum of squared errors.
TYPE:
|
object_grad
|
Gradient of the loss with respect to the object.
TYPE:
|
probe_grad
|
Gradient of the loss with respect to the probe.
TYPE:
|
pos_grad
|
Gradient of the loss with respect to scan position corrections.
TYPE:
|
tilts_grad
|
Gradient of the loss with respect to tilts.
TYPE:
|
static_background_grad
|
Gradient of the loss with respect to static background.
TYPE:
|
aberrations_array_grad
|
Gradient of the loss with respect to aberration coefficients.
TYPE:
|
beam_current_grad
|
Gradient of the loss with respect to beam current.
TYPE:
|
constraint_contributions
|
Individual regularization loss terms added to the total loss.
TYPE:
|
scatteradd_probe
¶
Adds batched probe updates to their respective positions in the full probe array. This wrapper is needed to support older CuPy version.
| PARAMETER | DESCRIPTION |
|---|---|
full
|
Full probe gradient array.
TYPE:
|
indic
|
Indices specifying where to add each batch.
TYPE:
|
batches
|
Batched gradients to scatter-add.
TYPE:
|
scatteradd_abers
¶
Adds batched aberration updates to their respective positions in the full aberration array. This wrapper is needed to support older CuPy version.
| PARAMETER | DESCRIPTION |
|---|---|
full
|
Full aberration gradient array.
TYPE:
|
indic
|
Indices specifying where to add each batch.
TYPE:
|
batches
|
Batched gradients to scatter-add.
TYPE:
|
charge_flip
¶
Perform charge-flipping style object regularization to enhance phase and absorption contrast.
| PARAMETER | DESCRIPTION |
|---|---|
a
|
Complex object to regularize.
TYPE:
|
delta_phase
|
Phase threshold ratio.
TYPE:
|
delta_abs
|
Absorption threshold ratio.
TYPE:
|
beta_phase
|
Inversion multiplier for low-phase regions.
TYPE:
|
beta_abs
|
Inversion multiplier for low-absorption regions.
TYPE:
|
fancy_sigma
|
Tuple of atomic-shape gaussian kernel sigmas (for phase, absorption).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray
|
Regularized complex object. |
make_states_orthogonal
¶
Apply Gram-Schmidt orthogonalization to probe modes.
| PARAMETER | DESCRIPTION |
|---|---|
probe_states
|
Probe array with multiple modes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray
|
Orthogonalized probe states. |
make_basis_orthogonal
¶
Orthogonalize a set of 1D basis vectors using Gram-Schmidt.
| PARAMETER | DESCRIPTION |
|---|---|
vectors
|
2D array of vectors to orthogonalize.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray
|
Orthogonalized basis. |
compute_fast_axis_constraint_on_grid
¶
Apply second-order TV regularization along the fast scan axis.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Positions or tilts to regularize.
TYPE:
|
scan_size
|
Size of the scan grid.
TYPE:
|
tv_reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Value of the regularization term.
TYPE:
|
grad
|
Gradient of the regularization.
TYPE:
|
compute_slow_axis_constraint_on_grid
¶
Apply second-order TV regularization along the slow scan axis.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Positions or tilts to regularize.
TYPE:
|
scan_size
|
Size of the scan grid.
TYPE:
|
tv_reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient with respect to the input.
TYPE:
|
compute_deformation_constraint_on_grid
¶
Penalize deviations from affine transformations in local scan patches.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Grid to regularize (positions or tilts).
TYPE:
|
scan_size
|
Dimensions of the scan.
TYPE:
|
reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient of the loss with respect to the grid.
TYPE:
|
compute_full_l1_constraint
¶
Apply L1 norm regularization to the object's phase and absorption.
| PARAMETER | DESCRIPTION |
|---|---|
object
|
Complex object array.
TYPE:
|
abs_norm_weight
|
Weight for absorption norm.
TYPE:
|
phase_norm_weight
|
Weight for phase norm.
TYPE:
|
grad_mask
|
Mask to restrict gradient computation.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
Memory-efficient option.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient if
TYPE:
|
compute_window_constraint
¶
Penalize probe values outside a predefined window region in real-space.
| PARAMETER | DESCRIPTION |
|---|---|
to_reg_probe
|
Complex probe array.
TYPE:
|
current_window
|
Window mask.
TYPE:
|
current_window_weight
|
Weight of the constraint.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Window constraint loss.
TYPE:
|
reg_grad
|
Gradient of the loss with respect to the probe.
TYPE:
|
compute_probe_constraint
¶
Apply reciprocal space constraint to the probe using an aperture mask. Penalize probe values outside an aperture.
| PARAMETER | DESCRIPTION |
|---|---|
to_reg_probe
|
Complex probe array.
TYPE:
|
aperture
|
Binary mask or scalar defining aperture radius.
TYPE:
|
weight
|
Regularization weight.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Loss from masked frequency components.
TYPE:
|
probe_fft
|
Gradient of the constraint if requested.
TYPE:
|
compute_atv_constraint
¶
Apply adaptive total variation (ATV) regularization to the object.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
Complex object.
TYPE:
|
atv_weight
|
Regularization weight.
TYPE:
|
atv_q
|
q-norm parameter.
TYPE:
|
atv_p
|
p-norm parameter.
TYPE:
|
pixel_size_x_A
|
Pixel size along x (Å).
TYPE:
|
pixel_size_y_A
|
Pixel size along y (Å).
TYPE:
|
atv_grad_mask
|
Optional gradient mask.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
If True, use memory-efficient computation.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
ATV regularization value.
TYPE:
|
dR_dTerm
|
Gradient with respect to the object.
TYPE:
|
compute_missing_wedge_constraint
¶
Enforce missing wedge constraint in 3D reciprocal space.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
3D complex object.
TYPE:
|
pixel_size_x_A
|
Pixel size along x (Å).
TYPE:
|
pixel_size_y_A
|
Pixel size along y (Å).
TYPE:
|
slice_distance
|
Slice spacing (Å).
TYPE:
|
beta_wedge
|
Cone sharpness.
TYPE:
|
wedge_mu
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
loss_term
|
Regularization loss.
TYPE:
|
grad_obj
|
Gradient of the loss with respect to the object.
TYPE:
|
compute_mixed_object_variance_constraint
¶
Regularize variance across object modes by penalizing their differences.
| PARAMETER | DESCRIPTION |
|---|---|
this_obj
|
Complex object array with multiple modes.
TYPE:
|
weight
|
Regularization strength.
TYPE:
|
sigma
|
Smoothing kernel width in frequency space.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
Use memory-efficient FFT loops.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Mixed variance loss.
TYPE:
|
grad
|
Gradient with respect to the object if
TYPE:
|