Metadata-Version: 2.4
Name: torchsim
Version: 0.0.4
Summary: A feature-rich MR simulator supporting massive parallelization on GPU and automatic differentiation.
Keywords: epg,mri,simulation,bloch
Author-Email: Matteo Cencini <matteo.cencini@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://github.com/FiRMLAB-Pisa/torchsim
Project-URL: Documentation, https://firmlab-pisa.github.io/torchsim/
Project-URL: Bug Reports, https://github.com/FiRMLAB-Pisa/torchsim/issues
Project-URL: Source, https://github.com/FiRMLAB-Pisa/torchsim
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: torch>=2.1
Provides-Extra: pulseq
Requires-Dist: pypulseq>=1.4; extra == "pulseq"
Provides-Extra: test
Requires-Dist: torchsim[pulseq]; extra == "test"
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-sugar; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: coverage; extra == "test"
Provides-Extra: doc
Requires-Dist: torchsim[pulseq]; extra == "doc"
Requires-Dist: sphinx>=7.0; extra == "doc"
Requires-Dist: sphinx_book_theme>=1.1; extra == "doc"
Requires-Dist: sphinx-design>=0.6; extra == "doc"
Requires-Dist: sphinx-gallery>=0.15; extra == "doc"
Requires-Dist: myst-parser>=4.0; extra == "doc"
Requires-Dist: linkify-it-py>=2.0; extra == "doc"
Requires-Dist: sphinx-exec-directive>=0.6; extra == "doc"
Requires-Dist: sphinx_copybutton>=0.5; extra == "doc"
Requires-Dist: matplotlib>=3.8; extra == "doc"
Requires-Dist: cmap>=0.1; extra == "doc"
Requires-Dist: ipywidgets>=8.0; extra == "doc"
Provides-Extra: examples
Requires-Dist: torchsim[pulseq]; extra == "examples"
Requires-Dist: brainweb-dl>=0.3; extra == "examples"
Requires-Dist: deepinv>=0.2; extra == "examples"
Requires-Dist: deepmriprep>=0.3; extra == "examples"
Requires-Dist: mri-nufft[finufft]>=1.0; extra == "examples"
Requires-Dist: sigpy>=0.1.26; extra == "examples"
Requires-Dist: torchio>=0.19; extra == "examples"
Provides-Extra: dev
Requires-Dist: torchsim[doc,examples,test]; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Description-Content-Type: text/markdown

# TorchSim

TorchSim is a pure Pytorch-based MR simulator, including analytical and EPG model.

[![codecov](https://codecov.io/gh/FiRMLAB-Pisa/torchsim/graph/badge.svg?token=l8xhIVORYm)](https://codecov.io/gh/FiRMLAB-Pisa/torchsim)
[![Tests](https://github.com/FiRMLAB-Pisa/torchsim/actions/workflows/test.yml/badge.svg)](https://github.com/FiRMLAB-Pisa/torchsim/actions/workflows/test.yml)
[![Lint](https://github.com/FiRMLAB-Pisa/torchsim/actions/workflows/lint.yml/badge.svg)](https://github.com/FiRMLAB-Pisa/torchsim/actions/workflows/lint.yml)
[![License](https://img.shields.io/github/license/FiRMLAB-Pisa/torchsim)](https://github.com/FiRMLAB-Pisa/torchsim/blob/main/LICENSE.txt)
[![Codefactor](https://www.codefactor.io/repository/github/FiRMLAB-Pisa/torchsim/badge)](https://www.codefactor.io/repository/github/FiRMLAB-Pisa/torchsim)
[![Documentation](https://github.com/FiRMLAB-Pisa/torchsim/actions/workflows/docs.yml/badge.svg)](https://firmlab-pisa.github.io/torchsim/)
[![PyPi](https://img.shields.io/pypi/v/torchsim)](https://pypi.org/project/torchsim)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PythonVersion](https://img.shields.io/badge/Python-%3E=3.10-blue?logo=python&logoColor=white)](https://python.org)

## Features

TorchSim contains tools to implement parallelized and differentiable MR simulators. Specifically, we provide

1. Automatic vectorization of across multiple atoms (e.g., voxels).
2. Automatic generation of forward and jacobian methods (based on forward-mode autodiff) to be used in parameter fitting or model-based reconstructions.
3. Support for custom manual defined jacobian methods to override auto-generated jacobian.
4. Support for advanced signal models, including diffusion, flow, magnetization transfer and chemical exchange.
5. GPU support.

## Installation

TorchSim can be installed via pip as:

```bash
pip install torchsim
```

## Basic Usage

Using TorchSim, we can quickly implement and run MR simulations.
We also provide pre-defined simulators for several applications:

```python
import numpy as np
import torchsim

# generate a flip angle pattern
flip = np.concatenate((np.linspace(5, 60.0, 300), np.linspace(60.0, 2.0, 300), np.ones(280)*2.0))
sig, jac = torchsim.mrf_sim(flip=flip, TR=10.0, T1=1000.0, T2=100.0, diff=("T1","T2"))
```

This way we obtained the forward pass signal (`sig`) as well as the jacobian
calculated with respect to `T1` and `T2`.

## Development

If you are interested in improving this project, install TorchSim in editable mode:

```bash
git clone git@github.com:FiRMLAB-Pisa/torchsim
cd torchsim
pip install -e ".[dev]"
pre-commit install
```

The install compiles the two C++ kernels, so it needs a C++17 compiler; CMake
and Ninja arrive as build-time wheels. `pre-commit` runs the formatter and the
linter -- both `ruff` -- on every commit, which is exactly what CI checks.

## Related projects

This package is inspired by the following excellent projects:

- epyg \<<https://github.com/brennerd11/EpyG>\>
- sycomore \<<https://github.com/lamyj/sycomore/>\>
- mri-sim-py \<<https://somnathrakshit.github.io/projects/project-mri-sim-py-epg/>\>
- ssfp \<<https://github.com/mckib2/ssfp>\>
- erwin \<<https://github.com/lamyj/erwin>\>
