"""System limits and shared raster defaults."""
from __future__ import annotations
__all__ = [
"MAX_B1_DERATE",
"MAX_GRAD_DERATE",
"MAX_SLEW_DERATE",
"Opts",
"apply_system_derates",
"cap_system",
"default_system",
]
import copy as _copy
import pypulseq as _pp
from pypulseq.convert import convert as _convert
_B1_PER_UNIT_T = {"T": 1.0, "mT": 1e-3, "uT": 1e-6, "G": 1e-4}
def _b1_to_hz(value: float, unit: str, gamma: float) -> float:
"""Return a positive B1 amplitude ``value`` in ``unit`` as gamma B1 in Hz."""
if unit != "Hz" and unit not in _B1_PER_UNIT_T:
raise ValueError(
f"b1_unit must be Hz or one of {sorted(_B1_PER_UNIT_T)}, got {unit!r}"
)
if not float(value) > 0.0:
raise ValueError(f"max_b1 must be positive, got {value}")
if unit == "Hz":
return float(value)
return float(value) * _B1_PER_UNIT_T[unit] * float(gamma)
[docs]
class Opts(_pp.Opts):
"""PyPulseq system limits with shared raster defaults.
The constructor accepts PyPulseq's parameters. Raster defaults are 20 us
for the gradient and block duration rasters, 2 us for the RF and ADC
rasters, and zero for the RF and ADC dead times and the RF ringdown time.
Set the actual hardware timings before checking a sequence.
Gradient amplitude and slew-rate limits are stored in Hz/m and Hz/m/s after
conversion from ``grad_unit`` and ``slew_unit``; ``gamma`` is in Hz/T and
``B0`` in T. ``max_b1``, the peak B1 the transmit chain allows, is stored in
Hz (gamma B1) after conversion from ``b1_unit``, one of ``Hz``, ``T``,
``mT``, ``uT`` (the default) and ``G``; ``None`` sets no limit. The
excitation and refocusing modules lengthen a pulse that would exceed
:data:`MAX_B1_DERATE` of it.
Importing pypulseqpp installs these defaults for PyPulseq factories.
Constructing Opts alone does not change the shared default; use
set_as_default or reset_default.
Examples
--------
>>> import pypulseqpp as pp
>>> system = pp.Opts(max_grad=40, grad_unit="mT/m", max_slew=150, slew_unit="T/m/s")
>>> system.max_grad
1703040.0
>>> system.grad_raster_time, system.rf_raster_time
(2e-05, 2e-06)
>>> round(pp.Opts(max_b1=11.2).max_b1, 1), pp.Opts().max_b1
(476.9, None)
"""
def __init__(
self,
adc_dead_time: float | None = 0.0,
adc_raster_time: float | None = 2e-6,
block_duration_raster: float | None = 20e-6,
gamma: float | None = None,
grad_raster_time: float | None = 20e-6,
grad_unit: str = "Hz/m",
max_grad: float | None = None,
max_slew: float | None = None,
rf_dead_time: float | None = 0.0,
rf_raster_time: float | None = 2e-6,
rf_ringdown_time: float | None = 0.0,
adc_samples_limit: int | None = None,
adc_samples_divisor: int | None = None,
rise_time: float | None = None,
slew_unit: str = "Hz/m/s",
B0: float | None = None,
max_b1: float | None = None,
b1_unit: str = "uT",
) -> None:
# Every raster is passed on explicitly rather than left None, which
# upstream would fill from the shared default -- and the shared
# default is what this class is being constructed to become.
super().__init__(
adc_dead_time=adc_dead_time,
adc_raster_time=adc_raster_time,
block_duration_raster=block_duration_raster,
gamma=gamma,
grad_raster_time=grad_raster_time,
grad_unit=grad_unit,
max_grad=max_grad,
max_slew=max_slew,
rf_dead_time=rf_dead_time,
rf_raster_time=rf_raster_time,
rf_ringdown_time=rf_ringdown_time,
adc_samples_limit=adc_samples_limit,
adc_samples_divisor=adc_samples_divisor,
rise_time=rise_time,
slew_unit=slew_unit,
B0=B0,
)
self.max_b1 = None if max_b1 is None else _b1_to_hz(max_b1, b1_unit, self.gamma)
[docs]
@classmethod
def reset_default(cls) -> None:
"""Install a fresh vendor-neutral system as the shared default."""
cls().set_as_default()
Opts.reset_default()
[docs]
def default_system(system: _pp.Opts | None) -> _pp.Opts:
"""Return ``system``, or the shared default system when it is ``None``.
Parameters
----------
system : Opts or None
The system limits a caller prescribed, if any.
Returns
-------
Opts
``system`` itself, or `Opts.default`.
Examples
--------
>>> import pypulseqpp as pp
>>> pp.default_system(None) is pp.Opts.default
True
>>> system = pp.Opts()
>>> pp.default_system(system) is system
True
"""
return _pp.Opts.default if system is None else system
#: Fraction of the gradient amplitude limit a designed waveform may reach.
MAX_GRAD_DERATE = 0.9
#: Fraction of the slew-rate limit a designed waveform may reach.
MAX_SLEW_DERATE = 0.9
#: Fraction of the peak-B1 limit a designed pulse may reach.
MAX_B1_DERATE = 0.9
[docs]
def apply_system_derates(
opts: _pp.Opts,
*,
grad_derate: float = MAX_GRAD_DERATE,
slew_derate: float = MAX_SLEW_DERATE,
b1_derate: float = MAX_B1_DERATE,
) -> _pp.Opts:
"""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 :func:`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
-------
Opts
The derated copy.
See Also
--------
cap_system : the same copy-not-mutate contract, for an absolute ceiling.
Notes
-----
The default fractions, :data:`MAX_GRAD_DERATE` and
:data:`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. :data:`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
"""
derated = _copy.copy(opts)
fractions = {"max_grad": grad_derate, "max_slew": slew_derate}
if getattr(opts, "max_b1", None) is not None:
fractions["max_b1"] = b1_derate
for name, fraction in fractions.items():
base = f"_base_{name}"
if not hasattr(derated, base):
setattr(derated, base, float(getattr(opts, name)))
value = getattr(derated, base) * float(fraction)
setattr(derated, name, min(value, getattr(derated, f"_ceiling_{name}", value)))
return derated
def b1_design_limit(opts: _pp.Opts) -> float | None:
"""Return the peak B1 a pulse is designed to (Hz), with the B1 derate applied once.
A system :func:`apply_system_derates` has derated already gives its
``max_b1``; any other gives :data:`MAX_B1_DERATE` of it. ``None`` when
the system has no ``max_b1``, a plain ``pypulseq.Opts`` among them.
Parameters
----------
opts : Opts
System limits.
Returns
-------
float or None
The peak a designed pulse may reach (Hz), or ``None`` for no limit.
Examples
--------
>>> import pypulseqpp as pp
>>> system = pp.Opts(max_b1=11.2)
>>> from pypulseqpp._opts import b1_design_limit
>>> b1_design_limit(system) == b1_design_limit(pp.apply_system_derates(system))
True
>>> round(b1_design_limit(system) / system.gamma * 1e6, 2)
10.08
"""
limit = getattr(opts, "max_b1", None)
if limit is None:
return None
if hasattr(opts, "_base_max_b1"):
return float(limit)
return MAX_B1_DERATE * float(limit)
[docs]
def cap_system(
opts: _pp.Opts,
*,
max_grad: float | None = None,
max_slew: float | None = None,
grad_unit: str = "mT/m",
slew_unit: str = "T/m/s",
max_b1: float | None = None,
b1_unit: str = "uT",
) -> _pp.Opts:
"""Return a copy with gradient, slew and RF limits lowered to the specified ceilings.
Parameters
----------
opts : Opts
System limits. Not modified.
max_grad : float, default=None
Gradient amplitude ceiling, in ``grad_unit``; the limit is unchanged
when None or already lower.
max_slew : float, default=None
Slew-rate ceiling, in ``slew_unit``; as ``max_grad``.
grad_unit : str, default='mT/m'
Unit of ``max_grad``.
slew_unit : str, default='T/m/s'
Unit of ``max_slew``.
max_b1 : float, default=None
Peak RF amplitude ceiling, in ``b1_unit``; as ``max_grad``. A system
with no RF limit takes it.
b1_unit : str, default='uT'
Unit of ``max_b1``: ``Hz`` (gamma B1), ``T``, ``mT``, ``uT`` or ``G``.
Returns
-------
Opts
The capped copy.
Notes
-----
On a system :func:`apply_system_derates` has derated, a limit becomes the
lower of the derated limit and the ceiling, and stays so when the copy is
derated again: the margin is taken from the system's limit, not from the
ceiling.
Examples
--------
>>> import pypulseqpp as pp
>>> from pypulseq.convert import convert
>>> system = pp.Opts(max_grad=80, grad_unit="mT/m", max_slew=200, slew_unit="T/m/s")
>>> capped = pp.cap_system(system, max_grad=40, max_slew=150)
>>> capped is system
False
>>> round(convert(from_value=capped.max_grad, from_unit="Hz/m", to_unit="mT/m", gamma=capped.gamma))
40
"""
capped = _copy.copy(opts)
ceilings = {}
if max_grad is not None:
ceilings["max_grad"] = _convert(
from_value=float(max_grad),
from_unit=grad_unit,
to_unit="Hz/m",
gamma=opts.gamma,
)
if max_slew is not None:
ceilings["max_slew"] = _convert(
from_value=float(max_slew),
from_unit=slew_unit,
to_unit="Hz/m/s",
gamma=opts.gamma,
)
if max_b1 is not None:
ceilings["max_b1"] = _b1_to_hz(max_b1, b1_unit, opts.gamma)
for name, ceiling in ceilings.items():
held = getattr(opts, name, None)
setattr(capped, name, ceiling if held is None else min(float(held), ceiling))
# A derated limit keeps its base; the ceiling is kept beside it, so
# derating again leaves the cap in place.
if hasattr(capped, f"_base_{name}"):
kept = getattr(capped, f"_ceiling_{name}", ceiling)
setattr(capped, f"_ceiling_{name}", min(kept, ceiling))
return capped