fullwave25 1.4.2.dev2__tar.gz → 1.4.2.dev3__tar.gz

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/.bumpversion.toml

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

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.2-dev2
+Version: 1.4.2-dev3
 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.4.2.dev2 → fullwave25-1.4.2.dev3}/fullwave/__init__.py

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

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/fullwave/beamformer/beamformer.py

@@ -14,6 +14,13 @@ class Beamformer:
     For faster implementations, consider using libraries such as
     mach beamformer: https://github.com/Forest-Neurotech/mach
 
+    Conventions: ``axial_position_m`` is measured from the top of the grid
+    (row 0), not from the array. ``transducer_coordinates`` must be the
+    receiver positions in grid points (for example from
+    ``Transducer.element_id_to_receiver_center``). The time origin is the
+    mean receiver row, so the array depth is subtracted from the two-way
+    travel time.
+
     References
     ----------
     - Fullwave2 BMME890 implementation
@@ -46,11 +53,11 @@ class Beamformer:
         lateral_position_m : np.ndarray
             Lateral positions (m) where the beamformed image will be computed.
         axial_position_m : np.ndarray
-            Axial positions (m) where the beamformed image will be computed.
+            Axial positions (m) from the top of the grid where the image is computed.
         num_elements : int
             Number of transducer elements.
         transducer_coordinates : np.ndarray
-            Coordinates of the transducer elements (m).
+            Receiver coordinates [n_elements, 2] in grid points (row, column).
         f_number : float, optional
             F-number for aperture calculation, by default 1.0.
 
@@ -83,6 +90,8 @@ class Beamformer:
         if signals.ndim == 2:
             signals = signals[:, :, np.newaxis]
         n_transmit = signals.shape[2]
+        # idt_0 is the pulse arrival at the receivers, so time is measured from the array.
+        z_array = np.mean(self.transducer_coordinates[:, 0]) * self.dx
 
         hilbert_signals = hilbert(signals, axis=1)
         beamformed_image = np.zeros(
@@ -133,7 +142,7 @@ class Beamformer:
                     dd = np.round(dd / (self.dt / self.dx * self.c0)).astype(int)
                     dd = dd - dd.min()
 
-                    idt = idt_0 + int(2 * axial / self.c0 / self.dt)
+                    idt = idt_0 + int(2 * (axial - z_array) / self.c0 / self.dt)
 
                     # idp: 1D indices into signals flattened array
                     # we convert 2D indices to 1D indices

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/fullwave/transducer.py

@@ -352,6 +352,9 @@ class TransducerGeometry:
     ) -> tuple[NDArray[np.int64], NDArray[np.int64], NDArray[np.int64], NDArray[np.int64]]:
         """Build flat coordinate arrays for source and sensor pixels.
 
+        For a flat array the sensor row is the first row in front of the element
+        (``position_px[0] + element_layer_px``), outside the source cells.
+
         Returns
         -------
         source_coords : NDArray[np.int64], shape [N_src, ndim]
@@ -404,7 +407,7 @@ class TransducerGeometry:
                     source_ids_parts.append(np.full(len(src), element_index + 1))
 
                     # Single center pixel for sensor output
-                    sx = element_pos_x + self.element_layer_px - 1
+                    sx = self._flat_sensor_row(element_pos_x=element_pos_x)
                     sy = element_pos_y + self.element_width_px - 1
                     sz = element_pos_z + self.element_height_px // 2 - 1
                     sensor_coords_parts.append(np.array([[sx, sy, sz]]))
@@ -432,7 +435,7 @@ class TransducerGeometry:
                     source_coords_parts.append(src)
                     source_ids_parts.append(np.full(len(src), element_index + 1))
 
-                    sx = element_pos_x + self.element_layer_px - 1
+                    sx = self._flat_sensor_row(element_pos_x=element_pos_x)
                     if self.average_surface_signals:
                         out_ys = np.arange(element_pos_y, element_pos_y + self.element_width_px)
                         out_xs = np.full(len(out_ys), sx)
@@ -452,6 +455,39 @@ class TransducerGeometry:
         sensor_ids = np.concatenate(sensor_ids_parts, axis=0).astype(np.int64)
         return source_coords, source_ids, sensor_coords, sensor_ids
 
+    def _flat_sensor_row(self, *, element_pos_x: int) -> int:
+        """Return the sensor row of a flat-array element.
+
+        The row lies in front of the source cells because a hard source keeps a
+        static pressure after the drive, which a receiver inside it would record.
+
+        Parameters
+        ----------
+        element_pos_x : int
+            First (back) source row of the element.
+
+        Returns
+        -------
+        int
+            The sensor row, ``element_pos_x + element_layer_px``.
+
+        Raises
+        ------
+        ValueError
+            If the sensor row is outside the grid.
+
+        """
+        sensor_row = int(element_pos_x + self.element_layer_px)
+        if sensor_row >= self.stored_grid_size[0]:
+            error_msg = (
+                f"The sensor row {sensor_row} (one row in front of the element) is "
+                f"outside the grid, which has {self.stored_grid_size[0]} rows in x. "
+                "Move the transducer back or enlarge the grid."
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+        return sensor_row
+
     def _arc_element_coords(
         self,
     ) -> tuple[NDArray[np.int64], NDArray[np.int64], NDArray[np.int64], NDArray[np.int64]]:
@@ -1728,6 +1764,18 @@ class Transducer:
                 out[eid] = np.rint(coords[sel].mean(axis=0)).astype(np.int64)
         return out
 
+    @property
+    def element_id_to_receiver_center(self) -> dict[int, NDArray[np.int64]]:
+        """Return the mapping from element IDs to the mean receiver coordinate in grid points."""
+        ndim = 3 if self.is_3d else 2
+        out: dict[int, NDArray[np.int64]] = {}
+        for eid, coords in self.element_id_to_element_surface.items():
+            if len(coords) == 0:
+                out[eid] = np.full(ndim, -1, dtype=np.int64)
+            else:
+                out[eid] = np.rint(coords.mean(axis=0)).astype(np.int64)
+        return out
+
     @property
     def sensor(self) -> fullwave.sensor.Sensor:
         """Return the Sensor object with active sensor coordinates.

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/fullwave/utils/relaxation_parameters.py

@@ -35,6 +35,44 @@ def _on_the_host(array: NDArray) -> NDArray:
     return _array_module(array).asnumpy(array)
 
 
+# float32 stores 1.2 as 1.2000000477 (about 6e-8 relative); table nodes are 1e-2 or more apart.
+_FLOAT32_NOISE_RTOL = 1e-6
+
+
+def _snap_to_nearby_node(
+    *,
+    values: NDArray[np.float64],
+    nodes: NDArray[np.float64],
+    xp: object,
+) -> NDArray[np.float64]:
+    """Replace each value that is float32 noise away from a table node by that node.
+
+    Parameters
+    ----------
+    values : NDArray[np.float64]
+        Requested values.
+    nodes : NDArray[np.float64]
+        Sorted table nodes.
+    xp : object
+        Array module of ``values``, numpy or cupy.
+
+    Returns
+    -------
+    NDArray[np.float64]
+        The values, with near-node values replaced by the node.
+
+    """
+    if nodes.size < 2:
+        return values
+    values = xp.asarray(values)
+    upper_index = xp.clip(xp.searchsorted(nodes, values, side="left"), 1, nodes.size - 1)
+    lower_node = nodes[upper_index - 1]
+    upper_node = nodes[upper_index]
+    is_near_lower = xp.abs(values - lower_node) <= _FLOAT32_NOISE_RTOL * xp.abs(lower_node)
+    is_near_upper = xp.abs(values - upper_node) <= _FLOAT32_NOISE_RTOL * xp.abs(upper_node)
+    return xp.where(is_near_lower, lower_node, xp.where(is_near_upper, upper_node, values))
+
+
 def scale_relaxation_attenuation(
     relaxation_param_dict: dict[str, NDArray[np.float64]],
     factor: NDArray[np.float64] | float,
@@ -938,6 +976,8 @@ class RelaxationParametersGenerator:
 
         """
         alpha_coeff = band_scaled_alpha_coeff(alpha_coeff, alpha_power, band_scale)
+        alpha_coeff = self._snap_to_table(alpha_coeff, table_axis=self.alpha_list)
+        alpha_power = self._snap_to_table(alpha_power, table_axis=self.power_list)
         self._warn_invalid(alpha_coeff, alpha_power)
 
         use_gpu = not isinstance(alpha_coeff, np.ndarray)
@@ -991,6 +1031,7 @@ class RelaxationParametersGenerator:
 
         """
         xp = np if isinstance(alpha_coeff, np.ndarray) else _array_module(alpha_coeff)
+        alpha_coeff = self._snap_to_table(alpha_coeff, table_axis=self.alpha_list)
         axis = xp.asarray(np.asarray(self.alpha_list).ravel().round(10))
         return (
             alpha_coeff / axis[self._axis_index(alpha_coeff, axis, self.alpha_min, self.alpha_max)]
@@ -1113,6 +1154,15 @@ class RelaxationParametersGenerator:
             ],
         )
 
+    @staticmethod
+    def _snap_to_table(
+        values: NDArray[np.float64], *, table_axis: NDArray[np.float64]
+    ) -> NDArray[np.float64]:
+        """Replace each value that is float32 noise away from a node of one table axis."""
+        xp = np if isinstance(values, np.ndarray) else _array_module(values)
+        nodes = xp.asarray(np.asarray(table_axis).ravel().round(10))
+        return _snap_to_nearby_node(values=values, nodes=nodes, xp=xp)
+
     @staticmethod
     def _axis_index(
         value: NDArray[np.float64],
@@ -1122,6 +1172,7 @@ class RelaxationParametersGenerator:
     ) -> NDArray[np.int64]:
         """Return the axis index the lookup kernel selects, which clips at both ends."""
         xp = np if isinstance(value, np.ndarray) else _array_module(value)
+        value = _snap_to_nearby_node(values=value, nodes=axis, xp=xp)
         clipped = xp.clip(value, lowest, highest)
         return xp.minimum(xp.searchsorted(axis, clipped, side="left"), axis.size - 1)
 

{fullwave25-1.4.2.dev2 → fullwave25-1.4.2.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fullwave25"
-version = "1.4.2-dev2" # Update via bump-my-version, not manually
+version = "1.4.2-dev3" # 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.4.2.dev2 → fullwave25-1.4.2.dev3}/uv.lock

@@ -784,7 +784,7 @@ wheels = [
 
 [[package]]
 name = "fullwave25"
-version = "1.4.2.dev2"
+version = "1.4.2.dev3"
 source = { editable = "." }
 dependencies = [
     { name = "cupy-cuda12x" },