fullwave25 1.2.6.dev0__tar.gz → 1.2.6.dev2__tar.gz

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "1.2.6-dev0"
+current_version = "1.2.6-dev2"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullwave25
-Version: 1.2.6.dev0
+Version: 1.2.6.dev2
 Summary: Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities
 Author: Masashi Sode, Gianmarco Pinton
 Maintainer: Masashi Sode

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/__init__.py

@@ -60,7 +60,7 @@ try:
     __version__ = version("fullwave")
 except PackageNotFoundError:
     # Update via bump-my-version, not manually
-    __version__ = "1.2.6-dev0"
+    __version__ = "1.2.6-dev2"
 
 VERSION = __version__  # for convenience
 logger.info("Fullwave version: %s", __version__)

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/sensor.py

@@ -21,13 +21,16 @@ class Sensor:
     outcoords: NDArray[np.int64]
     sampling_modulus_time: int = 1
 
-    def __init__(
+    def __init__(  # noqa: PLR0915
         self,
         mask: NDArray[np.bool] | None = None,
         sampling_modulus_time: int = 1,
         *,
         coords: NDArray[np.int64] | None = None,
         grid_shape: tuple[int, ...] | None = None,
+        mod_x: int | None = None,
+        mod_y: int | None = None,
+        mod_z: int = 0,
     ) -> None:
         """Sensor class for Fullwave.
 
@@ -36,7 +39,7 @@ class Sensor:
         mask : NDArray[np.bool] | None
             Binary matrix where the pressure is recorded at each time-step
             shape: [nx, ny] for 2D, [nx, ny, nz] for 3D.
-            Mutually exclusive with coords/grid_shape.
+            Mutually exclusive with coords/grid_shape and mod_x/mod_y.
         sampling_modulus_time: int
             Sampling modulus in time. Default is 1 (record at every time step).
             Changing this value to n will record the pressure every n time steps.
@@ -46,39 +49,95 @@ class Sensor:
             Must be provided together with grid_shape.
         grid_shape : tuple[int, ...] | None
             Shape of the computational grid. Required when using coords input.
+        mod_x : int | None
+            Spatial decimation stride in x (depth) for sparse-grid sensor output.
+            When provided together with mod_y, activates sparse-grid mode.
+            In this mode the solver binary generates sensor positions automatically
+            as [::mod_x, ::mod_y] (and [::mod_z] for 3D) across the domain,
+            ignoring any explicit coords/mask.  Mutually exclusive with mask/coords.
+        mod_y : int | None
+            Spatial decimation stride in y (lateral).  Must be provided with mod_x.
+        mod_z : int
+            Spatial decimation stride in z (elevational).  Only relevant in 3D simulations.
+            Providing mod_z > 0 together with mod_x and mod_y creates a 3D sparse sensor.
+            Default 0 (2D sensor, or no z-subsampling when used in a 3D run).
 
         Raises
         ------
         ValueError
             If grid_shape is not provided when using coords input.
             If both mask and coords are provided (mutually exclusive).
-            If neither mask nor coords (with grid_shape) is provided.
+            If only one of mod_x / mod_y is provided.
+            If mod_x/mod_y are mixed with mask or coords.
+            If none of the three input modes is supplied.
 
         """
-        if coords is not None:
+        if mod_x is not None or mod_y is not None:
+            # --- sparse-grid mode ---
+            if mod_x is None or mod_y is None:
+                msg = "Both mod_x and mod_y must be provided for sparse-grid sensor mode"
+                raise ValueError(msg)
+            if mask is not None or coords is not None:
+                msg = "mod_x/mod_y are mutually exclusive with mask and coords"
+                raise ValueError(msg)
+            if mod_x <= 0 or mod_y <= 0:
+                msg = "mod_x and mod_y must be positive integers"
+                raise ValueError(msg)
+            if mod_z < 0:
+                msg = "mod_z must be a non-negative integer"
+                raise ValueError(msg)
+            self.is_sparse_grid = True
+            self.mod_x = mod_x
+            self.mod_y = mod_y
+            self.mod_z = mod_z
+            self.is_3d = mod_z > 0
+            ndim = 3 if self.is_3d else 2
+            # Empty placeholder — the binary computes positions from mod values.
+            self.outcoords = np.empty((0, ndim), dtype=np.int64)
+            self.grid_shape = None
+        elif coords is not None:
             if grid_shape is None:
                 msg = "grid_shape is required when using coords input"
                 raise ValueError(msg)
             if mask is not None:
                 msg = "mask and coords are mutually exclusive"
                 raise ValueError(msg)
+            self.is_sparse_grid = False
+            self.mod_x = 0
+            self.mod_y = 0
+            self.mod_z = 0
             self.outcoords = np.atleast_2d(coords).astype(np.int64, copy=False)
             self.grid_shape = tuple(grid_shape)
+            self.is_3d = len(self.grid_shape) == 3
         elif mask is not None:
+            self.is_sparse_grid = False
+            self.mod_x = 0
+            self.mod_y = 0
+            self.mod_z = 0
             mask = np.atleast_2d(mask)
             self.grid_shape = mask.shape
             self.outcoords = map_to_coords(mask)
+            self.is_3d = len(self.grid_shape) == 3
         else:
-            msg = "Either mask or coords (with grid_shape) must be provided"
+            msg = "Either mask, coords (with grid_shape), or mod_x with mod_y must be provided"
             raise ValueError(msg)
 
         self.sampling_modulus_time = sampling_modulus_time
-        self.is_3d = len(self.grid_shape) == 3
         super().__init__()
         logger.debug("Sensor instance created.")
 
     def validate(self, grid_shape: NDArray[np.int64] | tuple) -> None:
         """Check if the sensor coordinates are consistent with the grid shape."""
+        if self.is_sparse_grid:
+            grid_shape = tuple(grid_shape) if isinstance(grid_shape, np.ndarray) else grid_shape
+            if len(grid_shape) == 3 and self.mod_z == 0:
+                msg = (
+                    "Sparse-grid sensor used in a 3D simulation but mod_z was not provided. "
+                    "Pass mod_z > 0 to Sensor (e.g. Sensor(mod_x=4, mod_y=4, mod_z=4))."
+                )
+                raise ValueError(msg)
+            logger.debug("Sparse-grid sensor validated.")
+            return
         grid_shape = tuple(grid_shape) if isinstance(grid_shape, np.ndarray) else grid_shape
         assert self.grid_shape == grid_shape, f"{self.grid_shape} != {grid_shape}"
         assert self.n_sensors > 0, "No active sensor found."
@@ -173,6 +232,11 @@ class Sensor:
             Formatted string containing source information.
 
         """
+        if self.is_sparse_grid:
+            mod_str = f"mod_x={self.mod_x}, mod_y={self.mod_y}"
+            if self.is_3d:
+                mod_str += f", mod_z={self.mod_z}"
+            return f"Sensor (sparse-grid): \n  Strides: {mod_str}\n  Is 3D: {self.is_3d}\n"
         return (
             f"Sensor: \n"
             f"  Number of sensors: {self.n_sensors}\n"

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/solver/binary_manager.py

@@ -28,7 +28,7 @@ CACHE_DIR = Path.home() / ".cache" / "fullwave25" / "bins"
 
 # Pinned release tag for the solver binaries.
 # Update this only when new binaries are uploaded to a GitHub release.
-BINARY_RELEASE_TAG = "fullwave_bin_v1.2"
+BINARY_RELEASE_TAG = "fullwave_bin_v1.3"
 
 
 def _download_url(filename: str, tag: str) -> str:

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/solver/input_file_writer.py

@@ -36,6 +36,7 @@ class InputFileWriter:
         use_exponential_attenuation: bool = False,
         use_isotropic_relaxation: bool = False,
         release_after_write: bool = False,
+        pml_thickness: int = 0,
     ) -> None:
         """Initialize the InputGeneratorBase instance.
 
@@ -74,6 +75,10 @@ class InputFileWriter:
             Whether to release the variable from memory after writing to file.
             This can help reduce memory usage when generating input files for large simulations.
             default is False.
+        pml_thickness : int, optional
+            PML boundary thickness in grid points (n_pml_layer + n_transition_layer).
+            Required by the solver binary when using sparse grid (mod_x/mod_y != 0) to determine
+            the interior domain boundaries. Also written when mod_x == 0 for future use.
 
         """
         logger.debug("Initializing InputFileWriter instance.")
@@ -99,6 +104,7 @@ class InputFileWriter:
         self.is_3d = self.grid.is_3d
         self.use_exponential_attenuation = use_exponential_attenuation
         self.release_after_write = release_after_write
+        self.pml_thickness = pml_thickness
 
         self._dim = int(
             np.rint(self.medium.sound_speed.max()) - np.rint(self.medium.sound_speed.min()),
@@ -828,6 +834,7 @@ class InputFileWriter:
         self._save_step_params(simulation_dir)
         self._save_coords_params(simulation_dir)
         self._save_d_params(simulation_dir, dim)
+        self._save_sparse_grid_params(simulation_dir)
 
         if self.use_isotropic_relaxation:
             rename_dict = {
@@ -894,6 +901,7 @@ class InputFileWriter:
         self._save_step_params(simulation_dir)
         self._save_coords_params(simulation_dir)
         self._save_d_params(simulation_dir, dim)
+        self._save_sparse_grid_params(simulation_dir)
 
     def _build_symbolic_links_for_dat_files(self, src_dir: Path, dst_dir: Path) -> None:
         var_name_list = [
@@ -916,6 +924,9 @@ class InputFileWriter:
             "ncoordszero",
             "nTic",
             "modT",
+            "modX",
+            "modY",
+            "pml_thickness",
             "d",
             "dmap",
             "ndmap",
@@ -948,6 +959,8 @@ class InputFileWriter:
                     "bpmly2",
                 ],
             )
+        if self.is_3d:
+            var_name_list.append("modZ")
         if self.is_3d and not self.use_isotropic_relaxation:
             var_name_list.extend(
                 [
@@ -1074,6 +1087,22 @@ class InputFileWriter:
             save_path = simulation_dir / f"{var_name}.dat"
             self._queue_v_abs_write(np.int32, save_path, var)
 
+    def _save_sparse_grid_params(self, simulation_dir: Path) -> None:
+        """Write sparse-grid parameters when the sensor is in sparse-grid mode.
+
+        modX / modY / modZ and pml_thickness are only written when the sensor
+        was constructed with mod_x/mod_y (i.e. sensor.is_sparse_grid is True).
+        In standard coordinate/mask mode these files are not produced, preserving
+        backward compatibility with older binaries that do not expect them.
+        """
+        if not self.sensor.is_sparse_grid:
+            return
+        self._queue_v_abs_write(np.int32, simulation_dir / "modX.dat", self.sensor.mod_x)
+        self._queue_v_abs_write(np.int32, simulation_dir / "modY.dat", self.sensor.mod_y)
+        if self.is_3d:
+            self._queue_v_abs_write(np.int32, simulation_dir / "modZ.dat", self.sensor.mod_z)
+        self._queue_v_abs_write(np.int32, simulation_dir / "pml_thickness.dat", self.pml_thickness)
+
     def _save_d_params(
         self,
         simulation_dir: Path,

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/solver/pml_builder.py

@@ -353,14 +353,24 @@ class PMLBuilder:
         logger.debug("building extended source for pml...done")
 
         logger.debug("building extended sensor for pml...")
-        extended_sensor_grid_shape = tuple(
-            s + 2 * self.num_boundary_points for s in self.sensor_org.grid_shape
-        )
-        self.extended_sensor = fullwave.Sensor(
-            coords=self.sensor_org.outcoords + self.num_boundary_points,
-            grid_shape=extended_sensor_grid_shape,
-            sampling_modulus_time=self.sensor_org.sampling_modulus_time,
-        )
+        if self.sensor_org.is_sparse_grid:
+            # Sparse-grid sensor: no explicit coordinates to shift.
+            # Pass mod values through; the binary generates positions at run time.
+            self.extended_sensor = fullwave.Sensor(
+                mod_x=self.sensor_org.mod_x,
+                mod_y=self.sensor_org.mod_y,
+                mod_z=self.sensor_org.mod_z,
+                sampling_modulus_time=self.sensor_org.sampling_modulus_time,
+            )
+        else:
+            extended_sensor_grid_shape = tuple(
+                s + 2 * self.num_boundary_points for s in self.sensor_org.grid_shape
+            )
+            self.extended_sensor = fullwave.Sensor(
+                coords=self.sensor_org.outcoords + self.num_boundary_points,
+                grid_shape=extended_sensor_grid_shape,
+                sampling_modulus_time=self.sensor_org.sampling_modulus_time,
+            )
         logger.debug("building extended sensor for pml...done")
         if self.is_3d:
             self.pml_mask_x, self.pml_mask_y, self.pml_mask_z = self._localize_pml_region()
@@ -1643,14 +1653,22 @@ class PMLBuilderExponentialAttenuation(PMLBuilder):
             w0=getattr(self.source_org, "w0", None),
             coords_w=incoords_w_ext,
         )
-        extended_sensor_grid_shape = tuple(
-            s + 2 * self.num_boundary_points for s in self.sensor_org.grid_shape
-        )
-        self.extended_sensor = fullwave.Sensor(
-            coords=self.sensor_org.outcoords + self.num_boundary_points,
-            grid_shape=extended_sensor_grid_shape,
-            sampling_modulus_time=self.sensor_org.sampling_modulus_time,
-        )
+        if self.sensor_org.is_sparse_grid:
+            self.extended_sensor = fullwave.Sensor(
+                mod_x=self.sensor_org.mod_x,
+                mod_y=self.sensor_org.mod_y,
+                mod_z=self.sensor_org.mod_z,
+                sampling_modulus_time=self.sensor_org.sampling_modulus_time,
+            )
+        else:
+            extended_sensor_grid_shape = tuple(
+                s + 2 * self.num_boundary_points for s in self.sensor_org.grid_shape
+            )
+            self.extended_sensor = fullwave.Sensor(
+                coords=self.sensor_org.outcoords + self.num_boundary_points,
+                grid_shape=extended_sensor_grid_shape,
+                sampling_modulus_time=self.sensor_org.sampling_modulus_time,
+            )
         logger.debug("Extended source and sensor for PML built successfully.")
 
         logger.debug("Localizing PML region...")

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/solver/solver.py

@@ -15,6 +15,7 @@ from fullwave.utils import (
     MemoryTempfile,
     check_functions,
 )
+from fullwave.utils.signal_filter import apply_filter
 
 from .binary_manager import ensure_binary
 from .cuda_utils import get_cuda_architecture, retrieve_cuda_version
@@ -638,10 +639,86 @@ class Solver:
         error_msg = f"{path_fullwave_simulation_bin} does not exist"
         assert path_fullwave_simulation_bin.exists(), error_msg
 
+    @staticmethod
+    def _validate_filter_params(
+        highpass_cutoff_mhz: float | None,
+        bandpass_cutoff_mhz: tuple[float, float] | None,
+        *,
+        load_results: bool,
+    ) -> None:
+        """Validate high-pass / band-pass filter arguments passed to run().
+
+        Raises
+        ------
+        ValueError
+            If both filter options are set simultaneously, or if a filter is
+            requested without ``load_results=True``.
+
+        """
+        if highpass_cutoff_mhz is not None and bandpass_cutoff_mhz is not None:
+            error_msg = (
+                "highpass_cutoff_mhz and bandpass_cutoff_mhz cannot both be specified. "
+                "Use highpass_cutoff_mhz for a simple high-pass filter or "
+                "bandpass_cutoff_mhz for a band-pass filter."
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+        if (highpass_cutoff_mhz is not None or bandpass_cutoff_mhz is not None) and (
+            not load_results
+        ):
+            error_msg = (
+                "Filtering requires load_results=True. "
+                "Set load_results=True or disable the filter options."
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+    @staticmethod
+    def _apply_output_filter(
+        result: NDArray[np.float64],
+        dt: float,
+        highpass_cutoff_mhz: float | None,
+        bandpass_cutoff_mhz: tuple[float, float] | None,
+    ) -> NDArray[np.float64]:
+        """Apply the optional frequency filter to the reshaped sensor output.
+
+        Parameters
+        ----------
+        result : NDArray[np.float64]
+            Sensor data shaped ``[n_sensors, n_t]``.
+        dt : float
+            Grid time step in seconds.
+        highpass_cutoff_mhz : float | None
+            High-pass edge in MHz, or ``None``.
+        bandpass_cutoff_mhz : tuple[float, float] | None
+            ``(f_low_mhz, f_high_mhz)`` band-pass edges, or ``None``.
+
+        Returns
+        -------
+        NDArray[np.float64]
+            Filtered (or unchanged) sensor data.
+
+        """
+        if highpass_cutoff_mhz is not None:
+            logger.info("Applying high-pass filter at %.4g MHz...", highpass_cutoff_mhz)
+            return apply_filter(result, dt, f_low_hz=highpass_cutoff_mhz * 1e6)
+        if bandpass_cutoff_mhz is not None:
+            f_low_hz = bandpass_cutoff_mhz[0] * 1e6
+            f_high_hz = bandpass_cutoff_mhz[1] * 1e6
+            logger.info(
+                "Applying band-pass filter %.4g-%.4g MHz...",
+                bandpass_cutoff_mhz[0],
+                bandpass_cutoff_mhz[1],
+            )
+            return apply_filter(result, dt, f_low_hz=f_low_hz, f_high_hz=f_high_hz)
+        return result
+
     @staticmethod
     def _reshape_sensor_data(
         raw_sensor_output: NDArray[np.float64],
         sensor: fullwave.Sensor,
+        *,
+        n_t: int | None = None,
     ) -> NDArray[np.float64]:
         """Reshape the raw sensor output data.
 
@@ -651,12 +728,21 @@ class Solver:
             The raw sensor output data from the simulation. [nt*ncoordsout, 1]
         sensor: fullwave.Sensor
             The sensor object used in the simulation.
+        n_t: int | None
+            Number of time steps in the extended grid.  Required for sparse-grid
+            sensors because n_sensors is not known at Python time.
 
         Returns
         -------
         NDArray[np.float64]: The reshaped sensor output data. [ncoordsout, nt]
 
         """
+        if sensor.is_sparse_grid:
+            if n_t is None:
+                msg = "n_t is required to reshape sparse-grid sensor output"
+                raise ValueError(msg)
+            n_t_recorded = -(-n_t // sensor.sampling_modulus_time)  # ceiling division
+            return raw_sensor_output.reshape(n_t_recorded, -1).T
         return raw_sensor_output.reshape(-1, sensor.n_sensors).T
 
     def run(
@@ -670,6 +756,8 @@ class Solver:
         load_results: bool = True,
         generate_input_only: bool = False,
         release_after_write: bool = False,
+        highpass_cutoff_mhz: float | None = None,
+        bandpass_cutoff_mhz: tuple[float, float] | None = None,
     ) -> NDArray[np.float64] | Path:
         r"""Run the fullwave simulation and return the result as a NumPy array.
 
@@ -729,6 +817,18 @@ class Solver:
             If True, the memory used by the input files will be released after writing them to disk.
             This is useful when run_on_memory is True to free up memory space for the simulation
             or when the input files are large. Default is False.
+        highpass_cutoff_mhz : float | None
+            Apply a high-pass filter to the sensor recordings after the simulation.
+            Removes low-frequency PML drift by attenuating frequencies below this value (in MHz).
+            Uses a cosine (Hann) taper to avoid Gibbs ringing.
+            Cannot be combined with ``bandpass_cutoff_mhz``.
+            Requires ``load_results=True``.  Default is ``None`` (no filtering).
+        bandpass_cutoff_mhz : tuple[float, float] | None
+            Apply a band-pass filter ``(f_low_mhz, f_high_mhz)`` to the sensor recordings
+            after the simulation.  Retains only frequencies inside the specified band.
+            Uses cosine (Hann) tapers on both edges.
+            Cannot be combined with ``highpass_cutoff_mhz``.
+            Requires ``load_results=True``.  Default is ``None`` (no filtering).
 
         Returns
         -------
@@ -746,6 +846,8 @@ class Solver:
             Static map simulations require input files to be stored on a disk.
             run_on_memory, on the other hand, removes the input files
             after the simulation is complete.
+            Also raised if both ``highpass_cutoff_mhz`` and ``bandpass_cutoff_mhz`` are given,
+            or if either filter option is set but ``load_results=False``.
 
         """
         # self._save_data_for_beamforming()
@@ -767,6 +869,12 @@ class Solver:
             logger.error(error_msg)
             raise ValueError(error_msg)
 
+        self._validate_filter_params(
+            highpass_cutoff_mhz,
+            bandpass_cutoff_mhz,
+            load_results=load_results,
+        )
+
         start_time = time.time()
         extended_medium = self.pml_builder.run(use_pml=self.use_pml)
         end_pml_builder_time = time.time()
@@ -783,30 +891,27 @@ class Solver:
             )
             logger.warning(warning_msg)
 
-        sensor_mask: NDArray[np.bool_]
         if record_whole_domain:
-            if self.is_3d:
-                sensor_mask = np.zeros(
-                    (
-                        self.pml_builder.extended_grid.nx,
-                        self.pml_builder.extended_grid.ny,
-                        self.pml_builder.extended_grid.nz,
-                    ),
-                    dtype=bool,
-                )
-            else:
-                sensor_mask = np.zeros(
-                    (self.pml_builder.extended_grid.nx, self.pml_builder.extended_grid.ny),
-                    dtype=bool,
-                )
-            sensor_mask[:, :] = True
+            mod_x = 1
+            mod_y = 1
+            mod_z = 1 if self.is_3d else None
+
             sensor = fullwave.Sensor(
-                mask=sensor_mask,
+                mod_x=mod_x,
+                mod_y=mod_y,
+                mod_z=mod_z,
                 sampling_modulus_time=sampling_modulus_time_whole_domain,
             )
         else:
             sensor = self.pml_builder.extended_sensor
 
+        # pml_thickness = PML + transition layers on each side, excluding ghost cells.
+        # Used by the binary to locate the interior domain when building a sparse sensor grid.
+        if record_whole_domain:
+            pml_thickness = 0
+        else:
+            pml_thickness = self.pml_builder.num_boundary_points - self.pml_builder.m_spatial_order
+
         start_input_file_writer_time = time.time()
         input_file_writer = InputFileWriter(
             work_dir=self.work_dir,
@@ -818,6 +923,7 @@ class Solver:
             use_exponential_attenuation=self.use_exponential_attenuation,
             use_isotropic_relaxation=self.use_isotropic_relaxation,
             release_after_write=release_after_write,
+            pml_thickness=pml_thickness,
         )
         simulation_dir = input_file_writer.run(
             simulation_dir_name,
@@ -850,6 +956,7 @@ class Solver:
             result = self._reshape_sensor_data(
                 sim_result,
                 sensor=sensor,
+                n_t=self.pml_builder.extended_grid.nt,
             )
             end_loading_time = time.time()
             message = (
@@ -857,7 +964,13 @@ class Solver:
                 f"{end_loading_time - start_loading_time:.2e} seconds."
             )
             logger.info(message)
-            return result
+
+            return self._apply_output_filter(
+                result,
+                self.grid.dt,
+                highpass_cutoff_mhz,
+                bandpass_cutoff_mhz,
+            )
         # if load_results is False, return the raw result
         # which is a list of file names
         return sim_result

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/fullwave/utils/__init__.py

@@ -1,6 +1,6 @@
 """misc utils for fullwave package."""
 
-from . import pulse, relaxation_parameters, signal_process
+from . import pulse, relaxation_parameters, signal_filter, signal_process
 from .memory_tempfile import MemoryTempfile
 from .scatterer import (
     generate_resolution_based_scatterer,
@@ -14,5 +14,6 @@ __all__ = [
     "generate_scatterer",
     "pulse",
     "relaxation_parameters",
+    "signal_filter",
     "signal_process",
 ]

fullwave25-1.2.6.dev2/fullwave/utils/signal_filter.py

@@ -0,0 +1,161 @@
+"""FFT-based frequency-domain filtering for sensor data.
+
+GPU backend: CuPy when available; falls back silently to NumPy.
+No new hard dependencies — CuPy is already listed under the ``examples`` optional extra.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+logger = logging.getLogger("__main__." + __name__)
+
+# Module-level cache to avoid repeated import overhead
+_CUPY_AVAILABLE: bool | None = None
+
+
+def _check_cupy() -> bool:
+    """Return True if CuPy is importable; result is cached after the first call."""
+    global _CUPY_AVAILABLE  # noqa: PLW0603
+    if _CUPY_AVAILABLE is None:
+        try:
+            import cupy  # noqa: F401
+
+            _CUPY_AVAILABLE = True
+        except ImportError:
+            _CUPY_AVAILABLE = False
+    return _CUPY_AVAILABLE
+
+
+def _build_frequency_mask(
+    n_fft: int,
+    dt: float,
+    f_low_hz: float | None = None,
+    f_high_hz: float | None = None,
+    taper_ratio: float = 0.1,
+) -> NDArray[np.float64]:
+    """Build a frequency-domain gain mask with cosine (Hann) tapers.
+
+    Parameters
+    ----------
+    n_fft : int
+        FFT length (number of time samples before zero-padding, i.e. ``n_t``).
+    dt : float
+        Simulation time step in seconds.
+    f_low_hz : float | None
+        High-pass cut-off frequency in Hz.  Frequencies below this value are
+        attenuated.  The mask transitions smoothly from 0 to 1 in a window of
+        width ``f_low_hz * taper_ratio`` centred at ``f_low_hz``.
+    f_high_hz : float | None
+        Low-pass cut-off frequency in Hz.  Frequencies above this value are
+        attenuated.  The mask transitions smoothly from 1 to 0 in a window of
+        width ``f_high_hz * taper_ratio`` centred at ``f_high_hz``.
+    taper_ratio : float
+        Fractional width of each cosine taper relative to its centre frequency.
+        Default is 0.1 (10 %).
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Frequency-domain gain mask of shape ``[n_fft // 2 + 1]``.
+
+    """
+    freqs = np.fft.rfftfreq(n_fft, d=dt)
+    mask = np.ones(len(freqs), dtype=np.float64)
+
+    if f_low_hz is not None:
+        half_width = f_low_hz * taper_ratio / 2.0
+        f_start = f_low_hz - half_width
+        f_end = f_low_hz + half_width
+        width = f_end - f_start  # == f_low_hz * taper_ratio
+
+        in_taper = (freqs >= f_start) & (freqs <= f_end)
+        below_taper = freqs < f_start
+
+        mask[below_taper] = 0.0
+        mask[in_taper] = 0.5 * (1.0 - np.cos(np.pi * (freqs[in_taper] - f_start) / width))
+
+    if f_high_hz is not None:
+        half_width = f_high_hz * taper_ratio / 2.0
+        f_start = f_high_hz - half_width
+        f_end = f_high_hz + half_width
+        width = f_end - f_start  # == f_high_hz * taper_ratio
+
+        in_taper = (freqs >= f_start) & (freqs <= f_end)
+        above_taper = freqs > f_end
+
+        lp_taper = np.ones(len(freqs), dtype=np.float64)
+        lp_taper[in_taper] = 0.5 * (1.0 + np.cos(np.pi * (freqs[in_taper] - f_start) / width))
+        lp_taper[above_taper] = 0.0
+        mask *= lp_taper
+
+    return mask
+
+
+def apply_filter(
+    data: NDArray[np.float64],
+    dt: float,
+    f_low_hz: float | None = None,
+    f_high_hz: float | None = None,
+    taper_ratio: float = 0.1,
+    *,
+    use_gpu: bool = True,
+) -> NDArray[np.float64]:
+    """Apply a frequency-domain filter to sensor data.
+
+    The filter is built as a cosine-tapered gain mask (see :func:`_build_frequency_mask`).
+    When CuPy is available and ``use_gpu=True``, the FFT operations run on the GPU
+    for maximum throughput; otherwise NumPy is used transparently.
+
+    Parameters
+    ----------
+    data : NDArray[np.float64]
+        Sensor time traces, shape ``[n_sensors, n_t]``.
+    dt : float
+        Simulation time step in seconds.
+    f_low_hz : float | None
+        High-pass edge frequency in Hz.  Pass ``None`` to skip high-passing.
+    f_high_hz : float | None
+        Low-pass edge frequency in Hz.  Pass ``None`` to skip low-passing.
+    taper_ratio : float
+        Fractional taper width relative to each cut-off frequency.  Default 0.1.
+    use_gpu : bool
+        If ``True`` (default), attempt to use CuPy for GPU-accelerated FFTs.
+        Falls back to NumPy silently if CuPy is unavailable.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        Filtered data, same shape as ``data``.
+
+    """
+    n_t = data.shape[1]
+    mask = _build_frequency_mask(
+        n_t,
+        dt,
+        f_low_hz=f_low_hz,
+        f_high_hz=f_high_hz,
+        taper_ratio=taper_ratio,
+    )
+
+    if use_gpu and _check_cupy():
+        import cupy as cp
+
+        logger.debug("apply_filter: using CuPy GPU backend")
+        data_gpu = cp.asarray(data, dtype=cp.float64)
+        mask_gpu = cp.asarray(mask, dtype=cp.float64)
+        spec = cp.fft.rfft(data_gpu, axis=1)
+        spec *= mask_gpu[cp.newaxis, :]
+        filtered = cp.fft.irfft(spec, n=n_t, axis=1)
+        return cp.asnumpy(filtered)
+
+    logger.debug("apply_filter: using NumPy CPU backend")
+    spec = np.fft.rfft(data, axis=1)
+    spec *= mask[np.newaxis, :]
+    return np.fft.irfft(spec, n=n_t, axis=1)

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fullwave25"
-version = "1.2.6-dev0" # Update via bump-my-version, not manually
+version = "1.2.6-dev2" # Update via bump-my-version, not manually
 description = "Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities"
 readme = "README.md"
 requires-python = ">=3.10"

{fullwave25-1.2.6.dev0 → fullwave25-1.2.6.dev2}/uv.lock

@@ -735,7 +735,7 @@ wheels = [
 
 [[package]]
 name = "fullwave25"
-version = "1.2.6.dev0"
+version = "1.2.6.dev2"
 source = { editable = "." }
 dependencies = [
     { name = "joblib" },