rename parameters and fix ordering

Author: chaithyagr

src/mrinufft/io/nsp.py

@@ -293,8 +293,8 @@ def write_trajectory(
                 "please set version to 5.1 or higher."
             )
         start_gradients = get_gradient_amplitudes_to_travel_for_set_time(
-            ke=initial_positions,
-            ge=gradients[:, 0],
+            kspace_end_loc=initial_positions,
+            end_gradients=gradients[:, 0],
             **scan_consts,
         )
         initial_positions = np.zeros_like(initial_positions)
@@ -311,9 +311,9 @@ def write_trajectory(
             # Always end at KMax, the spoilers can be handeled by the sequence.
             edge_locations[..., 0] = img_size[0] / FOV[0] / 2
         end_gradients = get_gradient_amplitudes_to_travel_for_set_time(
-            ke=edge_locations,
-            gs=gradients[:, -1],
-            ks=final_positions,
+            kspace_end_loc=edge_locations,
+            start_gradients=gradients[:, -1],
+            kspace_start_loc=final_positions,
             **scan_consts,
         )
         gradients = np.hstack([gradients, end_gradients])

src/mrinufft/trajectories/tools.py

@@ -379,10 +379,10 @@ def unepify(trajectory: NDArray, Ns_readouts: int, Ns_transitions: int) -> NDArr
 
 
 def get_gradient_times_to_travel(
-    ks: NDArray | None = None,
-    ke: NDArray | None = None,
-    gs: NDArray | None = None,
-    ge: NDArray | None = None,
+    kspace_end_loc: NDArray | None = None,
+    kspace_start_loc: NDArray | None = None,
+    end_gradients: NDArray | None = None,
+    start_gradients: NDArray | None = None,
     gamma: float = Gammas.Hydrogen,
     raster_time: float = DEFAULT_RASTER_TIME,
     gmax: float = DEFAULT_GMAX,
@@ -400,14 +400,14 @@ def get_gradient_times_to_travel(
 
     Parameters
     ----------
-    ks : NDArray
-        Starting k-space positions, shape (nb_shots, nb_dimension).
-    ke : NDArray, default None when it is 0
+    kspace_end_loc : NDArray
         Ending k-space positions, shape (nb_shots, nb_dimension).
-    gs : NDArray, default None when it is 0
-        Starting gradient values, shape (nb_shots, nb_dimension).
-    ge : NDArray, default None when it is 0
+    kspace_start_loc : NDArray, default None when it is 0
+        Starting k-space positions, shape (nb_shots, nb_dimension).
+    end_gradients : NDArray, default None when it is 0
         Ending gradient values, shape (nb_shots, nb_dimension).
+    start_gradients : NDArray, default None when it is 0
+        Starting gradient values, shape (nb_shots, nb_dimension).
     gamma : float, optional
         Gyromagnetic ratio in Hz/T. Default is Gammas.Hydrogen.
     raster_time : float, optional
@@ -425,19 +425,19 @@ def get_gradient_times_to_travel(
     n_plateau: The timing values for the plateau phase.
     gi: The intermediate gradient values for trapezoidal or triangular waveforms.
     """
-    area_needed = (ke - ks) / gamma / raster_time
+    area_needed = (kspace_end_loc - kspace_start_loc) / gamma / raster_time
 
     # Direct ramp steps
-    n_direct = np.ceil((ge - gs) / smax / raster_time).astype(int)
-    area_direct = 0.5 * n_direct * (ge + gs)
+    n_direct = np.ceil((end_gradients - start_gradients) / smax / raster_time).astype(int)
+    area_direct = 0.5 * n_direct * (end_gradients + start_gradients)
 
     i = np.sign(area_direct - area_needed)
 
-    n_ramp_down = np.ceil((gmax + i * gs) / smax / raster_time).astype(int)
-    n_ramp_up = np.ceil((gmax + i * ge) / smax / raster_time).astype(int)
+    n_ramp_down = np.ceil((gmax + i * start_gradients) / smax / raster_time).astype(int)
+    n_ramp_up = np.ceil((gmax + i * end_gradients) / smax / raster_time).astype(int)
 
-    area_lowest = n_ramp_down * 0.5 * (gs - i * gmax) + n_ramp_up * 0.5 * (
-        ge - i * gmax
+    area_lowest = n_ramp_down * 0.5 * (start_gradients - i * gmax) + n_ramp_up * 0.5 * (
+        end_gradients - i * gmax
     )
 
     gi = np.zeros_like(n_ramp_down, dtype=np.float32)
@@ -447,8 +447,8 @@ def get_gradient_times_to_travel(
     ramp_only_mask = np.abs(area_lowest) >= np.abs(area_needed)
     gi[ramp_only_mask] = (
         2 * area_needed[ramp_only_mask]
-        - (n_ramp_down[ramp_only_mask] + 1) * gs[ramp_only_mask]
-        - (n_ramp_up[ramp_only_mask] - 1) * ge[ramp_only_mask]
+        - (n_ramp_down[ramp_only_mask] + 1) * start_gradients[ramp_only_mask]
+        - (n_ramp_up[ramp_only_mask] - 1) * end_gradients[ramp_only_mask]
     ) / (n_ramp_down[ramp_only_mask] + n_ramp_up[ramp_only_mask])
 
     # Else: need plateau
@@ -461,8 +461,8 @@ def get_gradient_times_to_travel(
 
     gi[plateau_mask] = (
         2 * area_needed[plateau_mask]
-        - (n_ramp_down[plateau_mask] + 1) * gs[plateau_mask]
-        - (n_ramp_up[plateau_mask] - 1) * ge[plateau_mask]
+        - (n_ramp_down[plateau_mask] + 1) * start_gradients[plateau_mask]
+        - (n_ramp_up[plateau_mask] - 1) * end_gradients[plateau_mask]
     ) / (
         n_ramp_down[plateau_mask]
         + n_ramp_up[plateau_mask]
@@ -473,11 +473,11 @@ def get_gradient_times_to_travel(
 
 
 def get_gradient_amplitudes_to_travel_for_set_time(
-    ke: NDArray,
-    ks: NDArray | None = None,
-    gs: NDArray | None = None,
-    ge: NDArray | None = None,
-    N: int | None = None,
+    kspace_end_loc: NDArray,
+    kspace_start_loc: NDArray | None = None,
+    end_gradients: NDArray | None = None,
+    start_gradients: NDArray | None = None,
+    nb_raster_points: int | None = None,
     gamma: float = Gammas.Hydrogen,
     raster_time: float = DEFAULT_RASTER_TIME,
     gmax: float = DEFAULT_GMAX,
@@ -495,15 +495,15 @@ def get_gradient_amplitudes_to_travel_for_set_time(
 
     Parameters
     ----------
-    ke : NDArray
+    kspace_end_loc : NDArray
         Ending k-space positions, shape (nb_shots, nb_dimension).
-    ks : NDArray, default None when it is 0
+    kspace_start_loc : NDArray, default None when it is 0
         Starting k-space positions, shape (nb_shots, nb_dimension).
-    gs : NDArray, default None when it is 0
-        Starting gradient values, shape (nb_shots, nb_dimension).
-    ge : NDArray, default None when it is 0
+    end_gradients : NDArray, default None when it is 0
         Ending gradient values, shape (nb_shots, nb_dimension).
-    N : int, default None
+    start_gradients : NDArray, default None when it is 0
+        Starting gradient values, shape (nb_shots, nb_dimension).
+    nb_raster_points : int, default None
         Number of time steps (samples) for the gradient waveform.
         If None, timing is calculated based on the area needed and hardware limits.
     gamma : float, optional
@@ -517,7 +517,7 @@ def get_gradient_amplitudes_to_travel_for_set_time(
 
     Returns
     -------
-    G : NDArray
+    NDArray
         Gradient waveforms, shape (nb_shots, nb_samples_per_shot, nb_dimension)
         , where each entry contains the gradient value at each time step
          for each shot and dimension.
@@ -529,46 +529,46 @@ def get_gradient_amplitudes_to_travel_for_set_time(
     - The returned gradients are suitable for use in MRI pulse sequence design,
       ensuring compliance with specified hardware constraints.
     """
-    ke = np.atleast_2d(ke)
-    if ks is None:
-        ks = np.zeros_like(ke)
-    if gs is None:
-        gs = np.zeros_like(ke)
-    if ge is None:
-        ge = np.zeros_like(ke)
-    ks = np.atleast_2d(ks)
-    gs = np.atleast_2d(gs)
-    ge = np.atleast_2d(ge)
+    kspace_end_loc = np.atleast_2d(kspace_end_loc)
+    if kspace_start_loc is None:
+        kspace_start_loc = np.zeros_like(kspace_end_loc)
+    if start_gradients is None:
+        start_gradients = np.zeros_like(kspace_end_loc)
+    if end_gradients is None:
+        end_gradients = np.zeros_like(kspace_end_loc)
+    kspace_start_loc = np.atleast_2d(kspace_start_loc)
+    start_gradients = np.atleast_2d(start_gradients)
+    end_gradients = np.atleast_2d(end_gradients)
 
     assert (
-        ks.shape == ke.shape == gs.shape == ge.shape
+        kspace_start_loc.shape == kspace_end_loc.shape == start_gradients.shape == end_gradients.shape
     ), "All input arrays must have shape (nb_shots, nb_dimension)"
-    if N is None:
+    if nb_raster_points is None:
         # Calculate the number of time steps based on the area needed
         n_ramp_down, n_ramp_up, n_plateau, gi = get_gradient_times_to_travel(
-            ks=ks,
-            ke=ke,
-            ge=ge,
-            gs=gs,
+            kspace_end_loc=kspace_end_loc,
+            kspace_start_loc=kspace_start_loc,
+            end_gradients=end_gradients,
+            start_gradients=start_gradients,
             gamma=gamma,
             raster_time=raster_time,
             gmax=gmax,
             smax=smax,
         )
         # Extra 2 buffer samples
-        N = np.max(n_ramp_down + n_ramp_up + n_plateau) + 2
+        nb_raster_points = np.max(n_ramp_down + n_ramp_up + n_plateau) + 2
 
-    area_needed = (ke - ks) / gamma / raster_time
+    area_needed = (kspace_end_loc - kspace_start_loc) / gamma / raster_time
     # Intermediate gradient values. This is value of plateau or triangle gradients
-    gi = np.zeros_like(ks, dtype=np.float32)
+    gi = np.zeros_like(kspace_start_loc, dtype=np.float32)
 
     # Get the area for direct and estimate n_ramps
-    area_direct = 0.5 * N * (ge + gs)
+    area_direct = 0.5 * nb_raster_points * (end_gradients + start_gradients)
     i = np.sign(area_direct - area_needed)
 
-    n_ramp_down = np.ceil((gmax + i * gs) / smax / raster_time).astype(int)
-    n_ramp_up = np.ceil((gmax + i * ge) / smax / raster_time).astype(int)
-    n_plateau = N - n_ramp_up - n_ramp_down
+    n_ramp_down = np.ceil((gmax + i * start_gradients) / smax / raster_time).astype(int)
+    n_ramp_up = np.ceil((gmax + i * end_gradients) / smax / raster_time).astype(int)
+    n_plateau = nb_raster_points - n_ramp_up - n_ramp_down
 
     # Get intermediate gradients for triangle waveform, when n_plateau<0
     no_trapazoid = n_plateau <= 0
@@ -577,35 +577,35 @@ def get_gradient_amplitudes_to_travel_for_set_time(
     # Initial approximate calculation of gi
     gi[no_trapazoid] = (
         2 * area_needed[no_trapazoid]
-        - N * ge[no_trapazoid] * smax
-        - ge[no_trapazoid] * gs[no_trapazoid]
-        + ge[no_trapazoid] * smax
-        - gs[no_trapazoid] * smax
-        + gs[no_trapazoid] * gs[no_trapazoid]
-    ) / (N * smax - ge[no_trapazoid] + gs[no_trapazoid])
+        - nb_raster_points * end_gradients[no_trapazoid] * smax
+        - end_gradients[no_trapazoid] * start_gradients[no_trapazoid]
+        + end_gradients[no_trapazoid] * smax
+        - start_gradients[no_trapazoid] * smax
+        + start_gradients[no_trapazoid] * start_gradients[no_trapazoid]
+    ) / (nb_raster_points * smax - end_gradients[no_trapazoid] + start_gradients[no_trapazoid])
     n_ramp_down[no_trapazoid] = np.ceil(
-        np.abs(gi[no_trapazoid] - gs[no_trapazoid]) / smax
+        np.abs(gi[no_trapazoid] - start_gradients[no_trapazoid]) / smax
     )
-    n_ramp_up[no_trapazoid] = N - n_ramp_down[no_trapazoid]
+    n_ramp_up[no_trapazoid] = nb_raster_points - n_ramp_down[no_trapazoid]
 
     # Get intermediate gradients for trapazoids
-    gi = (2 * area_needed - (n_ramp_down + 1) * gs - (n_ramp_up - 1) * ge) / (
+    gi = (2 * area_needed - (n_ramp_down + 1) * start_gradients - (n_ramp_up - 1) * end_gradients) / (
         n_ramp_down + n_ramp_up + 2 * n_plateau
     )
-    nb_shots, nb_dimension = ke.shape
-    G = np.zeros((nb_shots, N, nb_dimension), dtype=np.float32)
+    nb_shots, nb_dimension = kspace_end_loc.shape
+    G = np.zeros((nb_shots, nb_raster_points, nb_dimension), dtype=np.float32)
     for i in range(nb_shots):
         for d in range(nb_dimension):
             start = 0
             G[i, : n_ramp_down[i, d], d] = np.linspace(
-                gs[i, d], gi[i, d], n_ramp_down[i, d], endpoint=False
+                start_gradients[i, d], gi[i, d], n_ramp_down[i, d], endpoint=False
             )
             start += n_ramp_down[i, d]
             if n_plateau[i, d] > 0:
                 G[i, start : start + n_plateau[i, d], d] = gi[i, d]
                 start += n_plateau[i, d]
             G[i, start : start + n_ramp_up[i, d], d] = np.linspace(
-                gi[i, d], ge[i, d], n_ramp_up[i, d], endpoint=False
+                gi[i, d], end_gradients[i, d], n_ramp_up[i, d], endpoint=False
             )
     return G
 

tests/test_io.py

@@ -63,8 +63,8 @@ def test_trajectory_state_changer(kspace_loc, shape, gamma, raster_time, gmax, s
     trajectory = kspace_loc / resolution
     gradients = np.diff(trajectory, axis=1) / gamma / raster_time
     GS = get_gradient_amplitudes_to_travel_for_set_time(
-        ke=trajectory[:, 0],
-        ge=gradients[:, 0],
+        kspace_end_loc=trajectory[:, 0],
+        end_gradients=gradients[:, 0],
         gamma=gamma,
         raster_time=raster_time,
         gmax=gmax,
@@ -84,9 +84,9 @@ def test_trajectory_state_changer(kspace_loc, shape, gamma, raster_time, gmax, s
     np.testing.assert_allclose(GS[:, 0], 0, atol=1e-5)
 
     GE = get_gradient_amplitudes_to_travel_for_set_time(
-        ks=trajectory[:, -1],
-        ke=np.zeros_like(trajectory[:, -1]),
-        gs=gradients[:, -1],
+        kspace_start_loc=trajectory[:, -1],
+        kspace_end_loc=np.zeros_like(trajectory[:, -1]),
+        start_gradients=gradients[:, -1],
         gamma=gamma,
         raster_time=raster_time,
         gmax=gmax,