Skip to content

trains: exact forward-mode derivatives of designed refocusing trains - #57

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

mcencini merged 2 commits into
mainfrom
claude/project-thread-5qxlqi

Conversation

@mcencini

Copy link
Copy Markdown
Contributor

Requested by Matteo · project thread

What changed

The _trains_cpu kernels can now return exact derivatives as well as values. They carry one extra set of EPG states per direction through the echo-by-echo recursion, which is forward mode. Each pulse's angle is solved in closed form, so its derivative follows from the implicit function theorem when the echo is met, from atan2(c, b) at an extremum, and is zero at an end of [0, π]. The new public options:

  • prescribed_flips(..., signal_tangents=, first_flip_tangents=) also returns the derivatives of the angles and of the echoes.
  • effective_te(..., flip_tangents=) also returns the derivatives of the echo times.
  • busse_flips(..., jacobian=True) also returns (…, echoes, 3), the derivatives of the train with respect to min_flip, centre_flip and max_flip. They come from the implicit function theorem over the shooting, with max_flip entering both directly and through the opening transient.

The Busse shooting's damped Newton steps and its MINPACK fallback now take their Jacobian from these derivatives instead of differencing the residual (_STEP_DEG is gone). _pss and _target carry their own derivatives.

Forward mode's torch.jit.script deprecation is silenced whatever warning class PyTorch raises it as. PyTorch 2.15 raises a FutureWarning.

Why

Finite differences in the train design were numerically fragile. This PR provides the derivatives the pypulseqpp Busse/PD optimizers need so they can drop finite differences entirely (companion pypulseqpp PR to follow). The design runs on the scanner host's CPU.

Validation

  • pytest tests/trains: 119 passed. New tests check every set of derivatives against central differences:
    • inverse angles and echoes, with and without relaxation and with a given first angle (atol 1e-6 deg / 1e-8);
    • effective TE;
    • the Busse Jacobian at two prescriptions (atol 1e-6), and that it plays each angle asked for one-to-one;
    • the batch Jacobian is zero past each train;
    • the PSS slope;
    • an out-of-reach echo whose angle ignores its target.
  • The busse_flips results are unchanged: the Figure 1 fixture and the hybrid-fallback tests pass as before. One 106-pulse design takes about 2.9 ms against 2.1 ms before (10-call loop, this container).
  • Full suite pytest tests -n 4: 1673 passed, 327 skipped, 1 failed. The failure was test_an_image_quality_design_fits_in_its_budget at 3.01 s against its 3.0 s wall-clock budget under parallel load. It passes alone (3.00–3.10 s here) and does not touch the trains.
  • pre-commit run --all-files: clean.

Documentation impact

  • docs/api/trains.md gains a paragraph on the derivatives.
  • The docstrings of the three functions document the new arguments and returns.
  • CHANGELOG has an entry under Added and one under Fixed.
  • bash scripts/build_docs.sh was not run in this session.

Checklist

  • pytest tests/ passes locally (except the wall-clock budget test above), and new tests cover what changed.
  • pre-commit run --all-files is clean.
  • Public functions carry a numpydoc docstring.
  • Comments and docstrings describe the code as it is now.
  • The kernel change is pinned against central differences of the unchanged value path. The trains kernels are host-only, with no GPU counterpart.
  • bash scripts/build_docs.sh not run here.

Generated by Claude Code

The C++ train kernels carry one extra set of EPG states per direction
through the echo-by-echo recursion, so prescribed_flips, effective_te and
busse_flips return exact derivatives (signal_tangents, flip_tangents,
jacobian=True). The Busse shooting takes its Newton and MINPACK Jacobians
from them instead of differencing the residual. Forward mode also silences
the torch.jit.script deprecation whatever warning class PyTorch raises it as.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V
@mcencini
mcencini merged commit d0c04c2 into main Nov 12, 2026
34 of 35 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.

2 participants