Pulseq-based 3D single- or multi-echo Wave-GRE sequence generation with integrated FLASH wave calibration and Python reconstruction from Siemens TWIX data.

The repository has two intentionally separate parts:

• MATLAB generates the integrated GRE + FLASH calibration sequence.
• Python reconstructs wave or no-wave GRE data from the resulting Siemens TWIX measurement.

pyproject.toml defines only the Python reconstruction environment. This repository is not configured as an installable Python package and does not need to be published to PyPI.

.
├── README.md
├── pyproject.toml
├── uv.lock
├── .python-version
├── docs/
│   ├── sequence.md
│   ├── reconstruction.md
│   └── troubleshooting.md
├── seq/
│   ├── gre_3d_wave_with_flash_calibration.m
│   └── utils/
├── recon/
│   ├── recon_wave_gre_from_twix_integrated_nifti.py
│   └── utils/
└── external/

Recommended entry points:

seq/gre_3d_wave_with_flash_calibration.m
recon/recon_wave_gre_from_twix_integrated_nifti.py

• MATLAB
• Pulseq MATLAB toolbox

Optional scanner-safety checks can use Safe PNS Prediction, a scanner .asc file, and an existing forbiddenFreqCheck.m helper.

• Python 3.11
• CPU reconstruction dependencies defined in pyproject.toml
• Optional NVIDIA GPU and CUDA 12-compatible CuPy for faster ESPIRiT calibration

Current device behavior:

A GPU is optional. With --espirit-device auto, the reconstruction uses a compatible visible GPU when available and otherwise falls back to CPU.

git clone --recurse-submodules https://github.com/HarmonizedMRI/wave-gre-flow-comp.git
cd wave-gre-flow-comp

Install uv, then create the locked CPU-capable environment:

uv sync --locked

Run commands inside the environment with uv run:

uv run python recon/recon_wave_gre_from_twix_integrated_nifti.py --help

To include CUDA 12 CuPy for GPU-assisted ESPIRiT:

uv sync --locked --group gpu

The committed uv.lock records the exact resolved Python dependencies. The host NVIDIA driver and GPU remain system requirements and are not included in the lockfile.

pip 25.1 or newer can install the standardized dependency groups from pyproject.toml:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "pip>=25.1"
python -m pip install --group recon

On Windows PowerShell, activate the environment with:

.venv\Scripts\Activate.ps1

For CUDA 12 CuPy:

python -m pip install --group gpu

The pip route resolves compatible versions at installation time. Use uv sync --locked when exact lockfile reproduction is important.

Open MATLAB and run:

cd seq
gre_3d_wave_with_flash_calibration

On the first run, enter the requested paths. Machine-specific settings are saved beside the script in:

seq/gre_flash_path_settings.json

Leaving the output path blank uses MATLAB's current folder. Generated sequence files are written under:

generated_seq_v141/
generated_seq_v151/

See Sequence generation for acquisition order, calibration SET layout, geometry, flow compensation, path handling, and output behavior.

The measurement is expected to contain:

image    -> single- or multi-echo GRE k-space
refscan  -> four FLASH projection-calibration sets plus one ACS set

Review all command-line arguments:

uv run python recon/recon_wave_gre_from_twix_integrated_nifti.py --help

Typical reconstruction with automatic wave/no-wave detection, automatic ESPIRiT device selection, and NIfTI export:

uv run python recon/recon_wave_gre_from_twix_integrated_nifti.py \
    --twix /path/to/meas_wave_gre.dat \
    --seq /path/to/matching_wave_gre.seq \
    --out /path/to/reconstruction \
    --wave-mode auto \
    --espirit-device auto \
    --save-nifti \
    --save-nifti-phase

Force a fully CPU-capable run:

uv run python recon/recon_wave_gre_from_twix_integrated_nifti.py \
    --twix /path/to/meas_wave_gre.dat \
    --seq /path/to/matching_wave_gre.seq \
    --out /path/to/reconstruction \
    --wave-mode auto \
    --espirit-device cpu

Use --espirit-device gpu --espirit-gpu-index 0 to require a specific GPU. Explicit GPU mode raises an error instead of silently falling back when the requested GPU is unavailable.

See Reconstruction for supported acquisition assumptions, the pipeline, complete argument guidance, cache reuse, outputs, and NIfTI conventions.

• Sequence generation
• Reconstruction
• Troubleshooting

Author: Yiyun Dong, Athinoula A. Martinos Center for Biomedical Imaging.

The GRE implementation is based on Berkin's GRE code in the HarmonizedMRI megre_label repository. The integrated calibration organization and path-setting workflow follow the Wave-MPRAGE project.

MIT License. See LICENSE.