Metadata-Version: 2.4
Name: ptydy
Version: 0.5.1
Summary: Ptydy: a PtyRAD studio for planning, inspecting, and reconstructing ptychography data
Author-email: Chia-Hao Lee <cl2696@cornell.edu>
License-Expression: LGPL-3.0
Project-URL: Homepage, https://github.com/chiahao3/ptydy
Project-URL: Repository, https://github.com/chiahao3/ptydy
Project-URL: Issues, https://github.com/chiahao3/ptydy/issues
Project-URL: Changelog, https://github.com/chiahao3/ptydy/blob/main/CHANGELOG.md
Keywords: Ptychography,4D-STEM,Electron microscopy,GUI
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: tifffile
Requires-Dist: PySide6>=6.6
Requires-Dist: pyqtgraph>=0.13.7
Provides-Extra: acbf
Requires-Dist: fast-acbf>=0.8; extra == "acbf"
Requires-Dist: scikit-image; extra == "acbf"
Provides-Extra: zarr
Requires-Dist: zarr>=3.0; extra == "zarr"
Provides-Extra: rsciio
Requires-Dist: rosettasciio; extra == "rsciio"
Provides-Extra: all
Requires-Dist: ptydy[acbf,rsciio,zarr]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-qt; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-qt; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Ptydy

*A PtyRAD studio. Pronounced "tidy".*

> **Status: early development (0.5.1).** The data viewer, fast-acbf and the result
> inspector 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](https://github.com/chiahao3/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**: PtyRAD results (v1 and v2), live jobs *(available)*

## 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 on a numbered axis beside each image; 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. **Export** saves
  a dataset (e.g. after a crop or bin) as HDF5 with its calibration and fast-acbf's
  aberrations and orientation; ptydy reopens it as it was and PtyRAD reads it as it is.
- **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.

- **Result inspector:** PtyRAD model files of **v1 and v2** (read without PtyRAD), a run's
  output folder or a folder of runs. A dashboard first (object, probe modes, the loss of
  every iteration, the run's facts, state and time left), then tabs: object (phase /
  amplitude / complex, modes, depth sum, mean or product / slice / orthogonal sections, FFT, change since
  the previous save), probe (real / Fourier, amplitude / phase, modes, propagation through
  z with the focus, **aberration fit** with PtyRAD params to copy and the coefficients over
  iterations), positions (the scan pattern thinned to stay readable, PtyRAD's scan arrow,
  the reference on demand, one view range over the iterations), PtyRAD's figures (saved, or redrawn by PtyRAD's plotting
  functions), metadata (filterable) and the log. Play through the saved iterations; a
  running job is followed as it saves. **Several runs stay open**, one tab each:
  switching keeps the tab, the display settings, the zoom and the iteration, so runs
  compare at a glance; a Files panel (View ▸ Files) shows them with thumbnails. Drop a
  model file or folder on the window, or `ptydy path/to/output_folder`.

## Installation (from source)

```sh
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

```sh
ptydy                       # then drop a dataset on the window
ptydy path/to/scan_x128_y128.raw
ptydy path/to/ptyrad/output/run_folder    # or a model_iter*.hdf5: the result inspector
```

See [notes/INSTRUCTION.md](notes/INSTRUCTION.md) for the controls, and use the `ptydy.io`
readers from scripts:

```python
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](PLAN.md) (state, next actions, architecture, decisions) and
[RELEASING.md](RELEASING.md).

```sh
QT_QPA_PLATFORM=offscreen pytest -q
ruff check src tests tools
```

## License

LGPL-3.0. See [LICENSE](LICENSE).
