pulseqzero 0.1.0__py3-none-any.whl

pulseqzero/adapter/pulses.py

@@ -0,0 +1,253 @@
+from dataclasses import dataclass
+from ..adapter import Opts, make_delay, make_trapezoid, calc_duration
+
+
+def make_arbitrary_rf(
+    signal,
+    flip_angle,
+    bandwidth=0,
+    delay=0,
+    dwell=None,
+    freq_offset=0,
+    no_signal_scaling=False,
+    max_grad=0,
+    max_slew=0,
+    phase_offset=0,
+    return_delay=False,
+    return_gz=False,
+    slice_thickness=0,
+    system=None,
+    time_bw_product=0,
+    use=str(),
+):
+    if system is None:
+        system = Opts.default
+    if dwell is None:
+        dwell = system.rf_raster_time
+    delay = max(delay, system.rf_dead_time)
+
+    duration = len(signal) * dwell
+
+    rf = Pulse(
+        flip_angle,
+        duration,
+        freq_offset,
+        phase_offset,
+        delay,
+        system.rf_ringdown_time
+    )
+    ret_val = (rf, )
+
+    if return_gz:
+        if max_grad is None:
+            max_grad = system.max_grad
+        if max_slew is None:
+            max_slew = system.max_slew
+
+        if bandwidth is None:
+            bandwidth = time_bw_product / duration
+        area = bandwidth / slice_thickness * duration
+
+        gz = make_trapezoid(
+            "z", system=system,
+            flat_area=area, flat_time=duration
+        )
+
+        if rf.delay > gz.rise_time:
+            gz.delay = rf.delay - gz.rise_time
+        if rf.delay < gz.rise_time + gz.delay:
+            rf.delay = gz.rise_time + gz.delay
+
+        ret_val = (*ret_val, gz)
+
+    if return_delay and rf.ringdown_time > 0:
+        delay = make_delay(calc_duration(rf) + rf.ringdown_time)
+        ret_val = (*ret_val, delay)
+
+    return ret_val
+
+
+def make_block_pulse(
+    flip_angle,
+    delay=0,
+    duration=None,
+    bandwidth=None,
+    time_bw_product=0.25,
+    freq_offset=0,
+    phase_offset=0,
+    return_delay=False,
+    system=None,
+    use="",
+):
+    if system is None:
+        system = Opts.default
+    delay = max(delay, system.rf_dead_time)
+
+    if duration is None:
+        if bandwidth is None:
+            duration = 1e-4
+        else:
+            duration = time_bw_product / bandwidth
+    else:
+        assert bandwidth is None
+
+    rf = Pulse(
+        flip_angle,
+        duration,
+        freq_offset,
+        phase_offset,
+        delay,
+        system.rf_ringdown_time
+    )
+
+    if system.rf_dead_time > rf.delay:
+        rf.delay = system.rf_dead_time
+
+    if return_delay:
+        return (rf, make_delay(calc_duration(rf) + system.rf_ringdown_time))
+    else:
+        return rf
+
+
+def make_gauss_pulse(
+    flip_angle,
+    apodization=0,
+    bandwidth=None,
+    center_pos=0.5,
+    delay=0,
+    dwell=0,
+    duration=4e-3,
+    freq_offset=0,
+    max_grad=0,
+    max_slew=0,
+    phase_offset=0,
+    return_gz=False,
+    return_delay=False,
+    slice_thickness=0,
+    system=None,
+    time_bw_product=4,
+    use=""
+):
+    if system is None:
+        system = Opts.default
+    delay = max(delay, system.rf_dead_time)
+
+    rf = Pulse(
+        flip_angle,
+        duration,
+        freq_offset,
+        phase_offset,
+        delay,
+        system.rf_ringdown_time
+    )
+    ret_val = (rf, )
+
+    if return_gz:
+        if max_grad is None:
+            max_grad = system.max_grad
+        if max_slew is None:
+            max_slew = system.max_slew
+
+        if bandwidth is None:
+            bandwidth = time_bw_product / duration
+        area = bandwidth / slice_thickness * duration
+
+        gz = make_trapezoid(
+            "z", system=system,
+            flat_area=area, flat_time=duration
+        )
+        gzr = make_trapezoid(
+            "z", system=system,
+            area=-area * (1 - center_pos) - 0.5 * (gz.area - area)
+        )
+
+        if rf.delay > gz.rise_time:
+            gz.delay = rf.delay - gz.rise_time
+        if rf.delay < gz.rise_time + gz.delay:
+            rf.delay = gz.rise_time + gz.delay
+
+        ret_val = (*ret_val, gz, gzr)
+
+    if return_delay and rf.ringdown_time > 0:
+        delay = make_delay(calc_duration(rf) + rf.ringdown_time)
+        ret_val = (*ret_val, delay)
+
+    return ret_val
+
+
+def make_sinc_pulse(
+    flip_angle,
+    apodization=0,
+    delay=0,
+    duration=4e-3,
+    dwell=0,
+    center_pos=0.5,
+    freq_offset=0,
+    max_grad=None,
+    max_slew=None,
+    phase_offset=0,
+    return_delay=False,
+    return_gz=False,
+    slice_thickness=0,
+    system=None,
+    time_bw_product=4,
+    use=""
+):
+    if system is None:
+        system = Opts.default
+    delay = max(delay, system.rf_dead_time)
+
+    rf = Pulse(
+        flip_angle,
+        duration,
+        freq_offset,
+        phase_offset,
+        delay,
+        system.rf_ringdown_time
+    )
+    ret_val = (rf, )
+
+    if return_gz:
+        if max_grad is None:
+            max_grad = system.max_grad
+        if max_slew is None:
+            max_slew = system.max_slew
+
+        BW = time_bw_product / duration
+        area = BW / slice_thickness * duration
+
+        gz = make_trapezoid(
+            "z", max_grad=max_grad, max_slew=max_slew,
+            flat_time=duration, flat_area=area
+        )
+        gzr = make_trapezoid(
+            "z", max_grad=max_grad, max_slew=max_slew,
+            area=-area * (1 - center_pos) - 0.5 * (gz.area - area)
+        )
+
+        if rf.delay > gz.rise_time:
+            gz.delay = rf.delay - gz.rise_time
+        if rf.delay < gz.rise_time + gz.delay:
+            rf.delay = gz.rise_time + gz.delay
+
+        ret_val = (*ret_val, gz, gzr)
+
+    if return_delay and rf.ringdown_time > 0:
+        delay = make_delay(rf.duration)
+        ret_val = (*ret_val, delay)
+
+    return ret_val
+
+
+@dataclass
+class Pulse:
+    flip_angle: ...
+    shape_dur: ...
+    freq_offset: ...  # ignored by sim
+    phase_offset: ...
+    delay: ...
+    ringdown_time: ...  # important for duration
+
+    @property
+    def duration(self):
+        return self.delay + self.shape_dur + self.ringdown_time

pulseqzero/adapter/seq_convert.py

@@ -0,0 +1,237 @@
+import torch
+import MRzeroCore as mr0
+from ..adapter import calc_duration
+from ..adapter.pulses import Pulse
+from ..adapter.adc import Adc
+from ..adapter.delay import Delay
+from ..adapter.grads import TrapGrad, FreeGrad
+
+
+def convert(pp0) -> mr0.Sequence:
+    seq = []
+
+    for block in pp0.blocks:
+        delay = None
+        adc = None
+        rf = None
+        grad_x = None
+        grad_y = None
+        grad_z = None
+        for ev in block:
+            if isinstance(ev, Delay):
+                assert delay is None
+                delay = ev
+            if isinstance(ev, Adc):
+                assert adc is None
+                adc = ev
+            if isinstance(ev, Pulse):
+                assert rf is None
+                rf = ev
+            if isinstance(ev, (TrapGrad, FreeGrad)):
+                assert ev.channel in ["x", "y", "z"]
+                if ev.channel == "x":
+                    assert grad_x is None
+                    grad_x = ev
+                elif ev.channel == "y":
+                    assert grad_y is None
+                    grad_y = ev
+                elif ev.channel == "z":
+                    assert grad_z is None
+                    grad_z = ev
+
+        if rf:
+            assert delay is None and adc is None
+            seq += parse_pulse(rf, grad_x, grad_y, grad_z)
+        elif adc:
+            assert delay is None
+            seq += parse_adc(adc, grad_x, grad_y, grad_z)
+        else:
+            seq += parse_spoiler(delay, grad_x, grad_y, grad_z)
+
+    reps = []
+    rep = []
+    for ev in seq:
+        if isinstance(ev, TmpPulse):
+            rep = []
+            reps.append(rep)
+        rep.append(ev)
+
+    seq = mr0.Sequence()
+    for rep_in in reps:
+        event_count = 0
+        for ev in rep_in:
+            if isinstance(ev, TmpAdc):
+                event_count += len(ev.event_time)
+            else:
+                event_count += 1
+
+        rep_out = seq.new_rep(event_count)
+        rep_out.pulse.angle = torch.as_tensor(rep_in[0].angle)
+        rep_out.pulse.phase = torch.as_tensor(rep_in[0].phase)
+        if rep_out.pulse.angle > 100 * torch.pi / 180:
+            rep_out.pulse.usage = mr0.PulseUsage.REFOC
+        else:
+            rep_out.pulse.usage = mr0.PulseUsage.EXCIT
+
+        i = 0
+        for ev in rep_in[1:]:
+            if isinstance(ev, TmpSpoiler):
+                rep_out.event_time[i] = ev.duration
+                rep_out.gradm[i, :] = ev.gradm
+                i += 1
+            else:
+                assert isinstance(ev, TmpAdc)
+                num = len(ev.event_time)
+                rep_out.event_time[i:i+num] = torch.as_tensor(ev.event_time)
+                rep_out.gradm[i:i+num, :] = torch.as_tensor(ev.gradm)
+                rep_out.adc_phase[i:i+num] = torch.pi / 2 - ev.phase
+                rep_out.adc_usage[i:i+num] = 1
+                i += num
+
+    seq.normalized_grads = False
+    return seq
+
+
+class TmpPulse:
+    def __init__(self, angle, phase) -> None:
+        self.angle = angle
+        self.phase = phase
+
+    def __repr__(self) -> str:
+        from math import pi
+        return f"Pulse(angle={self.angle * 180 / pi}°, phase={self.phase * 180 / pi}°)"
+
+
+class TmpSpoiler:
+    def __init__(self, duration, gx, gy, gz) -> None:
+        self.duration = torch.as_tensor(duration)
+        self.gradm = torch.stack([
+            torch.as_tensor(gx),
+            torch.as_tensor(gy),
+            torch.as_tensor(gz)
+        ])
+
+    def __repr__(self) -> str:
+        return f"Spoiler(gradm={self.gradm}, duration={self.duration})"
+
+
+class TmpAdc:
+    def __init__(self, event_time, gradm, phase) -> None:
+        self.event_time = event_time
+        self.gradm = gradm
+        self.phase = phase
+
+    def __repr__(self) -> str:
+        from math import pi
+        return f"Adc(phase={self.phase * 180 / pi}°, total_gradm={self.gradm.sum(0)}, total_time={self.event_time.sum(0)})"
+
+
+def parse_pulse(rf, grad_x, grad_y, grad_z) -> tuple[TmpSpoiler, TmpPulse, TmpSpoiler]:
+    t = rf.delay + rf.shape_dur / 2
+    duration = calc_duration(rf, grad_x, grad_y, grad_z)
+
+    gx1 = gx2 = gy1 = gy2 = gz1 = gz2 = 0.0
+    if grad_x:
+        gx1, gx2 = split_gradm(grad_x, t)
+    if grad_y:
+        gy1, gy2 = split_gradm(grad_y, t)
+    if grad_z:
+        gz1, gz2 = split_gradm(grad_z, t)
+
+    return (
+        TmpSpoiler(t, gx1, gy1, gz1),
+        TmpPulse(rf.flip_angle, rf.phase_offset),
+        TmpSpoiler(duration - t, gx2, gy2, gz2)
+    )
+
+
+def parse_spoiler(delay, grad_x, grad_y, grad_z) -> tuple[TmpSpoiler]:
+    duration = calc_duration(delay, grad_x, grad_y, grad_z)
+    gx = grad_x.area if grad_x is not None else 0.0
+    gy = grad_y.area if grad_y is not None else 0.0
+    gz = grad_z.area if grad_z is not None else 0.0
+    return (TmpSpoiler(duration, gx, gy, gz), )
+
+
+def parse_adc(adc: Adc, grad_x, grad_y, grad_z) -> tuple[TmpAdc, TmpSpoiler]:
+    duration = calc_duration(adc, grad_x, grad_y, grad_z)
+    time = torch.cat([
+        torch.as_tensor(0.0).view((1, )),
+        adc.delay + torch.arange(adc.num_samples) * adc.dwell,
+        torch.as_tensor(duration).view((1, ))
+    ])
+
+    gradm = torch.zeros((adc.num_samples + 2, 3))
+    if grad_x:
+        gradm[:, 0] = torch.vmap(lambda t: integrate(grad_x, t))(time)
+    if grad_y:
+        gradm[:, 1] = torch.vmap(lambda t: integrate(grad_y, t))(time)
+    if grad_z:
+        gradm[:, 2] = torch.vmap(lambda t: integrate(grad_z, t))(time)
+
+    event_time = torch.diff(time)
+    gradm = torch.diff(gradm, dim=0)
+    return (
+        TmpAdc(event_time[:-1], gradm[:-1, :], adc.phase_offset),
+        TmpSpoiler(event_time[-1], gradm[-1, 0], gradm[-1, 1], gradm[-1, 2])
+    )
+
+
+def split_gradm(grad, t):
+    before = integrate(grad, t)
+    total = integrate(grad, 1e9)  # Infinity produces 0*inf = NaNs internally
+    return (before, total - before)
+
+
+def integrate(grad, t):
+    if isinstance(grad, TrapGrad):
+        # heaviside could be replaced with error function for differentiability
+        def h(x):
+            return torch.heaviside(torch.as_tensor(x), torch.tensor(0.5))
+
+        # https://www.desmos.com/calculator/0q5co02ecm
+
+        d = grad.delay
+        t1 = grad.rise_time
+        t2 = grad.flat_time
+        t3 = grad.fall_time
+        T1 = d + t1
+        T12 = d + t1 + t2
+        T123 = d + t1 + t2 + t3
+
+        # Trapezoid, could be provided as derivative:
+        # f1 = h(t - d) * h(T1 - t) * (t - d) / t1
+        # f2 = h(t - T1) * h(T12 - t)
+        # f3 = h(t - T12) * h(T123 - t) * (T123 - t) / t3
+        # f = grad.amplitude * (f1 + f2 + f3)
+
+        F_inf = t1 / 2 + t2 + t3 / 2
+        F1 = h(t - d) * h(T1 - t) * 0.5 * (t - d)**2 / t1
+        F2 = h(t - T1) * h(T12 - t) * (t1 / 2 + t - T1)
+        F3 = h(t - T12) * h(T123 - t) * (F_inf - 0.5 * (T123 - t)**2 / t3)
+        F = grad.amplitude * (F1 + F2 + F3 + h(t - T123) * F_inf)
+
+        return F
+    elif isinstance(grad, FreeGrad):
+        # To stay differentiable, we don't want dynamic indexing, but instead
+        # calculate, how much of every segment of the gradient contributes
+        # https://www.desmos.com/calculator/j2vopzhb2z
+
+        # Start and end time point and amplitude of all line segments
+        t1 = torch.as_tensor(grad.times[:-1])
+        t2 = torch.as_tensor(grad.times[1:])
+        c1 = torch.as_tensor(grad.amplitudes[:-1])
+        c2 = torch.as_tensor(grad.amplitudes[1:])
+
+        # This is how much of every segment contributes, clamped to [0, width]
+        t_rel = torch.clamp(t - t1, 0 * t1, t2 - t1)
+        # The amplitude of the segment at t, will be clamped to the amplitude
+        # of the right point for segments before t and the left point for
+        # segments after; only one segment where t lies in will be interpolated
+        c_end = c1 + t_rel / (t2 - t1) * (c2 - c1)
+        # For integration, we calculate the area of the rectangle with the
+        # average height of the left and right side of the actual shape
+        c_avg = 0.5 * (c1 + c_end)
+        return (t_rel * c_avg).sum()
+    else:
+        raise NotImplementedError

pulseqzero/adapter/sequence.py

@@ -0,0 +1,66 @@
+from copy import copy, deepcopy
+import MRzeroCore
+from ..adapter import calc_duration
+from . import seq_convert
+
+
+class Sequence:
+    def __init__(self, system=None, use_block_cache=True):
+        self.definitions = {}
+        self.blocks = []
+
+    def __str__(self):
+        return f"mr0 sequence adapter; ({len(self.blocks)}) blocks"
+
+    def add_block(self, *args):
+        self.blocks.append([copy(arg) for arg in args])
+
+    def check_timing(self):
+        return (True, [])
+
+    def duration(self):
+        duration = sum(calc_duration(*block) for block in self.blocks)
+        num_blocks = len(self.blocks)
+        event_count = len(filter(lambda b: len(b) > 0, self.blocks))
+        return duration, num_blocks, event_count
+
+    def get_definition(self, key):
+        if key in self.definitions:
+            return self.definitions[key]
+        else:
+            return ""
+
+    def plot(
+        self,
+        label=str(),
+        show_blocks=False,
+        save=False,
+        time_range=(0, float("inf")),
+        time_disp="s",
+        grad_disp="kHz/m",
+        plot_now=True
+    ):
+        pass
+
+    def remove_duplicates(self, in_place=False):
+        if in_place:
+            return self
+        else:
+            return deepcopy(self)
+
+    def set_definition(self, key, value):
+        self.definitions[key] = value
+
+    def test_report(self):
+        return "No report generated in mr0 mode"
+
+    def write(self, name, create_signature, remove_duplicates):
+        if create_signature:
+            return ""
+        else:
+            return None
+
+    # What we do all of this for:
+    # To intercept pulseq calls and build an MR-zero sequence from it
+    def to_mr0(self) -> MRzeroCore.Sequence:
+        return seq_convert.convert(self)