pygrog 0.1.2

An interoperable GROG package to accelerate Non-Cartesian MR reconstructions.

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.

Related Projects

• mri-nufft — Non-uniform FFT for MRI
• mrpro — MRI reconstruction in PyTorch
• sigpy — Signal processing for inverse problems
• deepinverse — Deep learning for inverse problems

License

MIT — see LICENSE for details.