LineReadout3D

Contents

LineReadout3D#

class pypulseqpp.sequences.LineReadout3D[source]#

Bases: SequenceModule

One Cartesian line of a 3D slab, phase-encoded along y and z.

fov and matrix take three values, readout first.

An excitation gives a gradient echo; a refocusing pulse gives the readout half of a spin echo. The phase encodes are templates at their largest step, which the caller scales per shot.

Zero spoiling balances every axis. Positive spoiling after the acquisition gives SSFP-FID, before it SSFP-Echo; in the latter case the FID trajectory of calculate_kspace need not cross k = 0, and echo_time is still the timing interval.

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

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

  • gz (GradEvent, default=None) – Selection gradient played with rf; None for a hard pulse.

  • gz_reph (GradEvent, default=None) – Rephaser of gz, left-aligned in the first block after the pulse (the TE wait if there is one, else the prewinder block). None for a slab excitation (is_slab=True), which carries it in gz.

  • fov (float or sequence of float) – Field of view per encoded axis, readout first (m).

  • matrix (int or sequence of int) – Matrix size per encoded axis, readout first. The caller sets the number and order of acquired lines.

  • te (float, default=None) – Echo time (s), from the RF centre to the first echo. None is as short as possible.

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

  • partial_echo (float, default=1.0) – Fraction of the full echo acquired, in (0.5, 1]. The samples before the echo are omitted, which shortens TE.

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

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

  • spoiling_cycles (float, default=0.0) – Cycles of dephasing across voxel_size_m left at the end of the TR. Zero balances the TR.

  • voxel_size_m (float, default=None) – Length the spoiling is counted over (m); None is the readout resolution fov[0] / matrix[0].

  • spoiling_position ({'post', 'pre'}, default='post') – Side of the acquisition on which the spoiler is played.

  • n_echoes (int, default=1) – Echoes per repetition.

  • flyback (bool, default=True) – With several echoes, rewind between them so that all are read in the same direction (monopolar), or alternate the readout sign (bipolar). A bipolar train reads even echoes backwards, so a gradient delay error becomes a phase difference between echoes, and it needs as many samples before the echo as after it: partial_echo < 1 and an odd sample count are rejected.

  • echo_spacing (float, default=None) – Echo spacing (s); None is as short as possible. Ignored with one echo.

  • wave ({'phase', 'partition', 'both'}, default=None) – Wave-CAIPI encoding under the readout flat top: a sine on y, a cosine on z, or both. 3D only, unless wave_cycles or wave_amplitude is zero, which builds no wave gradients.

  • wave_cycles (int, default=8) – Wave periods across the sampling window.

  • wave_amplitude (float, default=0.008) – Upper bound of the wave gradient amplitude (T/m, not Hz/m); the slew rate may lower it. The module’s wave_amplitude attribute is the amplitude built.

  • labels (sequence of str, default=None) – Labels set to 0 on the acquisition block, to be changed per shot by the caller.

  • trigger (TriggerEvent or DigitalOutputEvent, default=None) – Event armed on the prewinder block.

Attributes:
  • rf (RfEvent) – The pulse the module was given.

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

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

  • gx_pre (GradEvent) – Readout prephaser, right-aligned in the prewinder block; includes the spoiler area under spoiling_position='pre'.

  • gx (GradEvent) – Readout lobe. With a single echo and a spoiler, the spoiler is joined to the lobe, which then lacks the ramp on that side. A spoiler joined at the end leaves from a plateau held to the end of the acquisition block, past the last sample by the ADC dead time, and gx_spoil has correspondingly less area.

  • gx_spoil (GradEvent) – Last read-axis gradient of the TR, left-aligned with gy_rew: rewinds the part of the line after the echo and, under spoiling_position='post', adds the spoiler.

  • 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 negated encodes that unwind them.

  • gx_flyback (TrapEvent) – Rewinder played after every echo but the last of a monopolar train.

  • gx_rev (GradEvent) – Negated lobe that reads the even echoes of a bipolar train.

  • gy_wave, gz_wave (GradEvent) – Wave gradients under the readout flat top, each self-balanced so that scaling one to zero changes nothing else. Only the channels driven by wave.

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

  • adc_labels (LabelSetEvent or list of LabelSetEvent) – One per name in labels; absent when labels is empty.

  • wait_te (DelayEvent) – Present only when te exceeds the minimum and the wait can hold gz_reph; otherwise the prewinder block starts later.

  • wait_esp (DelayEvent) – Present only when echo_spacing exceeds the minimum; played after every echo but the last (after the readout lobe of a bipolar train, after the rewinder of a monopolar one).

  • wait_tr (DelayEvent) – Present only when tr exceeds the minimum.

  • echo_time (float) – Time from the RF centre to the first echo (s), on the block raster.

  • echo_spacing (float) – Time between successive echoes (s), on the block raster; zero with one echo.

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

  • n_samples (int) – ADC samples per echo.

  • center_sample (int) – Index of the sample at the echo; partial_echo moves it toward the start.

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

  • readout_duration (float) – Duration of the sampled flat top (s).

  • wave_amplitude (float) – Peak wave gradient amplitude built (T/m), below the requested one where the slew rate binds; zero without wave.

Raises:

ValueError – If a count or a fraction is out of range, wave is not a wave mode or would build wave gradients on a 2D readout, gz_reph shares a channel with an encoded axis, or te, tr or echo_spacing is shorter than the module can achieve.

Examples

>>> import pypulseqpp.sequences as design
>>> import pypulseqpp as pp
>>> system = pp.Opts()
>>> slab = design.SpatialSelectiveExcitation(system, 8.0, 0.12, is_slab=True)
>>> readout = design.LineReadout3D(
...     system, slab.rf, slab.gz,
...     fov=(0.22, 0.22, 0.12), matrix=(128, 128, 64),
... )
>>> readout.gy_pre.channel, readout.gz_pre.channel
('y', 'z')

One repetition of the slab acquisition, and the line it reads:

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

(svg)#

../_images/pypulseqpp-sequences-LineReadout3D-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.