Metadata-Version: 2.4
Name: MIRTorch
Version: 0.3.0
Summary: a PyTorch-based image reconstruction toolbox
Author-email: Guanhua Wang <guanhuaw@umich.edu>
License-Expression: BSD-3-Clause
Project-URL: Documentation, https://mirtorch.readthedocs.io/
Project-URL: Issues, https://github.com/guanhuaw/MIRTorch/issues
Project-URL: Repository, https://github.com/guanhuaw/MIRTorch
Keywords: signal processing,inverse problems
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.13
Requires-Dist: torchvision
Requires-Dist: torchkbnufft<1.5.2,>=1.4.0
Requires-Dist: finufft<3,>=2.5; platform_system != "Darwin" and (platform_machine == "x86_64" or platform_machine == "AMD64")
Requires-Dist: numpy>=1.24
Requires-Dist: scipy
Requires-Dist: PyWavelets
Provides-Extra: examples
Requires-Dist: einops; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Provides-Extra: cufinufft
Requires-Dist: cufinufft<3,>=2.5; (platform_system == "Linux" or platform_system == "Windows") and extra == "cufinufft"
Provides-Extra: finufft
Requires-Dist: finufft<3,>=2.5; extra == "finufft"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "docs"
Requires-Dist: myst-parser<5,>=2; extra == "docs"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Provides-Extra: dev
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: ipywidgets; extra == "dev"
Requires-Dist: h5py; extra == "dev"
Requires-Dist: gdown; extra == "dev"
Requires-Dist: wget; extra == "dev"
Requires-Dist: scikit-image; extra == "dev"
Requires-Dist: scikit-learn; extra == "dev"
Requires-Dist: einops; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: check-manifest; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: sphinx<9,>=7; extra == "dev"
Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "dev"
Requires-Dist: myst-parser<5,>=2; extra == "dev"
Dynamic: license-file

# MIRTorch

![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/guanhuaw/mirtorch?include_prereleases)
![Read the Docs](https://img.shields.io/readthedocs/mirtorch)

A differentiable PyTorch toolbox for medical imaging reconstruction, developed
at the University of Michigan. MIRTorch provides composable linear maps,
proximal operators, iterative solvers, and MRI and SPECT system models.

[Documentation](https://mirtorch.readthedocs.io/en/latest/) ·
[Examples](https://github.com/guanhuaw/MIRTorch/tree/master/examples) ·
[API](https://mirtorch.readthedocs.io/en/latest/API.html)

## New

FINUFFT/cuFINUFFT now accelerate non-Cartesian and B0-informed MRI; warm NVIDIA
A10 benchmarks measured up to **5.2× faster NUFFT**, **9.4× faster Toeplitz**,
and **12.3× faster iterative solvers** (workload-dependent). Both NUFFT
backends also support efficient first-order trajectory gradients, enabling
SNOPY-style sampling-pattern optimization directly in MIRTorch
([Wang and Fessler, 2023](https://arxiv.org/abs/2111.02912)).

## Install

Install [PyTorch](https://pytorch.org/) for your platform, then:

```bash
pip install MIRTorch
```

CUDA users can install cuFINUFFT with:

```bash
pip install "MIRTorch[cufinufft]"
```

For local development:

```bash
pip install -e ".[dev]"
```

## Backends and compilation

`NuSense`, `NuSenseGram`, `Gmri`, and `GmriGram` use an installed FINUFFT or
cuFINUFFT library when the device supports it, then fall back to torchkbnufft.
Base macOS, Apple Metal, and Linux ARM installs therefore work without a
native library. Set `backend="torchkbnufft"` or `backend="finufft"` to
override the automatic choice.

Real-valued CUDA runs of `Diff2dgram`, FISTA, and POGM use `torch.compile`
automatically when PyTorch provides it. Other inputs stay eager; pass
`compile=False` to disable compilation explicitly.

## Examples

The notebooks choose CUDA, Apple Metal, or CPU at runtime:

- [`demo_mri.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_mri.ipynb):
  CG-SENSE and B0-informed PWLS
- [`demo_3d.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_3d.ipynb):
  3D non-Cartesian MRI and Toeplitz embedding
- [`demo_trajectory_optimization.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_trajectory_optimization.ipynb):
  SNOPY-style radial trajectory optimization
- [`demo_cs.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_cs.ipynb):
  compressed-sensing MRI
- [`demo_mlem.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_mlem.ipynb):
  SPECT reconstruction
- [`demo_mnist.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_mnist.ipynb):
  CG, FISTA, and POGM
- [`demo_dl.ipynb`](https://github.com/guanhuaw/MIRTorch/blob/master/examples/demo_dl.ipynb):
  dictionary learning

## Citation and acknowledgments

MIRTorch is inspired by
[MIRT](https://github.com/JeffFessler/mirt),
[MIRT.jl](https://github.com/JeffFessler/MIRT.jl),
[SigPy](https://github.com/mikgroup/sigpy), and
[PyLops](https://github.com/PyLops/pylops).

If MIRTorch is useful in your work, please cite:

```bibtex
@inproceedings{wang:22:mirtorch,
  title={{MIRTorch}: A {PyTorch}-powered Differentiable Toolbox for Fast Image
         Reconstruction and Scan Protocol Optimization},
  author={Wang, Guanhua and Shah, Neel and Zhu, Keyue and Noll, Douglas C. and
          Fessler, Jeffrey A.},
  booktitle={Proceedings of the International Society for Magnetic Resonance
             in Medicine (ISMRM)},
  pages={4982},
  year={2022}
}
```

See the
[documentation](https://mirtorch.readthedocs.io/en/latest/README.html#citation-and-acknowledgments)
for the BJORK and SPECT citations.

MIRTorch is distributed under the
[BSD 3-Clause License](https://github.com/guanhuaw/MIRTorch/blob/master/LICENSE).
