Source code for pypulseqpp.sequences.excitation._base

"""RF-module simulation and pulse-centre timing."""

from __future__ import annotations

__all__ = [
    "ADIABATICITY_FLOOR",
    "ADIABATIC_MAX_STRETCH",
    "RfModule",
    "adiabatic_fitted",
    "b1_fitted",
    "held_sweep",
    "rf_reference",
    "selective_slr",
]

from typing import Any

import numpy as np

import pypulseqpp as pp

from ..._adiabatic import HYPSEC_BETA, HYPSEC_MU
from ..._opts import b1_design_limit
from .._module import SequenceModule


def b1_fitted(
    system: Any, duration_s: float, make: Any, *, raster: float | None = None
) -> tuple[float, Any]:
    """Return a duration from ``duration_s`` up at which a pulse fits the derated ``system.max_b1``, and the pulse.

    The pulse is held to :data:`~pypulseqpp.MAX_B1_DERATE` of ``max_b1``, or
    to ``max_b1`` itself on a system :func:`~pypulseqpp.apply_system_derates`
    has derated, so the margin is taken once. The flip angle and
    time-bandwidth product are ``make``'s, so the envelope keeps its shape and
    its peak falls as the duration grows. A pulse whose peak exceeds the limit
    is designed again at its duration times the ratio of its peak to the
    limit, rounded up to ``raster``, until it fits. A system without a
    ``max_b1``, a plain ``pypulseq.Opts`` among them, or with the pulse
    already within the limit, takes ``duration_s`` and the pulse as designed.

    Parameters
    ----------
    system : pypulseqpp.Opts
        System limits; ``max_b1`` is the transmit chain's peak RF amplitude
        (Hz), ``None`` or absent for none.
    duration_s : float
        Duration the pulse is designed at when it fits (s).
    make : callable
        ``make(duration)`` designs the events at ``duration`` (s), the RF event
        alone or first in a tuple.
    raster : float, default=None
        Raster a lengthened duration is rounded up to (s);
        ``system.grad_raster_time`` when ``None``.

    Returns
    -------
    tuple
        ``(duration, events)``: the duration designed at (s) and what
        ``make`` returned for it.

    Raises
    ------
    ValueError
        If the pulse still exceeds the limit after four redesigns.

    Examples
    --------
    A 180 degree hard pulse of 1 ms peaks at 500 Hz, 11.7 uT; under a 5 uT
    limit it is held to 4.5 uT, lengthened by the ratio to the next gradient
    raster:

    >>> import pypulseqpp as pp
    >>> from pypulseqpp.sequences.excitation._base import b1_fitted
    >>> system = pp.Opts(max_b1=5.0)
    >>> make = lambda d: pp.make_block_pulse(3.14159, duration=d, system=system)
    >>> duration, rf = b1_fitted(system, 1e-3, make)
    >>> peak_ut = float(abs(rf.signal).max()) / system.gamma * 1e6
    >>> round(duration * 1e3, 2), round(peak_ut, 2)
    (2.62, 4.48)
    >>> b1_fitted(pp.Opts(), 1e-3, make)[0]
    0.001
    """
    limit = b1_design_limit(system)
    events = make(duration_s)
    if limit is None:
        return duration_s, events
    step = float(system.grad_raster_time if raster is None else raster)
    duration = duration_s
    for attempt in range(5):
        rf = events[0] if isinstance(events, tuple) else events
        peak = float(np.abs(np.asarray(rf.signal)).max())
        if peak <= limit * (1.0 + 1e-6):
            return duration, events
        if attempt == 4:
            break
        duration = float(np.ceil(duration * peak / limit / step - 1e-9) * step)
        events = make(duration)
    raise ValueError(
        f"the pulse peaks at {peak:.0f} Hz at {duration * 1e3:.2f} ms, above the "
        f"{limit:.0f} Hz a pulse is designed to"
    )


#: Most an adiabatic pulse is lengthened past its design duration, as a factor.
ADIABATIC_MAX_STRETCH = 2.0
#: Least fraction of its design adiabaticity an adiabatic pulse is lowered to.
ADIABATICITY_FLOOR = 0.75


def held_sweep(pulse_type: str, stretch: float) -> dict[str, float]:
    """Return the :func:`~pypulseqpp.make_adiabatic_pulse` keywords that keep a sweep's bandwidth over ``stretch`` times its duration.

    A hyperbolic secant sweeps ``mu * beta`` (rad/s) over an envelope
    ``sech(beta t)``: ``beta`` falls and ``mu`` rises by ``stretch``, so the
    sweep and the envelope's truncation are kept. The other sweeps are
    defined in time normalised to the duration and need nothing.

    Parameters
    ----------
    pulse_type : str
        Sweep family, as :func:`~pypulseqpp.make_adiabatic_pulse` names them.
    stretch : float
        Duration over the design duration.

    Returns
    -------
    dict
        ``beta`` and ``mu`` for ``"hypsec"``, empty otherwise.

    Examples
    --------
    >>> from pypulseqpp.sequences.excitation._base import held_sweep
    >>> held_sweep("hypsec", 2.0)
    {'beta': 400.0, 'mu': 9.8}
    >>> held_sweep("wurst", 2.0)
    {}
    """
    if pulse_type != "hypsec":
        return {}
    return {"beta": HYPSEC_BETA / stretch, "mu": HYPSEC_MU * stretch}


def adiabatic_fitted(
    system: Any,
    duration_s: float,
    adiabaticity: float,
    make: Any,
    *,
    raster: float | None = None,
) -> tuple[float, float, Any]:
    """Return a duration and adiabaticity at which an adiabatic pulse fits the derated ``system.max_b1``, and the pulse.

    The limit is :func:`b1_fitted`'s. At a fixed swept bandwidth the peak
    meeting ``adiabaticity`` at the sweep's centre falls as
    ``sqrt(adiabaticity / duration)``, so a pulse above the limit is first
    designed again at its duration times the square of its peak's ratio to the
    limit, rounded up to ``raster``, which holds its adiabaticity, its band
    and its response to B1. Past :data:`ADIABATIC_MAX_STRETCH` times
    ``duration_s`` the duration stays there and the adiabaticity is lowered
    by the square of the remaining ratio, to no less than
    :data:`ADIABATICITY_FLOOR` of ``adiabaticity``. A system without a
    ``max_b1``, or a pulse within the limit, takes ``duration_s``,
    ``adiabaticity`` and the pulse as designed.

    Parameters
    ----------
    system : pypulseqpp.Opts
        System limits; ``max_b1`` is the transmit chain's peak RF amplitude
        (Hz), ``None`` or absent for none.
    duration_s : float
        Duration the pulse is designed at when it fits (s).
    adiabaticity : float
        Sweep-rate margin over the adiabatic condition the pulse is designed
        at when it fits.
    make : callable
        ``make(duration, adiabaticity)`` designs the events at ``duration``
        (s) with the bandwidth swept at ``duration_s`` (see
        :func:`held_sweep`), the RF event alone or first in a tuple.
    raster : float, default=None
        Raster a lengthened duration is rounded up to (s);
        ``system.grad_raster_time`` when ``None``.

    Returns
    -------
    tuple
        ``(duration, adiabaticity, events)``: what the pulse was designed at
        and what ``make`` returned for it.

    Raises
    ------
    ValueError
        If the pulse exceeds the limit at :data:`ADIABATIC_MAX_STRETCH` times
        its duration and :data:`ADIABATICITY_FLOOR` of its adiabaticity.

    Examples
    --------
    The 10 ms hyperbolic-secant inversion at adiabaticity 4 peaks at 13.2 uT;
    under an 11.2 uT limit, held to 10.08 uT, it lasts 17.26 ms at the same
    adiabaticity:

    >>> import pypulseqpp as pp
    >>> from pypulseqpp.sequences.excitation._base import adiabatic_fitted, held_sweep
    >>> system = pp.Opts(max_b1=11.2)
    >>> def make(duration, adiabaticity):
    ...     return pp.make_adiabatic_pulse(
    ...         "hypsec", adiabaticity=adiabaticity, duration=duration, system=system,
    ...         **held_sweep("hypsec", duration / 10e-3),
    ...     )
    >>> duration, adiabaticity, rf = adiabatic_fitted(system, 10e-3, 4, make)
    >>> round(duration * 1e3, 2), adiabaticity
    (17.26, 4)

    Under 9.5 uT, held to 8.55 uT, twice the duration is not enough and the
    adiabaticity falls:

    >>> system = pp.Opts(max_b1=9.5)
    >>> duration, adiabaticity, rf = adiabatic_fitted(system, 10e-3, 4, make)
    >>> round(duration * 1e3, 2), round(adiabaticity, 2)
    (20.0, 3.34)
    """
    limit = b1_design_limit(system)
    events = make(duration_s, adiabaticity)
    if limit is None:
        return duration_s, adiabaticity, events
    step = float(system.grad_raster_time if raster is None else raster)
    ceiling = float(np.floor(ADIABATIC_MAX_STRETCH * duration_s / step + 1e-9) * step)
    floor = ADIABATICITY_FLOOR * adiabaticity
    duration, margin = duration_s, adiabaticity
    for attempt in range(5):
        rf = events[0] if isinstance(events, tuple) else events
        peak = float(np.abs(np.asarray(rf.signal)).max())
        if peak <= limit:
            return duration, margin, events
        if attempt == 4:
            break
        wanted = float(np.ceil(duration * (peak / limit) ** 2 / step - 1e-9) * step)
        if wanted <= ceiling:
            duration = wanted
        else:
            # The adiabaticity that brings the peak at the ceiling to just
            # under the limit; the sampled peak follows the square root of
            # the duration to within a part in 1e6.
            margin *= (1.0 - 1e-6) * (limit / peak) ** 2 * ceiling / duration
            duration = ceiling
            if margin < floor * (1.0 - 1e-9):
                raise ValueError(
                    f"the adiabatic pulse fits the {limit:.0f} Hz a pulse is "
                    f"designed to only at adiabaticity {margin:.2f} over "
                    f"{ADIABATIC_MAX_STRETCH:g} times its {duration_s * 1e3:.2f} ms, "
                    f"below {ADIABATICITY_FLOOR:g} of its {adiabaticity:g}"
                )
        events = make(duration, margin)
    raise ValueError(
        f"the adiabatic pulse peaks at {peak:.0f} Hz at {duration * 1e3:.2f} ms, "
        f"above the {limit:.0f} Hz a pulse is designed to"
    )


def rf_reference(rf: Any) -> float:
    """Return the RF pulse centre from the start of its block (s).

    This is ``delay + center``.

    Parameters
    ----------
    rf : object
        An RF event.

    Returns
    -------
    float
        Delay plus centre time of the pulse (s).
    """
    return float(rf.delay) + float(rf.center)


def selective_slr(flip_angle_deg: float, thickness_m: float, **design: Any) -> tuple:
    """Design an SLR pulse and the gradients that select ``thickness_m``.

    The thickness a pulse selects is its measured bandwidth,
    :func:`pypulseqpp.calc_rf_bandwidth`, over the selection plateau.
    :func:`pypulseqpp.make_slr_pulse` sizes the plateau for the nominal
    bandwidth, the time-bandwidth product over the duration, from which the
    designed envelope's spectrum departs; the plateau is sized again for the
    measured bandwidth.

    Parameters
    ----------
    flip_angle_deg : float
        Flip angle (degrees).
    thickness_m : float
        Thickness to select, from the pulse's measured bandwidth (m).
    **design
        The rest of :func:`pypulseqpp.make_slr_pulse`'s arguments, without
        ``slice_thickness`` and ``return_gz``.

    Returns
    -------
    tuple
        ``(rf, gz, gz_reph)``, as :func:`pypulseqpp.make_slr_pulse` returns
        them under ``return_gz``.
    """
    flip = np.deg2rad(flip_angle_deg)
    design.setdefault("delay", design["system"].rf_dead_time)
    rf, gz, _ = pp.make_slr_pulse(
        flip, slice_thickness=thickness_m, return_gz=True, **design
    )
    nominal = abs(gz.amplitude) * thickness_m
    return pp.make_slr_pulse(
        flip,
        slice_thickness=thickness_m * nominal / pp.calc_rf_bandwidth(rf),
        return_gz=True,
        **design,
    )


[docs] class RfModule(SequenceModule): """Sequence module whose RF pulse can be simulated across off-resonance. Base class of the excitation and preparation modules the package ships. Examples -------- >>> import pypulseqpp.sequences as design >>> import pypulseqpp as pp >>> module = design.SpatialSelectiveExcitation(pp.Opts(), 15.0, 5e-3) >>> isinstance(module, design.RfModule) True >>> mz_z, mz_xy, frequency = module.sim_rf()[:3] >>> mz_xy.shape == frequency.shape True """
[docs] def sim_rf(self, pulse=None, **kwargs): """Simulate this module's pulse across off-resonance. Parameters ---------- pulse : RfEvent, default=None Pulse to simulate; ``None`` takes the first RF event in block order. **kwargs Forwarded to :func:`pypulseqpp.sim_rf` (``rephase_factor``, ``df``, ``bandwidth_multiplier``, ``dt``). Returns ------- tuple MATLAB's six answers: ``mz_z``, ``mz_xy``, the frequency axis, ``ref_eff``, ``mx_xy`` and ``my_xy``. Examples -------- >>> import pypulseqpp.sequences as design >>> import pypulseqpp as pp >>> pulse = design.SpatialSelectiveExcitation(pp.Opts(), 15.0, 5e-3) >>> mz_z, mz_xy, frequency = pulse.sim_rf()[:3] >>> mz_z.shape == frequency.shape True """ import pypulseqpp as pp if pulse is None: pulse = next( event for block in self.blocks for event in block if getattr(event, "type", None) == "rf" ) return pp.sim_rf(pulse, **kwargs)