Radio-Frequency#

This module contains in the implementation of radio-frequency pulse building blocks

Classes:

`RFPulse`(system_specs, name, time, ...[, ...])	Generic MRI-sequence radio-frequency building block
`SincRFPulse`(system_specs, duration[, ...])	Defines a Sinc-RF pulse on a time grid with step length defined by system_specs.
`HardRFPulse`(system_specs[, flip_angle, ...])	Defines a constant (hard) RF pulse on a time grid with step length defined by system_specs.
`GaussRFPulse`(system_specs, duration[, ...])	Defines a Gauss-RF pulse on a time grid with step length defined by system_specs.
`ArbitraryRFPulse`(system_specs, name, ...[, ...])	Wrapper for arbitrary rf shapes, to adhere to building block concept.
`AdiabaticRFPulse`(system_specs, name, time, ...)	Class for implementation of adiabatic pulses, hence including amplitude and frequency modulation.
`SLRPulse`(system_specs, flip_angle, ...[, ...])	Bundles the construction of RF pulses using the Shinnar-Le Roux as implemented by the sigpy package.

class RFPulse(system_specs, name, time, rf_waveform, frequency_offset, phase_offset, bandwidth, rf_events, snap_to_raster=False)[source]#

Bases: SequenceBaseBlock

Generic MRI-sequence radio-frequency building block

This class implements all functionality that should be provided by all subtypes of RF-pulses.

The waveform (assuming linear interpolation between the points) and the time-points have to be specified on construction of the RF object, where the waveform is assumed to be real-valued. It also is assumed, that all RF-pulse subclasses correctly calculate and provide the following quantities:

Pulse bandwidth
Frequency offset
Phase offset

The phase offset and frequency offset attributes are used to compute the complex rf-waveform representation using the RFPulse.rf - property.

Parameters:

system_specs (SystemSpec) – SytemSpecifications object
name (str) – string
time (Quantity) – (# points) time-points defining the waveform duration
rf_waveform (Quantity) – (#points) rf-amplitude
phase_offset (Quantity) – Offset in radians, that is added when computing the complex-valued RF-waveform in RFPulse.rf
frequency_offset (Quantity) – Linear phase contribution, that is added when computing the complex-valued RF-waveform in RFPulse.rf
rf_events (Tuple[Quantity, Quantity]) – Tuple containing pairs of events defined as (center-time, flip-angle)
snap_to_raster (bool) – if True, all points in the rf definition are rounded to the nearest raster point.
bandwidth (Quantity) –

Attributes:

`rf_events`	Tuple containing rf events (time, flip_angle)
`phase_offset`	RF phase offset in radians.
`frequency_offset`	RF frequency offset in Hertz.
`bandwidth`	RF pulse bandwidth in kilo Hertz.
`tmin`	Calculates the smallest time occuring in all contained definitions.
`tmax`	Calculates the largest time occuring in all contained definitions.
`rf`	Returns the complex RF-amplitude shifted/modulated by the phase/frequency offsets
`isodelay`	Approximates isodelay as the time interval between peak RF energy and end of pulse, neglecting the (small) nonlinear dependence on flip angle.
`normalized_waveform`	Computes the normalized waveform (scaling between -1, 1).

Methods:

`validate`(system_specs)	Validates if the contained rf-definition is valid for the given system- specifications
`shift`(time_shift)	Adds the time-shift to all rf definition points and the rf-center
`flip`([time_flip])	Time reverses block by flipping about a given time point.
`scale_angle`(factor)	Scales the contained waveform amplitude and corresponding rf_events by given factor.
`snap_to_raster`(system_specs)

rf_events: Tuple[Quantity, Quantity]#: Tuple containing rf events (time, flip_angle)

phase_offset: Quantity#: RF phase offset in radians. This is used phase shift the complex rf amplitude in self.rf

frequency_offset: Quantity#: RF frequency offset in Hertz. This is used to modulate the complex rf amplitude in self.rf

bandwidth: Quantity#: RF pulse bandwidth in kilo Hertz. Used to calculate gradient strength

property tmin: Quantity#: Calculates the smallest time occuring in all contained definitions. :return: Quantity[time]

property tmax: Quantity#: Calculates the largest time occuring in all contained definitions. :return: Quantity[time]

validate(system_specs)[source]#

Validates if the contained rf-definition is valid for the given system- specifications

Parameters:: system_specs (SystemSpec) –

property rf: (<class 'pint.registry.Quantity'>, <class 'pint.registry.Quantity'>)#: Returns the complex RF-amplitude shifted/modulated by the phase/frequency offsets

property isodelay: Quantity#: Approximates isodelay as the time interval between peak RF energy and end of pulse, neglecting the (small) nonlinear dependence on flip angle. This is necessary to correctly compute the required gradient area in slice-selective excitation.

property normalized_waveform: (<class 'numpy.ndarray'>, <class 'pint.registry.Quantity'>, <class 'numpy.ndarray'>, <class 'pint.registry.Quantity'>)#

Computes the normalized waveform (scaling between -1, 1).

Returns:

Normalized amplitude between [-1, 1] [dimensionless] (flipped such that the
maximum normalized value is positive. Scaling with peak amplitude inverts the shape again)
Peak amplitude in uT
Phase per timestep in rad
Time raster definition points

shift(time_shift)[source]#

Adds the time-shift to all rf definition points and the rf-center

Return type:: None
Parameters:: time_shift (Quantity) –

flip(time_flip=None)[source]#

Time reverses block by flipping about a given time point. If no time is specified, the rf center of this block is choosen.

Parameters:: time_flip (Quantity | None) –

scale_angle(factor)[source]#

Scales the contained waveform amplitude and corresponding rf_events by given factor. Resulting in scaled flip angles.

Parameters:: factor (float) –

snap_to_raster(system_specs)[source]#

Parameters:: system_specs (SystemSpec) –

name: str#

class SincRFPulse(system_specs, duration, flip_angle=<Quantity(3.14159265, 'radian')>, time_bandwidth_product=3.0, center=0.5, delay=<Quantity(0.0, 'millisecond')>, apodization=0.5, frequency_offset=<Quantity(0.0, 'hertz')>, phase_offset=<Quantity(0.0, 'radian')>, name='sinc_rf')[source]#

Bases: RFPulse

Defines a Sinc-RF pulse on a time grid with step length defined by system_specs. The window function used to temporally limit the waveform is given as:

\[window = (1 - \beta) + \beta cos(2 \pi n /N)\]

where \(\beta\) is the specified apodization argument. If set to 0.5 the used window is a Hanning window resulting in 0 start and end. using 0.46 results in the use of a Hamming window.

Parameters:

flip_angle (Quantity) – Quantity[Angle] Desired Flip angle of the Sinc Pulse. For negative Values the flip-angle is stored as positive absolute plus a phase offset of 180°
duration (Quantity) – Quantity[Time] Total duration of the pulse
time_bandwidth_product (float) – float - Used to calculate the pulse-bandwidth. For a Sinc-Pulse bw = time_bandwidth_product/duration corresponds to the half central-lobe-width
center (float) – float [0, 1] factor to compute the pulse center relative to duration
delay (Quantity) – Adds temporal offset to pulse
apodization (float) – float from interval [0, 1] used to calculate cosine-apodization window
frequency_offset (Quantity) – Frequency offset in Hz in rotating frame ()
phase_offset (Quantity) – Phase offset in rad.
name (str) – semantic label of the building block
system_specs (SystemSpec) –

Methods:

`get_unit_waveform`(raster_time, ...)	Constructs the sinc-pulse waveform according to: :rtype: `Quantity`
`from_shortest`(system_specs, flip_angle[, ...])	Creates the shortest Sinc RF pulse for specified arguments.

static get_unit_waveform(raster_time, time_bandwidth_product, duration, apodization, center)[source]#

Constructs the sinc-pulse waveform according to: :rtype: Quantity

\[wf = (1 - \Gamma + \Gamma cos(2\pi / \Delta * t)) * sinc(tbw/\Delta t)\]

where

\[\begin{split}\Gamma :& apodization (typically 0.46) \\ \Delta :& Pulse duration \\ tbw :& Time-bandwidth-product \\ t :& time on raster where center defines 0.\end{split}\]

Parameters:

raster_time (Quantity) –
time_bandwidth_product (float) –
duration (Quantity) –
apodization (float) –
center (float) –

Return type:

Quantity

classmethod from_shortest(system_specs, flip_angle, time_bandwidth_product=3.0, center=0.5, delay=<Quantity(0.0, 'millisecond')>, apodization=0.5, frequency_offset=<Quantity(0.0, 'hertz')>, phase_offset=<Quantity(0.0, 'radian')>, name='sinc_rf')[source]#

Creates the shortest Sinc RF pulse for specified arguments.

Parameters:

flip_angle (Quantity) – Quantity[Angle] Desired Flip angle of the Sinc Pulse. For negative Values the flip-angle is stored as positive absolute plus a phase offset of 180°
time_bandwidth_product (float) – float - Used to calculated the pulse-bandwidth. For a Sinc-Pulse bw = time_bandwidth_product/duration corresponds to the half central-lobe-width
center (float) – float [0, 1] factor to compute the pulse center relative to duration
delay (Quantity) –
apodization (float) – float from interval [0, 1] used to calculate cosine-apodization window
frequency_offset (Quantity) – Frequency offset in Hz in rotating frame ()
phase_offset (Quantity) – Phase offset in rad.
name (str) –
system_specs (SystemSpec) –

class HardRFPulse(system_specs, flip_angle=<Quantity(3.14159265, 'radian')>, duration=<Quantity(1.0, 'millisecond')>, delay=<Quantity(0.0, 'millisecond')>, frequency_offset=<Quantity(0.0, 'hertz')>, phase_offset=<Quantity(0.0, 'radian')>, name='hard_rf')[source]#

Bases: RFPulse

Defines a constant (hard) RF pulse on a time grid with step length defined by system_specs.

Parameters:

system_specs (SystemSpec) –
flip_angle (Quantity) –
duration (Quantity) –
delay (Quantity) –
frequency_offset (Quantity) –
phase_offset (Quantity) –
name (str) –

class GaussRFPulse(system_specs, duration, flip_angle=<Quantity(3.14159265, 'radian')>, time_bandwidth_product=4.0, center=0.5, delay=<Quantity(0.0, 'millisecond')>, apodization=0.5, frequency_offset=<Quantity(0.0, 'hertz')>, phase_offset=<Quantity(0.0, 'radian')>, name='gauss_rf')[source]#

Bases: RFPulse

Defines a Gauss-RF pulse on a time grid with step length defined by system_specs. The window function used to temporally limit the waveform is given as:

\[window = (1 - \beta) + \beta cos(2 \pi n /N)\]

where \(\beta\) is the specified apodization argument. If set to 0.5 the used window is a Hanning window resulting in 0 start and end. using 0.46 results in the use of a Hamming window.

Parameters:

flip_angle (Quantity) – Quantity[Angle] Desired Flip angle of the Gauss Pulse. For negative Values the flip-angle is stored as positive absolute plus a phase offset of 180°
duration (Quantity) – Quantity[Time] Total duration of the pulse
time_bandwidth_product (float) – float - Used to calculate the pulse-bandwidth. For a Gauss-Pulse bw = time_bandwidth_product/duration corresponds to the half central-lobe-width
center (float) – float [0, 1] factor to compute the pulse center relative to duration
delay (Quantity) – Adds temporal offset to pulse
apodization (float) – float from interval [0, 1] used to calculate cosine-apodization window
frequency_offset (Quantity) – Frequency offset in Hz in rotating frame ()
phase_offset (Quantity) – Phase offset in rad.
name (str) – semantic label of the building block
system_specs (SystemSpec) –

Methods:

`get_unit_waveform`(raster_time, ...)	Constructs a normalized Gaussian pulse waveform according to: :rtype: `Quantity`
`from_shortest`(system_specs, flip_angle[, ...])	Creates the shortest Sinc RF pulse for specified arguments.

static get_unit_waveform(raster_time, time_bandwidth_product, duration, apodization, center)[source]#

Constructs a normalized Gaussian pulse waveform according to: :rtype: Quantity

\[wf = (1 - \Gamma + \Gamma cos(2\pi / \Delta * t)) * exp(-(tbw/\Delta t)^2)\]

where

\[\begin{split}\Gamma :& apodization (typically 0.46) \\ \Delta :& Pulse duration \\ tbw :& Time-bandwidth-product \\ t :& time on raster where center defines 0.\end{split}\]

Parameters:

raster_time (Quantity) –
time_bandwidth_product (float) –
duration (Quantity) –
apodization (float) –
center (float) –

Return type:

Quantity

Creates the shortest Sinc RF pulse for specified arguments.

Parameters:

flip_angle (Quantity) – Quantity[Angle] Desired Flip angle of the Sinc Pulse. For negative Values the flip-angle is stored as positive absolute plus a phase offset of 180°
time_bandwidth_product (float) – float - Used to calculated the pulse-bandwidth. For a Sinc-Pulse bw = time_bandwidth_product/duration corresponds to the half central-lobe-width
center (float) – float [0, 1] factor to compute the pulse center relative to duration
delay (Quantity) –
apodization (float) – float from interval [0, 1] used to calculate cosine-apodization window
frequency_offset (Quantity) – Frequency offset in Hz in rotating frame ()
phase_offset (Quantity) – Phase offset in rad.
name (str) –
system_specs (SystemSpec) –

class ArbitraryRFPulse(system_specs, name, time_points, waveform, delay=<Quantity(0.0, 'millisecond')>, bandwidth=None, frequency_offset=<Quantity(0.0, 'hertz')>, phase_offset=<Quantity(0.0, 'radian')>, snap_to_raster=False)[source]#

Bases: RFPulse

Wrapper for arbitrary rf shapes, to adhere to building block concept. The gridding is assumed to be on raster time and not shifted by half a raster time. This shift (useful for simulations) can be incorporated when calling the gridding function of the sequence.

The waveform is assumed to start and end with values of 0 uT. If the given waveform does not adhere to that definition, the arrays are padded.

The rf-center (time-point of effective excitation) is estimated from pulse maximum.

If not specified, the bandwidth of the given waveform is estimated by using the full width at half maximum of the power-spectrum.

Warning

For very long pulses, the estimation of bandwidth might not be reasonable anymore, due to relaxation.

Parameters:

system_specs (SystemSpec) –
name (str) –
time_points (Quantity) – Shape (#steps)
waveform (Quantity) – Shape (#steps) in uT as real-valued array
bandwidth (Optional[Quantity]) – in Hz, if not specified, the pulse bandwidth is estimated
frequency_offset (Quantity) –
phase_offset (Quantity) –
snap_to_raster (bool) –
delay (Quantity) –

class AdiabaticRFPulse(system_specs, name, time, rf_waveform, frequency_offset, phase_offset, bandwidth, rf_events, phase_modulation, snap_to_raster=False)[source]#

Bases: RFPulse

Class for implementation of adiabatic pulses, hence including amplitude and frequency modulation.

The phase offset and frequency offset attributes are used to compute the complex rf-waveform representation using the RFPulse.rf - property.

Parameters:

system_specs (SystemSpec) – SystemSpecs object
name (str) – string to name the building block
time (Quantity) – (# points) time-points defining the waveform duration
rf_waveform (Quantity) – (#points) rf-amplitude
phase_offset (Quantity) – Phase in radians, Used to compute the complex rf-waveform
frequency_offset (Quantity) – Used to compute the linear phase modulation due to a frequency offset of the complex rf-waveform
rf_events (Tuple[Quantity, Quantity]) – tuple containing (event, flip angle)
phase_modulation (Quantity) – Quantity containing a variable phase modulation for all points in the specified rf_waveform
snap_to_raster (bool) –
bandwidth (Quantity) –

Attributes:

`phase_modulation`	Variable RF phase modulation of the complex waveform in (rad)
`rf`	Returns the complex RF-amplitude shifted/modulated by the phase/frequency offsets

Methods:

`from_bir4`(system_specs, duration, ...[, ...])	Constructs an adiabatic B_1-insensitive rotation pulse by wrapping the sigpy implementation given at.
`from_hyperbolic_secant`(system_specs, ...[, ...])	Constructs an adiabatic hyperbolic secant pulse, by either using target flip-angle or a peak rf amplitude.

phase_modulation: Quantity#: Variable RF phase modulation of the complex waveform in (rad)

property rf: (<class 'pint.registry.Quantity'>, <class 'pint.registry.Quantity'>)#: Returns the complex RF-amplitude shifted/modulated by the phase/frequency offsets

classmethod from_bir4(system_specs, duration, flip_angle, beta, kappa, b1_amplitude, phase_offset=<Quantity(0, 'radian')>, delay=<Quantity(0, 'millisecond')>, d0=1)[source]#

Constructs an adiabatic B_1-insensitive rotation pulse by wrapping the sigpy implementation given at.

https://sigpy.readthedocs.io/en/latest/generated/sigpy.mri.rf.adiabatic.bir4.html

Raises:

SequenceArgumentError - if duration is not a 4x multiple of RF-raster time

Parameters:

system_specs (SystemSpec) –
duration (Quantity) –
flip_angle (Quantity) –
beta (float) –
kappa (float) –
b1_amplitude (Quantity) –
phase_offset (Quantity) –
delay (Quantity) –
d0 (float) –

Return type:

AdiabaticRFPulse

Parameters:

system_specs (SystemSpec) – SystemSpecification object
duration (Quantity) – Total duration of the pulse
flip_angle (Quantity) – Expected maximal flip-angle
beta (float) – dimensionless AM constant, determines how well adiabatic condition is met
kappa (float) – dimensionless FM constant, determines how well adiabatic condition is met
phase_offset (Quantity) – Phase in radians, Used to compute the complex rf-waveform
b1_amplitude (Quantity) – B1-max scaling in uT
delay (Quantity) – Shift of start point
d0 (float) –

Return type:

AdiabaticRFPulse

Returns:

AdiabaticRFPulse

classmethod from_hyperbolic_secant(system_specs, duration, beta, mu, flip_angle=None, max_amplitude=None, phase_offset=<Quantity(0, 'radian')>, frequency_offset=<Quantity(0, 'hertz')>, delay=<Quantity(0, 'millisecond')>)[source]#

Constructs an adiabatic hyperbolic secant pulse, by either using target flip-angle or a peak rf amplitude. If

https://sigpy.readthedocs.io/en/latest/generated/sigpy.mri.rf.adiabatic.hypsec.html

For more information on how the parameters relate to the inversion profile see following presentation: https://labs.dgsom.ucla.edu/mrrl/files/view/m229-2021/M229_Lecture5_Adiabatic_Pulses.pdf

Computations for relation of max amplitude and flip-angle as well as bandwidth is given in the appendix of

Wastling SJ, Barker GJ. Designing hyperbolic secant excitation pulses to reduce signal dropout in gradient-echo echo-planar imaging. Magn. Reson. Med. 2015;74:661–672 doi: 10.1002/MRM.25444.

Raises:

SequenceArgumentError - if duration is not on RF-raster time

Parameters:

system_specs (SystemSpec) – SystemSpecification object
duration (Quantity) – Total duration of the pulse
beta (Quantity) – modulation parameter in rad/s, which determines how well adiabatic condition is met, with usual values of multiple kHz
mu (float) – \(\beta\mu\) is scaling the frequency modulation with \(2 < \mu < 8\) being reasonable values
flip_angle (Optional[Quantity]) – If specified, the max amplitude is computed to achieve the target flip angle as stated in (doi: 10.1002/MRM.25444).
max_amplitude (Optional[Quantity]) – Peak RF amplitude. This does not influence the flip-angle if adiabaticity is given (\(B_{1max} >> (\beta\sqrt{\mu} / \gamma)\)) but refines the inversion profile as described in slide 33 of the reference stated above. In this case the spectral RF bandwidth is given \(\beta\mu\)
phase_offset (Quantity) – Phase in radians, Used to compute the complex rf-waveform
frequency_offset (Quantity) – Linear phase contribution, that is added when computing the complex-valued RF-waveform in RFPulse.rf
delay (Quantity) – Shift of start point

Return type:

AdiabaticRFPulse

Returns:

AdiabaticRFPulse

rf_events: Tuple[Quantity, Quantity]#: Tuple containing rf events (time, flip_angle)

bandwidth: Quantity#: RF pulse bandwidth in kilo Hertz. Used to calculate gradient strength

phase_offset: Quantity#: RF phase offset in radians. This is used phase shift the complex rf amplitude in self.rf

frequency_offset: Quantity#: RF frequency offset in Hertz. This is used to modulate the complex rf amplitude in self.rf

name: str#

class SLRPulse(system_specs, flip_angle, pulse_duration, time_bandwidth_product, pulse_type, filter_type, passband_ripple=0.01, stopband_ripple=0.01, phase_offset=<Quantity(0, 'radian')>, frequency_offset=<Quantity(0, 'hertz')>, delay=<Quantity(0.0, 'millisecond')>, cancel_alpha_phs=False)[source]#

Bases: RFPulse

Bundles the construction of RF pulses using the Shinnar-Le Roux as implemented by the sigpy package. For more details on suitable argument values, refer to the following publication:

Pauly, J., Le Roux, Patrick., Nishimura, D., and Macovski, A.(1991). ‘Parameter Relations for the Shinnar-LeRoux Selective Excitation Pulse Design Algorithm’. IEEE Transactions on Medical Imaging, Vol 10, No 1, 53-65.

https://sigpy.readthedocs.io/en/latest/generated/sigpy.mri.rf.slr.dzrf.html

Parameters:

system_specs (Quantity) –
flip_angle (Quantity) –
pulse_duration (Quantity) –
time_bandwidth_product (float) –
pulse_type (str) – Allowed values [“small_tip”, “excitation”, “se_refocus”, “inversion”, “saturation”]
filter_type (str) – Allowed values [“sinc”, “pm_equal_ripple”, “min_phase”, “max_phase”, “least_squares”]
passband_ripple (float) – Allowed ripple amplitude inside the pass-band in percent (within slice profile)
stopband_ripple (float) – Allowed ripple amplitude outside the pass-band in percent (determines side-band excitation signal).
phase_offset (Quantity) – Offset in radians, that is added when computing the complex-valued RF-waveform in RFPulse.rf
frequency_offset (Quantity) – Linear phase contribution, that is added when computing the complex-valued RF-waveform in RFPulse.rf
cancel_alpha_phs (bool) – For ‘excitation’ pulses, absorb the alpha phase profile from beta’s profile, so they cancel for a flatter total phase
delay (Quantity) –