make_adiabatic_pulse

make_adiabatic_pulse#

pypulseqpp.make_adiabatic_pulse()[source]#

Construct an adiabatic RF pulse, a frequency sweep insensitive to B1.

Four sweeps:

  • "hypsec": hyperbolic-secant inversion (Baum, Tycko and Pines 1985).

  • "wurst": WURST inversion, a uniform-rate sweep under a smoothly truncated envelope (Kupce and Freeman 1995).

  • "bir4": a B1-insensitive rotation by flip_angle: two BIR-1 halves back to back, the flip set by the phase jumps between their quarters (Staewen et al. 1990). Selects no slice.

  • "goia_wurst": a slice-selective inversion whose gradient is modulated with the sweep, so every position in the slice sees the same adiabaticity (Andronesi et al. 2010). Returned with that gradient.

The first two are built by PyPulseq’s factory. For every sweep the amplitude meets adiabaticity where the frequency sweep crosses zero: (gamma B1)^2 = adiabaticity * |d omega / dt| there, in rad/s. BIR-4 and GOIA-WURST are referenced to zero phase at that crossing, and use a multiple of four samples, zero-padded to duration.

Parameters:

  • pulse_type ({"hypsec", "wurst", "bir4", "goia_wurst"}) – Which sweep.

  • adiabaticity (float, default=4) – Margin over the adiabatic condition at the sweep’s zero crossing.

  • bandwidth (float, default=40000) – Full frequency sweep, in Hz. Unused by "hypsec", whose sweep is mu * beta.

  • beta (float, default=None) – Envelope parameter: in 1/s for "hypsec" (800 by default), and dimensionless for "bir4", where it sets how steep the tanh quarters are (10 by default).

  • delay (float, default=0.0) – Delay before the pulse, in s. A "goia_wurst" pulse starts no earlier than its gradient’s ramp ends, so its delay can be longer.

  • duration (float, default=0.01) – Pulse duration, in s.

  • dwell (float, default=None) – RF raster, in s; the system’s by default.

  • freq_offset (float, default=0.0) – Frequency (Hz) and phase (rad) offsets.

  • phase_offset (float, default=0.0) – Frequency (Hz) and phase (rad) offsets.

  • max_grad (float, default=None) – Limits for the slice-selection gradient, in place of the system’s.

  • max_slew (float, default=None) – Limits for the slice-selection gradient, in place of the system’s.

  • n_fac (int, default=None) – Order of the envelope’s truncation, 1 - |cos(pi t / T)|^n_fac: 40 for "wurst" and 16 for "goia_wurst" by default.

  • mu (float, default=4.9) – "hypsec" sweep amplitude, in units of beta.

  • return_gz (bool, default=False) – Also return the slice-selection gradient and its rephaser. Required by "goia_wurst", refused by "bir4".

  • slice_thickness (float, default=0.0) – Slice thickness, in m, when return_gz.

  • system (Opts, default=None) – System limits.

  • use (str, default='inversion') – What the pulse is for, as Pulseq records it.

  • freq_ppm (float, default=0.0) – Field-strength-relative offsets.

  • phase_ppm (float, default=0.0) – Field-strength-relative offsets.

  • flip_angle (float, default=np.pi / 2) – "bir4" rotation, in rad.

  • kappa (float, default=math.atan(20.0)) – "bir4" frequency-sweep shape: tan(kappa * s) / tan(kappa) over each quarter.

  • gradient_modulation (float, int, default=0.9) – "goia_wurst": the gradient follows (1 - gradient_modulation) + gradient_modulation * |cos(pi t / T)|^gradient_order of its peak, bandwidth / slice_thickness; gradient_modulation lies in [0, 1).

  • gradient_order (float, int, default=4) – "goia_wurst": the gradient follows (1 - gradient_modulation) + gradient_modulation * |cos(pi t / T)|^gradient_order of its peak, bandwidth / slice_thickness; gradient_modulation lies in [0, 1).

Returns:

  • rf (RfEvent) – The pulse.

  • gz, gzr (GradEvent or TrapEvent, optional) – The slice-selection gradient and its rephaser, when return_gz: a trapezoid for the first two sweeps, the modulated gradient for "goia_wurst".

Raises:

ValueError – If pulse_type is unknown, a BIR-4 pulse is asked for a gradient, a GOIA-WURST pulse is not or has no positive slice_thickness, or a BIR-4 or GOIA-WURST duration holds fewer than eight RF samples.

Examples

>>> import numpy as np
>>> import pypulseqpp as pp
>>> rf = pp.make_adiabatic_pulse("bir4", flip_angle=np.pi / 2, duration=6e-3)
>>> rf.type
'rf'
>>> rf, gz, gzr = pp.make_adiabatic_pulse(
...     "goia_wurst", bandwidth=10e3, duration=5e-3, return_gz=True, slice_thickness=0.01
... )
>>> gz.channel
'z'