LineReadout2D#

class pypulseqpp.sequences.LineReadout2D[source]#

Bases: SequenceModule

One Cartesian line, frequency-encoded along x and phase-encoded along y.

fov and matrix take two 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()
>>> excitation = design.SpatialSelectiveExcitation(system, 15.0, 5e-3)
>>> readout = design.LineReadout2D(
...     system, excitation.rf, excitation.gz, excitation.gz_reph,
...     fov=0.22, matrix=128,
... )
>>> int(readout.adc.num_samples)
128
>>> readout.blocks[1] == (readout.gx_pre, readout.gy_pre, readout.gz_reph)
True
../_images/pypulseqpp-sequences-LineReadout2D-1_00.svg

(svg)#

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

Examples using LineReadout2D#

Slice-selective excitation

Slice-selective excitation

Minimum-phase excitation

Minimum-phase excitation