check_mech_resonance

check_mech_resonance#

pypulseqpp.safety.check_mech_resonance()[source]#

Check the gradient amplitude spectrum against forbidden gradient bands.

Parameters:
  • seq (Sequence) – Sequence to check.

  • bands (iterable of ForbiddenBand, or path) – Bands as (axis, f_min, f_max, tolerance) tuples, or the path of a .asc file read by read_forbidden_bands().

  • window_width (float, default=0.04) – Window length (s).

  • stride (float, default=None) – Step between window starts (s); window_width / 2 when None.

  • frequency_oversampling (int, default=3) – Zero-padded transform length, in window lengths.

  • min_threshold (float, default=10.0) – Threshold (mT/m) for a band whose tolerance is 0.

  • tolerance_limits ({"line", "gradient"}, default="line") – What a positive tolerance limits. "line": the amplitude of any line inside the band. "gradient": the gradient amplitude on the guarded axis, as echo-spacing lockout tables state it; a window then violates the band when the band holds a line above min_line and the axis’s gradient over the window exceeds the tolerance.

  • min_line (float, default=6.0) – Line amplitude (mT/m) a band with tolerance_limits="gradient" must hold before its tolerance is compared with the gradient.

  • reread (bool, default=True) – Read each window that exceeds a band again over a window four times longer, centred on it. The excess is leakage, and no violation, when the strongest line there lies outside the band and keeps 80 % of the amplitude it read at.

  • rotation (array_like, default=None) – 3x3 prescription rotation from logical to physical axes, applied after each block’s own rotation; identity (axial) by default.

  • system (pypulseqpp.Opts, default=None) – Source of the gyromagnetic ratio; the sequence’s own by default.

Returns:

  • is_ok (bool) – True when no window exceeds any band’s threshold.

  • report (SimpleNamespace) – window_width, stride (as sampled, s), frequency_step (Hz), windows, the FFT backend mech_resonance_spectrum() transforms with, and bands: one entry per band, in the order given, with the band’s axis (None for every axis), f_min, f_max, tolerance and applied threshold (mT/m); the band’s worst window, its strongest violating one when any violates and its strongest reading otherwise: its peak amplitude (mT/m), on peak_axis at frequency, in the 0-based window starting at window_start (s), with that axis’s largest gradient magnitude over the window (mT/m); violations, the windows violating the band on any guarded axis; leakage, the exceeding windows the longer read put down to a line outside the band, counted per axis; and axes, the same reading for each guarded axis on its own.

Raises:

ValueError – If min_threshold, min_line, window_width or stride is not positive, frequency_oversampling is below 1, tolerance_limits is neither "line" nor "gradient", a band’s frequency range is empty or negative, or rotation is not a 3x3 orthonormal matrix.

Notes

The gradient is sampled at the centres of the sequence’s own gradient raster, the one its definitions record. Each window is mean-subtracted, Hann-tapered and zero-padded before a real FFT, and a bin’s amplitude is 2 |X_k| / sum(w), so a sustained sinusoid of amplitude A at a bin frequency reads A. A band’s threshold is its tolerance where that is positive and min_threshold otherwise.

A wide band is read only up to the frequency the gradient can reach its threshold at: a window’s reading at f is at most 3 V / (sum(w) sin(pi f dt)), with V the total variation of the axis’s gradient over the window and dt the gradient raster. This leaves every verdict as it is and bounds the cost of a band open towards the raster’s Nyquist frequency. A band’s peak is the largest reading of the frequencies read.

The FFT is MKL’s when the mkl package is installed, and pocketfft otherwise.