Metadata-Version: 2.3
Name: ptylab
Version: 0.3.5
Summary: A cross-platform, open-source inverse modeling toolbox for conventional and Fourier ptychography
Author: Lars Loetgering, PtyLab Team
Author-email: Lars Loetgering <lars.loetgering@fulbrightmail.org>
Requires-Dist: numpy~=2.0
Requires-Dist: matplotlib~=3.7
Requires-Dist: h5py~=3.9
Requires-Dist: scipy~=1.11
Requires-Dist: scikit-image>=0.21.0
Requires-Dist: tqdm~=4.65
Requires-Dist: scikit-learn~=1.3
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: cupy-cuda12x[ctk] ; sys_platform != 'darwin' and extra == 'gpu'
Requires-Dist: pyqtgraph>=0.13 ; extra == 'gui'
Requires-Dist: pyside6-essentials>=6.2 ; extra == 'gui'
Requires-Python: >=3.10, <3.14
Provides-Extra: gpu
Provides-Extra: gui
Description-Content-Type: text/markdown

# PtyLab.py: Unified Ptychography Toolbox
![Python 3.10+](https://img.shields.io/badge/python-3.10+-green.svg)
[![PyPI](https://img.shields.io/pypi/v/ptylab.svg)](https://pypi.org/project/ptylab/)
![Tests](https://github.com/PtyLab/PtyLab.py/actions/workflows/test.yml/badge.svg)
[![Docs](https://github.com/PtyLab/PtyLab.py/actions/workflows/docs.yml/badge.svg)](https://ptylab.github.io/PtyLab.py/)

[**Key Features**](#key-features) | [**Getting Started**](#getting-started) | [**Installation**](https://ptylab.github.io/PtyLab.py/getting-started/installation/) | [**Documentation**](https://ptylab.github.io/PtyLab.py/)

PtyLab is an inverse modeling toolbox for Conventional (CP) and Fourier (FP) ptychography in a unified framework. For more information please check the [paper](https://opg.optica.org/oe/fulltext.cfm?uri=oe-31-9-13763&id=529026).

## Key Features

- **Classic engines**: ePIE, mPIE, mqNewton, qNewton
- **Advanced corrections**: position correction, defocus correction (zPIE), angle correction (aPIE), orthogonal probe relaxation (OPR)
- **Multi-modal**: multi-slice, multi-wavelength, mixed-state object and probe
- **Multiple propagators**: Fraunhofer, Fresnel, Angular Spectrum (ASP), scaled ASP, polychromatic variants
- **Unified array layout**: object and probe are 6D arrays `(nlambda, nosm, npsm, nslice, N, N)`, i.e. wavelengths, object and probe state mixtures, depth slices, then the frame
- **GPU acceleration**: same code runs on CPU and GPU (NumPy/CuPy)
- **Live monitor**: follow the object, probe and error metric as the iterations run, along with any corrected parameters such as scan positions, sample-detector distance, wavelength or angle

### How it works

PtyLab.py is built around five core classes: `ExperimentalData`, `Reconstruction`, `Params`, `Engine` and `Monitor`. Data flows through them to a reconstruction as below:

```mermaid
flowchart LR
    file[(HDF5 data)] --> exp[ExperimentalData]
    exp --> recon["Reconstruction<br/>(object, probe)"]
    exp & recon & params[Params] --> engine["Engine<br/>(ePIE, mPIE, ...)"]
    engine -.->|updates| recon
    engine <-->|each iteration| corr["Optional Corrections: positions, distance, angle"]
    engine -.-> mon[Monitor<br/>live plots]
    corr -.-> mon
    engine -->|reconstruct| out["Saved to HDF5<br/>object, probe, error, corrected parameters"]
```

## Getting started

Try the demo in Google Colab:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PtyLab/PtyLab.py/blob/main/demo.ipynb)
![demo](https://raw.githubusercontent.com/PtyLab/PtyLab.py/main/assets/recon.gif)

For more use cases, start with the [tutorials](https://ptylab.github.io/PtyLab.py/tutorials/) in our documentation, then see the [example_scripts](https://github.com/PtyLab/PtyLab.py/tree/main/example_scripts) directory.

## Installation

Install from PyPI within your virtual environment:

```bash
pip install -U ptylab
```
For faster installs, we recommend [uv](https://docs.astral.sh/uv/getting-started/installation/): `uv pip install -U ptylab`

To utilize GPU for faster reconstruction, enable GPU support:

```bash
uv pip install -U "ptylab[gpu]" # supports CuPy with CUDA 12
```
Check whether GPU is correctly configured with `uv run ptylab check gpu`. For additional information on other extras such `gui`, see the [installation guide](https://ptylab.github.io/PtyLab.py/getting-started/installation/).

## Contributing

Contributions are welcome! See the [development guide](https://ptylab.github.io/PtyLab.py/development/) for the development setup, running the tests and building the documentation locally.

## Citation

If you use this package, please cite:

```tex
@article{Loetgering:23,
        author = {Lars Loetgering and Mengqi Du and Dirk Boonzajer Flaes and Tomas Aidukas and Felix Wechsler and Daniel S. Penagos Molina and Max Rose and Antonios Pelekanidis and Wilhelm Eschen and J\"{u}rgen Hess and Thomas Wilhein and Rainer Heintzmann and Jan Rothhardt and Stefan Witte},
        journal = {Opt. Express},
        number = {9},
        pages = {13763--13797},
        publisher = {Optica Publishing Group},
        title = {PtyLab.m/py/jl: a cross-platform, open-source inverse modeling toolbox for conventional and Fourier ptychography},
        volume = {31},
        month = {Apr},
        year = {2023},
        doi = {10.1364/OE.485370},
}
```

