Ptydy

A PtyRAD studio. Pronounced "tidy".

Status: early development (0.1.1). The data viewer and fast-acbf apps work; the other planned apps do not exist yet. Expect the interface to change between releases; installing from source is recommended while it does.

Ptydy is a desktop program that brings the PtyRAD ecosystem together in one place, so the steps of a ptychography workflow share their settings instead of being copied between tools by hand:

1. Experiment planning: dose, probe overlap, sampling, and the expected result (planned)
2. Dataset inspection: a fast 4D-STEM browser with fast-acbf tcBF/acBF (available)
3. PtyRAD plan helper: build and check reconstruction settings, submit jobs (planned)
4. Dataset simulation: simulated datasets with known ground truth (planned)
5. Output inspector: reconstruction results next to their inputs (planned)

What works today

Ptydy is a shell of pipeline apps: pick an app on the rail at the left; its tools appear in the ribbon under the main menu.

• Data viewer (a py4DGUI replacement without py4DSTEM): diffraction and virtual-image panes, and a result pane (FFT, EWPC or a task's output) on demand; point / rectangle / circle / annulus detectors with integrating, maximum, centre-of-mass and iCoM responses; scan point or rectangle for the diffraction pattern; statistics, colour map, scaling and a level histogram next to each pane; scale bars from the calibration; TIFF / PNG / clipboard export.
• Files: EMPAD .raw (memory-mapped), py4DSTEM / emdfile HDF5 with its calibration, any HDF5 / MATLAB v7.3 / Zarr / NumPy array through a flexible loader that maps the axes (fixed indices, flattened scans), and DigitalMicrograph / Medipix / blockfile through RosettaSciIO. Large files are memory-mapped when they don't fit in RAM.
• fast-acbf: GPU tcBF / acBF reconstruction. The everyday steps (tcBF, acBF, orientation, defocus search, C10) are in the data viewer's ribbon; the fast-acbf app has the dashboard: per-aberration values, automated refinement with a restorable history, the reconstruction next to the probe (|ψ|, |ψ|², complex), the aberration surface χ, ∇χ and the vBF image shifts as arrows, and 3D depth stacks over defocus with an orthogonal view, exported as multi-page TIFF stacks.

Installation (from source)

conda create -n ptydy python=3.12
conda activate ptydy
git clone https://github.com/chiahao3/ptydy.git
cd ptydy
pip install -e ".[all]"   # or ".[acbf]" for fast-acbf only, "." for the browser alone

For GPU reconstructions, install the PyTorch build that matches your CUDA version first (and torchvision from the same index), e.g. pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126.

Optional extras: acbf (fast-acbf + PyTorch), zarr, rsciio (DigitalMicrograph, Medipix, ...), dev (tests, lint, build).

Usage

ptydy                       # then drop a dataset on the window
ptydy path/to/scan_x128_y128.raw

See notes/INSTRUCTION.md for the controls, and use the ptydy.io readers from scripts:

from ptydy.io import open_datacube

dc = open_datacube("scan_x128_y128.raw")      # DataCube: data[scan_y, scan_x, det_y, det_x]
dc = open_datacube("data.mat", dataset="/dp", scan_shape=(64, 64))

Development

See PLAN.md (state, next actions, architecture, decisions) and RELEASING.md.

QT_QPA_PLATFORM=offscreen pytest -q
ruff check src tests tools

License

LGPL-3.0. See LICENSE.