Merge branch 'master' of https://github.com/jonbmartin/sigpy-rf

mikgroup · Nov 5, 2019 · ef733ae · ef733ae
2 parents b32bc2a + e789025
commit ef733ae
Show file tree

Hide file tree

Showing 86 changed files with 1,272 additions and 41 deletions.
diff --git a/.coveragerc b/.coveragerc
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
diff --git a/.gitignore b/.gitignore
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/.travis.yml b/.travis.yml
diff --git a/conda.recipe/bld.bat b/conda.recipe/bld.bat
diff --git a/conda.recipe/build.sh b/conda.recipe/build.sh
diff --git a/conda.recipe/meta.yaml b/conda.recipe/meta.yaml
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/core.rst b/docs/core.rst
diff --git a/docs/core_alg.rst b/docs/core_alg.rst
diff --git a/docs/core_app.rst b/docs/core_app.rst
diff --git a/docs/core_linop.rst b/docs/core_linop.rst
diff --git a/docs/core_prox.rst b/docs/core_prox.rst
diff --git a/docs/guide_basic.rst b/docs/guide_basic.rst
diff --git a/docs/guide_iter.rst b/docs/guide_iter.rst
diff --git a/docs/guide_multi_devices.rst b/docs/guide_multi_devices.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,6 +25,7 @@
    mri
    mri_linop
    mri_app
+   mri_rf
 
 .. toctree::
    :hidden:

diff --git a/docs/learn.rst b/docs/learn.rst
diff --git a/docs/learn_app.rst b/docs/learn_app.rst
diff --git a/docs/make.bat b/docs/make.bat
@@ -1,36 +1,36 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-set SPHINXPROJ=sigpy
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=sigpy
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/docs/mri.rst b/docs/mri.rst
@@ -46,6 +46,7 @@ Sampling Functions
 
    sigpy.mri.poisson
    sigpy.mri.radial
+   sigpy.mri.spiral
 
 Simulation Functions
 --------------------

diff --git a/docs/mri_app.rst b/docs/mri_app.rst
diff --git a/docs/mri_linop.rst b/docs/mri_linop.rst
diff --git a/docs/mri_rf.rst b/docs/mri_rf.rst
@@ -0,0 +1,36 @@
+MRI RF Design (`sigpy.mri.rf`)
+==============================
+
+.. automodule::
+   sigpy.mri.rf
+
+SLR Pulse Design
+--------------------------
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    sigpy.mri.rf.slr.dzrf
+    sigpy.mri.rf.slr.root_flip
+    sigpy.mri.rf.slr.dz_gslider_rf
+    sigpy.mri.rf.slr.dz_gslider_b
+    sigpy.mri.rf.slr.dz_hadamard_b
+
+RF Pulse Simulation
+--------------------------
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    sigpy.mri.rf.sim.abrm
+    sigpy.mri.rf.sim.abrm_nd
+    sigpy.mri.rf.sim.abrm_hp
+
+RF Utility
+--------------------------
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    sigpy.mri.rf.util.dinf
+
diff --git a/docs/plot.rst b/docs/plot.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/run_tests.sh b/run_tests.sh
diff --git a/sigpy/__init__.py b/sigpy/__init__.py
diff --git a/sigpy/alg.py b/sigpy/alg.py
@@ -220,6 +220,7 @@ class ConjugateGradient(Alg):
 
     def __init__(self, A, b, x, P=None, max_iter=100, tol=0):
         self.A = A
+        self.b = b
         self.P = P
         self.x = x
         self.tol = tol
@@ -552,7 +553,6 @@ def _update(self):
             gradf_x = self.gradf(self.x)
             p = -self.inv_hessf(self.x)(gradf_x)
             self.lamda2 = -xp.real(xp.vdot(p, gradf_x)).item()
-
             if self.lamda2 < 0:
                 raise ValueError(
                     'Direction is not descending. Got lamda2={}. '

diff --git a/sigpy/app.py b/sigpy/app.py
diff --git a/sigpy/backend.py b/sigpy/backend.py
diff --git a/sigpy/block.py b/sigpy/block.py
diff --git a/sigpy/config.py b/sigpy/config.py
diff --git a/sigpy/conv.py b/sigpy/conv.py
diff --git a/sigpy/fourier.py b/sigpy/fourier.py
diff --git a/sigpy/interp.py b/sigpy/interp.py
diff --git a/sigpy/learn/__init__.py b/sigpy/learn/__init__.py
diff --git a/sigpy/learn/app.py b/sigpy/learn/app.py
diff --git a/sigpy/learn/util.py b/sigpy/learn/util.py
diff --git a/sigpy/linop.py b/sigpy/linop.py
diff --git a/sigpy/mri/__init__.py b/sigpy/mri/__init__.py
diff --git a/sigpy/mri/app.py b/sigpy/mri/app.py
diff --git a/sigpy/mri/bloch.py b/sigpy/mri/bloch.py
diff --git a/sigpy/mri/dcf.py b/sigpy/mri/dcf.py
diff --git a/sigpy/mri/linop.py b/sigpy/mri/linop.py
diff --git a/sigpy/mri/precond.py b/sigpy/mri/precond.py
diff --git a/sigpy/mri/rf/__init__.py b/sigpy/mri/rf/__init__.py
@@ -0,0 +1,23 @@
+"""This MRI submodule contains functions and classes for MRI pulse design.
+
+It currently provides tools for SLR pulse design and RF pulse simulation.
+Tools for designing pTx, adiabatic, and other types of rf pulses,
+as well as gradient and trajectory designers will be added soon.
+
+Explore RF design tutorials at `sigpy-rf-tutorials`_.
+
+See in-progress features at `sigpy-rf`_.
+
+.. _sigpy-rf-tutorials: https://github.com/jonbmartin/sigpy-rf-tutorials
+.. _sigpy-rf: https://github.com/jonbmartin/sigpy-rf
+
+"""
+from sigpy.mri.rf import slr, sim, util
+from sigpy.mri.rf.sim import *  # noqa
+from sigpy.mri.rf.slr import *  # noqa
+from sigpy.mri.rf.util import *  # noqa
+
+__all__ = []
+__all__.extend(slr.__all__)
+__all__.extend(sim.__all__)
+__all__.extend(util.__all__)
diff --git a/sigpy/mri/rf/sim.py b/sigpy/mri/rf/sim.py
@@ -0,0 +1,163 @@
+"""RF Pulse Simulation Functions.
+
+"""
+from sigpy import backend
+
+__all__ = ['abrm', 'abrm_nd', 'abrm_hp']
+
+
+def abrm(rf, x, balanced=False):
+    r"""1D RF pulse simulation, with simultaneous RF + gradient rotations.
+
+    Args:
+         rf (array): rf waveform input.
+         x (array): spatial locations.
+         balanced (bool): toggles application of rewinder.
+
+    Returns:
+        2-element tuple containing
+
+        - **a** (*array*): SLR alpha parameter.
+        - **b** (*array*): SLR beta parameter.
+
+    References:
+        Pauly, J., Le Roux, Patrick., Nishimura, D., and Macovski, A.(1991).
+        'Parameter Relations for the Shinnar-LeRoux Selective Excitation
+        Pulse Design Algorithm'.
+        IEEE Transactions on Medical Imaging, Vol 10, No 1, 53-65.
+     """
+
+    device = backend.get_device(rf)
+    xp = device.xp
+    with device:
+        eps = 1e-16
+
+        g = xp.ones(xp.size(rf)) * 2 * xp.pi / xp.size(rf)
+
+        a = xp.ones(xp.size(x), dtype=complex)
+        b = xp.zeros(xp.size(x), dtype=complex)
+        for mm in range(xp.size(rf)):
+            om = x * g[mm]
+            phi = xp.sqrt(xp.abs(rf[mm]) ** 2 + om ** 2) + eps
+            n = xp.column_stack((xp.real(rf[mm]) / phi,
+                                 xp.imag(rf[mm]) / phi,
+                                 om / phi))
+            av = xp.cos(phi / 2) - 1j * n[:, 2] * xp.sin(phi / 2)
+            bv = -1j * (n[:, 0] + 1j * n[:, 1]) * xp.sin(phi / 2)
+            at = av * a - xp.conj(bv) * b
+            bt = bv * a + xp.conj(av) * b
+            a = at
+            b = bt
+
+        if balanced:  # apply a rewinder
+            g = -2 * xp.pi / 2
+            om = x * g
+            phi = xp.abs(om) + eps
+            nz = om / phi
+            av = xp.cos(phi / 2) - 1j * nz * xp.sin(phi / 2)
+            a = av * a
+            b = xp.conj(av) * b
+
+        return a, b
+
+
+def abrm_nd(rf, x, g):
+    r"""N-dim RF pulse simulation
+
+    Assumes that x has inverse spatial units of g, and g has gamma*dt applied.
+
+    Assumes dimensions x = [...,Ndim], g = [Ndim,Nt].
+
+    Args:
+         rf (array): rf waveform input.
+         x (array): spatial locations.
+         g (array): gradient array.
+
+    Returns:
+        2-element tuple containing
+
+        - **a** (*array*): SLR alpha parameter.
+        - **b** (*array*): SLR beta parameter.
+
+    References:
+        Pauly, J., Le Roux, Patrick., Nishimura, D., and Macovski, A.(1991).
+        'Parameter Relations for the Shinnar-LeRoux Selective Excitation
+        Pulse Design Algorithm'.
+        IEEE Transactions on Medical Imaging, Vol 10, No 1, 53-65.
+     """
+
+    device = backend.get_device(rf)
+    xp = device.xp
+    with device:
+        eps = 1e-16
+
+        a = xp.ones(xp.shape(x)[0], dtype=complex)
+        b = xp.zeros(xp.shape(x)[0], dtype=complex)
+        for mm in range(xp.size(rf)):
+            om = x @ g[mm, :]
+            phi = xp.sqrt(xp.abs(rf[mm]) ** 2 + om ** 2)
+            n = xp.column_stack((xp.real(rf[mm]) / (phi + eps),
+                                 xp.imag(rf[mm]) / (phi + eps),
+                                 om / (phi + eps)))
+            av = xp.cos(phi / 2) - 1j * n[:, 2] * xp.sin(phi / 2)
+            bv = -1j * (n[:, 0] + 1j * n[:, 1]) * xp.sin(phi / 2)
+            at = av * a - xp.conj(bv) * b
+            bt = bv * a + xp.conj(av) * b
+            a = at
+            b = bt
+
+        return a, b
+
+
+def abrm_hp(rf, gamgdt, xx, dom0dt=0):
+    r"""1D RF pulse simulation, with non-simultaneous RF + gradient rotations.
+
+    Args:
+        rf (array): rf pulse samples in radians.
+        gamdt (array): gradient samples in radians/(units of xx).
+        xx (array): spatial locations.
+        dom0dt (float): off-resonance phase in radians.
+
+    Returns:
+        2-element tuple containing
+
+        - **a** (*array*): SLR alpha parameter.
+        - **b** (*array*): SLR beta parameter.
+
+    References:
+        Pauly, J., Le Roux, Patrick., Nishimura, D., and Macovski, A.(1991).
+        'Parameter Relations for the Shinnar-LeRoux Selective Excitation
+        Pulse Design Algorithm'.
+        IEEE Transactions on Medical Imaging, Vol 10, No 1, 53-65.
+     """
+
+    device = backend.get_device(rf)
+    xp = device.xp
+    with device:
+        Ns = xp.shape(xx)
+        Ns = Ns[0]  # Ns: # of spatial locs
+        Nt = xp.shape(gamgdt)
+        Nt = Nt[0]  # Nt: # time points
+
+        a = xp.ones((Ns,))
+        b = xp.zeros((Ns,))
+
+        for ii in xp.arange(Nt):
+            # apply phase accural
+            z = xp.exp(-1j * (xx * gamgdt[ii, ] + dom0dt))
+            b = b * z
+
+            # apply rf
+            C = xp.cos(xp.abs(rf[ii]) / 2)
+            S = 1j * xp.exp(1j * xp.angle(rf[ii])) * xp.sin(xp.abs(rf[ii]) / 2)
+            at = a * C - b * xp.conj(S)
+            bt = a * S + b * C
+
+            a = at
+            b = bt
+
+        z = xp.exp(1j / 2 * (xx * xp.sum(gamgdt, axis=0) + Nt * dom0dt))
+        a = a * z
+        b = b * z
+
+        return a, b