Fix Greptile P1+P2: guard MATLAB multi-source reordering, fix FutureWarning sentinel

P1: simulate_from_dicts now reorders multi-row source signals from
MATLAB's F-flat mask ordering to C-flat before passing to the solver.
Previously this was documented but unguarded — callers with multi-source
signals would get wrong physics.

P2: FutureWarning in cart2grid, combine_sensor_data, get_distributed_source_signal
now uses a sentinel default so explicit order="F" does NOT warn. Only
implicit (unspecified) default triggers the deprecation warning.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: waltsims

kwave/solvers/kspace_solver.py

@@ -779,12 +779,52 @@ def create_simulation(kgrid, medium, source, sensor, device="auto", smooth_p0=Fa
     )
 
 
+def _f_to_c_source_reorder(source, grid_shape):
+    """Reorder multi-row source signals from MATLAB F-flat to C-flat mask order.
+
+    MATLAB sends source signal rows ordered by F-flattened mask indices.
+    The solver uses C-flat ordering internally.  For single-row (uniform)
+    sources, no reordering is needed.
+    """
+    ndim = len(grid_shape)
+    if ndim < 2:
+        return source
+
+    for mask_key, signal_keys in [("p_mask", ["p"]), ("u_mask", ["ux", "uy", "uz"])]:
+        mask_raw = source.get(mask_key)
+        if mask_raw is None:
+            continue
+        mask = np.asarray(mask_raw, dtype=bool)
+        if mask.size <= 1:
+            continue
+        mask_grid = mask.reshape(grid_shape)
+        n_src = int(mask_grid.sum())
+        if n_src < 2:
+            continue
+
+        # Build F→C permutation for mask points
+        f_nz = np.where(mask_grid.ravel(order="F"))[0]
+        c_nz = np.where(mask_grid.ravel())[0]
+        f_equiv = np.ravel_multi_index(np.unravel_index(c_nz, grid_shape), grid_shape, order="F")
+        perm = np.searchsorted(f_nz, f_equiv)
+
+        for sig_key in signal_keys:
+            sig = source.get(sig_key)
+            if sig is None:
+                continue
+            sig = np.asarray(sig)
+            if sig.ndim >= 2 and sig.shape[0] == n_src:
+                source[sig_key] = sig[perm]
+
+    return source
+
+
 def simulate_from_dicts(kgrid, medium, source, sensor, device="auto", smooth_p0=False):
     """MATLAB interop entry point.
 
-    NOTE: The solver uses C-order internally.  MATLAB sends grid-shaped arrays
-    (which are order-agnostic via logical indexing) but source signals with
-    rows ordered by F-flattened mask positions.  Multi-row source signals from
-    MATLAB may need reordering at the kWavePy shim layer.
+    Reorders multi-row source signals from MATLAB's F-flat mask ordering
+    to the solver's C-flat ordering before running the simulation.
     """
+    grid_shape = tuple(kgrid[k] for k in ["Nx", "Ny", "Nz"] if k in kgrid)
+    source = _f_to_c_source_reorder(source, grid_shape)
     return create_simulation(kgrid, medium, source, sensor, device, smooth_p0=smooth_p0).run()

kwave/utils/conversion.py

@@ -13,6 +13,8 @@
 from kwave.utils.matlab import matlab_mask
 from kwave.utils.matrix import sort_rows
 
+_default = object()  # sentinel for detecting implicit default order="F"
+
 
 @typechecker
 def db2neper(alpha: Real[kt.ArrayLike, "..."], y: Real[kt.ScalarLike, ""] = 1) -> Real[kt.ArrayLike, "..."]:
@@ -165,7 +167,7 @@ def cart2grid(
     cart_data: Union[Float[ndarray, "1 NumPoints"], Float[ndarray, "2 NumPoints"], Float[ndarray, "3 NumPoints"]],
     axisymmetric: bool = False,
     *,
-    order: str = "F",
+    order: str = _default,
 ) -> Tuple:
     """Interpolate Cartesian points onto a binary grid using nearest neighbour.
 
@@ -180,14 +182,15 @@ def cart2grid(
     Returns:
         (grid_data, order_index, reorder_index)
     """
-    if order == "F":
+    if order is _default:
         import warnings
 
         warnings.warn(
             "cart2grid default order='F' will change to order='C' in a future release. Pass order='C' explicitly.",
             FutureWarning,
             stacklevel=2,
         )
+        order = "F"
 
     # check for axisymmetric input
     if axisymmetric and kgrid.dim != 2:

kwave/utils/kwave_array.py

@@ -16,6 +16,8 @@
 from kwave.utils.math import make_affine, sinc
 from kwave.utils.matlab import matlab_assign, matlab_find, matlab_mask
 
+_DEFAULT_ORDER = object()  # sentinel for detecting implicit default order="F"
+
 
 @dataclass(eq=False)
 class Element:
@@ -692,15 +694,15 @@ def get_off_grid_points(self, kgrid, element_num, mask_only):
 
         return grid_weights
 
-    def get_distributed_source_signal(self, kgrid, source_signal, *, order="F"):
+    def get_distributed_source_signal(self, kgrid, source_signal, *, order=_DEFAULT_ORDER):
         """Distribute per-element source signals onto grid source points.
 
         Args:
             order: ``"C"`` for C-order (new API) or ``"F"`` for Fortran-order
                 (legacy).  Default ``"F"`` — will change to ``"C"`` in a
                 future release.
         """
-        if order == "F":
+        if order is _DEFAULT_ORDER:
             import warnings
 
             warnings.warn(
@@ -709,6 +711,7 @@ def get_distributed_source_signal(self, kgrid, source_signal, *, order="F"):
                 FutureWarning,
                 stacklevel=2,
             )
+            order = "F"
 
         start_time = time.time()
         self.check_for_elements()
@@ -753,22 +756,23 @@ def get_distributed_source_signal(self, kgrid, source_signal, *, order="F"):
 
         return distributed_source_signal
 
-    def combine_sensor_data(self, kgrid, sensor_data, *, order="F"):
+    def combine_sensor_data(self, kgrid, sensor_data, *, order=_DEFAULT_ORDER):
         """Combine sensor data from grid points back to array elements.
 
         Args:
             order: ``"C"`` for C-order (new API) or ``"F"`` for Fortran-order
                 (legacy).  Default ``"F"`` — will change to ``"C"`` in a
                 future release.
         """
-        if order == "F":
+        if order is _DEFAULT_ORDER:
             import warnings
 
             warnings.warn(
                 "combine_sensor_data default order='F' will change to order='C' in a future release. " "Pass order='C' explicitly.",
                 FutureWarning,
                 stacklevel=2,
             )
+            order = "F"
 
         self.check_for_elements()
 

tests/test_c_order.py

@@ -155,6 +155,18 @@ def test_cart2grid_warns_on_f_order(self):
         with pytest.warns(FutureWarning, match="cart2grid"):
             cart2grid(kgrid, cart)
 
+    def test_cart2grid_no_warn_on_explicit_f(self):
+        """Explicit order='F' should NOT warn — only implicit default warns."""
+        from kwave.utils.conversion import cart2grid
+
+        kgrid = kWaveGrid(Vector([32, 32]), Vector([1e-4, 1e-4]))
+        cart = np.array([[0.0], [0.0]])
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", FutureWarning)
+            cart2grid(kgrid, cart, order="F")
+
     def test_cart2grid_no_warn_on_c_order(self):
         from kwave.utils.conversion import cart2grid