Skip to content

FSE trains: design Busse and PD schedules with blochsim.trains - #228

Merged
mcencini merged 2 commits into
mainfrom
busse-via-blochsim
Nov 11, 2026
Merged

mcencini merged 2 commits into
mainfrom
busse-via-blochsim

Conversation

@mcencini

Copy link
Copy Markdown
Contributor

What

The NumPy extended phase graph that #224 added for the Busse and PD refocusing schedules is removed. make_busse_schedule, make_pd_schedule, calc_fse_effective_te and the effective-TE centre search of fse3D_sequence now call blochsim.trains (pulserver/blochsim#56), which inverts the phase graph in a C++ kernel.

Depends on blochsim 0.0.18, which is pulserver/blochsim#56 merged and released. Until that version is on PyPI the Install step of the test jobs cannot resolve blochsim>=0.0.18 and CI fails; that is expected. Merge order: blochsim#56, tag blochsim v0.0.18, wait for PyPI, re-run CI here, merge, release pypulseqpp.

Changes

  • _busse.py: the forward and inverse EPG, the pseudo-steady-state function and both shooting solvers are gone (372 to 180 lines). make_busse_schedule keeps its signature, validation and cache and calls blochsim.trains.busse_flips; _make_busse_schedules calls it once for the batch.
  • _fse_contrast.py: calc_fse_effective_te calls blochsim.trains.effective_te. _select_busse_centre calls busse_centre_echo, which designs the train for every candidate centre in one batch and returns the nearest; the Python bisection and its per-candidate cache are gone.
  • _pd.py: _inverse_pd calls blochsim.trains.prescribed_flips with relaxation. The PD signal family and its solver are unchanged.
  • blochsim is imported inside these functions, never at import pypulseqpp, and blochsim.trains does not import PyTorch. Without blochsim they raise ImportError naming the design extra.
  • design = ["blochsim>=0.0.18"]; the test jobs install .[dev,design] with the CPU build of PyTorch on Linux.
  • Docs: installation pages, extras table, AGENTS.md, the build-and-test skill, and the docstrings of the four functions and of fse3D_sequence say which paths need blochsim.

Parity

tests/fixtures/fse3d_busse_trains.json freezes the trains of two 3D FSE acquisitions as 0.0.62 designed and played them (60 echoes after 6 startup echoes, effective TE 60 ms and 44 ms).

TE 60 TE 44
Largest flip-angle difference from the played train 4.2e-11 deg 7.1e-11 deg
Centre echo selected 32 (played 32) 21 (played 21)
Effective TE of the centre echo, difference 0 s 0 s

The tests hold these to 1e-7 deg in angle, 1e-9 in the relaxation-free echo signal (isochromat summation of both trains), an identical centre echo, and 1e-9 s in effective TE. PD schedules of 26 to 166 pulses differ from 0.0.62 by at most 6.6e-12 deg.

Sequence structure is untouched: the same flip angles go into the same blocks, so segmentation, waveform memory and played time are unchanged.

Timing

Laptop under load (load average about 30); centre search plus schedule for the ETL 60 train, median of 5 fresh processes:

0.0.62 (NumPy) this PR
First call in a fresh process 460-550 ms 32-36 ms
Warm 340-375 ms 28 ms
Importing the engine n/a 1.6 ms, PyTorch not imported
make_pd_schedule, 26-166 pulses 0.5-3.2 s 10-53 ms

Not measured on the scanner host or the simulator image.

Tests

With blochsim built from pulserver/blochsim#56: full suite pytest -n 8, 5184 passed, 37 skipped (reference toolbox absent), plus tests/test_sequence_docstrings.py (140 passed) once sphinx was installed in the environment. ruff check and ruff format --check clean.

A decision for the maintainer: blochsim stays an optional extra, so a plain pip install pypulseqpp can no longer design Busse or PD trains or compute the effective TE. Making it a hard dependency would bring PyTorch into every install.

🤖 Generated with Claude Code

mcencini and others added 2 commits November 10, 2026 21:13
The NumPy phase graph in _busse.py, _pd.py and _fse_contrast.py is removed.
make_busse_schedule, make_pd_schedule, calc_fse_effective_te and the
effective-TE centre search call blochsim.trains (blochsim>=0.0.18, the design
extra), which inverts the phase graph in a C++ kernel and tries every centre
echo in one batch. blochsim is imported when a schedule is designed, and
importing blochsim.trains does not import PyTorch.

The trains two 3D FSE acquisitions played are frozen as a fixture and
reproduced in angle, signal, centre echo and effective TE.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…9 deg

The API tables name the design extra for the three functions blochsim
computes, the played trains are held to 1e-9 degrees, and a design without
blochsim is tested to raise an ImportError naming the extra.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@codecov

codecov Bot commented Nov 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 86.36364% with 3 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/pypulseqpp/_busse.py 84.61% 2 Missing ⚠️
src/pypulseqpp/_fse_contrast.py 85.71% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@mcencini
mcencini marked this pull request as ready for review November 11, 2026 02:20
@mcencini
mcencini merged commit 4f7de3f into main Nov 11, 2026
15 of 23 checks passed
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.

1 participant