PyGROG#

GPU-accelerated GROG (GRAPPA Operator Gridding) for non-Cartesian MRI reconstruction.

PyGROG implements the GROG algorithm — a data-driven, parallel-imaging-aware gridding method that maps non-Cartesian k-space samples onto a Cartesian grid using GRAPPA kernels trained from an auto-calibration region. It provides:

GROG interpolator (pygrog.calib.GrogInterpolator) — non-Cartesian to Cartesian gridding via fractional GRAPPA operators.
SparseFFT operator (pygrog.operator.SparseFFT) — fast sparse forward and adjoint Cartesian FFT for undersampled MRI, with optional sensitivity maps and GPU pipelining.
MaskedFFT operator (pygrog.operator.MaskedFFT) — dense-grid masked FFT companion for GROG gridded paths.
Reconstruction gadgets (pygrog.gadgets) — off-resonance correction and low-rank subspace projection, stackable on any base operator. Public aliases include SubspaceGadget, OffResonanceGadget, with_subspace, and with_offresonance.
Calibration utilities (pygrog.utils) — NLINV coil sensitivity estimation and PCA coil compression.
Iterative solvers (op.solve(...), pygrog.solve) — CG/LSMR interfaces that accept torch, NumPy, and CuPy arrays (CuPy via DLPack, no CPU copy).
Interoperability (pygrog.interop) — drop-in adapters for mri-nufft, sigpy, mrpro, and deepinverse.

Quick Start#

pip install pygrog

CUDA builds are published on GitHub Releases (not on PyPI). If your PyTorch is CUDA-enabled, install the matching PyGROG CUDA wheel with -f:

# CUDA must match your installed torch wheel: cu126 | cu128 | cu130
CUDA=cu128
PYGROG_VERSION=1.0.0

pip install "pygrog==${PYGROG_VERSION}+${CUDA}" \
  -f "https://github.com/FiRMLAB-Pisa/pygrog/releases/expanded_assets/v${PYGROG_VERSION}"

Find your torch CUDA version with:

python -c "import torch; print(torch.version.cuda)"

import numpy as np
from pygrog.calib import GrogInterpolator
from pygrog.operator import SparseFFT

# 1. Build the GROG plan from the non-Cartesian trajectory
grog = GrogInterpolator(shape=(256, 256), coords=coords)

# 2. Fit GRAPPA kernels from the auto-calibration region (ACR)
grog.calc_interp_table(acr_data)

# 3. Grid and reconstruct in one call
image = grog.interpolate(kspace_nc, ret_image=True)

See the documentation for full examples, API reference, and theory.

Documentation#

Full documentation (installation, examples, API, theory) lives at https://pygrog.readthedocs.io/en/latest/.

Installation#

# CPU (from PyPI)
pip install pygrog

# Development install with all optional dependencies
pip install --no-build-isolation -e ".[dev]"

CUDA wheels are attached to each GitHub Release.

Install them with a torch-scatter-style -f command:

# CUDA must match your installed torch wheel: cu126 | cu128 | cu130
CUDA=cu128
PYGROG_VERSION=1.0.0

pip install "pygrog==${PYGROG_VERSION}+${CUDA}" \
  -f "https://github.com/FiRMLAB-Pisa/pygrog/releases/expanded_assets/v${PYGROG_VERSION}"

Development Style#

For contributors, formatting and linting are Ruff-only:

ruff format .
ruff check .

ruff check is configured to apply safe auto-fixes by default.

License#

MIT — see LICENSE for details.

PyGROG

Contents