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

Getting Started

Explore practical examples and tutorials in the dedicated HoToPy-Examples repository.

Installation

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

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

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

uv pip install hotopy

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

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:

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.

You can also use auto for automatic backend detection:

uv pip install hotopy --torch-backend=auto

For more details, refer to the official uv PyTorch integration guide.

🐍 Alternative: Install with pip

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

pip install hotopy

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

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.

PyTorch Backend with pip

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

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 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:

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

@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},
}