← Back to the Ptycho step on the WASP page
The WASP step 04_ptychography.py (“Ptycho – patches, reconstruction and
merge”) turns a calibrated, drift-corrected 4D-STEM stack into the image the particle
analysis reads. It works in three stages: it lays out the regions that are reconstructed
(stage A), reconstructs each of them by ptychography (stage B), and merges the amplitude
and phase of that reconstruction into one image (stage C). The step does no image processing
itself. Each stage is a complete script of its own in
scripts/image/WASP/dependents/; the step bakes, runs and chains them. This page follows
the data through all three stages, with the default settings unless stated otherwise.
The three stages at a glance
Each stage has its own switch: pty_run_patches, pty_run_reconstruct and
pty_run_merge. A stage that is switched off is skipped, and the stages after it use
whatever its last run left behind. You can therefore lay the ROIs out and check the overlay
without reconstructing, reconstruct again on the stored layout, or rerun the merge in seconds
with other filter cutoffs.
How the step runs a stage
- Engine and progress bar.
pty_enginepicks the engine: GSharp if it names GSharp, Torchslice if it names Torchslice (the default), and otherwise py4DSTEM, with a warning for anything unrecognised. The progress bar is split into bands, roughly by run time: 5 % for the ROI layout, 85 % for the reconstruction and 10 % for the merge. When some stages are off, the bands of the stages that run are scaled to fill the bar. - Bake.
The stage's source is read from
dependents/. Everything below its# From here on followsline is kept, and a header is written above it with one assignment for every value the step was given, exactly as the app does for a script it starts. The values returned by the earlier stages of this run are included. The result is written toproc/in the image directory. - Run.
The baked copy runs with the same Python interpreter, in the image directory, writing to
this step's results file. Its output streams into the step's log as it is produced, and its
<<@progress>>marks are rescaled into the stage's band. A non-zero exit code stops the whole step, because the stages after it would otherwise work on stale results. - Forward.
Run as separate steps, the stages would pass values to each other through the project
configuration, which 4d only updates after a step has ended. Inside this one step, the
setlines (includingset -force) that a stage appends to the results file are read back and baked into the stages after it. This is howpty_dosefrom stage A reaches stage B in the same run.
Two rules belong to this step alone. When stage B runs, stage C is baked with
apmerge_source set to the engine B has just run, whatever the GUI says. Every engine
writes files under its own name, and latest or another engine's name would otherwise merge
an older result. After stage B, the step itself writes set pty_engine_used for the
merge and the particle analysis.
Stage A – ROI layout
A full field of view is too large, and too uneven, to reconstruct as one object. Stage A
(dependents/ptycho_patches.py) therefore cuts it into regions of interest (ROIs), each
reconstructed on its own.
- Positions.
The stage uses the most refined positions the stack holds:
positions/shadowfrom the drift correction, else the calibratedpositions/angs, else the rawpositions/units. The hole found by the scan calibration is carried into that frame through the transform fitted between the two position sets. - Dose.
The total number of electrons (the sum of all patterns divided by the counts per electron,
CPE) is divided by the area of the convex hull of the scan positions. The result is the mean applied dose in e/Ų, returned aspty_dose. - Layout. An N × N block of tiles is laid over the hole (default 3 × 3 squares), or over the centre of the scanned field. Square tiles sit on a square lattice; round and hexagonal ones sit on a hexagonal lattice. An odd N puts one tile on the centre; an even N puts a corner there. In the automatic size mode the tiles cover the field of view exactly. The 2 + 3 + 2 rosette instead lays 7 tiles over a round field, with less of each tile outside the scan.
- Assignment.
Every scan position gets the 1-based index of the tile it falls in, or 0 outside all tiles;
where tiles overlap, the higher index wins. The labels go to
mask/patches/ptychoin the stack, and an overlay is drawn asptycho_roi.png. The rim transit waypoints (mask/transit, where the beam travels round the scanned area between passes, off the specimen) are left out of every selection.
Stage B – reconstruction
Stage B runs the engine's own script, dependents/ptycho_<engine>.py.
Figure 3 follows one ROI through the default engine, Torchslice. The GSharp engine shares
everything down to the levels; the py4DSTEM engine has the same overall shape with a different
solver and preprocessing (see the three engines).
ROI selection
With pty_ROI_id = 0 every ROI of the mask is reconstructed in turn and every output
gains a _roiN suffix. A ROI that fails is reported and skipped, so one bad region
cannot lose the rest of the run. Each ROI's patterns are cut out of the stack, and its positions
are shifted to a non-negative origin on the reconstruction canvas.
Defocus
The starting defocus is the mean of the defocus map (data/defocus/map, written by
the defocus step) over the ROI, or the manual pty_dF. Torchslice and GSharp use the
opposite sign convention to the one 4d stores, so these two engines negate the value on the way in
and log both numbers. With pty_defocus_local on, a low-order surface is fitted to the
per-position defocus, and every exposure's probe is propagated to its own defocus. This keeps a
tilted specimen in focus at the edges of the ROI.
Preprocessing
- Hot pixel and bright-field disc. The hottest detector pixel is masked first, because one stuck pixel can outshine the whole disc. The bright-field disc is then fitted on the average pattern (PACBED). Its radius sets the mrad per detector pixel, and through it the pixel size of the reconstruction.
- Smooth descan. The disc's centre of mass in every exposure is fitted with a Zernike polynomial of the scan position: the slow drift of the disc across the field.
- Row-direction descan. On a serpentine scan the disc also sits a fixed
distance off that smooth field, and the offset flips sign from one scan row to the next,
with the direction the beam travels along the row. A polynomial of position cannot carry a term that changes sign from row to row.
It is measured on the disc rim (or taken from the CBED calibration,
data/descan_direction) and applied with each exposure's travel sign. - CBED alignment. Torchslice fits the shift field that best aligns every pattern with the average. The fit is accepted only if it sharpens the disc edge (10–90 % width) on the compensated average by at least 5 %; otherwise the raw disc centre and the centre-of-mass model stay. Its memory grows with the number of patterns, so on large ROIs it runs on a fixed random subset within a 12 GB budget.
- Aperture fit. A generalised circle is fitted to the PACBED. The starting probe is built through that soft-edged aperture instead of a hard disc, whose sharp edge would put ringing into the probe.
- Descan model. The whole-field model stored by the CBED calibration
(
data/descan_model) is preferred. Otherwise the ROI's own fit is used, and only if it passes a correlation check against the measured shifts. The model is applied per exposure inside the probe generator. - Scan-coil lag (optional, off by default). The scan coils trail the commanded position along the direction of travel, which prints stripes two rows apart. A fixed or refined lag moves every position back along its own travel direction before the solve.
Recursive levels
A multi-pass scan exposes the same area several times, so the earliest passes carry the least
damaged signal. The levels spend that dose in steps. With the default scheme “all, two
thirds, one third” on a 9-pass stack, level 0 uses all 9 passes, level 1 the first 6
and level 2 the first 3. Level 0 starts from an empty object. Every later level starts from
the damage-weighted Fourier sum of the levels already solved. Each level runs
sharp_lvl_iter iterations (default 10) of minibatch optimisation with the chosen loss
(poisson_approx), refining the object, the probe and the scan positions with learning
rates that fall from level to level (sharp_lvl_lrnet, sharp_lvl_lrprobe,
sharp_lvl_lrgrid). The solver runs on whatever GPU the machine has: CUDA on Linux and
Windows with an NVIDIA card, Metal on a Mac, otherwise the CPU.
Damage model and level fusion
Every level gets a resolution cutoff from the damage model. The default Grant & Grigorieff
smooth roll-off weights each spatial frequency by
exp(−0.5 · dose / Nc(q)), with
Nc the critical dose at that frequency. The alternatives are a hard stop at the optimal
exposure (2.51284 × Nc), a hard stop where the weight falls to 0.1, or fixed
Butterworth cutoffs (sharp_lvl_dmg). In the example above the cutoffs come out at 23.8,
18.3 and 11.4 Å. The levels are registered onto level 0 first, because a Fourier
merge damps whatever is misaligned between its inputs. They are then fused:
- SNR-weighted (Wiener), the default: every level contributes at every frequency up to its own cutoff, weighted by dose, so overlapping levels average coherently and there are no band edges to leave seams.
- Plain ring fusion: a hard hand-off, where the highest-dose level supplies
the coarse frequencies and the least damaged level the finest.
sharp_fusion_marginpulls each hand-over slightly early to avoid an empty ring between bands.
Single-pass data (one layer in mask/frame_id) has no dose to split. It is reconstructed
in one level on all exposures, with no damage model and no fusion.
Outputs of the stage
ptycho_torchslice_amplitude.mrc and ptycho_torchslice_phase.mrc (the fused
object, with the pixel size stamped as the voxel size), the figures
ptycho_torchslice_levels.png, _summary.png and
_spectrum_gold.png, and the preprocessing diagnostics
ptycho_prep_cbed_align.png and ptycho_prep_aperture_fit.png. The single
levels are not written. The other engines write the same set under their own names.
The three engines
| Engine | Solver | How the dose is used | Specific to it |
|---|---|---|---|
| py4DSTEM | py4DSTEM single-slice ptychography | Nested levels, then Fourier fusion | Detector-orientation search; a centre-of-mass plane is removed from the patterns
themselves; the probe is re-fitted to an aberration basis after every iteration
(sharp_probe_cor); complex or potential object; optional upsampling; defocus
used with the stored sign. |
| Torchslice default | Torchslice BaseReconstructor (PyTorch) |
Nested levels, then Fourier fusion | Descan and row-direction terms applied in the probe generator; CBED alignment; aperture fit; scan-coil lag; defocus negated. |
| GSharp | Torchslice GSharpReconstructor |
Disjoint dose fractions in one joint solve, no fusion | Shares all inputs and preprocessing with Torchslice; the fractions are cut by
pty_gsharp_fractions. |
Stage C – amplitude–phase merge
Amplitude and phase carry different information about the same object. The phase resolves the
fine detail; the amplitude mostly reports large-scale mass-thickness and is noisy at high
frequencies. The merge (dependents/ptycho_merge.py) therefore takes each channel only
where it is reliable and adds the two.
- Source.
When stage B has run, the merge reads the files of that engine. Otherwise
apmerge_sourcechooses: an engine by name, or latest for the engine the reconstruction ran last (pty_engine_used), failing that the newest files on disk. - Filter. Each channel is filtered at full size, as in Figure 5, so the transforms keep the context outside the later crop.
- Crop. Each ROI's canvas is sized to its own scan extent, so every result is centre-cropped to the smallest canvas among them, which keeps the outputs directly comparable.
- Z-score. Both channels have their mean subtracted and are divided by their standard deviation, so neither dominates just by its numerical range.
- Flip the phase.
With
apmerge_inverton (the default) the phase changes sign, so features read dark in both channels and reinforce instead of cancelling. - Add.
The sum is written as
a_p_merge.mrc(float32, unclipped, the pixel size as the voxel size) anda_p_merge.png(filtered channels and their sum on top, the unfiltered inputs below). In potential mode the py4DSTEM engine writes no amplitude, and the merge stops with a note.
Inputs and outputs
| Stage | Reads | Writes | Returns to 4d |
|---|---|---|---|
| A | data/dpatterns, the positions, scan_hole, CPE |
mask/patches/ptycho (in the stack), ptycho_roi.png |
pty_dose |
| B | each ROI's patterns and positions, mask/frame_id,
data/defocus/map, data/descan_model,
data/descan_direction; KV, CSA,
pacbed_PIX_itr, pty_dose |
ptycho_<engine>_amplitude.mrc, _phase.mrc, the engine's
figures, ptycho_prep_*.png |
pty_engine_used |
| C | ptycho_<engine>_amplitude.mrc and _phase.mrc |
a_p_merge.mrc, a_p_merge.png |
– |
With more than one ROI every file name gains a _roiN suffix. Each stage's own page
lists every parameter and figure in full:
ROI layout,
py4DSTEM,
Torchslice,
GSharp and
amplitude–phase merge.