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.ascfile read byread_forbidden_bands().window_width (float, default=0.04) – Window length (s).
stride (float, default=None) – Step between window starts (s);
window_width / 2whenNone.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 abovemin_lineand 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 FFTbackendmech_resonance_spectrum()transforms with, andbands: one entry per band, in the order given, with the band’saxis(None for every axis),f_min,f_max,toleranceand appliedthreshold(mT/m); the band’s worst window, its strongest violating one when any violates and its strongest reading otherwise: itspeakamplitude (mT/m), onpeak_axisatfrequency, in the 0-basedwindowstarting atwindow_start(s), with that axis’s largestgradientmagnitude 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; andaxes, the same reading for each guarded axis on its own.
- Raises:
ValueError – If
min_threshold,min_line,window_widthorstrideis not positive,frequency_oversamplingis below 1,tolerance_limitsis neither"line"nor"gradient", a band’s frequency range is empty or negative, orrotationis 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 andmin_thresholdotherwise.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’speakis the largest reading of the frequencies read.The FFT is MKL’s when the
mklpackage is installed, and pocketfft otherwise.