pulserver 0.1.0__py3-none-any.whl

pulserver/__init__.py

@@ -0,0 +1,17 @@
+"""Pulseforge public API."""
+
+__all__ = []
+
+from pypulseq import Opts  # noqa
+
+from . import blocks  # noqa
+from . import plan  # noqa
+from . import sequences  # noqa
+
+from . import _server  # noqa
+
+from ._core import Sequence  # noqa
+from ._core import SequenceParams  # noqa
+
+__all__.append("Opts")
+__all__.extend(["Sequence", "SequenceParams"])

pulserver/_apps/SPGR2D.py

@@ -0,0 +1,206 @@
+"""2D Spoiled Gradient Echo sequence."""
+
+__all__ = ["SPGR2D"]
+
+from collections.abc import Iterable
+
+
+import numpy as np
+import pypulseq as pp
+
+
+from pulserver import Sequence
+from pulserver.plan import RfPhaseCycle
+
+
+def SPGR2D(
+    fov: Iterable[float],
+    slice_thickness: float,
+    npix: Iterable[int],
+    nslices: int,
+    alpha: float,
+    rectime: float,
+    max_grad: float,
+    max_slew: float,
+    raster_time: float,
+    slice_spacing: float = 0.0,
+    seqformat: str | bool = "bytes",
+):
+    """
+    Generate a 2D Spoiled Gradient Recalled Echo (SPGR) pulse sequence.
+
+    This function designs a 2D SPGR sequence based on the provided field of view (FOV), matrix size,
+    number of slices, slice thickness and spacing, flip angle, recovery time,
+    and hardware constraints such as maximum gradient amplitude and slew rate.
+    The output can be formatted in different sequence file formats if specified.
+
+    Parameters
+    ----------
+    fov : Iterable[float]
+        Field of view along each spatial dimension [fov_x, fov_y] in mm.
+        If scalar, assume squared fov.
+    slice_thickness : float)
+        Slice thickness in mm.
+    npix : Iterable[int]
+        Number of voxels along each spatial dimension [nx, ny] (matrix size).
+        If scalar, assume squared matrix size.
+    nslices : int
+        Number of slices.
+    alpha : float
+        Flip angle in degrees.
+    rectime : float
+        Recovery time after spoiling in ms.
+    max_grad : float
+        Maximum gradient amplitude in mT/m.
+    max_slew : float
+        Maximum gradient slew rate in T/m/s.
+    raster_time : float
+        Waveform raster time in seconds (the time between successive gradient samples).
+    slice_spacing : float, optional
+        Additional slice spacing in mm. The default is 0.0 (contiguous slices).
+    seqformat : str or bool, optional
+        Output sequence format. If a string is provided, it specifies the desired output format (e.g., 'pulseq', 'bytes').
+        If False, the sequence is returned as an internal object. Default is False.
+
+    Returns
+    -------
+    seq : object or dict
+        The generated SPGR sequence. If `seqformat` is a string, the sequence is returned in the specified format.
+        If `seqformat` is False, the sequence is returned as an internal representation.
+
+    Notes
+    -----
+    - This function is designed to work within the constraints of MRI scanners, taking into account the physical limits
+      on gradient amplitude and slew rates.
+    - The flip angle (`alpha`) controls the excitation of spins and directly impacts the signal-to-noise ratio (SNR) and contrast.
+
+    Examples
+    --------
+    Generate a 2D SPGR sequence for a single 5 mm thick slice and 240x240 mm FOV, 256x256 matrix size,
+    15-degree flip angle, 5s recovery time and hardware limits 4mT/m, 150T/m/s, 4e-6 s raster time as:
+
+    >>> from pulseforge import SPGR2D
+    >>> SPGR2D(240.0, 5.0, 256, 1, 15.0, 5.0, 40, 150, 4e-6)
+
+    Generate the same sequence and export it in bytes format:
+
+    >>> SPGR2D(240.0, 5.0, 256, 1, 15.0, 5.0, 40, 150, 4e-6, format='bytes')
+
+    """
+    # RF specs
+    rf_spoiling_inc = 117.0  # RF spoiling increment
+
+    # initialize system limits
+    system = pp.Opts(
+        max_grad=max_grad,
+        grad_unit="mT/m",
+        max_slew=max_slew,
+        slew_unit="T/m/s",
+        grad_raster_time=raster_time,
+        rf_raster_time=raster_time,
+    )
+
+    # initialize sequence
+    seq = Sequence(system=system, format=seqformat)
+
+    # initialize prescription
+    fov, slice_thickness, slice_spacing = (
+        fov * 1e-3,
+        slice_thickness * 1e-3,
+        slice_spacing * 1e-3,
+    )
+    slice_spacing += slice_thickness
+
+    if np.isscalar(npix):
+        Nx, Ny, Nz = npix, npix, nslices  # in-plane resolution, slice thickness
+    else:
+        Nx, Ny, Nz = npix[0], npix[1], nslices  # in-plane resolution, slice thickness
+
+    # initialize event events
+    # RF pulse
+    rf, gss, _ = pp.make_sinc_pulse(
+        flip_angle=np.deg2rad(alpha),
+        duration=3e-3,
+        slice_thickness=slice_thickness,
+        apodization=0.42,
+        time_bw_product=4,
+        system=system,
+        return_gz=True,
+    )
+    gss_reph = pp.make_trapezoid(
+        channel="z", area=-gss.area / 2, duration=1e-3, system=system
+    )
+    seq.register_block(name="excitation", rf=rf, gz=gss)
+    seq.register_block(name="slab_rephasing", gz=gss_reph)
+
+    # readout
+    delta_kx, delta_ky = 1 / fov, 1 / fov
+    g_read = pp.make_trapezoid(
+        channel="x", flat_area=Nx * delta_kx, flat_time=3.2e-3, system=system
+    )
+    adc = pp.make_adc(
+        num_samples=Nx, duration=g_read.flat_time, delay=g_read.rise_time, system=system
+    )
+    seq.register_block("dummy_readout", gx=g_read)
+    seq.register_block("readout", gx=g_read, adc=adc)
+
+    # phase encoding
+    gx_phase = pp.make_trapezoid(
+        channel="x", area=-g_read.area / 2, duration=1e-3, system=system
+    )
+    gy_phase = pp.make_trapezoid(channel="y", area=delta_ky * Ny, system=system)
+    seq.register_block("g_phase", gx=gx_phase, gy=gy_phase)
+
+    # crusher gradient
+    gz_spoil = pp.make_trapezoid(channel="z", area=32 / slice_thickness, system=system)
+    delay = pp.make_delay(rectime)
+    seq.register_block("g_spoil", gz=gz_spoil, delay=delay)
+
+    # phase encoding plan TODO: helper routine
+    pey_steps = ((np.arange(Ny)) - (Ny / 2)) / Ny
+    FOVz = Nz * slice_spacing
+    foff_steps = np.linspace(-FOVz / 2, FOVz / 2, Nz) * gss.amplitude
+    encoding_plan = np.meshgrid(pey_steps, foff_steps, indexing="xy")
+    encoding_plan = [enc.ravel() for enc in encoding_plan]
+
+    # scan duration
+    dummy_scans = 10
+    calib_scans = 10
+    imaging_scans = Ny * nslices
+
+    # generate rf phases
+    rf_phases = RfPhaseCycle(
+        num_pulses=dummy_scans + imaging_scans + calib_scans,
+        phase_increment=rf_spoiling_inc,
+    )
+
+    # construct sequence
+    seq.section(name="ss_prep")
+    for n in range(dummy_scans):
+        rf_phase = rf_phases()
+        seq.add_block("excitation")
+        seq.add_block("slab_rephasing")
+        seq.add_block("g_phase", gy_amp=0.0)
+        seq.add_block("dummy_readout", rf_phase=rf_phase)
+        seq.add_block("g_phase", gy_amp=0.0)
+        seq.add_block("g_spoil")
+
+    seq.section(name="scan_loop")
+    for n in range(imaging_scans + calib_scans):
+        rf_phase = rf_phases()
+
+        if n < calib_scans:
+            rf_freq = 0.0
+            y_amp = 0.0
+        else:
+            rf_freq = encoding_plan[1][n - calib_scans]
+            y_amp = encoding_plan[0][n - calib_scans]
+
+        seq.add_block("excitation", rf_freq=rf_freq)
+        seq.add_block("slab_rephasing")
+        seq.add_block("g_phase", gy_amp=y_amp)
+        seq.add_block("readout", rf_phase=rf_phase, adc_phase=rf_phase)
+        seq.add_block("g_phase", gy_amp=-y_amp)
+        seq.add_block("g_spoil")
+
+    return seq.export()

pulserver/_apps/SPGR3D.py

@@ -0,0 +1,184 @@
+"""3D Spoiled Gradient Echo sequence."""
+
+__all__ = ["SPGR3D"]
+
+from collections.abc import Iterable
+
+
+import numpy as np
+import pypulseq as pp
+
+
+from pulserver import Sequence
+from pulserver.plan import RfPhaseCycle
+
+
+def SPGR3D(
+    fov: Iterable[float],
+    npix: Iterable[int],
+    alpha: float,
+    max_grad: float,
+    max_slew: float,
+    raster_time: float,
+    seqformat: str | bool = "bytes",
+):
+    """
+    Generate a 3D Spoiled Gradient Recalled Echo (SPGR) pulse sequence.
+
+    This function designs a 3D SPGR sequence based on the provided field of view (FOV), matrix size,
+    flip angle, and hardware constraints such as maximum gradient amplitude and slew rate. The output
+    can be formatted in different sequence file formats if specified.
+
+    Parameters
+    ----------
+    fov : Iterable[float]
+        Field of view along each spatial dimension [fov_plane, fov_z] in mm.
+        If scalar, assume cubic fov.
+    npix : Iterable[int]
+        Number of voxels along each spatial dimension [plane_mtx, nz] (matrix size).
+        If scalar, assume cubic matrix size.
+    alpha : float
+        Flip angle in degrees.
+    max_grad : float
+        Maximum gradient amplitude in mT/m.
+    max_slew : float
+        Maximum gradient slew rate in T/m/s.
+    raster_time : float
+        Waveform raster time in seconds (the time between successive gradient samples).
+    seqformat : str or bool, optional
+        Output sequence format. If a string is provided, it specifies the desired output format (e.g., 'pulseq', 'bytes').
+        If False, the sequence is returned as an internal object. Default is False.
+
+    Returns
+    -------
+    seq : object or dict
+        The generated SPGR sequence. If `seqformat` is a string, the sequence is returned in the specified format.
+        If `seqformat` is False, the sequence is returned as an internal representation.
+
+    Notes
+    -----
+    - This function is designed to work within the constraints of MRI scanners, taking into account the physical limits
+      on gradient amplitude and slew rates.
+    - The flip angle (`alpha`) controls the excitation of spins and directly impacts the signal-to-noise ratio (SNR) and contrast.
+
+    Examples
+    --------
+    Generate a 3D SPGR sequence for a 256x256x128 matrix with a 240x240x120 mm FOV, a 15-degree flip angle, and hardware limits:
+
+    >>> from pulseforge import SPGR3D
+    >>> SPGR3D([240, 120], [256, 128], 15, 0.04, 150, 4e-6)
+
+    Generate the same sequence and export it in bytes format:
+
+    >>> SPGR3D([240, 120], [256, 128], 15, 0.04, 150, 4e-6, seqformat='bytes')
+
+    """
+    # RF specs
+    rf_spoiling_inc = 117.0  # RF spoiling increment
+
+    # initialize system limits
+    system = pp.Opts(
+        max_grad=max_grad,
+        grad_unit="mT/m",
+        max_slew=max_slew,
+        slew_unit="T/m/s",
+        grad_raster_time=raster_time,
+        rf_raster_time=raster_time,
+    )
+
+    # initialize sequence
+    seq = Sequence(system=system, format=seqformat)
+
+    # initialize prescription
+    if np.isscalar(fov):
+        fov, slab_thickness = fov * 1e-3, fov * 1e-3  # isotropic
+    else:
+        fov, slab_thickness = (
+            fov[0] * 1e-3,
+            fov[1] * 1e-3,
+        )  # in-plane FOV, slab thickness
+
+    if np.isscalar(npix):
+        Nx, Ny, Nz = npix, npix, npix  # in-plane resolution, slice thickness
+    else:
+        Nx, Ny, Nz = npix[0], npix[0], npix[1]  # in-plane resolution, slice thickness
+
+    # initialize event events
+    # RF pulse
+    rf, gss, _ = pp.make_sinc_pulse(
+        flip_angle=np.deg2rad(alpha),
+        duration=3e-3,
+        slice_thickness=slab_thickness,
+        apodization=0.42,
+        time_bw_product=4,
+        system=system,
+        return_gz=True,
+    )
+    gss_reph = pp.make_trapezoid(
+        channel="z", area=-gss.area / 2, duration=1e-3, system=system
+    )
+    seq.register_block(name="excitation", rf=rf, gz=gss)
+    seq.register_block(name="slab_rephasing", gz=gss_reph)
+
+    # readout
+    delta_kx, delta_ky, delta_kz = 1 / fov, 1 / fov, 1 / slab_thickness
+    g_read = pp.make_trapezoid(
+        channel="x", flat_area=Nx * delta_kx, flat_time=3.2e-3, system=system
+    )
+    adc = pp.make_adc(
+        num_samples=Nx, duration=g_read.flat_time, delay=g_read.rise_time, system=system
+    )
+    seq.register_block("dummy_readout", gx=g_read)
+    seq.register_block("readout", gx=g_read, adc=adc)
+
+    # phase encoding
+    gx_phase = pp.make_trapezoid(
+        channel="x", area=-g_read.area / 2, duration=1e-3, system=system
+    )
+    gy_phase = pp.make_trapezoid(channel="y", area=delta_ky * Ny, system=system)
+    gz_phase = pp.make_trapezoid(channel="z", area=delta_kz * Nz, system=system)
+    seq.register_block("g_phase", gx=gx_phase, gy=gy_phase, gz=gz_phase)
+
+    # crusher gradient
+    gz_spoil = pp.make_trapezoid(channel="z", area=32 / slab_thickness, system=system)
+    seq.register_block("g_spoil", gz=gz_spoil)
+
+    # phase encoding plan TODO: helper routine
+    pey_steps = ((np.arange(Ny)) - (Ny / 2)) / Ny
+    pez_steps = ((np.arange(Nz)) - (Nz / 2)) / Nz
+    encoding_plan = np.meshgrid(pey_steps, pez_steps, indexing="xy")
+    encoding_plan = [enc.ravel() for enc in encoding_plan]
+
+    # scan duration
+    dummy_scans = Ny
+    imaging_scans = Ny * Nz
+
+    # generate rf phases
+    rf_phases = RfPhaseCycle(
+        num_pulses=dummy_scans + imaging_scans, phase_increment=rf_spoiling_inc
+    )
+
+    # construct sequence
+    seq.section(name="ss_prep")
+    for n in range(dummy_scans):
+        rf_phase = rf_phases()
+        seq.add_block("excitation")
+        seq.add_block("slab_rephasing")
+        seq.add_block("g_phase", gy_amp=0.0, gz_amp=0.0)
+        seq.add_block("dummy_readout", rf_phase=rf_phase)
+        seq.add_block("g_phase", gy_amp=0.0, gz_amp=0.0)
+        seq.add_block("g_spoil")
+
+    seq.section(name="scan_loop")
+    for n in range(imaging_scans):
+        rf_phase = rf_phases()
+        seq.add_block("excitation")
+        seq.add_block("slab_rephasing")
+        seq.add_block("g_phase", gy_amp=encoding_plan[0][n], gz_amp=encoding_plan[1][n])
+        seq.add_block("readout", rf_phase=rf_phase, adc_phase=rf_phase)
+        seq.add_block(
+            "g_phase", gy_amp=-encoding_plan[0][n], gz_amp=-encoding_plan[1][n]
+        )
+        seq.add_block("g_spoil")
+
+    return seq.export()

pulserver/_apps/bar.py

@@ -0,0 +1,15 @@
+"""Another demo function."""
+
+
+def bar(arg1, arg2):
+    """
+    Another function.
+
+    Parameters
+    ----------
+    arg1 : int
+        A parameter.
+    arg2 : float
+        Another parameter.
+
+    """

pulserver/_apps/foo.py

@@ -0,0 +1,15 @@
+"""A demo function."""
+
+
+def foo(arg1, arg2):
+    """
+    A function.
+
+    Parameters
+    ----------
+    arg1 : int
+        A parameter.
+    arg2 : float
+        Another parameter.
+
+    """

pulserver/_cli.py

@@ -0,0 +1,70 @@
+"""Command Line Interface for server."""
+
+import os
+
+import click
+
+from . import _server
+
+
+@click.group()
+def cli():
+    pass
+
+
+@click.command()
+@click.option("--config-path", default=None, help="Location of config.yml file.")
+@click.option("--scanner-address", default=None, help="IP address of MR scanner.")
+@click.option("--scanner-port", default=None, help="MR scanner port.")
+@click.option(
+    "--recon-server-address", default=None, help="IP address of reconstruction servr."
+)
+@click.option("--recon-server-port", default=None, help="Reconstruction server port.")
+def start(
+    config_path, scanner_address, scanner_port, recon_server_address, recon_server_port
+):
+    """
+    Start sequence design server.
+    """
+    if config_path is not None:
+        os.environ["PULSEFORGE_CONFIG"] = config_path
+    else:
+        if scanner_address is not None:
+            os.environ["PULSEFORGE_SCANNER_ADDRESS"] = scanner_address
+        if scanner_port is not None:
+            os.environ["PULSEFORGE_SCANNER_PORT"] = scanner_port
+        if recon_server_address is not None:
+            os.environ["PULSEFORGE_RECON_SERVER_ADDRESS"] = recon_server_address
+        if recon_server_port is not None:
+            os.environ["PULSEFORGE_RECON_SERVER_PORT"] = recon_server_port
+
+    # start the server
+    _server.start_server()
+
+
+@click.command()
+@click.option(
+    "--name",
+    default=None,
+    help="Function whose docstring we want to see. If not provided, print list of available commands.",
+)
+def apps(name):
+    """
+    Design function documentations
+    """
+    # Load plugin list
+    plugins = _server.load_plugins()
+    if name is None:
+        for fun in plugins.values():
+            name = fun.__name__
+            summary = fun.__doc__.split("\n")[1]
+            click.echo(name + "\t" + summary)
+    else:
+        click.echo(plugins[name].__doc__)
+
+
+cli.add_command(start)
+cli.add_command(apps)
+
+if __name__ == "__main__":
+    cli()

pulserver/_core/__init__.py

@@ -0,0 +1,12 @@
+"""Core Sequence representations.
+
+This is an intermediate representation to handle both
+native pypulseq Sequence and Ceq structure.
+"""
+
+__all__ = []
+
+from ._ceq import SequenceParams  # noqa
+from ._sequence import Sequence  # noqa
+
+__all__.extend(["Sequence", "SequenceParams"])

pulserver/_core/_autoseg.py

@@ -0,0 +1,128 @@
+"""Automatic segment definition subroutines."""
+
+__all__ = ["find_segment_definitions", "find_segments", "split_rotated_segments"]
+
+import numpy as np
+import numba as nb
+
+
+def find_segment_definitions(arr):
+    # here, we make the (reasonable?) assumption
+    # that all the "prescan", dummy / syncronization / calibration
+    # scans are performed at the beginning of the sequence,
+    # then we have a long periodic main loop. We want to find the beginning
+    # of the main loop
+    main_loop, dummy_loop = _find_periodic_pattern(arr.astype(int))
+
+    if len(dummy_loop) > 0:  # TODO: make this recursive?
+        # here, we make the (reasonable?) assumption
+        # that all the "prescan", dummy / syncronization / calibration
+        # scans are also periodic
+        dummy_loop, rem = _find_periodic_pattern(dummy_loop.astype(int))
+
+        # hopefully rem is empty; if it is not, append at the beginning
+        if len(rem) > 0 and len(dummy_loop) == 0:
+            dummy_loop = [rem.tolist()]
+        elif len(rem) > 0:
+            dummy_loop = [rem.tolist() + dummy_loop.tolist()]
+        else:
+            dummy_loop = [dummy_loop.tolist()]
+        if len(main_loop) > 0:
+            return dummy_loop + [main_loop.tolist()]
+        return dummy_loop
+
+    return [main_loop.tolist()]
+
+
+def find_segments(array, subarray):
+    arr = nb.typed.List(array)
+    subarr = nb.typed.List(subarray)
+    return list(_find_segments(arr, subarr))
+
+
+@nb.njit(cache=True, fastmath=True)
+def _find_segments(array, subarray):
+    n = len(array)
+    m = len(subarray)
+    result = np.zeros(n, dtype=np.bool_)
+
+    for i in range(n - m + 1):
+        match = True
+        for j in range(m):
+            if array[i + j] != subarray[j]:
+                match = False
+                break
+        if match:
+            for k in range(m):
+                result[i + k] = True
+
+    return result
+
+
+def split_rotated_segments(input):
+    output = []
+    for segment in input:
+        tmp = _split_signed_blocks(segment)
+        for item in tmp:
+            output.append(item)
+    return output
+
+
+# %% local utils
+def _principal_period(s):
+    i = (s + s).find(s, 1, -1)
+    return None if i == -1 else s[:i]
+
+
+def _find_periodic_pattern(arr):
+    numel = len(arr)
+    loop = _principal_period(arr.tobytes())
+
+    for start in range(numel):
+        loop = _principal_period(arr[start:].tobytes())
+        if loop is not None:
+            break
+
+    if loop is not None:
+        loop = np.frombuffer(loop, dtype=int)
+        remainder = np.frombuffer(arr[:start], dtype=int)
+    else:
+        loop = np.frombuffer(arr, dtype=int)
+        remainder = np.asarray([], dtype=int)
+    return loop, remainder
+
+
+# Here we make the (I think) reasonable assumption that rotated blocks with different angles
+# (e.g., two consecutive (spiral arm, spiral rewinder) pairs with different angles)
+# are separated by non rotated blocks (e.g., RF pulses or z-spoilers)
+def _split_signed_blocks(arr):
+    if not arr:
+        return []
+
+    # Convert the input list to a numpy array
+    arr = np.array(arr)
+
+    # Create a sign array where positive numbers are marked as 1, negative as -1
+    sign = np.sign(arr)
+    sign[sign == 0] = 1
+
+    # Find the indices where the sign changes
+    change_indices = np.where(np.diff(sign) != 0)[0] + 1
+
+    # Split the array at the change indices
+    split_blocks = np.split(arr, change_indices)
+
+    # Convert the numpy arrays in the list to python lists
+    result = [list(abs(block)) for block in split_blocks]
+
+    # Get sizes of each block
+    osize = np.asarray([len(block) for block in result])
+    max_size = max(osize)
+    tmp = [np.pad(result[n], (0, max_size - osize[n])) for n in range(len(result))]
+    tmp = np.stack(tmp, axis=0)
+    tmp, idx = np.unique(tmp, return_index=True, axis=0)
+    tmp = tmp[np.argsort(idx)]
+    osize = osize[np.sort(idx)]
+    result = [tmp[n][: osize[n]].tolist() for n in range(len(osize))]
+
+    return result