MRArbGrad 4.3.0__tar.gz → 4.4.1__tar.gz

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2025 Rui Luo
+Copyright 2026 Rui Luo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

mrarbgrad-4.4.1/MANIFEST.in

@@ -0,0 +1 @@
+graft mrarbgrad_src

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1/MRArbGrad.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MRArbGrad
-Version: 4.3.0
+Version: 4.4.1
 Summary: Gradient waveform design tool for arbitrary k-space trajectories.
 Author-email: Ryan <ryan_shanghaitech@proton.me>
 License-Expression: MIT

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/MRArbGrad.egg-info/SOURCES.txt

@@ -12,13 +12,13 @@ MRArbGrad.egg-info/SOURCES.txt
 MRArbGrad.egg-info/dependency_links.txt
 MRArbGrad.egg-info/requires.txt
 MRArbGrad.egg-info/top_level.txt
-example/example_BuiltInTraj.py
-example/example_ExternalFunction2D.py
-example/example_ExternalSamples2D.py
-example/example_ExternalSamples3D.py
 mrarbgrad_src/Function.py
 mrarbgrad_src/Utility.py
 mrarbgrad_src/__init__.py
+mrarbgrad_src/ext.cpython-312-x86_64-linux-gnu.so
+mrarbgrad_src/__pycache__/Function.cpython-312.pyc
+mrarbgrad_src/__pycache__/Utility.cpython-312.pyc
+mrarbgrad_src/__pycache__/__init__.cpython-312.pyc
 mrarbgrad_src/ext/main.cpp
 mrarbgrad_src/ext/mag/Mag.cpp
 mrarbgrad_src/ext/mag/Mag.h

{mrarbgrad-4.3.0/MRArbGrad.egg-info → mrarbgrad-4.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MRArbGrad
-Version: 4.3.0
+Version: 4.4.1
 Summary: Gradient waveform design tool for arbitrary k-space trajectories.
 Author-email: Ryan <ryan_shanghaitech@proton.me>
 License-Expression: MIT

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/mrarbgrad_src/Function.py

@@ -23,10 +23,24 @@ def calGrad4ExFunc\
     p0:float64 = 0e0, 
     p1:float64 = 1e0, 
 ) -> tuple[NDArray, NDArray]:
-    '''
-    :return: gradient waveform, corresponding parameter
-    :rtype: tuple[NDArray, NDArray]
-    '''
+    """
+    Generate gradient waveforms for external functions.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        getK (Callable | None, optional): Trajectory function.
+        getDkDp (Callable | None, optional): 1st order derivative to trajectory function.
+        getD2kDp2 (Callable | None, optional): 2nd order derivative to trajectory function.
+        p0 (float64, optional): Lower bound of the trajectory parameter.
+        p1 (float64, optional): Upper bound of the trajectory parameter.
+
+    Returns:
+        tuple[NDArray, NDArray]: Gradient waveform (in `Hz/pix`); Corresponding parameter
+    """
     return ext.calGrad4ExFunc\
     (
         float64(fov),
@@ -55,10 +69,20 @@ def calGrad4ExSamp\
     
     arrK: NDArray = np.empty((0,3)),
 ) -> tuple[NDArray, NDArray]:
-    '''
-    :return: gradient waveform, corresponding parameter
-    :rtype: tuple[NDArray, NDArray]
-    '''
+    """
+    Generate gradient waveforms for external trajectory samples.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        arrK (NDArray, optional): External trajectory samples, shape: `[nK,nAx]`
+
+    Returns:
+        tuple[NDArray, NDArray]: Gradient waveform (in `Hz/pix`); Corresponding parameter
+    """
     return ext.calGrad4ExSamp\
     (
         float64(fov),
@@ -83,10 +107,21 @@ def getG_Spiral\
     nSlice: int64 = 1,
     kRhoPhi: float64 = 0.5 / (4 * pi)
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a standard spiral trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        nSlice (int64, optional): Number of slices.
+        kRhoPhi (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Spiral\
     (
         float64(fov),
@@ -113,10 +148,22 @@ def getG_VDSpiral\
     kRhoPhi0: float64 = 0.5 / (8 * pi),
     kRhoPhi1: float64 = 0.5 / (2 * pi),
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a variable density (VD) spiral trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        nSlice (int64, optional): Number of slices.
+        kRhoPhi0 (float64, optional): Inner shape parameter.
+        kRhoPhi1 (float64, optional): Outer shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_VDSpiral\
     (
         float64(fov),
@@ -143,10 +190,21 @@ def getG_VDSpiral_RT\
     kRhoPhi0: float64 = 0.5 / (8 * pi),
     kRhoPhi1: float64 = 0.5 / (2 * pi),
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a real-time variable density spiral trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        kRhoPhi0 (float64, optional): Inner shape parameter.
+        kRhoPhi1 (float64, optional): Outer shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_VDSpiral_RT\
     (
         float64(fov),
@@ -174,10 +232,23 @@ def getG_Rosette\
     om2: float64 = 3*pi, 
     tMax: float64 = 1e0,
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a rosette trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        nSlice (int64, optional): Number of slices.
+        om1 (float64, optional): Shape parameter.
+        om2 (float64, optional): Shape parameter.
+        tMax (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Rosette\
     (
         float64(fov),
@@ -208,10 +279,24 @@ def getG_Rosette_Trad\
     tMax: float64 = 1e0,
     tAcq: float64 = 2.523e-3,
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a traditional rosette trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        nSlice (int64, optional): Number of slices.
+        om1 (float64, optional): Shape parameter.
+        om2 (float64, optional): Shape parameter.
+        tMax (float64, optional): Shape parameter.
+        tAcq (float64, optional): Acquisition duration.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Rosette_Trad\
     (
         float64(fov),
@@ -239,10 +324,20 @@ def getG_Shell3d\
     
     kRhoTht: float64 = 0.5 / (2 * pi),
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a 3D shell trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        kRhoTht (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Shell3d\
     (
         float64(fov),
@@ -266,10 +361,20 @@ def getG_Yarnball\
     
     kRhoPhi: float64 = 0.5 / (2 * pi),
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a yarnball trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        kRhoPhi (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Yarnball\
     (
         float64(fov),
@@ -293,10 +398,20 @@ def getG_Yarnball_RT\
     
     kRhoPhi: float64 = 0.5 / (2 * pi)
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a real-time yarnball trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        kRhoPhi (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Yarnball_RT\
     (
         float64(fov),
@@ -321,10 +436,21 @@ def getG_Seiffert\
     m: float64 = 0.07, 
     uMax: float64 = 20.0, 
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a Seiffert spiral trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        m (float64, optional): Shape parameter.
+        uMax (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Seiffert\
     (
         float64(fov),
@@ -349,10 +475,20 @@ def getG_Cones\
     
     kRhoPhi: float64 = 0.5 / (4 * pi),
 ) -> tuple[list[NDArray], list[NDArray]]:
-    '''
-    :return: list of trajectory start, list of gradient waveforms
-    :rtype: tuple[list[NDArray], list[NDArray]]
-    '''
+    """
+    Generate gradient waveforms for a 3D cones trajectory.
+
+    Args:
+        fov (float64, optional): Field of view, unit: `m`.
+        nPix (int64, optional): Number of pixel, unit: `a.u.`.
+        sLim (float64, optional): l2 Slew limit, unit: `Hz/pix/s`.
+        gLim (float64, optional): l2 Gradient limit, unit: `Hz/pix`.
+        dt (float64, optional): Time step, unit: `s`.
+        kRhoPhi (float64, optional): Shape parameter.
+
+    Returns:
+        tuple[list[NDArray], list[NDArray]]: List of trajectory start points (in `/pix`); List of gradient waveforms (in `Hz/pix`)
+    """
     return ext.getG_Cones\
     (
         float64(fov),

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/mrarbgrad_src/Utility.py

@@ -1,6 +1,7 @@
 from numpy import *
 from numpy.linalg import norm
 from numpy.typing import *
+from itertools import product
 
 goldrat = (1+sqrt(5))/2
 goldang = (2*pi)/(1+goldrat)
@@ -8,6 +9,86 @@ goldang = (2*pi)/(1+goldrat)
 def getGoldrat()->float: return goldrat
 def getGoldang()->float: return goldang
 
+def unitcvt(x:float, fov:float, nPix:int, dir:int, gamma:float=42.5756e6) -> float:
+    """
+    This package uses `Hz/pix` for gradient unit, and `Hz/pix/s` for slew unit, and `pix` for length unit. This unit system has several good properties for theory derivation. You may need this helper function for unit conversion in case you are not familiar with this unit system.
+    
+    You may need `dir=1,2` to convert common units (like `mT/m` for gradient and `T/m/s` for slew) to units supported by this package (like `Hz/pix` for gradient and `Hz/pix/s` for slew), before you call any gradient generation functions, or `dir=-1` when converting gradients generated by this package in `Hz/pix` back to `mT/m`.
+
+    Args:
+        x (float): Input value.
+        fov (float): Field of view.
+        nPix (int): Number of pixels.
+        dir (int):
+            `1`: from `mT/m` to `Hz/pix`.
+            `2`: from `T/m/s` to `Hz/pix/s`.
+            `-1`: from `Hz/pix` to `mT/m`.
+            `-2`: from `Hz/pix/s` to `T/m/s`.
+        gamma (float): Gyromagnetic ratio `Hz/T`.
+        
+    Returns:
+        float: Converted value.
+    """
+    if dir==1:
+        return x * (1e-3*gamma*fov/nPix)
+    if dir==2:
+        return x * (gamma*fov/nPix)
+    if dir==-1:
+        return x / (1e-3*gamma*fov/nPix)
+    if dir==-2:
+        return x / (gamma*fov/nPix)
+    raise RuntimeError("dir")
+
+def getK_Cartesian(nPix:int, nAx:int) -> list[NDArray]:
+    """
+    Generates a Cartesian sampling pattern.
+    
+    Args:
+        nPix (int): Number of pixels.
+        nAx (int): Number of dimensions.
+        
+    Returns:
+        list[NDArray]: List of trajectories in `[nK,nAx]`.
+    """
+    arrK1D = linspace(-0.5, 0.5, nPix, endpoint=0)
+    lstArrK:list[NDArray] = []
+    
+    for arrKyKz in product(arrK1D, repeat=nAx-1):
+        arrK = empty((nPix,nAx), dtype=float32)
+        arrK[:,0] = arrK1D
+        arrK[:,1:] = arrKyKz
+        lstArrK.append(arrK)
+        
+    return lstArrK
+
+
+def getK_Radial(nPix:int, nAx:int, nSpoke:int, enGoldAng:bool) -> list:
+    """
+    Generates a Radial sampling pattern.
+    
+    Args:
+        nPix (int): Number of pixels.
+        nAx (int): Number of dimensions.
+        nSpoke (int): Number of radial spokes.
+        enGoldAng (bool): If True, uses the golden angle for spoke spacing.
+        
+    Returns:
+        list: A list of numpy arrays, each of shape [nPix, nAx], representing radial spokes.
+    """
+    if nAx!=2: raise NotImplementedError("nAx!=2")
+    lstArrK = []
+    arrK1D = linspace(-0.5, 0.5, nPix, endpoint=0)
+    
+    for iSpoke in range(nSpoke):
+        if enGoldAng: tht = iSpoke * goldang
+        else: tht = iSpoke * (pi / nSpoke)
+        arrK = empty((nPix,nAx), dtype=float32)
+        arrK[:,0] = arrK1D * cos(tht)
+        arrK[:,1] = arrK1D * sin(tht)
+        lstArrK.append(arrK)
+        
+    return lstArrK
+
 def gradClip(lstArrGrad:list[NDArray]|NDArray, dt:float, sLim:float, gLim:float) -> list[NDArray]|NDArray:
     """
     Clip the slewrate and gradient amlitude of a list of gradient waveforms
@@ -64,70 +145,70 @@ def genPermTab(n:int) -> list[int]:
         lstIdx.append(i*inc%n)
     return lstIdx
 
-def cvtGrad2Traj(arrG:NDArray, dtGrad:int|float, dtADC:int|float, nShift:int|float=1.0) -> tuple[NDArray, NDArray]:
+def cvtGrad2Traj(arrGrad:NDArray, dtGrad:int|float, dtAdc:int|float, nShift:int|float=1.0) -> tuple[NDArray, NDArray]:
     """
     # description:
     interpolate gradient waveform and calculate trajectory
 
     # parameter
-    `arrG`: array of gradient waveform
-    `dtGrad`, `dtADC`: temporal resolution of gradient system and ADC
+    `arrGrad`: array of gradient waveform
+    `dtGrad`, `dtAdc`: temporal resolution of gradient system and ADC
 
     # return:
     interpolated trajectory and gradient
     """
-    dtShift = nShift*dtADC
-    nGrad, nDim = arrG.shape
-    nADC = int(dtGrad/dtADC)*(nGrad-1)
-    arrG_Resamp = zeros([nADC,nDim], dtype=float64)
-    for iDim in range(nDim):
-        arrG_Resamp[:,iDim] = interp(dtADC*arange(nADC)+dtShift, dtGrad*arange(nGrad), arrG[:,iDim])
-    arrDk = zeros_like(arrG_Resamp)
-    arrDk[0,:] = (arrG[0,:] + arrG_Resamp[0,:])*dtShift/2
-    arrDk[1:,:] = (arrG_Resamp[:-1] + arrG_Resamp[1:])*dtADC/2
+    dtShift = nShift*dtAdc
+    nGrad, nAx = arrGrad.shape
+    nAdc = int(dtGrad/dtAdc)*(nGrad-1)
+    arrGrad_Resamp = zeros([nAdc,nAx], dtype=float64)
+    for iDim in range(nAx):
+        arrGrad_Resamp[:,iDim] = interp(dtAdc*arange(nAdc)+dtShift, dtGrad*arange(nGrad), arrGrad[:,iDim])
+    arrDk = zeros_like(arrGrad_Resamp)
+    arrDk[0,:] = (arrGrad[0,:] + arrGrad_Resamp[0,:])*dtShift/2
+    arrDk[1:,:] = (arrGrad_Resamp[:-1] + arrGrad_Resamp[1:])*dtAdc/2
     arrK = cumsum(arrDk,axis=0)
-    return arrK, arrG_Resamp
+    return arrK, arrGrad_Resamp
 
-def delGrad(arrG:NDArray, tau:int|float) -> NDArray:
+def delGrad(arrGrad:NDArray, tau:int|float) -> NDArray:
     """
     # description:
     delay the input gradient waveform by time constant tau
 
     # parameter
-    `arrG`: array of single gradient waveform
+    `arrGrad`: array of single gradient waveform
     `tau`: time constant in RL circuit transfer function
 
     # return:
     delayed gradient waveform
     """
-    assert arrG.ndim == 2, "only single gradient waveform is supported."
-    if tau == 0: return arrG.copy() # avoid divided-by-0 later
-    nPt, nAx = arrG.shape
+    assert arrGrad.ndim == 2, "only single gradient waveform is supported."
+    if tau == 0: return arrGrad.copy() # avoid divided-by-0 later
+    nPt, nAx = arrGrad.shape
 
     # perform oversample to get better impluse response profile
     ov = clip(10/tau, 1, 1e3).astype(int64) # the smaller the ov, the bigger oversampling is needed
-    arrG_ov = zeros([nPt*ov,nAx], dtype=arrG.dtype)
+    arrGrad_ov = zeros([nPt*ov,nAx], dtype=arrGrad.dtype)
     for iAx in range(nAx):
-        arrG_ov[:,iAx] = interp(linspace(0,nPt,nPt*ov,0), linspace(0,nPt,nPt,0), arrG[:,iAx]) # oversample
+        arrGrad_ov[:,iAx] = interp(linspace(0,nPt,nPt*ov,0), linspace(0,nPt,nPt,0), arrGrad[:,iAx]) # oversample
     nPt *= ov
     tau *= ov
 
     # derive impluse response of RL circuit
-    arrG_Pad = zeros_like(arrG_ov)
-    arrG_Pad[:nPt//2,:] = arrG_ov[-1:,:]
-    arrG_Pad[nPt//2:,:] = arrG_ov[:1,:]
-    arrG_ov = concatenate([arrG_ov, arrG_Pad], axis=0)
+    arrGrad_Pad = zeros_like(arrGrad_ov)
+    arrGrad_Pad[:nPt//2,:] = arrGrad_ov[-1:,:]
+    arrGrad_Pad[nPt//2:,:] = arrGrad_ov[:1,:]
+    arrGrad_ov = concatenate([arrGrad_ov, arrGrad_Pad], axis=0)
     arrT = linspace(0,2*nPt,2*nPt,0) + 0.5
     arrImpResRL = (1/tau)*exp(-arrT/tau)
     if abs(arrImpResRL.sum() - 1) > 1e-2: raise ValueError(f"arrImpResRL.sum() = {arrImpResRL.sum():.2f} (supposed to be 1) (tau too small or too large)")
     
     # perform convolution between input waveform and impulse response
-    arrG_ov = fft.ifft(fft.fft(arrG_ov,axis=0)*fft.fft(arrImpResRL)[:,newaxis], axis=0).real
+    arrGrad_ov = fft.ifft(fft.fft(arrGrad_ov,axis=0)*fft.fft(arrImpResRL)[:,newaxis], axis=0).real
     
     # de-oversample
-    arrG = arrG_ov[:nPt:ov,:]
+    arrGrad = arrGrad_ov[:nPt:ov,:]
 
-    return arrG
+    return arrGrad
 
 def rotate(arr:NDArray, ang:float64, axis:int64) -> NDArray:
     if axis==0: # x

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/mrarbgrad_src/__init__.py

@@ -1,6 +1,6 @@
 from .Function import calGrad4ExFunc, calGrad4ExSamp
 from .Function import getG_Cones, getG_Rosette, getG_Rosette_Trad, getG_Seiffert, getG_Shell3d, getG_Spiral, getG_VDSpiral, getG_VDSpiral_RT, getG_Yarnball, getG_Yarnball_RT
 from .Function import setSolverMtg, setTrajRev, setGoldAng, setShuf, setMaxG0, setMaxG1, setMagGradSamp, setMagTrajSamp, setMagOverSamp, setMagSFS, setMagGradRep, setMagTrajRep, setDbgPrint, saveF64, loadF64, saveF32, loadF32
-from .Utility import _calDiaphony, rotate, _calJacElip, _calCompElipInt, _calSphFibPt, cvtGrad2Traj, getGoldang, getGoldrat, rand3d, gradClip, genPermTab
+from .Utility import _calDiaphony, rotate, _calJacElip, _calCompElipInt, _calSphFibPt, cvtGrad2Traj, getGoldang, getGoldrat, rand3d, gradClip, genPermTab, unitcvt, getK_Cartesian, getK_Radial
 
 from . import trajfunc

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/mrarbgrad_src/ext/traj/MrTraj.h

@@ -13,7 +13,7 @@
 bool gMrTraj_enMtg = false; // whether to use Lustig's minTimeGrad solver
 f64 gMrTraj_g0Norm = 0e0; // initial gradient amplitude
 f64 gMrTraj_g1Norm = 0e0; // final gradient amplitude
-i64 gMrTraj_nGradSampRsv = 10000; // buffer size of mag solver
+i64 gMrTraj_nGradSampRsv = 10000; // buffer size of MAG solver
 i64 gMrTraj_nTrajSampRsv = 10000; // num. of samp. when doing Traj. Rep.
 
 /* 
@@ -204,7 +204,7 @@ protected:
             minRotang = std::min(minRotang, rotang);
         }
 
-        // ensure the rot. Num. is a integer
+        // ensure the rot. Num. is an integer
         return (i64)std::ceil(2e0*M_PI/minRotang);
     }
     

{mrarbgrad-4.3.0 → mrarbgrad-4.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "MRArbGrad"
-version = "4.3.0"
+version = "4.4.1"
 dependencies = ["numpy"]
 
 description = "Gradient waveform design tool for arbitrary k-space trajectories."

mrarbgrad-4.3.0/MANIFEST.in

@@ -1 +0,0 @@
-global-include *.py *.c *.cpp *.h

mrarbgrad-4.3.0/example/example_BuiltInTraj.py

@@ -1,105 +0,0 @@
-import mrarbgrad as mag
-from numpy import *
-from matplotlib.pyplot import *
-from numpy.linalg import norm
-
-gamma = 42.5756e6
-fov = 0.256
-nPix = 256
-dtGrad = 10e-6
-dtADC = 2.5e-6
-sLim = 50 * gamma * fov/nPix
-gLim = 20e-3 * gamma * fov/nPix
-# gLim = 1/nPix/dtADC
-argCom = dict(fov=fov, nPix=nPix, sLim=sLim, gLim=gLim, dt=dtGrad)
-
-mag.setSolverMtg(0) # set solver, 0 for proposed method, 1 for baseline method, baseline method may be removed due to copyright reason
-mag.setTrajRev(0) # reverse the trajectory
-mag.setGoldAng(1) # enable golden-angle interleaving (only for 2D)
-mag.setShuf(0) # enable TR-shuffling
-mag.setMaxG0(0) # use maximum possible initial gradient amplitude
-mag.setMaxG1(0) # use maximum possible final gradient amplitude
-mag.setMagOverSamp(8) # set oversampling ratio (default: 8, reduce only if hardware performance is too low to support real-time)
-mag.setMagSFS(0) # disable DTFBS (experimental)
-mag.setMagGradRep(1) # enable gradient reparameterization (experimental)
-mag.setMagTrajRep(1) # enable trajectory reparameterization (experimental)
-mag.setDbgPrint(1) # enable debug info (for benchmark purpose)
-
-# calculate gradient
-# lstArrK0, lstArrGrad = mag.getG_Spiral(**argCom); nAx = 2
-# lstArrK0, lstArrGrad = mag.getG_VDSpiral(**argCom); nAx = 2
-# lstArrK0, lstArrGrad = mag.getG_VDSpiral_RT(**argCom); nAx = 2
-# lstArrK0, lstArrGrad = mag.getG_Rosette(**argCom); nAx = 2
-# lstArrK0, lstArrGrad = mag.getG_Rosette_Trad(**argCom); nAx = 2
-# lstArrK0, lstArrGrad = mag.getG_Shell3d(**argCom); nAx = 3
-lstArrK0, lstArrGrad = mag.getG_Yarnball(**argCom); nAx = 3
-# lstArrK0, lstArrGrad = mag.getG_Seiffert(**argCom); nAx = 3
-# lstArrK0, lstArrGrad = mag.getG_Cones(**argCom); nAx = 3
-
-# lstArrGrad = mag.gradClip(lstArrGrad, dtGrad, sLim, gLim) # clip slew/grad amp with hardware constraint
-
-print("")
-print(f"Intlea Num.: {len(lstArrGrad)}")
-nRO_Max = amax([arrG.shape[0] for arrG in lstArrGrad])
-print(f"Tacq: {nRO_Max*dtGrad*1e3:.3f} ms")
-tTR = (nRO_Max*dtGrad + 2e-3)
-print(f"TR: {tTR*1e3:.3f} ms")
-tScan = tTR*len(lstArrGrad)
-print(f"Tscan: {tScan:.3e} s")
-
-# derive shape parameter
-if nAx==2:
-    lstArrK0 = [arrK0[:2] for arrK0 in lstArrK0]
-    lstArrGrad = [arrG[:,:2] for arrG in lstArrGrad]
-nRO, nAx = lstArrGrad[0].shape
-
-# derive slewrate
-lstArrSlew = [diff(arrG, axis=0)/dtGrad for arrG in lstArrGrad]
-sMax = max(norm(concatenate(lstArrSlew)/gamma*nPix/fov, axis=-1))
-gMax = max(norm(concatenate(lstArrGrad)/gamma*nPix/fov, axis=-1))
-
-# derive trajectory
-lstArrK = []
-for arrK0, arrGrad in zip(lstArrK0, lstArrGrad):
-    arrK, _ = mag.cvtGrad2Traj(arrGrad, dtGrad, dtADC)
-    arrK += arrK0
-    lstArrK.append(arrK)
-
-iArrK = len(lstArrK)*2//3
-
-# k-space and g-space
-figure(figsize=(18,9), dpi=120)
-
-subplot(221, projection="3d" if nAx==3 else None)
-plot(*lstArrK[iArrK].T, ".-")
-axis("equal")
-grid("on")
-title(f"kspace {1}/{len(lstArrGrad)}")
-
-subplot(223, projection="3d" if nAx==3 else None)
-plot(*lstArrGrad[iArrK].T, ".-")
-axis("equal")
-grid("on")
-title("gspace")
-
-# gradient and slewrate
-subplot(222)
-for iAx in range(nAx):
-    plot(lstArrGrad[iArrK][:,iAx]/gamma*nPix/fov, ".-")
-grid("on")
-title(f"Gradient")
-
-subplot(224)
-plot(norm(lstArrSlew[iArrK],axis=-1)/gamma*nPix/fov, ".-", c="tab:blue")
-ylim(sLim/gamma*nPix/fov*0.9, sLim/gamma*nPix/fov*1.1)
-grid("on")
-
-twinx()
-plot(norm(lstArrGrad[iArrK],axis=-1)/gamma*nPix/fov*1e3, ".-", c="tab:orange")
-ylim(gLim/gamma*nPix/fov*0.9*1e3, gLim/gamma*nPix/fov*1.1*1e3)
-grid("on")
-title(f"Grad & Slew amp., max grad:{gMax*1e3:.3f}, max slew:{sMax:.3f}")
-
-subplots_adjust(0.05,0.1,0.95,0.9, 0.2, 0.2)
-
-show()

mrarbgrad-4.3.0/example/example_ExternalFunction2D.py

@@ -1,80 +0,0 @@
-from numpy import *
-from numpy.linalg import norm
-from matplotlib.pyplot import *
-import mrarbgrad as mag
-
-gamma = 42.5756e6
-fov = 0.256
-nPix = 256
-dtGrad = 10e-6
-dtADC = 1e-6
-sLim = 50 * gamma * fov/nPix
-gLim = 20e-3 * gamma * fov/nPix
-# gLim = 1/nPix/dtADC
-
-# Rosette
-nAx = 2
-om1 = 19*pi
-om2 = 17*pi
-def Rosette(t):
-    rho = 0.5*sin(om1*t)
-    return array\
-    ([
-        rho*cos(om2*t),
-        rho*sin(om2*t),
-        0*t
-    ])
-    
-pLim = [0,1]
-
-# derive slew-rate constrained trajectory
-mag.setMaxG0(0)
-mag.setMaxG1(0)
-arrGrad = mag.calGrad4ExFunc(fov, nPix, sLim, gLim, dtGrad, Rosette, None, None, pLim[0], pLim[1])[0]
-# arrGrad = mag.gradClip(arrGrad, dtGrad, sLim, gLim) # clip slew/grad amp with hardware constraint
-nRO = arrGrad.shape[0]
-
-arrSlew = diff(arrGrad, axis=0)/dtGrad
-print(f"sMax: {max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov)}")
-
-arrK = mag.cvtGrad2Traj(arrGrad, dtGrad, dtADC, 0.5)[0]
-
-# derive reference trajectory
-arrP_Ref = linspace(pLim[0], pLim[1], int(1e4))
-arrK_Ref = Rosette(arrP_Ref).T
-
-# plot
-figure(figsize=(20,10), dpi=120)
-
-subplot(221, projection=None if nAx==2 else "3d")
-if nAx==2: plot(arrK_Ref[:,0], arrK_Ref[:,1], "--", label="K_Ref")
-if nAx==3: plot(arrK_Ref[:,0], arrK_Ref[:,1], arrK_Ref[:,2], "--", label="K_Ref")
-if nAx==2: plot(arrK[:,0], arrK[:,1], ".-", label="K_Imp")
-if nAx==3: plot(arrK[:,0], arrK[:,1], arrK[:,2], ".-", label="K_Imp")
-xlim(-0.5,0.5)
-ylim(-0.5,0.5)
-axis("equal")
-grid("on")
-legend()
-title("k-Space")
-
-subplot(222)
-for iAx in range(nAx):
-    plot(arrGrad[:,iAx]/(42.58e6)*(nPix/fov), ".-")
-grid("on")
-title("Gradient")
-
-subplot(223, projection=None if nAx==2 else "3d")
-if nAx==2: plot(arrGrad[:,0], arrGrad[:,1], ".-")
-if nAx==3: plot(arrGrad[:,0], arrGrad[:,1], arrGrad[:,2], ".-")
-axis("equal")
-grid("on")
-title("g-Space")
-
-subplot(224)
-plot(norm(arrSlew,axis=-1)/(42.58e6)*(nPix/fov), ".-")
-ylim(sLim/(42.58e6)*(nPix/fov)*0.9, sLim/(42.58e6)*(nPix/fov)*1.1)
-grid("on")
-title(f"Slewrate, max:{max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov):.3f}")
-
-show()

mrarbgrad-4.3.0/example/example_ExternalSamples2D.py

@@ -1,84 +0,0 @@
-from numpy import *
-from numpy.linalg import norm
-from matplotlib.pyplot import *
-import mrarbgrad as mag
-
-gamma = 42.5756e6
-fov = 0.256
-nPix = 256
-dtGrad = 10e-6
-dtADC = 2.5e-6
-sLim = 50 * gamma * fov/nPix
-gLim = 20e-3 * gamma * fov/nPix
-# gLim = 1/nPix/dtADC
-
-# Rosette
-om1 = 5*pi
-om2 = 3*pi
-pLim = [0,1]
-def TrajFunc(t):
-    rho = 0.5*sin(om1*t)
-    return array\
-    ([
-        rho*cos(om2*t),
-        rho*sin(om2*t),
-        zeros_like(t)
-    ])
-
-# sample
-arrP = linspace(pLim[0], pLim[1], 1000)
-arrK = TrajFunc(arrP).T
-nAx = 2
-
-# derive slew-rate constrained trajectory
-for i in range(1):
-    arrGrad = mag.calGrad4ExSamp(fov, nPix, sLim, gLim, dtGrad, arrK)[0]
-    # arrGrad = mag.gradClip(arrGrad, dtGrad, sLim, gLim) # clip slew/grad amp with hardware constraint
-nRO = arrGrad.shape[0]
-
-arrSlew = diff(arrGrad, axis=0)/dtGrad
-print(f"sMax: {max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov)}")
-
-arrK, _ = mag.cvtGrad2Traj(arrGrad, dtGrad, dtADC, 0.5)
-arrK += TrajFunc(pLim[0])
-print(f"Err: {norm(arrK[-1,:]-TrajFunc(pLim[1])):.1e}")
-
-# derive reference trajectory
-arrP_Ref = linspace(pLim[0], pLim[1], int(1e4))
-arrK_Ref = TrajFunc(arrP_Ref).T
-
-# plot
-figure(figsize=(20,10), dpi=120)
-
-subplot(221, projection=None if nAx==2 else "3d")
-if nAx==2: plot(arrK_Ref[:,0], arrK_Ref[:,1], "--", label="K_Ref")
-if nAx==3: plot(arrK_Ref[:,0], arrK_Ref[:,1], arrK_Ref[:,2], "--", label="K_Ref")
-if nAx==2: plot(arrK[:,0], arrK[:,1], ".-", label="K_Imp")
-if nAx==3: plot(arrK[:,0], arrK[:,1], arrK[:,2], ".-", label="K_Imp")
-xlim(-0.5,0.5)
-ylim(-0.5,0.5)
-axis("equal")
-grid("on")
-legend()
-title("k-Space")
-
-subplot(222)
-for iAx in range(nAx):
-    plot(arrGrad[:,iAx]/(42.58e6)*(nPix/fov), ".-")
-grid("on")
-title("Gradient")
-
-subplot(223, projection=None if nAx==2 else "3d")
-if nAx==2: plot(arrGrad[:,0], arrGrad[:,1], ".-")
-if nAx==3: plot(arrGrad[:,0], arrGrad[:,1], arrGrad[:,2], ".-")
-axis("equal")
-grid("on")
-title("g-Space")
-
-subplot(224)
-plot(norm(arrSlew,axis=-1)/(42.58e6)*(nPix/fov), ".-")
-ylim(sLim/(42.58e6)*(nPix/fov)*0.9, sLim/(42.58e6)*(nPix/fov)*1.1)
-grid("on")
-title(f"Slewrate, max:{max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov):.3f}")
-
-show()

mrarbgrad-4.3.0/example/example_ExternalSamples3D.py

@@ -1,72 +0,0 @@
-from numpy import *
-from numpy.linalg import norm
-from matplotlib.pyplot import *
-import mrarbgrad as mag
-
-gamma = 42.5756e6
-fov = 0.256
-nPix = 256
-dtGrad = 10e-6
-dtADC = 2.5e-6
-sLim = 50 * gamma * fov/nPix
-gLim = 20e-3 * gamma * fov/nPix
-# gLim = 1/nPix/dtADC
-
-# Yarnball
-nAx = 3
-
-kRhoPhi = 0.5/(2*pi)
-Yarnball = lambda sqrtTht: mag.trajfunc.Yarnball(sqrtTht, kRhoPhi)
-pLim = mag.trajfunc.prange_Yarnball(kRhoPhi)
-    
-arrP = linspace(pLim[0], pLim[1], 1000)
-arrK = Yarnball(arrP)
-
-# derive slew-rate constrained trajectory
-mag.setDbgPrint(1)
-arrGrad = mag.calGrad4ExSamp(fov, nPix, sLim, gLim, dtGrad, arrK)[0]
-# arrGrad = mag.gradClip(arrGrad, dtGrad, sLim, gLim) # clip slew/grad amp with hardware constraint
-nRO = arrGrad.shape[0]
-
-arrSlew = diff(arrGrad, axis=0)/dtGrad
-print(f"sMax: {max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov)}")
-
-arrK, _ = mag.cvtGrad2Traj(arrGrad, dtGrad, dtADC, 0.5)
-
-# derive reference trajectory
-arrP_Ref = linspace(pLim[0], pLim[1], int(1e4))
-arrK_Ref = Yarnball(arrP_Ref)
-
-# plot
-figure(figsize=(20,10), dpi=120)
-
-subplot(221, projection="3d")
-plot(arrK_Ref[:,0], arrK_Ref[:,1], arrK_Ref[:,2], "--", label="K_Ref")
-plot(arrK[:,0], arrK[:,1], arrK[:,2], ".-", label="K_Imp")
-xlim(-0.5,0.5)
-ylim(-0.5,0.5)
-axis("equal")
-grid("on")
-legend()
-title("k-Space")
-
-subplot(222)
-for iAx in range(nAx):
-    plot(arrGrad[:,iAx]/(42.58e6)*(nPix/fov), ".-")
-grid("on")
-title("Gradient")
-
-subplot(223, projection=None if nAx==2 else "3d")
-if nAx==2: plot(arrGrad[:,0], arrGrad[:,1], ".-")
-if nAx==3: plot(arrGrad[:,0], arrGrad[:,1], arrGrad[:,2], ".-")
-axis("equal")
-grid("on")
-title("g-Space")
-
-subplot(224)
-plot(norm(arrSlew,axis=-1)/(42.58e6)*(nPix/fov), ".-")
-ylim(sLim/(42.58e6)*(nPix/fov)*0.9, sLim/(42.58e6)*(nPix/fov)*1.1)
-grid("on")
-title(f"Slewrate, max:{max(norm(arrSlew,axis=-1))/(42.58e6)*(nPix/fov):.3f}")
-
-show()