make_wave_gradients

make_wave_gradients#

pypulseqpp.make_wave_gradients()[source]#

Create self-balanced wave-encoding gradient events for one readout flat top.

A sine on sine_channel and a cosine on cosine_channel run cycles periods across the flat top. Played with the readout gradient, the pair traces the corkscrew k-space trajectory of wave-CAIPI [1]; the events themselves are two sinusoidal gradient waveforms.

Each sinusoid is tapered in and out by a raised-cosine envelope over a quarter period (rounded down to the raster) and offset under that envelope, so it starts and ends at zero amplitude with zero net area: scaling either event, including to zero, leaves every rewinder unchanged.

Parameters:

  • flat_time (float) – Readout flat-top duration (s), rounded to the gradient raster; the waveforms span it exactly.

  • cycles (int) – Sinusoid periods across the flat top.

  • amplitude (float) – Requested sinusoid amplitude, in T/m rather than the Hz/m used elsewhere in this module. An upper bound: the amplitude built is lowered as needed to keep the played waveforms within system.max_slew and system.max_grad. The balancing offset can lift a played peak a few percent above the amplitude.

  • sine_channel ({"x", "y", "z"} or None, default='y') – Channels for the sine and the cosine; None omits that one.

  • cosine_channel ({"x", "y", "z"} or None, default='z') – Channels for the sine and the cosine; None omits that one.

  • delay (float, default=0.0) – Start of the flat top within the block (s), normally the readout lobe’s rise time.

  • return_amplitude (bool, default=False) – Also return the amplitude built.

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

Returns:

  • sine, cosine (GradEvent or None) – Arbitrary gradients, None for an omitted channel.

  • amplitude (float) – Amplitude built, in T/m. Only with return_amplitude.

Raises:

ValueError – If neither channel is given or both name the same one, if cycles or amplitude is not positive, or if the flat top holds fewer than 4 * cycles gradient raster periods.

Examples

>>> import numpy as np
>>> import pypulseqpp as pp
>>> gy, gz = pp.make_wave_gradients(3e-3, 4, 10e-3)
>>> [abs(round(float(np.sum(g.waveform)), 6)) for g in (gy, gz)]
[0.0, 0.0]

References