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), or a table for read_forbidden_bands().

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

  • stride (float, default=None) – Step between window starts in seconds; window_width / 2 by default.

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

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

  • 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, 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, kept whether or not it violates: its largest peak amplitude (mT/m), on peak_axis at frequency, in the 0-based window starting at window_start (s); violations, the windows exceeding the threshold on any guarded axis; and axes, the same reading for each guarded axis on its own.

Raises:

ValueError – If a band’s frequency range is empty or negative, or a rotation is not a 3x3 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. The FFT is MKL’s when the mkl package is installed, and pocketfft otherwise.