Skip to content

EPI recon: delay-aware ramp regrid, one coil-map volume, CG-SENSE, one distortion field per stack - #385

Open
mcencini wants to merge 18 commits into
mainfrom
claude/project-thread-72h2ls
Open

mcencini wants to merge 18 commits into
mainfrom
claude/project-thread-72h2ls

Conversation

@mcencini

@mcencini mcencini commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Matteo · project thread

What changed

Proxy (proxy/_enrich.py)

  • A navigator space with no geometry of its own sits on the grid of the imaging lines it navigates. Both therefore carry the same half-voxel phase, and the navigator measures the train's own odd/even phase.
  • Ramp sampling is detected from the readout's 1D k-space trajectory (uneven sample spacing), not from trapezoid parameters in [DEFINITIONS].
  • Multiband: each band group is reconstructed as a partition volume. The matrix along z is the multiband factor, and the FOV along z is that factor times the band gap. The volume is centred on the group.

EPI recon (recon/handlers/epi.py)

  • The read-gradient delay is fitted once per stream from the navigator or reference odd/even linear phase, by the secant method. The ramp regrid (bartorch.tools.epi_ramp_operator) delays the trajectory by that amount before resampling.
  • Coil maps come from the calibration scan once: each calibration slice (or slab) is fitted by nlinv on its own, never per frame. A slab's maps use a lower Sobolev weight (EPI_SOBOLEV, through nlinv_maps(sobolev=...), bartorch#177) so they follow the sensitivity across its wrapping end partitions; a slice keeps BART's weight.
  • Multiband: when every band of a group lies on a calibrated slice, split-slice GRAPPA (bartorch.tools.slice_grappa_kernel / slice_grappa, bartorch#177) separates the bands, trained on those slices' calibration k-space, and each band is solved as its own slice. Joint CG-SENSE over the partition volume remains for groups without that calibration. No background masking.
  • Solvers:
    • Fully sampled: linear SENSE combine.
    • Undersampled: wavelet PICS by default, at EPI_WAVELET_SLAB (0.1) for a slab and EPI_WAVELET_SLICE (0.03) for a slice; wavelet=0 gives CG-SENSE (bartorch.optim.CG).
    • POCS for partial Fourier.
  • Distortion: one PyHySCO field is estimated for the whole stack, from the phase-encode-reversed reference, with the edge partitions replicate-padded. It is applied to every frame and re-estimated only when a new reference arrives.

Virtual scanner (virtual/_fourier.py)

  • The Fourier engine acquires a station's samples in batches that fit its memory budget. Before this, a 3D slab with a B0 field allocated 18.5 GB at once.
  • A batch whose samples all lie on a 3D grid's kz = 0 plane is transformed as the 2D transform of the image summed along z. bartorch transforms an all-zero-kz trajectory in 2D, and without this the batch's samples came back on the wrong grid.

Zoo: the EPI 2D and 3D evaluations count the calibration that every scan now opens with (pypulseqpp#239).

Why

Measured in the physics simulation (blochsim EPG plus NUFFT virtual scanner):

Before After
Ghost at a 5 µs read delay 7.8% 0.42%
Ghost at a 10 µs read delay 15% 0.49%
Distortion NRMSE at 40 Hz/cm (6 slices) 0.44 0.12
R=2 alias residual 16–28% (PICS) ~3% (CG)

Recon takes about 4 s for 36 slice-frames on CPU.

Validation

bash scripts/format_and_lint.sh --check    All checks passed!
pytest -q -n 4 -ra                         9 failed, 4105 passed, 105 skipped, 2 errors   (before the virtual-scanner commits)
pytest -q -n 2 tests/test_virtual*.py      530 passed, 32 skipped                          (at 1bc2ee9)

Of those 9 failures:

  • 4 are the epi3d evaluation and flip-layout tests. They are fixed in a later commit and now pass: pytest tests/test_zoo_evaluation.py -k "flip_angle_scales or epi" gives 98 passed.
  • 5 are the *_import_no_torch tests. They fail in this container because python -S cannot see the editable pypulseqpp's compiled extension.

The 2 errors are the test_proxy DICOM-receiver tests, which need pynetdicom, a package not installed here. Both the 5 failures and the 2 errors also occur on main in this environment.

New tests:

  • tests/recon/test_epi_solve.py
  • the delay-fit test in tests/recon/test_epi.py
  • the stack-field tests
  • the navigator-grid and trajectory ramp tests in tests/test_enrich.py
  • test_a_scan_acquired_in_batches_under_a_small_budget_reads_what_it_reads_whole
  • test_a_3d_image_sampled_only_on_its_kz_zero_plane_transforms_as_in_3d

Multiband and 3D, end to end through this recon (7T sim, 32-ch head coil, noise-free, NRMSE vs a single-band / fully sampled reference with the same TE):

Before After
2D MB2 0.123 0.029
2D MB2 × Ry2 0.31 0.073
3D Ry2 0.065 0.031
3D Rz2 0.063 0.014
3D CAIPI 2×2 0.19 0.17 (CG); noise-limited on an 8-partition slab

With noise (0.2% of the k-space peak), 8-partition slab:

  • Ry2 goes from 0.37 to 0.050.
  • CAIPI 2×2 goes from 0.49 to 0.127 with the default wavelet prior (fully sampled at that noise: 0.058).

On a 16-partition slab, CAIPI 2×2 CG is 0.114 noise-free at 30 iterations. Coil compression to 6 virtual coils was checked and is not limiting: 16 and 32 coils give the same.

The 2D figures need pypulseqpp#239's CAIPI receiver phase. CI needs releases of bartorch (#177) and pypulseqpp (#239), and the floors bumped. Per Matteo, releases wait until the EPI work is complete.

Documentation impact

  • docs/api/recon.md gains volume_coil_maps.
  • The epi row in docs/user-guide/reconstruction-plugins.md describes the new behaviour.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB

…one stack distortion field

- A navigator space without geometry of its own is on the grid of the
  readouts it navigates, so it carries their half-voxel phase and measures
  the odd/even phase the train carries.
- Whether a Cartesian readout is ramp sampled is decided from its k-space
  trajectory, not from trapezoid rise and flat times.
- EpiPhaseCorrection fits the read-gradient delay to the first reference
  train or navigator (secant on the linear term) and RampSampling resamples
  every readout along the trajectory delayed by it.
- EpiRecon estimates the coil sensitivities of the whole stack once, as one
  volume (volume_coil_maps), combines fully sampled units by least-squares
  SENSE, solves undersampled ones by CG-SENSE, completes partial Fourier by
  POCS, and corrects every image by one displacement field estimated from
  the stack's first volume and its reversed reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
…lumes

The zoo EPI evaluations count the calibration every scan opens with. A
multiband group's bands are the partitions of one volume, whose maps are the
stored slices' maps at the band positions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
@mcencini mcencini self-assigned this Nov 21, 2026
@codecov

codecov Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 76.00000% with 102 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/pulserver/recon/handlers/epi.py 81.23% 41 Missing and 23 partials ⚠️
src/pulserver/proxy/_enrich.py 35.89% 20 Missing and 5 partials ⚠️
src/pulserver/recon/_calibration.py 70.45% 8 Missing and 5 partials ⚠️

📢 Thoughts on this report? Let us know!

Copy link
Copy Markdown
Contributor Author

CI is red on 4 test_zoo_evaluation.py epi3d cases (scan_time_of_the_design[epi3d], [epi3d+NAVIGATOR-navigator], [epi3d-frames], regular_tr_of_the_design[epi3d-frames]).

The cause is a version mismatch. CI installs the released pypulseqpp (0.0.69), whose epi3d does not play the calibration at R=1. This PR's evaluation counts the calibration, because pulserver/pypulseqpp#239 makes every EPI scan open with it. Against a pypulseqpp checkout that includes #239, the same tests pass (pytest tests/test_zoo_evaluation.py -k "flip_angle_scales or epi": 98 passed).

The fix is to release pypulseqpp with #239 and raise the pypulseqpp>= floor in this PR. That release is waiting on the maintainer's OK.


Generated by Claude Code

…onov weight on CG-SENSE

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
…n object filling the field of view at R=3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
…on maps

A multiband unit whose bands each lie on a calibrated slice has its bands
separated by split-slice GRAPPA (bartorch.tools.slice_grappa_kernel /
slice_grappa), trained on those slices' calibration k-space, and each band
is solved as its own slice; joint CG-SENSE remains for units without that
calibration. Each calibration slice is fitted its own nlinv maps: a slice
stack with gaps is not a contiguous volume.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
nlinv_estimate takes the Sobolev weight of the maps; the EPI recon fits its
calibration at EPI_SOBOLEV, so the maps follow the sensitivity where SENSE
unfolds in-plane, multiband and partition aliases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB

Copy link
Copy Markdown
Contributor Author

CI on 76fe254 has one new failure besides the epi3d evaluation tests (those need the pypulseqpp release with #239). test_split_slice_grappa_returns_each_caipi_band_of_a_multiband_unit_as_its_own_kspace needs bartorch.tools.slice_grappa_kernel from pulserver/bartorch#177, which isn't released yet. The same goes for nlinv_maps(sobolev=...), used by the EPI coil maps since 0b6703f. Both will pass once bartorch and pypulseqpp are released and their floors are bumped. Per Matteo, releases wait until the EPI work is complete. Locally, the recon and docs tests pass against the branches.


Generated by Claude Code

A slice's maps keep BART's weight: split-slice GRAPPA and SENSE of a
multiband slice group unfold best with them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
A slab at EPI_WAVELET_SLAB, a slice at EPI_WAVELET_SLICE; wavelet=0 keeps
the conjugate-gradient SENSE solve.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
At PyHySCO's own weight, a slab whose blip-up and blip-down images differ
only by T2* blur gets a field that steps by over half a voxel between lines,
and its Jacobian darkens a line of the corrected image. A weight of 3000
removes the step; a 5 Hz/cm linear field is still corrected as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
At 7T the off-resonance phase near the sinuses wraps within a few voxels
by a BOLD echo time, and a wavelet prior on that complex image rings at
each wrap. The maps of the wavelet solve carry the low-passed phase of
the conjugate-gradient SENSE image, so the prior acts on a near-real
image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
…ities

The calibration's forward and reversed shots share the imaging's echo
spacing, and so its distortion, at the calibration's short echo time. At
7T the imaging volume and its reversed reference at a BOLD echo time
lose signal near the sinuses, and a field fitted to them corrects less
than none. The reversed reference volume remains the reference of a scan
without a FLEET calibration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
…ibration

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
At a 128 matrix and threefold in-plane undersampling, FISTA from zero is
far from converged after the iterations a slice is given, while the
conjugate-gradient SENSE image the phase is taken from already is.
pics_image takes an optional starting image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
A station's signal weights and transforms grow with its samples; a 3D
slab with a susceptibility field asked for 18 GB in one batch. The
samples are now taken in batches that fit _BUDGET.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
A batch of samples that all lie on a 3D grid's kz = 0 plane is
transformed as the 2D transform of the image summed along z, which is
what bartorch's 2D transform of such a trajectory expects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB
… engine

The temporal basis is chosen over the atoms' signals both alone and weighted
by the magnetization each carries, so a class holding most of the image keeps
its terms when thousands of small classes share another signal. Truncation
energies accumulate in double precision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MFB6QKTJCRjBZwuMZZnaBB

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants