Gradients#

This module contains implementation for gradient blocks

Classes:

Gradient(t, grads, system_specs, name, ...)

Generic implementation of a MRI-sequence building block containing gradient waveforms on 3 channels.

TrapezoidalGradient(system_specs, ...[, ...])

Module implementing a trapezoidal gradient pulse, from specified parameters

ArbitraryGradient(system_specs, time_points, ...)

Wraps a definition of an arbitrary waveform defined as numpy arrays.
class Gradient(t, grads, system_specs, name, snap_to_raster)[source]#

Bases: SequenceBaseBlock

Generic implementation of a MRI-sequence building block containing gradient waveforms on 3 channels.

This class implements all functionality that should be provided by all types of gradients. Special cases of gradients are meant to be inherited from this class.

Some of the implemented functionalities and their underlying assumptions are described below.

Addition: Gradient instances can be added using the + operator, where breakpoints are combined and linear interpolation of the waveform per channel inbetween the breakpoints is assumed. The result of adding two Gradient objects, is a tuple containing the time and waveform definition as shown in the example code below.

Example addition
trap1 = cmrseq.bausteine.TrapezoidalGradient.from_dur_amp(system_specs,
                                                    orientation=np.array([1., 0., 0.]),
                                                    duration=Quantity(1, "ms"),
                                                    amplitude=Quantity(10, "mT/m"),
                                                     name="trap_1")

trap2 = cmrseq.bausteine.TrapezoidalGradient.from_dur_amp(system_specs,
                                                    orientation=np.array([1., 0., 0.]),
                                                    duration=Quantity(1, "ms"),
                                                     amplitude=Quantity(10, "mT/m"),
                                                     delay=Quantity(0.2, "ms"),
                                                     name="trap_2")
combined_t, combined_wf = trap1 + trap2
combined_gradient = cmrseq.bausteine.ArbitraryGradient(system_specs, combined_t,
                                                    combined_wf, name="combined_trap")
seq = cmrseq.Sequence([combined_gradient], system_specs)

Split: This functionality mainly is required to adhere to the pulseq file format, which requires the gradient definition to be sub-divided into blocks, such that the each gradient channel has at max one gradient block. The split function allows to separate the gradient definition at an arbitrary time.

Validation: Gradient objects are validated against the system-specifications with regard to: 1. Maximal gradient strength 2. Maximal gradient slew-rate 3. Adherence to the gradient-raster time

If the raster time does not match, one option is to apply the snap to raster method, which rounds all temporal definitions to the closest raster point. In most cases this includes unwanted side-effects e.g changing moments. If all time-points are offset from the grid by the same amount this methods should not have unwanted side effects.

Attributes:

gradients

Tuple containing defining points of gradient waveforms as np.array (wrapped as Quantity) with shape (time: (t, ), waveform: (3, t)).

tmin

Calculates the smallest time occuring in all contained definitions.

tmax

Calculates the largest time occuring in all contained definitions.

Methods:

split(t)

Splits the gradient waveform at given time and returns to new definining tuples that both include the split point.

scale_gradients(factor)

Scales gradients by given factor if gradients are defined.

rotate_gradients(rotation_matrix)

Rotates gradients to according to the gradient axes transformation:

validate(system_specs)

Validates if the contained gradient_definition is valid for the given system- specifications.

snap_to_raster(system_specs)

shift(time_shift)

Adds the time-shift to all gradient definition points

flip([time_flip])

Time reverses block by flipping about a given time point.
Parameters:

  • t (Quantity) –

  • grads (Quantity) –

  • system_specs (cmrseq.SystemSpec) –

  • name (str) –

  • snap_to_raster (bool) –

gradients: Tuple[Quantity, Quantity]#

Tuple containing defining points of gradient waveforms as np.array (wrapped as Quantity) with shape (time: (t, ), waveform: (3, t)). Between points, linear interpolation is assumed

split(t)[source]#

Splits the gradient waveform at given time and returns to new definining tuples that both include the split point. This output is meant to yield the original waveform when calling the __add__ functions on the result

Parameters:

t (Quantity) –

Return type:

(Quantity, Quantity)

Returns:

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]

scale_gradients(factor)[source]#

Scales gradients by given factor if gradients are defined.

Parameters:

factor (float) – factor to globally scale the amplitude of gradient definition.

Return type:

None

rotate_gradients(rotation_matrix)[source]#

Rotates gradients to according to the gradient axes transformation:

[[1 0 0][0 1 0][0 0 0]].T -> rotation matrix

Raises:

ValueError - if rotation_matrix is not valid : must be an orthogonal matrix

Parameters:

rotation_matrix (ndarray) – (3, 3) rotation matrix containing the new column basis vectors (meaning in [:, i], i indexes the new orientation of MPS). Vectors are normalized along axis=0 to ensure same magnitude

Return type:

None

validate(system_specs)[source]#

Validates if the contained gradient_definition is valid for the given system- specifications.

Return type:

None

Parameters:

system_specs (SystemSpec) –

snap_to_raster(system_specs)[source]#
Parameters:

system_specs (SystemSpec) –

shift(time_shift)[source]#

Adds the time-shift to all gradient definition points

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 center of this gradient block is choosen.

Parameters:

time_flip (Quantity | None) –

name: str#
class TrapezoidalGradient(system_specs, orientation, amplitude, flat_duration, rise_time, fall_time=None, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal', snap_to_raster=False)[source]#

Bases: Gradient

Module implementing a trapezoidal gradient pulse, from specified parameters

Attributes:

rise_time

Duration of the first trapezoidal gradient slope

fall_time

Duration of the second trapezoidal gradient slope

flat_duration

Duration of the trapezoidal gradient plateau

amplitude

Amplitude of the trapezoidal gradient plateau in mT/m

magnitude

Magnitude (norm over spatial dimensions) of the trapezoidal gradient plateau in mT/m

signed_amplitude

Signed amplitude the amplitude per gradient channel

area

Area of the trapezoidal gradient: ((rise_time + fall_time + flat_duration) * amplitude)

Methods:

from_area(system_specs, orientation, area[, ...])

Constructs the shortest Trapezoidal or triangular gradient pulse with specified area given the system limits:

from_dur_area(system_specs, orientation, ...)

Constructs the Trapezoidal or triangular gradient pulse with specified area and duration (flat + 2 ramp), given the system limits.

from_fdur_area(system_specs, orientation, ...)

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified area and flat duration, given the system limits.

from_dur_amp(system_specs, orientation, ...)

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified duration

from_fdur_amp(system_specs, orientation, ...)

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified flat duration and amplitude, given the system limits.

from_fdur_farea(system_specs, orientation, ...)

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified flat duration and flat_area, given the system limits.
Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • amplitude (Quantity) –

  • flat_duration (Quantity) –

  • rise_time (Quantity) –

  • fall_time (Quantity) –

  • delay (Quantity) –

  • name (str) –

  • snap_to_raster (bool) –

property rise_time: Quantity#

Duration of the first trapezoidal gradient slope

property fall_time: Quantity#

Duration of the second trapezoidal gradient slope

property flat_duration: Quantity#

Duration of the trapezoidal gradient plateau

property amplitude: Quantity#

Amplitude of the trapezoidal gradient plateau in mT/m

property magnitude: Quantity#

Magnitude (norm over spatial dimensions) of the trapezoidal gradient plateau in mT/m

property signed_amplitude: Quantity#

Signed amplitude the amplitude per gradient channel

property area: Quantity#

Area of the trapezoidal gradient: ((rise_time + fall_time + flat_duration) * amplitude)

classmethod from_area(system_specs, orientation, area, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#

Constructs the shortest Trapezoidal or triangular gradient pulse with specified area given the system limits:

Raises:

AssertionError – If area < 0

Parameters:

  • system_specs (SystemSpec) – System-Limit context (SystemSpec instance)

  • area (Quantity) – Quantity[Tesla/Length*Time] Desired first moment of the Gradient Pulse

  • orientation (ndarray) – np.array of shape (3, ). Vector defining the gradient orientation in (gx, gy, gz) channels. Is normalized internally

  • delay (Quantity) – Quantity[Time] Leading time without gradients, defaults to 0. ms

  • name (str) –

Return type:

TrapezoidalGradient

Returns:

TrapezoidalGradient object

classmethod from_dur_area(system_specs, orientation, duration, area, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#

Constructs the Trapezoidal or triangular gradient pulse with specified area and duration (flat + 2 ramp), given the system limits. Ramp time is calculated under the assumption of using maximal slew rate. Is equivalent to solving:

\[ \begin{align}\begin{aligned}a=amplitude, A=area, \delta=ramp, D=duration, s_m=max slew \\Triangular: \\A = a (D-\delta) \ \ and \ \ \delta * s_m= a \\\rightarrow \delta = (D/2)-\sqrt{(D/2)^2 - A/s_m}\end{aligned}\end{align} \]
Raises:

  • ValueError –

    • Duration is not on gradient raster time

    • If area is not feasible with given duration and system limits

  • AssertionError – If area < 0

Return type:

TrapezoidalGradient

Returns:

TrapezoidalGradient object

Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • duration (Quantity) –

  • area (Quantity) –

  • delay (Quantity) –

  • name (str) –

classmethod from_fdur_area(system_specs, orientation, flat_duration, area, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified area and flat duration, given the system limits. Ramp time is calculated under the assumption of using maximal slew rate. Is equivalent to solving:

\[ \begin{align}\begin{aligned}a=amplitude, A=area, \delta=ramp, \Delta=flatduration, s_m=max slew \\Triangular: \\A = a (\Delta + \delta) \ \ and \ \ \delta * s_m = a \\\rightarrow \delta = -(\Delta/2) + \sqrt{(\Delta/2)^2 - A/s_m}\end{aligned}\end{align} \]
Raises:

  • ValueError –

    • Flat duration is not on gradient raster time

  • ValueError –

    • If area is not feasible with given duration and system limits

  • AssertionError – If area < 0

Returns:

TrapezoidalGradient object

Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • flat_duration (Quantity) –

  • area (Quantity) –

  • delay (Quantity) –

  • name (str) –

classmethod from_dur_amp(system_specs, orientation, duration, amplitude, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#
Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified duration

and amplitude, given the system limits. Ramp time is calculated under the assumption of using maximal slew rate.

Raises:

ValueError – If duration is not on grid & If amplitude is not reachable within specified duration / 2 with given system limits

Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • duration (Quantity) –

  • amplitude (Quantity) –

  • delay (Quantity) –

  • name (str) –

classmethod from_fdur_amp(system_specs, orientation, flat_duration, amplitude, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified flat duration and amplitude, given the system limits. Ramp time is calculated under the assumption of using maximal slew rate.

Raises:

ValueError – If flat_duration is not on grid

Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • flat_duration (Quantity) –

  • amplitude (Quantity) –

  • delay (Quantity) –

  • name (str) –

classmethod from_fdur_farea(system_specs, orientation, flat_duration, flat_area, delay=<Quantity(0.0, 'millisecond')>, name='trapezoidal')[source]#

Constructs the Trapezoidal or triangular (fdur=0) gradient pulse with specified flat duration and flat_area, given the system limits. Ramp time is calculated under the assumption of using maximal slew rate.

Raises:

ValueError – If flat_duration is not on grid

Parameters:

  • system_specs (SystemSpec) –

  • orientation (ndarray) –

  • flat_duration (Quantity) –

  • flat_area (Quantity) –

  • delay (Quantity) –

  • name (str) –

class ArbitraryGradient(system_specs, time_points, waveform, delay=<Quantity(0, 'millisecond')>, name='name', snap_to_raster=False)[source]#

Bases: Gradient

Wraps a definition of an arbitrary waveform defined as numpy arrays.

Methods:

from_kspace_trajectory(system_specs, kspace_traj)

Parameters:

  • system_specs (SystemSpec) –

  • time_points (Quantity) –

  • waveform (Quantity) –

  • delay (Quantity) –

  • name (str) –

  • snap_to_raster (bool) –

classmethod from_kspace_trajectory(system_specs, kspace_traj)[source]#
Parameters:

  • system_specs (SystemSpec) –

  • kspace_traj (Quantity) –