FseReadout3D

Contents

FseReadout3D#

class pypulseqpp.sequences.FseReadout3D[source]#

Bases: SequenceModule

Single-slab CPMG train, phase-encoded along y and partition-encoded along z.

fov and matrix take three values, readout first. Refocusing may be selective or non-selective; a non-selective train is crushed only by spoiling_cycles, on the read axis.

Each refocusing pulse is centred midway between the preceding RF centre or echo and the following echo. The phase encodes and the refocusing amplitude are templates that the caller may scale per echo; the sampling order sets the effective TE.

A 2D train spaces its echoes uniformly from the excitation onward. A 3D train is packed: the read prephaser shares the excitation block, and the tail of the prephaser and of each echo’s rewinders plays in the next refocusing pulse’s dead time, beyond its ringdown, so every refocusing block opens on the gradient of the block before it and the echo spacing is shorter by twice that overlap. Its first interval may be longer than the others (esp_first); a caller designing the refocusing angles models it.

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

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

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

  • gz_reph (GradEvent, default=None) – Rephaser of gz. None for a slab excitation (is_slab=True), which carries it in gz; a 3D train takes none.

  • rf_ref (RfEvent) – Refocusing pulse, built with use="refocusing": the rf_ref of a SpatialSelectiveRefocusing for a selective train, or of a NonSelectiveRefocusing for a hard-pulse train.

  • gz_ref (GradEvent, default=None) – Selection gradient of rf_ref with its crushers, as one event played in the pulse’s block: the gz of a SpatialSelectiveRefocusing. None for a non-selective train, which is crushed on the read axis by spoiling_cycles.

  • 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.

  • etl (int, default=8) – Echo train length: refocusing pulses and encoded lines per repetition.

  • esp (float, default=None) – Echo spacing (s). None is as short as possible, including the excitation, its rephaser and the read prephaser in the first half spacing in 2D; in 3D they set esp_first instead.

  • tr (float, default=None) – Repetition time (s), over 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.

  • 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 read-axis crushing across voxel_size_m on each side of every acquisition.

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

  • 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 prephaser block. 2D only: a 3D train’s prephaser shares the excitation block.

  • wave ({'phase', 'partition', 'both'}, default=None) – Wave-CAIPI encoding under every readout plateau: 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.

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 the prephaser block so that it starts at the end of the selection lobe.

  • rf_ref (RfEvent) – The refocusing pulse, one event for the whole train.

  • gz_ref (GradEvent) – Its selection gradient and crushers, if one was given.

  • gx_pre (TrapEvent) – Read prephaser, played once before the train and right-aligned in its block.

  • gx_bridge_pre, gx_bridge_post (GradEvent) – Read-axis lobes, including the crushers, that ramp onto and off the readout plateau, one on each side of every acquisition. Each spans its whole block, so the echo timing is unchanged when the loop omits an encode.

  • gx (GradEvent) – The readout plateau, flat from end to end.

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

  • gy_rew, gz_rew (TrapEvent) – The encodes negated, unwinding each line before the next refocusing pulse.

  • gy_wave, gz_wave (GradEvent) – Wave gradients under the readout plateau, 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.

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

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

  • esp_first (float) – Initial echo interval (s): esp in 2D, and in 3D wherever the excitation and the read prephaser fit in half an echo spacing.

  • layout (RfOverlapLayout) – The packed train’s events, 3D only, each echo’s played through excitation, refocusing, encoding and rewinding.

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

  • 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 sampling window (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 fraction is out of range, wave is not a wave mode or would build wave gradients on a 2D train, gz_reph is on the read channel or given to a 3D train, a 3D train is given a trigger, rf_ref is not a refocusing pulse, or esp or tr is shorter than the train can achieve.

Examples

>>> import pypulseqpp.sequences as design
>>> import pypulseqpp as pp
>>> system = pp.Opts()
>>> slab = design.SpatialSelectiveExcitation(system, 90.0, 0.12, is_slab=True)
>>> refocusing = design.SpatialSelectiveRefocusing(system, 0.12)
>>> readout = design.FseReadout3D(
...     system, slab.rf, slab.gz,
...     rf_ref=refocusing.rf_ref, gz_ref=refocusing.gz,
...     fov=(0.22, 0.22, 0.12), matrix=(64, 64, 32), etl=6,
... )
>>> readout.gy_pre.channel, readout.gz_pre.channel
('y', 'z')

One CPMG train through the slab, and the readout line each echo takes:

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

(svg)#

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