PropellerStackReadout

PropellerStackReadout#

class pypulseqpp.sequences.PropellerStackReadout[source]#

Bases: SequenceModule

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

The blade turns about z, which the rotation leaves unchanged, so the partition encode is unaffected by it: scale gz_pre per partition and rotate the blocks per blade.

Each blade is blade_width phase-encode lines wide and spans the readout matrix. The caller scales gy_pre by blade_start and applies the blade’s rotation about z to its encoding gradients. The slice and partition axes remain along z. Further keyword arguments are those of the EPI readouts.

The caller sets the shot origin by scaling the prewinders. Blips step between the lines of order and share the readout ramps; with flyback they play in the rewind gaps instead. TE is timed to the line te_line (the first by default), because which line samples the centre of k-space depends on the shot origin the caller sets.

Navigator lines 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 continues the alternation.

Parameters:
  • system (pypulseqpp.Opts) – System limits.

  • rf (RfEvent) – Pulse that opens the repetition.

  • gz (GradEvent, default=None) – Selection gradient played with rf.

  • gz_reph (GradEvent, default=None) – Rephaser of gz.

  • fov (float) – Isotropic in-plane field of view (m).

  • matrix (int) – Isotropic in-plane matrix size.

  • blade_width (int, default=16) – Phase-encode lines per blade.

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

  • scheme ({'uniform', 'golden'}, default='uniform') – Distribution of the generated angles. 'uniform' divides half a turn evenly between the blades, uniform only for the complete set; 'golden' keeps any prefix of the set near-uniform.

  • angles (array_like, default=None) – In-plane blade angles (rad) instead of a generated set; excludes n_blades.

  • fov_z (float, int, default=None) – Slab field of view (m) and partition count; required by PropellerStackReadout only.

  • matrix_z (float, int, default=None) – Slab field of view (m) and partition count; required by PropellerStackReadout only.

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

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

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

  • 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' and rejected by the other schemes.

  • te (float, default=None) – Echo time (s), from the RF centre to the echo of line te_line. None is as short as possible. Consecutive echoes are esp apart; echo_times lists them.

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

  • tr (float, default=None) – Repetition time (s) of the whole module, including the longest echo shift. None is as short as possible.

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

  • echo_shifts (int, default=1) – Number of shots whose trains are delayed by successive multiples of esp / echo_shifts. The module plays no shift: the caller lengthens wait_shift.

  • oversampling (float, default=1.0) – Readout oversampling: the sample spacing in k-space is 1 / (oversampling * fov).

  • readout_bandwidth_hz (float, default=500000.0) – Requested ADC sampling rate (Hz); bandwidth_hz is the rate achieved on the ADC and gradient rasters.

  • ramp_sampling (bool, default=True) – Sample across the read ramps as well as the plateau, which shortens the echo spacing. False restricts the window to the plateau.

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

  • spoiling_cycles (float, default=0.0) – Cycles of read-axis dephasing across voxel_size_m left at the end of the repetition.

  • voxel_size_m (float, default=None) – Length the spoiling is counted over (m); None is the readout resolution.

  • labels (sequence of str, default=None) – Names of the labels holding the shot origin of each encoded axis, phase encode first: two for a 3D train, one for 2D.

  • trigger (TriggerEvent or DigitalOutputEvent, default=None) – Event 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, left-aligned in whichever block follows the pulse.

  • gx_pre (TrapEvent) – Read prewinder, half a line lobe against the first line’s polarity, right-aligned in the prewinder block so that it ends where the first line starts.

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

  • gx_navigator (list of 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, etl long, with None where no step is taken. In a blipped train an entry carries the second half of the step into the line and the first half of the step to the next line out of it; in a flyback train it is the whole step, played in the rewind block after that line, so the last entry is None. gz_blips is 3D only.

  • gy_pre, gz_pre (TrapEvent) – Phase encodes at their largest step, to be scaled per shot, right-aligned with gx_pre; with navigator_lines they play in a block of their own after the navigator. gz_pre is 3D only.

  • gy_rew, gz_rew (TrapEvent) – The negated encodes, left-aligned 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 to k = 0 and adds the spoiling.

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

  • shot_labels (tuple of LabelSetEvent) – SET events on the prewinder block, one per name in labels, for the caller to set to the shot origin. Always a tuple, so it can be unpacked into a block.

  • line_labels (tuple of tuple of LabelIncEvent) – Per line, the INC events that step from the previous line to this one; empty for the first line, which shot_labels places.

  • order (numpy.ndarray) – Integer (etl, 2) (ky, kz) offsets from the shot origin.

  • wait_te (DelayEvent) – Present only when te exceeds the minimum.

  • wait_shift (DelayEvent) – Echo-shift delay before the first train line, one block raster long; present only with echo_shifts above 1. The caller lengthens it by s * echo_shift_step on shot s and shortens wait_tr by the same amount.

  • wait_tr (DelayEvent) – Present when tr exceeds the minimum, or when echo_shifts is above 1, in which case it holds the longest shift.

  • etl (int) – Lines per repetition.

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

  • echo_times (numpy.ndarray) – Echo time of each line (s) from the RF centre, without echo shift.

  • echo_time (float) – Echo time (s) of line te_line, the time 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 1 / dwell (Hz).

  • n_samples (int) – ADC samples per line.

  • delta_kx (float) – K-space sample spacing along the readout (1/m).

  • blip_span (float) – Duration of one phase-encode step (s), taken from the read ramps.

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

  • blade_start (float) – Factor by which to scale gy_pre to centre the blade on k = 0; the same for every blade.

  • 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 together with n_blades. 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:

../_images/pypulseqpp-sequences-PropellerStackReadout-1_00.svg

(svg)#

../_images/pypulseqpp-sequences-PropellerStackReadout-1_01.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, whether or not they were added to a block.

Attributes

blocks

Block tuples in play order, holding the original event objects.

duration

Duration of the module (s).

seq

Sequence holding the module's construction-time block layout.