Metadata-Version: 2.4
Name: mrax
Version: 0.1.0
Summary: JAX-based tools for quantitative MRI model fitting, reconstruction, and analysis.
Author: Chris Lippe
License-Expression: MIT
Project-URL: Homepage, https://github.com/chris-lippe/MRax
Project-URL: Documentation, https://chris-lippe.github.io/MRax
Project-URL: Repository, https://github.com/chris-lippe/MRax
Project-URL: Issues, https://github.com/chris-lippe/MRax/issues
Keywords: MRI,JAX,quantitative imaging,reconstruction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax<0.11,>=0.4.35
Requires-Dist: optax<0.3,>=0.2.4
Requires-Dist: numpy<3,>=2
Requires-Dist: scipy<2,>=1.14
Requires-Dist: ismrmrd<2,>=1.14
Requires-Dist: nibabel<6,>=5.3
Requires-Dist: dipy<2,>=1.10
Requires-Dist: pypulseq<2,>=1.4
Requires-Dist: SimpleITK<3,>=2.4
Requires-Dist: PySide6<7,>=6.8
Requires-Dist: pyqtgraph<0.15,>=0.13
Requires-Dist: qtpy<3,>=2.4
Requires-Dist: superqt<1,>=0.7
Requires-Dist: matplotlib<4,>=3.9
Provides-Extra: nufft
Requires-Dist: jax-finufft<2,>=1; extra == "nufft"
Provides-Extra: denoise-external
Requires-Dist: bm3d<5,>=4; extra == "denoise-external"
Requires-Dist: bm4d<5,>=4; extra == "denoise-external"
Provides-Extra: all
Requires-Dist: jax-finufft<2,>=1; extra == "all"
Requires-Dist: bm3d<5,>=4; extra == "all"
Requires-Dist: bm4d<5,>=4; extra == "all"
Provides-Extra: docs
Requires-Dist: sphinx<11,>=8; extra == "docs"
Requires-Dist: myst-parser<6,>=4; extra == "docs"
Requires-Dist: pydata-sphinx-theme<1,>=0.16; extra == "docs"
Requires-Dist: nbsphinx<1,>=0.9; extra == "docs"
Provides-Extra: notebooks
Requires-Dist: jupyterlab<5,>=4; extra == "notebooks"
Requires-Dist: scikit-image<1,>=0.25; extra == "notebooks"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: coverage<8,>=7.6; extra == "dev"
Requires-Dist: isort<7,>=5.13; extra == "dev"
Requires-Dist: pytest<10,>=8.3; extra == "dev"
Requires-Dist: pyright<2,>=1.1.400; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

![MRax logo](MRax_logo.png)

# MRax

MRax is a JAX-based Python library for quantitative MRI research. It provides
data structures for experiments and studies, differentiable signal models,
optimization utilities, reconstruction helpers, analysis tools, and ISMRMRD-backed
storage for images, k-space, and fitted maps.

Disclaimer: MRax is intended for research use only. This is an early release, and bugs may occur.
Coding agents were used to assist in development. Code was manually reviewed and validated on Bruker ParaVision 360 3.6 data.

## Installation

Install the release package from PyPI:

```bash
pip install mrax
```

The default install includes fitting, Cartesian reconstruction, import, built-in
denoising, registration, analysis, storage, and desktop GUI support. Optional
non-Cartesian and external denoising backends are installed explicitly:

```bash
pip install "mrax[nufft]"
pip install "mrax[denoise-external]"
```

`jax-finufft` does not publish Windows wheels. The upstream `bm3d` and `bm4d`
packages are licensed for non-commercial use; review their licenses before installing
the `denoise-external` extra. Development, documentation, and notebook authoring tools
remain outside the base runtime package.

MRax uses the `mrax.*` import namespace:

```python
from mrax.core.loss_builder import run_fit
from mrax.library import make_t2_se_model
```

Contributor extras are available for notebook and documentation workflows:

```bash
pip install "mrax[notebooks]"
pip install "mrax[docs]"
```

For local development from a clone:

```bash
python -m pip install --upgrade pip
python -m pip install -e ".[all,dev,docs,notebooks]"
pytest
```

## Dev Container

The repository includes one VS Code compatible dev container. Open the public clone in
VS Code and choose **Dev Containers: Reopen in Container**. The container installs
all runtime features plus development, documentation, and notebook tooling, then
installs MRax in editable mode:

```bash
python -m pip install -e ".[all,dev,docs,notebooks]"
```

Inside the container, common checks are:

```bash
pytest
sphinx-build -E -b html docs docs/_build/html
jupyter lab notebooks
```

## Documentation Website

Documentation is built with Sphinx:

```bash
python -m pip install -e ".[docs]"
sphinx-build -E -b html docs docs/_build/html
```

## PyPI Release

Build and inspect a local distribution with:

```bash
python -m pip install -e ".[all,dev,docs,notebooks]"
python -m build
twine check dist/*
```
## Quick Example

```python
import jax.numpy as jnp

from mrax.core.loss_builder import run_fit
from mrax.data_struct import DataSet, Quantity
from mrax.library import build_default_experiment, make_t2_se_model

te = jnp.asarray([8.0, 24.0, 48.0, 96.0])
experiment = build_default_experiment(
    "mse",
    frame_count=te.size,
    spatial_shape=(2, 2),
    observables={"TE": Quantity(te, "ms")},
)
model = make_t2_se_model(scale=1.0)
dataset = DataSet(data=jnp.ones((te.size, 2, 2)), name="demo")

fields, losses = run_fit(experiment, model, dataset, num_steps=20, step_size=0.03)
print(fields["t2"].si_unit, losses[-1])
```
