check_pns

Contents

check_pns#

pypulseqpp.safety.check_pns()[source]#

Check peripheral nerve stimulation against a SAFE or chronaxie model.

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

  • model (ChronaxieModel, mapping, SAFE description, or path) – A ChronaxieModel or a mapping of its fields; a SAFE description shaped like upstream’s safe_example_hw(); or a .asc file for read_safe_model().

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

  • system (pypulseqpp.Opts, default=None) – Source of the gyromagnetic ratio (Hz/T); seq.system when None, then the default Opts.

  • trace (bool, default=False) – Also return the response over time, which a diagnostic plot draws. The trace has one value per gradient raster interval over the whole sequence: at its end under a chronaxie model, at its centre under SAFE.

Returns:

  • is_ok (bool) – True when the axis-combined response, as a fraction of the model’s threshold, stays below 1 at every sample.

  • report (SimpleNamespace) – model ("safe" or "chronaxie"), raster (s), samples, peak, the largest root-sum-square response, and axes, the largest response of each of x, y and z. A peak carries value as a fraction of threshold, the sample time (s) and the 1-based block that plays it. Under trace, time (s), response – the root-sum-square, as a fraction of threshold – and each axis’s own response, all of length samples.

Raises:
  • TypeError – If model is none of the accepted forms.

  • ValueError – If a model coefficient is not positive, a SAFE axis lacks a field or its a1 + a2 + a3 is not 1, or rotation is not a 3x3 orthonormal matrix.

Notes

The gradient is sampled on the sequence’s own gradient raster, from rest, and its slew is the difference between neighbouring samples. Under a chronaxie model the samples are the ends of the raster intervals, so the slew is the one each interval plays and the response is the exact convolution at every interval end, where a ramp’s response peaks. Under SAFE they are the interval centres; this and the SAFE model are upstream PyPulseq’s calc_pns. The response is evaluated over the whole sequence in one pass, carrying each model’s memory, in bounded storage.