apply_system_derates

apply_system_derates#

pypulseqpp.apply_system_derates()[source]#

Return a copy with gradient, slew and peak-B1 limits scaled from their base values.

Base limits are retained on the copy, so repeated derating does not compound, and a ceiling cap_system() puts on a derated copy holds when it is derated again.

Parameters:
  • opts (Opts) – System limits. Not modified.

  • grad_derate (float, default=MAX_GRAD_DERATE) – Fraction of the base max_grad to allow.

  • slew_derate (float, default=MAX_SLEW_DERATE) – Fraction of the base max_slew to allow.

  • b1_derate (float, default=MAX_B1_DERATE) – Fraction of the base max_b1 to allow; a system without a max_b1 keeps none.

Returns:

The derated copy.

Return type:

Opts

See also

cap_system

the same copy-not-mutate contract, for an absolute ceiling.

Notes

The default fractions, MAX_GRAD_DERATE and MAX_SLEW_DERATE, leave a margin below the amplitude and slew-rate limits for waveforms designed on one axis at a time and played while other axes are active. MAX_B1_DERATE keeps a designed pulse’s peak below the transmit chain’s limit; the excitation and refocusing modules fit their pulses to it whether or not the system was derated.

Examples

>>> import pypulseqpp as pp
>>> opts = pp.Opts(max_grad=40, grad_unit="mT/m", max_slew=150, slew_unit="T/m/s")
>>> derated = pp.apply_system_derates(opts)
>>> derated.max_grad == 0.9 * opts.max_grad
True
>>> derated is opts
False

The caller’s own limits are untouched, and repeating does not compound:

>>> pp.apply_system_derates(derated).max_grad == derated.max_grad
True
>>> b1 = pp.apply_system_derates(pp.Opts(max_b1=11.2))
>>> round(b1.max_b1 / b1.gamma * 1e6, 2), pp.apply_system_derates(b1).max_b1 == b1.max_b1
(10.08, True)

A ceiling below the derated limit survives a second derate:

>>> capped = pp.cap_system(derated, max_grad=30)
>>> pp.apply_system_derates(capped).max_grad == capped.max_grad
True