ptyrad.runtime.convergence

ConvergenceMonitor: periodic convergence metric tracking for optimizable tensors.

Functions

create_convergence_monitor(...)

Factory that returns a ConvergenceMonitor when convergence_monitor_params is not None.

Classes

ConvergenceMonitor(params, model)

Tracks convergence of optimizable tensors during ptychographic reconstruction.

class ptyrad.runtime.convergence.ConvergenceMonitor(params, model)

Bases: object

Tracks convergence of optimizable tensors during ptychographic reconstruction.

Takes periodic snapshots of tracked tensors and computes the iter-to-iter change (relative to the previous snapshot) at each snapshot.

Tracked tensors: obja, objp, probe, probe_pos_shifts. slice_thickness and obj_tilts are excluded — they are already tracked every iteration via model.dz_iters and model.avg_tilt_iters and fed directly to the dashboard.

For obja and objp, metrics are computed on the ROI crop (scanned area bounding box) only. obja is transformed as 1 - obja so vacuum → 0 and material → >0. Two scalars are stored per tensor per step using percentile masking on the current snapshot: a background metric (pixels below p_low) and a signal metric (pixels above p_high). The results are stored under keys obja_bg, obja_fg, objp_bg, objp_fg.

For probe, the fractional intensity change (sum|ΔI| / sum(I_prev)) of mode-summed probe intensity is tracked. For probe_pos_shifts, the RMS displacement change in Å is tracked.

Results are stored in model.convergence_iters as a dict of lists of 2-tuples (niter, value).

Parameters:

• params (dict) – Parsed ConvergenceMonitorParams dict (with keys tensors, every_n_iters, percentile_range).

• model – PtychoModel instance. An initial snapshot is taken during __init__ so the baseline is the state before the first optimizer update.

should_step(niter, save_iters)

Return True if a convergence snapshot should be taken at niter.

Parameters:

• niter (int)

• save_iters (int | None)

Return type:

bool

step(model, niter)

Compute and record convergence metrics for all tracked tensors.

Parameters:

niter (int)

Return type:

None

ptyrad.runtime.convergence.create_convergence_monitor(convergence_monitor_params, model)

Factory that returns a ConvergenceMonitor when convergence_monitor_params is not None.

Parameters:

• convergence_monitor_params – Parsed dict from ReconParams.convergence_monitor, or None to disable monitoring.

• model – PtychoModel instance used for the initial snapshot.

Returns:

A configured ConvergenceMonitor, or None if params is None.

Return type:

ConvergenceMonitor | None