FatSaturation

class pypulseqpp.sequences.FatSaturation

Bases: RfModule

SLR fat saturation with a three-axis spoiler and optional spatial selection.

Position and orientation place the selection band at construction. NOPOS and NOROT are set on entry and cleared on exit so subsequent FOV placement leaves the band unchanged. Position is specified in millimetres along the channel axes; the RF frequency offset remains in ppm.

Parameters:

• system (pypulseqpp.Opts) – System limits.

• freq_offset_ppm (float, default=FAT_SHIFT_PPM) – Fat offset from water (ppm). Carried on the pulse as a ppm offset rather than as hertz, so the interpreter resolves it against the field the scan actually runs at.

• flip_angle_deg (float, default=110.0) – Saturation flip angle (degrees).

• bandwidth_hz (float, default=250.0) – Spectral passband (Hz). With time_bw_product it fixes the pulse duration, which is time_bw_product / bandwidth_hz.

• time_bw_product (float, default=2.0) – Time-bandwidth product.

• thickness_m (float, default=None) – Band thickness (m). None saturates the whole transmit volume, which is the usual fat saturation and the only form that needs no gradient.

• axis ({'z', 'x', 'y'}, default='z') – Band normal, before orientation turns it.

• position_mm (sequence of float, default=None) – (dx, dy, dz) offset of the band from the isocentre, along the channel axes, in millimetres. Needs thickness_m.

• orientation (array_like or scipy.spatial.transform.Rotation, default=None) – A (3, 3) matrix, or a rotation, taking the channel axes to the axes the band lies on: the band’s own rotation. Needs thickness_m.

• use_rotation_extension (bool, default=True) – Encode the orientation as a ROTATIONS extension rather than rotating the gradient waveforms. Only True is implemented; see TransformFOV.

• spoiling_cycles (float, default=4.0) – Cycles of dephasing each spoiler axis winds across voxel_size_m.

• voxel_size_m (float, default=0.001) – Length the dephasing is counted over (m).

Attributes:

• rf_prep (RfEvent) – The saturation pulse, as placed.

• gz (GradEvent) – Its selection gradient. Only when thickness_m was given, and named for the channel axis it is drawn on whatever axis was.

• gx_spoil, gy_spoil, gz_spoil (GradEvent) – Closing spoiler on all three axes.

• prep_labels (list of LabelSetEvent) – NOPOS and NOROT, set on the first block.

• reset_labels (list of LabelSetEvent) – The same two cleared, on the last.

• freq_offset_ppm (float, default=FAT_SHIFT_PPM) – The fat offset the pulse carries (ppm).

• freq_offset_hz (float) – What that comes to at system.B0 (Hz), for reference; the pulse itself is field-independent.

Raises:

ValueError – If a bandwidth, thickness or voxel size is not positive, axis is not a gradient channel, the spoiler was asked for zero cycles, or a position or orientation was given for a band that has no thickness.

Examples

>>> import pypulseqpp.sequences as design
>>> import pypulseqpp as pp
>>> fatsat = design.FatSaturation(pp.Opts(B0=3.0))
>>> len(fatsat.blocks), round(fatsat.freq_offset_hz)
(2, -441)

>>> [event.type for event in fatsat.blocks[0]]
['rf', 'labelset', 'labelset']

The pulse with its spoiler, and the longitudinal magnetization left across the spectrum. The band sits at the fat resonance for the field the module was designed at, and water at zero offset is untouched:

(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.
sim_rf	Simulate this module's pulse across off-resonance.

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.