Metadata-Version: 2.4
Name: hotopy
Version: 0.26
Summary: A toolbox for X-ray holo-tomography in Python
Author: Jens Lucht, Paul Meyer, Leon M. Lohse
Author-email: Jens Lucht <jens.lucht@uni-goettingen.de>, Paul Meyer <paul.meyer@uni-goettingen.de>, Leon M. Lohse <llohse@uni-goettingen.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: numpy>=2
Requires-Dist: pooch>=1.2
Requires-Dist: torch
Requires-Dist: scikit-image
Requires-Dist: tqdm
Requires-Dist: ptwt
Requires-Dist: ruff>=0.7.2 ; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0 ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: pydata-sphinx-theme ; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: ipykernel ; extra == 'docs'
Requires-Dist: astra-toolbox>=2.4.1 ; extra == 'tomo'
Requires-Dist: tomosipo ; extra == 'tomo'
Requires-Python: >=3.10
Project-URL: homepage, https://gitlab.gwdg.de/irp/hotopy
Project-URL: repository, https://gitlab.gwdg.de/irp/hotopy.git
Project-URL: documentation, https://irp.pages.gwdg.de/hotopy/
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: tomo
Description-Content-Type: text/markdown

HoToPy - A toolbox for X-ray holo-tomography in Python

# HoToPy

## Documentation

The full API reference and user guide are available online at:  
👉 [https://irp.pages.gwdg.de/hotopy/reference](https://irp.pages.gwdg.de/hotopy/reference)

## Getting Started

Explore practical examples and tutorials in the dedicated [HoToPy-Examples repository](https://gitlab.gwdg.de/irp/hotopy-examples).

---

## Installation

### ✅ Recommended: Install with `uv` (fastest and most convenient)

We strongly recommend using [`uv` from Astral][uv] for the most efficient and hassle-free setup.

To install HoToPy in a dedicated virtual environment (e.g., created with `uv venv`), run:

```bash
uv pip install hotopy
```

For tomography support, install with the `tomo` extra and the `tomosipo` interface for the [ASTRA Toolbox][astra]:

```bash
uv pip install hotopy[tomo] git+https://github.com/cicwi/tomosipo
```

> 💡 *Note:* `uv` automatically manages dependencies and virtual environments, and supports PyTorch backend selection out of the box.

#### PyTorch Backend Selection with `uv`

`uv` offers seamless integration with PyTorch. You can specify the desired backend directly during installation:

```bash
uv pip install hotopy --torch-backend=cu130
```

Replace `cu130` with your preferred version: `cpu`, `cu126`, `cu128`, etc.  
See the full list of available targets in the [PyTorch documentation][pytorch-legacy-versions].

You can also use `auto` for automatic backend detection:

```bash
uv pip install hotopy --torch-backend=auto
```

For more details, refer to the official [uv PyTorch integration guide](https://docs.astral.sh/uv/guides/integration/pytorch/).

---

### 🐍 Alternative: Install with `pip`

If you prefer using `pip`, you can install HoToPy with:

```bash
pip install hotopy
```

For tomography support, install with the `tomo` extra and the `tomosipo` dependency:

```bash
pip install hotopy[tomo] git+https://github.com/cicwi/tomosipo
```

> ⚠️ *Note:* The ASTRA Toolbox is not included in the default PyPI release. For alternative installation methods, consult the [ASTRA Toolbox documentation][astra].

#### PyTorch Backend with `pip`

To install with a specific PyTorch backend (e.g., CUDA 13.0), use the PyTorch index URLs:

```bash
pip install hotopy --index-url https://download.pytorch.org/whl/cu130 --extra-index-url https://pypi.org/simple/
```

Replace `cu130` with your desired version (`cpu`, `cu126`, `cu128`, etc.).  
See the [PyTorch official installation guide](https://pytorch.org/get-started/locally/) for more options.

> 🔍 *We strongly recommend using `uv` for a smoother, faster, and more reliable experience.*

---

## Source Installation (Development)

For the latest bleeding-edge features, you can install directly from the source repository:

```bash
git clone https://gitlab.gwdg.de/irp/hotopy.git
cd hotopy
uv sync --all-extras
```

> 💡 This installs HoToPy with tomography support and development dependencies (e.g., testing, linting, documentation tools).

---

## Paper & Citation

If you use HoToPy, please cite the paper [HoToPy: a toolbox for X-ray holo-tomography in Python][paper]

```
@article{Lucht2025_hotopy,
    author = "Lucht, Jens and Meyer, Paul and Lohse, Leon Merten and Salditt, Tim",
    title = "{{\it HoToPy}: a toolbox for X-ray holo-tomography in Python}",
    journal = "Journal of Synchrotron Radiation",
    year = "2025",
    volume = "32",
    number = "6",
    pages = "1586--1594",
    month = "Nov",
    doi = {10.1107/S1600577525008550},
    url = {https://doi.org/10.1107/S1600577525008550},
    keywords = {X-ray imaging, phase retrieval, computed tomography, phase contrast, holography},
}
```

[holotomo]: https://gitlab.gwdg.de/irp/holotomotoolbox
[astra]: https://astra-toolbox.com/
[paper]: https://doi.org/10.1107/S1600577525008550
[uv]: https://docs.astral.sh/uv/
[pytorch-legacy-versions]: https://pytorch.org/get-started/previous-versions/
