Wave-encoded multi-echo GRE with flow compensation

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.

Repository layout

.
├── README.md
├── pyproject.toml
├── uv.lock
├── .python-version
├── docs/
│   ├── sequence.md
│   ├── reconstruction.md
│   └── troubleshooting.md
├── seq/
│   ├── gre_3d_wave_with_flash_calibration_tra.m
│   ├── gre_3d_wave_with_flash_calibration_sag.m
│   └── utils/
├── recon/
│   ├── recon_wave_gre_from_twix_integrated_nifti.py
│   ├── bart/
│   │   ├── run_wave_recon.sh
│   │   ├── wave_to_nifti.py
│   │   └── bart_utils/
│   ├── tests/
│   └── utils/
└── external/

Recommended entry points:

seq/gre_3d_wave_with_flash_calibration_tra.m
seq/gre_3d_wave_with_flash_calibration_sag.m
recon/recon_wave_gre_from_twix_integrated_nifti.py

Requirements

Sequence generation

• MATLAB
• Pulseq MATLAB toolbox

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

Reconstruction

• Python 3.11
• CPU reconstruction dependencies defined in pyproject.toml
• GPU-enabled BART and an NVIDIA GPU for the default bart wave -g or bart pics -g path
• Optional CUDA 12-compatible CuPy only for GPU SigPy ESPIRiT in the explicit SENSE path

Current device behavior:

Step	Device
Coil-compression estimation and application	CPU
Default sensitivity-map calibration	BART ecalib; SigPy ESPIRiT is skipped
Default Wave reconstruction	BART GPU wavelet/FISTA (-w -f -g)
Default no-wave reconstruction	BART Cartesian PICS (-l1 -r 1e-5 --fista -i 300 -g -S)
Explicit legacy Wave/no-wave CG-SENSE	CPU

A GPU is optional. With --espirit-device auto, the reconstruction uses a compatible visible GPU when available and otherwise falls back to CPU. For acquisitions with more than 32 physical receiver channels, consider --espirit-device cpu when GPU memory is limited or CPU resources are more suitable.

ESPIRiT calibration modes

The explicit --reconstruction-backend sense path supports two SigPy sensitivity-map calibration modes:

• --espirit-calib-mode 3d is the native SigPy 3D method and remains the default/reference. It can use --espirit-device auto, cpu, or gpu.
• --espirit-calib-mode slice2d removes readout oversampling first, transforms logical readout to hybrid space, and runs independent 2D ESPIRiT calibrations across the joint LIN-PAR plane. It is CPU-only and is useful when native 3D CPU calibration is too slow or memory-intensive.

The top-level --espirit-crop also configures bart ecalib -c when using the default BART backend. On the explicit SENSE backend it applies to both SigPy modes. A practical tested range is 0.8–0.9: use 0.8 for broader low-SNR support and 0.9 for a stricter map-support mask.

For slice2d, omit --espirit-cpu-workers to use Joblib's available physical-core count automatically, or set an explicit limit on shared systems. For example:

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 \
    --reconstruction-backend sense \
    --espirit-calib-mode slice2d \
    --espirit-device cpu \
    --espirit-crop 0.8 \
    --espirit-cpu-workers 16

Before either backend, integrated set-4 ACS readout oversampling is removed by a centered IFFT, central nominal-FOV image crop, and centered FFT. Direct k-space striding is forbidden because it aliases outside-FOV anatomy into the coil calibration. Native 3D and slice2d CSM files use separate versioned cache names, while the coil-compression matrix is shared. A hash-bound JSON manifest prevents reuse of historical stride-derived caches or mismatched settings.

Clone

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

Install the reconstruction environment

Recommended: uv

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.

Alternative: pip

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.

Generate the integrated sequence

Open MATLAB and run:

cd seq
gre_3d_wave_with_flash_calibration_tra  % or gre_3d_wave_with_flash_calibration_sag

Review the machine-specific Pulseq, optional safety-tool, output, and scanner .asc paths near the beginning of each source. Generated v1.5.1 sequence files are written under:

evaluation/output/v1.5.1/high_slew_wave_gre_tra/
evaluation/output/v1.5.1/high_slew_wave_gre_sag/

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

Scanner protocol recommendations

For the verified transverse Wave-GRE workflow:

• prescribe phase encoding right-to-left (R -> L);
• disable neck-coil elements when they are not needed for the target anatomy, to reduce neck and shoulder signal contamination;
• place the FOV box so it covers the complete signal-producing volume. Anatomy outside the prescribed FOV can wrap into the acquisition, and wave-induced aliasing from that signal may not be fully resolved.

Follow local scanner-safety and coil-selection procedures.

Reconstruct an integrated acquisition

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 \
    --coil-compression-channels 12 \
    --espirit-device auto \
    --save-nifti-phase

Wave acquisitions export the calibrated PSF, coil-compressed k-space, and ACS in BART CFL format by default, then run BART ecalib and wave. No-wave acquisitions remove readout oversampling with centered image-domain cropping, export logical-grid Cartesian k-space, and run BART ecalib and GPU pics with -S. Select --reconstruction-backend sense only when the traditional local CG-SENSE solver is required. The companion recon/bart/run_wave_recon.sh and recon/bart/run_cartesian_recon.sh wrappers can also be run independently. NIfTI conversion is enabled by default and can be disabled with --no-save-nifti in the integrated command or --skip-nifti in the wrapper. A rerun with the same TWIX, sequence, output directory, and tag automatically reuses complete, current BART maps and echo images. If BART was killed after input export, validated modern BART inputs skip TWIX preprocessing and resume missing maps or echo images in place. --resume may be passed explicitly; use --no-resume to force reconstruction. Complete legacy BART outputs without source-path provenance are validated and upgraded in place on their first resumed run. The virtual-coil count is configurable with --coil-compression-channels N; --vcc-channels and the existing --ncc spelling are equivalent aliases. Use --no-vcc (alias --no-coil-compression) to bypass SVD compression and retain all physical channels. This can substantially increase BART memory use. See Reconstruction for dimensions and usage.

For lightweight sensitivity-support inspection without TWIX or sequence metadata, convert BART maps in unchanged logical axis order:

python recon/bart/csm_to_nifti_local.py \
  --csm /path/to/coil_sens_bart \
  --out /path/to/coil_sens_bart_rss.nii.gz \
  --voxel-size 0.64 0.64 0.64

This diagnostic NIfTI uses a synthetic affine and must not be interpreted as having correct anatomical orientation.

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. PSF coefficients use smoothing by default. If their diagnostic looks unreliable, sine-line can first select a fit interval automatically; both kx bounds remain available as a reproducible manual override. See Reconstruction and Troubleshooting.

Documentation

• Sequence generation
• Reconstruction
• Troubleshooting

Attribution

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.

License

MIT License. See LICENSE.