Skip to content

FSE trains: exact derivatives for the Busse and PD designs - #231

Merged
mcencini merged 1 commit into
mainfrom
claude/project-thread-5qxlqi
Nov 12, 2026
Merged

mcencini merged 1 commit into
mainfrom
claude/project-thread-5qxlqi

Conversation

@mcencini

Copy link
Copy Markdown
Contributor

Requested by Matteo · project thread

What changed

No residual or cost in the Busse and PD refocusing-train designs is differenced any more; every derivative is exact.

  • PD shooting (_pd.py): the 2×2 Newton Jacobian comes from prescribed_flips(signal_tangents=), using analytic derivatives of the envelope with respect to level, ratio and plateau fraction (_Envelope). _pd_fraction_slopes gives the solved train's derivative with respect to the plateau fraction, by the implicit function theorem over the two levels.
  • Busse optimizer (_busse_opt.optimize_controls): dflip/du comes from busse_flips(jacobian=True) (cached as _busse._schedule_slopes). The ensemble echoes and their slopes come from forward-mode JVPs through FSESimulator: torch.func.jvp vmapped over the 2 directions, on blochsim's native simulate_jvp. The PSF radius, contrast, RF-energy and effective-TE constraints are differentiated analytically from those, the last through effective_te(flip_tangents=). Each SLSQP evaluation is one ensemble forward plus one JVP per control, where it was 5 forwards on probes.
  • PD optimizer (_pd_opt.optimize_pd_controls): works the same way, with 1 direction (plateau fraction).
  • The duplicated TimedFSE of _pd_opt is now shared as _busse_opt._ForwardSignal.
  • The design extra pins blochsim>=0.0.19.

Why

Matteo found the finite differences numerically unstable. The optimizers stepped 0.025° in angle through a float32 simulator, so the gradient carried round-off noise. The design runs on the scanner host's CPU.

Depends on pulserver/blochsim#57 (tangent kernels, busse_flips(jacobian=True)). CI here will fail on the blochsim>=0.0.19 pin until that is merged and released.

Validation

  • pytest -q -n 4 against blochsim#57 installed editable: 5338 passed, 37 skipped.
  • bash scripts/format_and_lint.sh --check: all checks passed.
  • New tests check the exact derivatives against central differences:
    • test_busse_schedule_slopes_are_the_derivative_of_the_schedule
    • test_psf_radius_slopes_are_its_derivative
    • test_ensemble_echo_slopes_are_the_derivative_of_the_simulated_echoes (float32 simulator, so a 1e-2 step)
    • test_pd_fraction_slope_is_the_derivative_of_the_solved_train
  • test_outer_fit_keeps_family_and_improves_forward_psf now records through _ForwardSignal, because vmapped JVP tensors have no storage to copy.
  • OMP_NUM_THREADS=1 python benchmarks/busse_schedule.py, run on this branch and on main in the same container. The fitted angles and PSF are the same, and the fits take equal or less time:
ETL fit, main (s) fit, this PR (s) min / centre angle, this PR (°) PSF RMS, prescribed → fitted (voxels)
40 0.42 0.37 30.000 / 67.696 1.7935 → 1.7416
80 1.58 1.48 23.263 / 70.615 1.5169 → 1.5119
120 3.07 3.04 20.548 / 71.620 1.6135 → 1.5320
160 2.81 2.75 20.000 / 70.428 1.7580 → 1.6070

These timings are from this container and only compare the two branches.

Documentation impact

None. The changed functions are private, and the public make_busse_schedule/make_pd_schedule return the same trains. benchmarks/busse_schedule.py also clears the new slopes cache between timed fits.


Generated by Claude Code

Copy link
Copy Markdown
Contributor Author

CI is red at install, before any test runs: Could not find a version that satisfies the requirement blochsim>=0.0.19 (from pypulseqpp[design,dev]). The latest blochsim on PyPI is 0.0.18.

This is expected. The pin is to the tangent kernels and busse_flips(jacobian=True) from pulserver/blochsim#57. Once #57 is merged and blochsim 0.0.19 is released, re-running CI here should go green. Locally, against #57 installed editable: pytest -q -n 4 gave 5338 passed, 37 skipped.


Generated by Claude Code

The PD shooting and both outer optimizers take their derivatives from
blochsim: the Newton Jacobian from prescribed_flips tangents, the train's
slope with respect to its controls from busse_flips(jacobian=True) or the
implicit function theorem over the PD levels, and the ensemble echoes'
slopes from forward-mode JVPs through FSESimulator. No residual or cost is
differenced any more. Requires blochsim>=0.0.19.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V
@mcencini
mcencini force-pushed the claude/project-thread-5qxlqi branch from 3cc126b to 6664d41 Compare November 12, 2026 18:28
@codecov

codecov Bot commented Nov 12, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.47059% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/pypulseqpp/_busse.py 77.77% 2 Missing ⚠️
src/pypulseqpp/_busse_opt.py 96.87% 2 Missing ⚠️
src/pypulseqpp/_pd_opt.py 93.54% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

@mcencini
mcencini merged commit dcf83e0 into main Nov 12, 2026
16 of 17 checks passed
mcencini added a commit that referenced this pull request Nov 13, 2026
…ve kernel

#231 took the optimizer's flip derivatives with torch.func.vmap(jvp(...)).
blochsim differentiates a sequence argument by reverse mode ("build a cost
and call backward()"), and its native packing reads the train's structure
with .tolist(), which a torch.func wrapper does not allow under the
PyTorch the deployed environments pin (2.7.1): every fse3d Busse protocol
failed at generation with "Cannot access data pointer of Tensor that
doesn't have storage" on the 7 T (exam 5195). CI passed because it only
ran the latest PyTorch.

_ForwardSignal.slopes now takes one backward pass, J^T u with create_graph,
and its derivative along each direction, J d: exact, plain autograd,
blochsim's native backward. In the deployed environment
tests/test_fse_busse.py and tests/test_fse_effective_te.py pass 40/40 (4
failed before, with the 7 T error); native reverse-mode gradients match
float32-safe central differences to 4-5 digits.

CI's Python 3.10 job now also installs torch 2.7.1.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
mcencini added a commit that referenced this pull request Nov 13, 2026
#235)

* EPI sequences: blip-free phase reference train in a dummy shot

epi2D/epi3D take phase_reference (default False) and navigator_lines (None:
NAVIGATOR_LINES without the reference, none with it). With the reference,
the last dummy shot of each slice (2D), of the volume (3D) and the FLEET
calibration's dummy shot plays the shot's own train with every phase- and
partition-encode prewinder, blip and rewinder scaled to zero, its lines
acquired and labelled PHASECORR; every train line carries its position in
the train in USER0 (ECHO_COUNTER). A scan without dummies plays one dummy
cycle for it. The reference reuses the imaging shot's events, so it adds no
segment. gain_calibration_readouts counts PHASECORR readouts with the
dummies, as it does navigators.

Scanner hot-fix, 13 Nov 7 T session (exam 5195 series 2: the navigator's
odd/even slope, +52 mrad/px, is not the train's, +35 mrad/px).

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

* Busse optimizer: exact slopes by reverse mode through blochsim's native kernel

#231 took the optimizer's flip derivatives with torch.func.vmap(jvp(...)).
blochsim differentiates a sequence argument by reverse mode ("build a cost
and call backward()"), and its native packing reads the train's structure
with .tolist(), which a torch.func wrapper does not allow under the
PyTorch the deployed environments pin (2.7.1): every fse3d Busse protocol
failed at generation with "Cannot access data pointer of Tensor that
doesn't have storage" on the 7 T (exam 5195). CI passed because it only
ran the latest PyTorch.

_ForwardSignal.slopes now takes one backward pass, J^T u with create_graph,
and its derivative along each direction, J d: exact, plain autograd,
blochsim's native backward. In the deployed environment
tests/test_fse_busse.py and tests/test_fse_effective_te.py pass 40/40 (4
failed before, with the 7 T error); native reverse-mode gradients match
float32-safe central differences to 4-5 digits.

CI's Python 3.10 job now also installs torch 2.7.1.

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

* Docs: the EPI phase reference train in the EPI tour; te without a navigator

The EPI tour says what the shipped EPI sequences acquire for the odd/even
correction: navigator lines, or with phase_reference the blip-free
reference train. The te default of epi2D/epi3D no longer assumes a
navigator.

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

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
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