Skip to content

Scanner 11 Nov: hot-fixes from the 7 T session - #230

Closed
mcencini wants to merge 15 commits into
mainfrom
scanner-1111-hotfixes
Closed

mcencini wants to merge 15 commits into
mainfrom
scanner-1111-hotfixes

Conversation

@mcencini

@mcencini mcencini commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Collects every pypulseqpp fix made during the 11 Nov 7 T session. Each one is deployed on the scanner as a hot-fix (replaced package files in the scanner's Python environment), and this PR is merged only after the scan session has confirmed them.

Fix Hot-fixed on scanner Confirmed on scanner
bSSFP (BssfpReadout2D/3D): the slice rephasers and partition encodes share the ramp on which the largest summed lobe is fastest at the slew rate, not the full-scale ramp max_grad / max_slew (604 us at 80 mT/m and 132.6 T/m/s, which made the 2D rewind a 1.208 ms triangle at 19 T/m/s). Slot 2 default (192x192, 300 mm, 8 mm, 125 kHz): TR 5.016 -> 3.736 ms at 132.6 T/m/s, 3.912 ms at the 105 T/m/s the design server lowers it to for PNS; slot 3: 8.512 -> 7.280 ms (default), 8.104 -> 7.176 ms (64 partitions). Moments per TR exact on every axis; segments unchanged staged: sequences/readout/bssfp.py ☑ 11 Nov (TR 3.91 ms on slot 2)
bssfp2D_sequence: an ungated train plays each slice's lines n_phases times back to back, a free-running series labelled PHS, with no dummies between frames (it played one frame whatever n_phases); needs the bssfp2d plugin evaluate of pulserver #379 for the console scan time staged: sequences/sequence/bssfp2D_sequence.py ☑ 11 Nov (9 slices x 2 frames)
epi2D_sequence, epi3D_sequence: the gradient-echo calibration plays CALIBRATION_FLIP_DEG = 10° whatever the imaging flip (2D: the single-band pulse's samples scaled, no second SLR design; 3D: the excitation designed at the imaging pulse's duration), so it plays the imaging waveform and the RF definition and segments are unchanged. Exam 28827 (epi2d, flip 70, R 3, 2 slices) was refused at predownload: the calibration played the 70° pulse every 6.4 ms, SAR at 117% of its 10 s limit; at 10° it is (10/70)² of that, about 2.4 %. At 70° the calibration's k-space centre also carried about 1 % of its first line's signal. Needs the epi2d/epi3d RF layout bound of pulserver #379 for the console to refuse what predownload would staged: sequences/sequence/epi2D_sequence.py, epi3D_sequence.py (build/scanner-2026-11-11/hotfix-epi-calib/) ☐
BssfpReadout2D(bridge=True) and bssfp2D_sequence: the slices of a free-running scan of several slices join their blocks on the slice axis (the selection ramps run through zero to 1/16 of the plateau where the excitation block meets the rewind and the acquisition; gz_open/gz_close open and close a slice at rest), so a scanner that cuts segments between blocks at rest plays a slice as one segment: local 128², 9 slices, 16 frames: 24570 → 9 segment starts, RF to RF 3614 → 3360 µs in every TR, echo −127 → 0 µs from half the played TR. Block durations, TR and TE unchanged (falls back to the resting layout where bridging would lengthen a window). A single slice, a gated train and the 3D readout are unchanged. One slice is then one segment of lines × frames × 3 blocks (8189 blocks, 819,000 RF samples here), not yet played in the simulator or on the scanner staged, not deployed: build/scanner-2026-11-11/hotfix-bssfp-bridge/ ☐
bssfp2D_sequence: every 2D slice is one bridged train. A single ungated slice is bridged too (2c2679b). Gated (7bac2b1): a prospective slice waits for ONE trigger, ahead of its half flip, then runs free at the nominal heart rate, each heartbeat's cardiac phases followed by repetitions that do not acquire (prospective_starts); retrospective plays as before with no trigger. After the first beat the prospective phases follow the heart rate entered, not the patient's staged, not deployed: hotfix-bssfp-single/ (app ddf3890c) then hotfix-bssfp-gated/ (app 15d45034) ☐
BssfpReadout2D(bridge=True) always bridges (2c7e15f): the earlier fallback to the resting layout un-bridged every prescription on a 4 µs gradient raster (scanner series 21/22, seg 1 nb=3), at the minimum TR and at a SAR-raised one alike. The windows now hold the bridged rephasers; a longer TR lengthens the acquisition and rewind blocks, which carry lobes end to end. Offline at 4 µs rasters, 105 T/m/s: 1 segment per slice at TR 4.0, 8.0 and 15.6 ms, RF to RF constant, echo at TR/2 staged, not deployed: hotfix-bssfp-anytr/ (readout af998541) ☐
Adaptive EPI ADC sampling (32a4cb532): the shared 2D/3D readout adds the minimum raster-compatible sample count needed to retain the requested dwell across the gradient-limited window, preserving k-space extent. Counts obey the ADC divisor; a receiver sample cap falls back to a longer dwell. Uses the existing gradient and timing helpers. Requires the pixel-bandwidth and triangular-trajectory changes in pulserver #379. deployed 11 Nov: readout plus both sequence-function files; hashes/backups checked ☐ acquisition pending
2D fat saturation (epi2D) and saturation bands (gre2D, se2D) designed under pp.cap_system(system, max_slew=PREPARATION_MAX_SLEW), 40 T/m/s: their three-axis spoilers set the nerve stimulation of the whole sequence, so the slew search slowed a fat-sat EPI to 49.9 T/m/s instead of 88 (8a6b9dc) staged 12 Nov: build/scanner-2026-11-12/hotfix-prep-slew/ ☐
FLEET calibration for EPI (489dea9, 9934531), the default; calibration="gre" keeps the gradient echo. The central n_acs_y lines (rounded up to whole shots, at least 2 lines a shot) are read in n_shots * ry interleaved EPI shots. Each shot has the imaging train's read lobe, navigator, blip window, ESP and TE, and is delayed by esp / (n_shots * ry). So echo time against line has the imaging slope: 0.440 ms/line in both, TE 27.661 ms at the series-31 prescription. A slice's (3D: a partition's) shots run in rapid succession at 10°, forward (SET 0) then reversed (SET 1), after one unsampled shot. EpiReadout2D/3D(blip_span=) lets the calibration match a multiband train's ESP. Series-31 limits: 3 segments as with GRE (FLEET segment 22 blocks), 0 waveforms, played +5 ms over file, ir.check clean; epi3d 5 segments (GRE 4), ir.check clean staged, not deployed: build/scanner-2026-11-12/hotfix-epi-fleet/ (with pulserver #379; epi2D file also carries 8a6b9dc) ☐
bssfp2D_sequence prospective (96e05de, with pulserver #379 2538735ff): the trigger sits on the slice's half-flip block, so the slice train itself waits for the R wave; the trigger delay is played as non-acquiring repetitions (prospective_starts(..., trigger_delay)). The deployed layout (a 4 us trigger segment before the ~16k-block train) is refused by the PSD's segment set-up check staged 12 Nov in hotfix-bssfp-frames (supersedes hotfix-bssfp-prospective), not deployed ☐
bssfp2D_sequence frames (1201a57): an ungated slice with dummies is two files, half flip + dummies then the frames, each frame opened from rest (gz_open) and closed to it (gz_close) at the same TR, TRSize one frame; BssfpReadout2D.gz_close always exists and rephases gz_open staged 12 Nov in hotfix-bssfp-frames, not deployed ☐

Not in this PR: running the rewinders on into the next pulse's dead time, as the packed FSE does. Measured on a local branch, it shortens the slot 2 TR by a further 0.21 ms at 132.6 T/m/s, but every rewind-to-excitation join then carries gradient, so pulserver's receive calibration span (excitation to next excitation) no longer ends at rest and generate refuses the design, and the segmentation loses its per-TR cut.

Adaptive EPI validation: full pypulseqpp suite 6483 passed, 69 skipped; both virtual EPI image reconstructions and Python 3.10 smoke tests pass; lint and strict documentation build pass. Complete local design-service examples retain segment/block counts while reducing minimum TE from 89.1 to 54.6 ms (2D without fat saturation), 91.2 to 71.9 ms (2D with fat saturation), and 28.2 to 19.5 ms (3D slab example). These are offline results; scanner acquisition confirmation is pending.

EPI control protocol for the first EPI scans on 13 Nov

All on PSD pulserver4 (Z04_epi2d). The base is series 31: FOV 220 mm, 192², one 5 mm slice, flip 70°, oprbw ±250 kHz, TR/TE Minimum, readout oversampling 2 (opuser9), 1 shot, MB 1. Every control has fat sat off (opfat) and keeps the same geometry and bandwidth, so the ESP is the same. Every series also plays the blip-down reference (set 1), so each one measures the up/down displacement.

Series Change from base Isolates
A Ry 1 (opaccel_ph_stride), PF 1.00 (opuser5) N/2 ghost and navigator correction, plus pure distortion. No PI calibration is played
C Ry 2, PF 1.00, Calibration GRE (opuser15 = 1) Residual FOV/2 from GRE maps vs the distorted EPI (compare with A)
D Ry 2, PF 1.00, Calibration FLEET (opuser15 = 0, the default), ACS lines 48 (opuser7; give C the same) FLEET maps (compare with C)
B (if time) A with PF 0.75 Homodyne partial Fourier
E (if time) Ry 2, PF 0.75, FLEET The series 31 target
F (if time) Ry 1, opnshots 2, PF 1.00 Shot phase at the Ry-2 k-space velocity, without PI
epi2D_sequence, epi3D_sequence: every acquiring file of the chain states kSpaceCenterLine (3D also kSpaceCenterPartition) (27783f9). The reference (blip-down, SET 1) and the GRE calibration stated none, so pulserver's enrichment centred each on the lines it read. Under partial Fourier 0.75, series 32's reference lines 2..144 of 192 sat 23 rows off (buffer rows 25..167), which misplaces its echo for homodyne and for HySCO's comparison with set 0 staged, not deployed: in build/scanner-2026-11-12/hotfix-epi-fleet/ ☐

🤖 Generated with Claude Code

The z lobes of BssfpReadout2D/3D were all built on the full-scale ramp
max_grad / max_slew, so that a slice rephaser and a partition encode
sum to one trapezoid. At 80 mT/m and 132.6 T/m/s that ramp is 604 us,
and a small 2D slice rephaser became a 1.208 ms triangle at 19 T/m/s
that set both windows of the repetition (TR 5.016 ms at 7 T for
192x192, 300 mm, 8 mm, 125 kHz). The shared ramp is now the one on
which the largest summed lobe is fastest at the slew rate, the
half-flip lobe has its own, and each window takes only its own floors.
Same protocol: 3.736 ms at 132.6 T/m/s; 3.912 ms at the 105 T/m/s the
design server lowers it to for PNS. Balance is exact (moments below
5e-14 of a k-space step on every axis).

An ungated bssfp2D_sequence now plays each slice's lines n_phases times
back to back, a free-running series labelled PHS, without dummies
between frames; it used to ignore n_phases and play one frame.

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 90.90909% with 13 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/pypulseqpp/sequences/readout/bssfp.py 89.28% 9 Missing and 3 partials ⚠️
src/pypulseqpp/sequences/readout/epi.py 96.77% 0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

mcencini and others added 14 commits November 11, 2026 12:37
… flip

The gradient-echo calibration that epi2d plays when undersampled or
multiband, and epi3d when undersampled, excited every line with the
imaging pulse at the imaging flip. Its lines follow one another at its
shortest TR, so at 7 T a 70 degree scan (exam 28827: 2 slices, R 3,
calibration TR 6.4 ms) was refused at predownload: "SAR at 117% of its
10 s limit: 6.4 ms of scan need 7.5 ms". At that flip the calibration also
read its k-space centre at about a hundredth of the first line's signal.

The calibration now plays CALIBRATION_FLIP_DEG, 10 degrees, near the
Ernst angle of its TR: (10/70)^2 of the RF power, about 2 % of the limit
in that scan, and its signal held across the calibration region. The
calibration only measures coil sensitivities. epi2d scales the
single-band pulse's samples (a small-tip SLR pulse, no second design or
bandwidth measurement); epi3d designs its excitation at the imaging
pulse's duration. Either way the calibration plays the imaging
waveform, so the RF definition and the segmentation are unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…led read axis

On the 7 T (11 Nov, series 15-17) the two forward lines of the three-line
navigator differed by a linear phase of 2.0-2.35 rad, an echo shift of
0.64 samples: the first lobe after the prewinder echoes away from where the
steady train does. The odd-even phase fitted to the navigator was then off by
about 0.5 rad and 0.8-1.4 rad/half-FOV, leaving an N/2 ghost of 15 % in a
single-shot EPI where the best linear correction leaves 6 %.

The train now plays one negative lobe, without ADC, between the read
prewinder (which opposes it) and the navigator; the navigator keeps its
+ - + polarity and its labels, and the train its alternation. The echo time
of the centre line grows by one echo spacing at the shortest TE; the spacing,
the shapes and the ADC are unchanged (one more block per shot, a scaled copy
of the read lobe).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A scanner that prepares a segment between blocks at rest cut a slice of the
balanced SSFP into one segment a repetition, and took its segment time after
each: the played repetition was longer than the designed one and the echo sat
ahead of its middle.

BssfpReadout2D(bridge=True) runs the ramps of the selection plateau through
zero to a fraction of its amplitude where the excitation block meets the
rewind before it and the acquisition after it, and the rephasers end and
start there. No join between two repetitions of a slice then has every
gradient at rest, the areas either side of the pulse centre are unwound
exactly, and the block durations are those of a slice axis that rests; where
they could not be, the slice is left unbridged (bridged is False). gz_open
opens a slice from rest and gz_close closes its last rewind to rest.

bssfp2d bridges the slices of a free-running scan of several slices. A gated
train rests where it waits for the heartbeat. A single slice is no repetition
of the scan, and a receive calibration then plays one repetition alone, from
rest to rest, which a bridged repetition is not. The 3D readout is unchanged.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
One slice is the several-slice scan with one slice: it opens and closes at
rest and is played as one segment. The receive calibration of a single
bridged slice is the scan's own start (pulserver).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A gated slice rested and waited for a trigger at every heartbeat, so its
repetitions could not be joined and a scanner played them a segment each.

Every 2D slice is now bridged. Under prospective gating a slice waits for one
trigger, ahead of its half flip, and then runs free at the nominal heart rate:
each heartbeat plays its segment once per cardiac phase and repetitions that
do not acquire fill the rest of it (prospective_starts), so the steady state
is kept across heartbeats. A heart rate away from the nominal one drifts
against the cardiac phases, which a trigger per heartbeat corrected.
Retrospective gating plays as before, with no trigger, and is bridged.

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

The bridged readout fell back to a slice axis that rests wherever a bridged
rephaser was longer than the window a resting one needs. On a 4 us gradient
raster that is every prescription, by a raster step, so a scanner played an
unbridged slice at any repetition time, the minimum and a longer one alike.

bridge=True now always bridges. The windows either side of the excitation
hold the bridged rephasers; the shortest repetition is then within a few
rasters of that of a resting slice axis (the same at 105 T/m/s and above on
both rasters, up to 0.24 ms longer at 30 T/m/s). A longer repetition time
lengthens the acquisition and rewind blocks, which carry the read and phase
lobes from one end to the other, so no block and no join rests. The half-flip
gap holds its two rephasers apart where it has the room, and one lobe held at
the bridge level where it does not. gz_close is None where the closing lobe
does not fit the last rewind.

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

The spoilers of a fat saturation or a saturation band play on three axes
at once. Designed at the sequence's slew they set its nerve stimulation,
and the design server's slew search then slows every gradient of the
sequence for them: a 2D EPI with fat saturation was designed at 49.9 T/m/s
instead of 88, the spoiler alone at 0.95 of the stimulation limit and the
train at 0.60. epi2D, gre2D and se2D now build these modules under
pp.cap_system(system, max_slew=PREPARATION_MAX_SLEW), 40 T/m/s; the
spoiler of the fat saturation grows from 2.76 to 2.88 ms and the train
keeps the sequence's slew. The safety search still checks the whole
sequence.

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

The calibration of an undersampled 2D or 3D EPI reads its central lines in
n_shots * ry interleaved EPI shots with the imaging train's read lobe,
navigator, blip window, echo spacing and echo time (Polimeni et al., MRM
2016), a slice's or partition's shots in rapid succession at 10 degrees,
forward (SET 0) and reversed (SET 1). It is the default; calibration='gre'
keeps the gradient echo per line. EpiReadout2D/3D take blip_span, so the
calibration matches a multiband train's echo spacing.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The trigger had a block of its own ahead of the half flip, a segment the
scanner played for microseconds, and the slice's train after it had to be
set up in that time: a slice-long train cannot be, and the interpreter
refuses it. The trigger now sits on the half-flip block, so the train
itself waits for it and is set up before the trigger, or while the slice
before it plays. The trigger delay is played as repetitions that do not
acquire (prospective_starts), keeping the steady state through it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The reference (reversed phase encode) and the gradient-echo calibration stated
no kSpaceCenterLine (3D: kSpaceCenterPartition), so pulserver's enrichment
centred them on the lines they read. Under partial Fourier the reference's
lines 2..144 of 192 were placed 23 rows off (exam 5190 series 32), which
misplaces its echo for the homodyne completion and for any joint
reconstruction with the forward shots.

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

Matteo, 12 Nov: the frames of a 2D cine must not be one segment. An ungated
slice with dummies is now two files of the chain: the half flip and dummies,
closed to rest, then the frames, each opened from rest (gz_open) and closed
to it (gz_close) at the bridged repetition time, the file's TRSize one frame.
A scanner that segments a repetition then prepares one segment for the
dummies and one for a frame, played once per frame, and dedups both across
slices. Gated slices are one train as before.

BssfpReadout2D(bridge=True): gz_close is the rest-to-rest lobe that rephases
gz_open, always present, and the rewind window holds it (the repetition time
at 7 T limits is unchanged at 192 and 256).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…st, a FIESTA-like pulse

A free-running slice is no longer bridged: every repetition opens from rest
and closes to it, and its files declare no TRSize, so a scanner that segments
a repetition plays each repetition as the same segment and adds its segment
start time to every repetition time alike. A frame-long segment lengthened
only the repetition at each frame boundary and set off a transient in the
steady state there. Gated slices stay bridged, one train with the designed
timing against the heartbeat.

The half flip is replaced by a linear ramp of the flip angle over the first
CATALYST_RAMP (20) dummies. It damps the oscillating transient better off
resonance (worst over +-0.45/TR at TR 1: 9 % against 46 %) and frees the
repetition from the half-flip timing, which refused 166-250 kHz at 192^2.
Repetitions are counted from the slice's first excitation, the trigger's
under prospective gating, with no half-repetition offset.

Default dummies bring the steady state within STEADY_STATE_TOLERANCE (5 %),
and the selective pulse defaults to 0.48 ms at a time-bandwidth product of 2,
as product balanced SSFP excites (about half the RF energy of 0.6 ms at 4),
both pulse settings now arguments; the default bandwidth is 250 kHz.

The paper-plot and expand-repeats tests, which the chain commit had broken
(a chain given to the plot; a frames file without ONCE), now use the
single-file prescription without dummies.

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

Copy link
Copy Markdown
Contributor Author

Landed on main through #232 (these commits plus a docstring-contract fix for the bssfp2D return type), released as v0.0.64.


Generated by Claude Code

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