FseReadout3D

class pypulseqpp.sequences.FseReadout3D

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 RF centre or echo before it and the echo after it. Echoes are esp apart, except that the first echo is esp_first after the excitation. Phase encodes, and the refocusing amplitude, are templates the loop may scale per echo; the sampling order sets the effective TE.

Parameters:

• system (pypulseqpp.Opts) – System limits.

• rf (RfEvent) – The excitation 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. A slab excitation (is_slab=True) has already merged it into gz and passes nothing.

• rf_ref (RfEvent) – The refocusing pulse, which must be built with use="refocusing": SpatialSelectiveRefocusing’s rf_ref for a selective train, NonSelectiveRefocusing’s for a hard-pulse train.

• gz_ref (GradEvent, default=None) – Selection gradient for rf_ref with its crushers, as one event played in the pulse’s block: the gz of SpatialSelectiveRefocusing. A non-selective train passes nothing and crushes on the read axis through spoiling_cycles.

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

• matrix (int or sequence of int) – Matrix size per encoded axis, used to set gradient areas. The scan loop controls 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.

• esp_first (float, default=None) – Spacing of the first echo (s). None is the shortest that accommodates the excitation, which is esp whenever the excitation fits in half of one. Rounded so that esp_first - esp is a multiple of twice the block raster.

• 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]. Truncates the samples before the echo.

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

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

• spoiling_cycles (float, default=0.0) – Read-axis crushing each side of every acquisition, in cycles across voxel_size_m.

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

• labels (sequence of str, default=None) – Counters emitted on the acquisition block. The acquisition loop assigns their values.

• trigger (event, default=None) – A trigger or digital output armed on the prephaser 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-encoding gradients.

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

• wave_amplitude (float, default=0.008) – Requested peak wave-encoding gradient amplitude, in T/m rather than the Hz/m used elsewhere. A ceiling: the slew rate may lower it, and the module’s wave_amplitude attribute reports 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 block that contains the prephaser, 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-encoding gradients played under the readout plateau, each self-balanced so scaling one to zero changes nothing else. Only the channels wave drives.

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

• adc_labels (LabelSetEvent or list of LabelSetEvent) – One per name in labels; a bare event when there is one.

• wait_esp1 (DelayEvent) – Played after the first refocusing pulse only, when esp_first exceeds esp. Absent otherwise.

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

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

• esp_first (float) – Spacing of the first echo (s), equal to esp unless the excitation needed more room.

• echo_times (numpy.ndarray) – Each echo’s time (s) from the excitation isodelay.

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

• n_samples (int) – Samples per echo.

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

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

• readout_duration (float) – Sampling window (s).

• wave_amplitude (float) – Peak wave-encoding gradient amplitude built, in 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 names no wave mode or would build wave-encoding gradients on a 2D train, gz_reph is on the read channel, rf_ref is not marked as a refocusing pulse, or the requested echo spacing 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:

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