Consolidate cartesian interp option and introduce structured SimulationResult return

kwave/data.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Optional
 
 import numpy as np
 
@@ -119,3 +119,128 @@ def append(self, val):
         assert len(self.data) <= 2
         self.data.append(val)
         return self
+
+
+@dataclass
+class SimulationResult:
+    """
+    Structured return type for kWave simulation results.
+
+    Contains all possible fields that can be returned by the kWave C++ binaries.
+    Fields are populated based on the sensor.record configuration.
+    """
+
+    # Grid information (always present)
+    Nx: int
+    Ny: int
+    Nz: int
+    Nt: int
+    pml_x_size: int
+    pml_y_size: int
+    pml_z_size: int
+    axisymmetric_flag: bool
+
+    # Pressure fields (optional - based on sensor.record). Field names match
+    # the user-facing sensor.record keys, not the binary's HDF5 dataset names
+    # (e.g. sensor.record=("p",) → result.p; binary dataset is "p_raw").
+    p: Optional[np.ndarray] = None
+    p_max: Optional[np.ndarray] = None
+    p_min: Optional[np.ndarray] = None
+    p_rms: Optional[np.ndarray] = None
+    p_max_all: Optional[np.ndarray] = None
+    p_min_all: Optional[np.ndarray] = None
+    p_final: Optional[np.ndarray] = None
+
+    # Velocity fields (optional - based on sensor.record). `u` is the
+    # collocated (pressure-grid) velocity; `u_staggered` is the mid-cell
+    # variant. The legacy C++ binary inverts this naming (its "u" is
+    # mid-cell and "u_non_staggered" is collocated); from_dotdict
+    # translates so the user-facing API always uses the modern convention.
+    u: Optional[np.ndarray] = None
+    u_max: Optional[np.ndarray] = None
+    u_min: Optional[np.ndarray] = None
+    u_rms: Optional[np.ndarray] = None
+    u_max_all: Optional[np.ndarray] = None
+    u_min_all: Optional[np.ndarray] = None
+    u_final: Optional[np.ndarray] = None
+    u_staggered: Optional[np.ndarray] = None
+
+    # Intensity fields (optional - based on sensor.record)
+    I_avg: Optional[np.ndarray] = None
+    I: Optional[np.ndarray] = None
+
+    def __getitem__(self, key: str):
+        """
+        Enable dictionary-style access for backward compatibility.
+
+        Args:
+            key: Field name to access
+
+        Returns:
+            Value of the field
+
+        Raises:
+            KeyError: If the field does not exist
+        """
+        if hasattr(self, key):
+            return getattr(self, key)
+        raise KeyError(f"'{key}' field not found in SimulationResult")
+
+    def __contains__(self, key: str) -> bool:
+        """
+        Enable dictionary-style membership testing for backward compatibility.
+
+        Args:
+            key: Field name to check
+
+        Returns:
+            True if the field exists, False otherwise
+        """
+        return hasattr(self, key)
+
+    @classmethod
+    def from_dotdict(cls, data: dict) -> "SimulationResult":
+        """
+        Create SimulationResult from dotdict returned by parse_executable_output.
+
+        Args:
+            data: Dictionary containing simulation results from HDF5 file
+
+        Returns:
+            SimulationResult instance with all available fields populated
+        """
+        return cls(
+            # Grid information
+            Nx=int(data.get("Nx", 0)),
+            Ny=int(data.get("Ny", 0)),
+            Nz=int(data.get("Nz", 0)),
+            Nt=int(data.get("Nt", 0)),
+            pml_x_size=int(data.get("pml_x_size", 0)),
+            pml_y_size=int(data.get("pml_y_size", 0)),
+            pml_z_size=int(data.get("pml_z_size", 0)),
+            axisymmetric_flag=bool(data.get("axisymmetric_flag", False)),
+            # Pressure fields — the binary writes HDF5 datasets named after
+            # sensor.record keys (e.g. /p, /p_max, /p_final), not the --p_raw
+            # CLI flag name, so we look up by the user-facing names.
+            p=data.get("p"),
+            p_max=data.get("p_max"),
+            p_min=data.get("p_min"),
+            p_rms=data.get("p_rms"),
+            p_max_all=data.get("p_max_all"),
+            p_min_all=data.get("p_min_all"),
+            p_final=data.get("p_final"),
+            # Velocity fields. Legacy C++ binary names are inverted vs the
+            # modern user-facing convention: binary's `u` is mid-cell
+            # (staggered), binary's `u_non_staggered` is collocated.
+            u=data.get("u_non_staggered"),
+            u_max=data.get("u_max"),
+            u_min=data.get("u_min"),
+            u_rms=data.get("u_rms"),
+            u_max_all=data.get("u_max_all"),
+            u_min_all=data.get("u_min_all"),
+            u_final=data.get("u_final"),
+            u_staggered=data.get("u"),
+            # Intensity fields
+            I_avg=data.get("I_avg"),
+            I=data.get("I"),
+        )

kwave/executor.py

@@ -6,6 +6,7 @@
 import h5py
 
 import kwave
+from kwave.data import SimulationResult
 from kwave.options.simulation_execution_options import SimulationExecutionOptions
 from kwave.utils.dotdictionary import dotdict
 
@@ -32,7 +33,7 @@ def _make_binary_executable(self):
             raise FileNotFoundError(f"Binary not found at {binary_path}")
         binary_path.chmod(binary_path.stat().st_mode | stat.S_IEXEC)
 
-    def run_simulation(self, input_filename: str, output_filename: str, options: list[str]) -> dotdict:
+    def run_simulation(self, input_filename: str, output_filename: str, options: list[str]) -> SimulationResult:
         command = [str(self.execution_options.binary_path), "-i", input_filename, "-o", output_filename] + options
 
         try:
@@ -68,7 +69,7 @@ def run_simulation(self, input_filename: str, output_filename: str, options: lis
         if not self.simulation_options.pml_inside:
             self._crop_pml(sensor_data)
 
-        return sensor_data
+        return SimulationResult.from_dotdict(sensor_data)
 
     def _crop_pml(self, sensor_data: dotdict):
         Nx = sensor_data["Nx"].item()

kwave/kspaceFirstOrder2D.py

@@ -1,9 +1,10 @@
 import warnings
-from typing import Union
+from typing import Optional, Union
 
 import numpy as np
 from beartype import beartype as typechecker
 
+from kwave.data import SimulationResult
 from kwave.executor import Executor
 from kwave.kgrid import kWaveGrid
 from kwave.kmedium import kWaveMedium
@@ -86,7 +87,7 @@ def kspaceFirstOrder2DC(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-):
+) -> Optional[SimulationResult]:
     """
     2D time-domain simulation of wave propagation using C++ code.
 
@@ -146,7 +147,7 @@ def kspaceFirstOrder2D(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-):
+) -> Optional[SimulationResult]:
     """
     2D time-domain simulation of wave propagation using k-space pseudospectral method.
 

kwave/kspaceFirstOrder3D.py

@@ -1,9 +1,9 @@
 import warnings
-from typing import Union
+from typing import Optional, Union
 
 import numpy as np
-from deprecated import deprecated
 
+from kwave.data import SimulationResult
 from kwave.executor import Executor
 from kwave.kgrid import kWaveGrid
 from kwave.kmedium import kWaveMedium
@@ -27,7 +27,7 @@ def kspaceFirstOrder3DG(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-) -> Union[np.ndarray, dict]:
+) -> Optional[SimulationResult]:
     """
     3D time-domain simulation of wave propagation on a GPU using C++ CUDA code.
 
@@ -81,7 +81,7 @@ def kspaceFirstOrder3DC(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-):
+) -> Optional[SimulationResult]:
     """
     3D time-domain simulation of wave propagation using C++ code.
 
@@ -138,7 +138,7 @@ def kspaceFirstOrder3D(
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
     time_rev: bool = False,  # deprecated parameter
-):
+) -> Optional[SimulationResult]:
     """
     3D time-domain simulation of wave propagation using k-space pseudospectral method.
 

kwave/kspaceFirstOrderAS.py

@@ -1,9 +1,10 @@
 import logging
-from typing import Union
+from typing import Optional, Union
 
 import numpy as np
 from numpy.fft import ifftshift
 
+from kwave.data import SimulationResult
 from kwave.enums import DiscreteCosine
 from kwave.executor import Executor
 from kwave.kgrid import kWaveGrid
@@ -30,7 +31,7 @@ def kspaceFirstOrderASC(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-):
+) -> Optional[SimulationResult]:
     """
     Axisymmetric time-domain simulation of wave propagation using C++ code.
 
@@ -89,7 +90,7 @@ def kspaceFirstOrderAS(
     medium: kWaveMedium,
     simulation_options: SimulationOptions,
     execution_options: SimulationExecutionOptions,
-):
+) -> Optional[SimulationResult]:
     """
     Axisymmetric time-domain simulation of wave propagation.
 
@@ -158,7 +159,7 @@ def kspaceFirstOrderAS(
     if simulation_options.simulation_type is not SimulationType.AXISYMMETRIC:
         logging.log(
             logging.WARN,
-            "simulation type is not set to axisymmetric while using kSapceFirstOrderAS. " "Setting simulation type to axisymmetric.",
+            "simulation type is not set to axisymmetric while using kSapceFirstOrderAS. Setting simulation type to axisymmetric.",
         )
         simulation_options.simulation_type = SimulationType.AXISYMMETRIC
 
@@ -296,7 +297,7 @@ def kspaceFirstOrderAS(
 
     # option to run simulations without the spatial staggered grid is not
     # supported for the axisymmetric code
-    assert options.use_sg, "Optional input " "UseSG" " is not supported for axisymmetric simulations."
+    assert options.use_sg, "Optional input UseSG is not supported for axisymmetric simulations."
 
     # =========================================================================
     # SAVE DATA TO DISK FOR RUNNING SIMULATION EXTERNAL TO MATLAB

kwave/options/simulation_options.py

@@ -47,10 +47,6 @@ class SimulationOptions(object):
     """
     Args:
         axisymmetric: Flag that indicates whether axisymmetric simulation is used
-        cart_interp: Interpolation mode used to extract the pressure when a Cartesian sensor mask is given.
-                     If set to 'nearest' and more than one Cartesian point maps to the same grid point,
-                     duplicated data points are discarded and sensor_data will be returned
-                     with less points than that specified by sensor.mask (default = 'linear').
         pml_inside: put the PML inside the grid defined by the user
         pml_alpha: Absorption within the perfectly matched layer in Nepers per grid point (default = 2).
         save_to_disk: save the input data to a HDF5 file
@@ -85,7 +81,6 @@ class SimulationOptions(object):
     """
 
     simulation_type: SimulationType = SimulationType.FLUID
-    cart_interp: str = "linear"
     pml_inside: bool = True
     pml_alpha: float = 2.0
     save_to_disk: bool = False
@@ -203,9 +198,6 @@ def option_factory(kgrid: "kWaveGrid", options: SimulationOptions):
             elastic_code: Flag that indicates whether elastic simulation is used
             **kwargs: Dictionary that holds following optional simulation properties:
 
-                * cart_interp: Interpolation mode used to extract the pressure when a Cartesian sensor mask is given.
-                               If set to 'nearest', duplicated data points are discarded and sensor_data
-                               will be returned with fewer points than specified by sensor.mask (default = 'linear').
                 * create_log: Boolean controlling whether the command line output is saved using the diary function
                               with a date and time stamped filename (default = false).
                 * data_cast: String input of the data type that variables are cast to before computation.