Metadata-Version: 2.4
Name: ptydy
Version: 0.0.3
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.0.3).** 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](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**: 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.

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

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).
