PropellerStackReadout

class pypulseqpp.sequences.PropellerStackReadout

Bases: SequenceModule

A stack of 2D PROPELLER blade sets, partition-encoded along z.

The blade turns about z, the one axis the rotation leaves unchanged, so the partition encode is unaffected by it: scale gz_pre per partition and turn the block per blade.

Each blade is blade_width phase-encode lines wide and spans the readout matrix. Scale gy_pre by blade_start and apply the blade’s rotation to its encoding gradients. Slice and partition axes remain along z.

The scan loop sets the shot origin by scaling prewinders. Blips implement the relative offsets and share the readout ramps; flyback blips instead play in the rewind gaps. TE is measured to the train line te_line, the first by default, because which line samples the centre of k-space depends on the shot origin that the loop sets.

Navigator lines, when asked for, are read after the read prewinder and before the phase-encode prewinder, without blips, so they sample the centre line at alternating polarities. The train then continues the alternation.

Parameters:

• system (pypulseqpp.Opts) – System limits.

• rf (RfEvent) – The pulse that opens the repetition.

• gz (GradEvent, default=None) – A selection gradient played in the same block as rf.

• gz_reph (GradEvent, default=None) – The rephaser that unwinds gz.

• fov (float) – In-plane field of view (m), isotropic: the blade turns, so it cannot be anything else.

• matrix (int) – In-plane matrix size, isotropic.

• blade_width (int, default=16) – Phase-encode lines per blade. Narrow blades turn a scan into many short trains – less distortion per blade, more blades to cover the disc.

• n_blades (int, default=None) – Blades in the set. The default is the smallest that samples the edge of the disc at Nyquist, ceil(pi * matrix / (2 * blade_width)).

• scheme ({'uniform', 'golden'}, default='uniform') – How the default angles are spread. 'uniform' divides half a turn between the blades, which is exact for the whole set and only for the whole set. 'golden' leaves any prefix of the set near-uniform, including incomplete acquisitions.

• angles (array_like, default=None) – In-plane angles (rad) to use instead of generating a set.

• fov_z (float, int, default=None) – Slab field of view (m) and partitions. PropellerStackReadout only, where they are required.

• matrix_z (float, int, default=None) – Slab field of view (m) and partitions. PropellerStackReadout only, where they are required.

• etl (int, default=None) – Lines per repetition. Defaults to what one shot of the requested scheme needs to cross the phase-encode matrix.

• acceleration (int, default=1) – Phase-encode undersampling, Ry: lines the blip skips.

• segments (int, default=1) – Shots the train is interleaved across, S. The blip becomes S * Ry, which shortens the train without changing the lattice sampled.

• partition_acceleration (int, default=1) – Partition undersampling Rz, the height of the CAIPI cycle. 'caipi' only.

• caipi_shift (int, default=1) – Partitions the pattern climbs per acquired line. 'caipi' only.

• extent (int, default=None) – Phase-encode lines one pass spans. Required by 'zigzag', refused by the others.

• te (float, default=None) – Excitation isodelay to the echo of train line te_line (s). None is as short as possible; every echo is esp from the next, and echo_times lists them.

• te_line (float, default=0.0) – Train line, counted from zero and possibly fractional, that te is timed to.

• tr (float, default=None) – Repetition time (s), over the whole module. It includes the longest echo shift.

• navigator_lines (int, default=0) – Lines read without blips between the read and the phase-encode prewinders, for odd-even phase correction. Refused with flyback.

• echo_shifts (int, default=1) – Shots whose trains are delayed by successive multiples of esp / echo_shifts, so the echo time grows smoothly across the interleaved lines. The module plays no shift; the loop lengthens wait_shift.

• oversampling (float, default=1.0) – Read oversampling: delta_kx shrinks and the sampled read field of view grows, while resolution is fixed by fov and matrix.

• readout_bandwidth_hz (float, default=500000.0) – Requested ADC sampling rate (Hz). bandwidth_hz reports the achieved raster-compatible rate.

• ramp_sampling (bool, default=True) – Sample across the read ramps as well as the plateau, which shortens the echo spacing. When off, the window covers the plateau only and the train is longer.

• flyback (bool, default=False) – Read every line in the same direction, rewinding between them, instead of alternating polarity. This adds a rewind per line and removes the odd-even echo inconsistency of a bipolar train.

• spoiling_cycles (float, default=0.0) – Read-axis spoiling at the end of the repetition, in cycles across voxel_size_m.

• voxel_size_m (float, default=None) – Length the spoiling is counted over (m). The read resolution by default.

• labels (Sequence[str], default=None) – Counters for the encoded axes, phase encode first. Two names for a 3D train, one for 2D.

• trigger (TriggerEvent, default=None) – A trigger or digital output armed on the prewinder block.

Attributes:

• rf (RfEvent) – The excitation.

• gz (GradEvent) – Its selection gradient, if one was given.

• gz_reph (GradEvent) – Its rephaser, if one was given.

• gx_pre (TrapEvent) – Read prewinder, half a line lobe against the first line’s polarity.

• gx (list[GradEvent]) – One read lobe per line: alternating polarity for a blipped train, the same lobe every time for a flyback one.

• gx_navigator (list[GradEvent]) – One read lobe per navigator line, the first positive. Present only with navigator_lines.

• gx_flyback (TrapEvent) – The rewind between two lines. flyback only.

• gy_blips, gz_blips (list) – One phase-encode event per line, or None where no step is asked for, always etl long. A blipped train’s entry carries the second half of the step into the line and the first half of the next out of it; a flyback train’s is the whole step, played in the rewind block after that line, so its last entry is always None. gz_blips is 3D only.

• gy_pre, gz_pre (TrapEvent) – Phase encodes at their largest step, to be scaled per shot. gz_pre is 3D only.

• gy_rew, gz_rew (TrapEvent) – The encodes negated, in the last block of the repetition.

• gx_spoil (GradEvent) – Read-axis trapezoid in the last block: returns the read axis from the end of the last line through k = 0 and adds the requested spoiling.

• adc (AdcEvent) – The acquisition window, shared by every line.

• shot_labels (tuple[LabelEvent, …]) – SET counters on the prewinder block, one per name in labels. The acquisition loop sets them to the shot’s origin. Always a tuple, whatever the number of names, so that it can be unpacked into a block.

• line_labels (tuple[tuple[LabelEvent, …], …]) – Per line, the INC counters that step from the previous line to this one – the ordering, expressed as labels. Empty for the first line, which the SET already placed.

• order (NDArray[np.int64]) – (etl, 2) integer (ky, kz) offsets from the shot’s origin.

• wait_te (DelayEvent) – Present only when a TE longer than the minimum was asked for.

• wait_shift (DelayEvent) – The echo-shift delay right before the first train line, one block raster long. Present only with echo_shifts above one; the loop lengthens it by s * echo_shift_step on shot s and shortens wait_tr by as much.

• wait_tr (DelayEvent) – Present when a TR longer than the minimum was asked for, or when echo_shifts is above one: it then holds the longest shift.

• etl (int) – Lines per repetition.

• esp (float) – Echo spacing (s).

• echo_times (NDArray[np.float64]) – Each line’s echo time (s) from the excitation isodelay, with no echo shift.

• echo_time (float) – Echo time (s) of train line te_line, the echo time that te specifies.

• echo_shift_step (float) – Echo shift between successive shots (s), esp / echo_shifts on the block raster; zero with one shift.

• bandwidth_hz (float) – Achieved ADC sampling rate (Hz).

• n_samples (int) – Samples per line.

• delta_kx (float) – Read-axis k-space step (1/m).

• blip_span (float) – Time one phase-encode step takes (s). It is paid out of the read ramps.

• blade_angles (numpy.ndarray) – In-plane angles (rad), one per blade. Turn about z.

• blade_start (float) – What to scale gy_pre by to put the blade astride k = 0. It does not vary: a blade is centred by construction, so only the angle moves.

• blade_width (int) – Phase-encode lines in one blade.

• n_blades (int) – Blades in the set.

Raises:

ValueError – If a count is out of range, scheme is unknown, or angles is given alongside a count it would contradict. If a count is out of range, order is the wrong shape or steps outside the matrix, labels does not name one counter per encoded axis, te_line lies outside the train, a navigator is asked of a flyback train, or the requested TE or TR is shorter than the train can achieve.

Examples

>>> import pypulseqpp.sequences as design
>>> import pypulseqpp as pp
>>> system = pp.Opts(max_grad=50, grad_unit="mT/m", max_slew=180, slew_unit="T/m/s")
>>> slab = design.SpatialSelectiveExcitation(system, 15.0, 0.12, is_slab=True)
>>> blade = design.PropellerStackReadout(
...     system, slab.rf, slab.gz, fov=0.22, matrix=128, blade_width=16,
...     fov_z=0.12, matrix_z=24,
... )
>>> blade.n_blades, blade.gz_pre.channel
(13, 'z')

The partition does not move inside a blade, so nothing is blipped on z:

>>> set(blade.gz_blips)
{None}

One blade of one partition, with the partition encode on z:

(svg)

(svg)

Methods

init_module	Build the module's block layout; implemented by the subclass.
publish	Publish events from the caller's locals and register keyword aliases.
register	Publish named events without requiring prior block registration.

Attributes

blocks	Return block tuples in play order, retaining the original event objects.
duration	Duration of the module in seconds.
seq	Sequence holding the module's construction-time block layout.