fullwave25 1.4.2.dev2__py3-none-any.whl → 1.4.2.dev3__py3-none-any.whl

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__)

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

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.

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.dist-info → fullwave25-1.4.2.dev3.dist-info}/METADATA

@@ -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.dist-info → fullwave25-1.4.2.dev3.dist-info}/RECORD

@@ -1,12 +1,12 @@
-fullwave/__init__.py,sha256=kB7UDg9SHqBPUkMZSPknt2b4sEI6WArCltM-2ExrS1c,2382
+fullwave/__init__.py,sha256=Lu4dG1mNq4CKaKD34LmhtJNlYn8m2gRXrw8qYqnAZKg,2382
 fullwave/grid.py,sha256=YbxAAgdYKR8AXwobtTZzHm9C4KR4D5--51zgbs0aQGY,7435
 fullwave/medium.py,sha256=qoAh-aYLVkC_ojt1K61hDNV0j9KfIeRkh35tZU8gSKM,68574
 fullwave/sensor.py,sha256=McHyaSKxM11_Kfb_2hfnOtV9Z1UMBCLkeovncLT8_bA,9308
 fullwave/source.py,sha256=5IHktJubOsk94qBWlLBbu-Vxo2UczVFL4EnEyKqEIUE,21321
-fullwave/transducer.py,sha256=WmaYwKOPSWLVnjDFZkpP1qlLs4IT27HLtB04vJhm0Ec,75778
+fullwave/transducer.py,sha256=H67VF_T2KKF68mWtXG6DrVYKaaZieGc7p-IDtWxX1SQ,77623
 fullwave/transmit.py,sha256=BAD_G-J7Q1pMppXw1yjLrQDUdkhPq-3Q4eNq4jaf7Ss,9693
 fullwave/beamformer/__init__.py,sha256=tNPq_5lfLXfAdueyfQtdTxLTVEV6nEDkeSGAeTf7Q5s,88
-fullwave/beamformer/beamformer.py,sha256=0jE_B5UlxDDBsUcQSHa5d1q3uSTSCyqgNiUJrU10juI,5601
+fullwave/beamformer/beamformer.py,sha256=7dlQVArUGpUeUP6O-9QyMpR6asbbI5JBVJ_F1fpSowU,6175
 fullwave/constants/__init__.py,sha256=WOmkhLsSe86D71gwKsa4Tz8QPeOdayLGgvBCh7UEOPk,104
 fullwave/constants/material_properties.py,sha256=SouMKD4ONzYl0VU8ZsC2I_85y-ZLj9scRNwAArCD7bg,2729
 fullwave/medium_builder/__init__.py,sha256=QVz0sA4niq51O94RnXUVlHutx7FYEIa1TRcR5fDc_Ps,201
@@ -64,11 +64,11 @@ fullwave/utils/memory_tempfile.py,sha256=RqoFX67VCMIHNIDYWwHLCaS4dwSPK6eKsvElXX4
 fullwave/utils/numerical.py,sha256=khdi2KE3y_Ky9cEnmGXvVHjeYuKfb-8gQTV1a8nx9uA,3260
 fullwave/utils/plot_utils.py,sha256=SoByd2fEr3VdvMM9D2kNq8VgaAQ-fh82bDGRFdeq2R8,39327
 fullwave/utils/pulse.py,sha256=aqnCdBxivACouIGlot1aE2k4V9nctUxNCEPzdBpsupg,2811
-fullwave/utils/relaxation_parameters.py,sha256=wHUNMtJGAJwgCyUYd24_qtQZflMnkQTYhxSJwjE3vA4,46151
+fullwave/utils/relaxation_parameters.py,sha256=pNul3_8rrbBrjkcc0nKBJ6An9y3bI92DVxNu1Ww8cf4,48133
 fullwave/utils/scatterer.py,sha256=CLqD085f9pqX4cF1YiT2IkzT5P0o1xp45Do7lf5BLnM,24049
 fullwave/utils/signal_filter.py,sha256=_Tf42aBygGtIUrcSPybYqvZoAW2o_4dd-hHTEvZ8--E,5219
 fullwave/utils/signal_process.py,sha256=MP38r37JSPHN4sT-lIReXS5BT2GT_tkRxD0Y1wQ-lNs,5153
-fullwave25-1.4.2.dev2.dist-info/METADATA,sha256=D3sDh1xucymIxtFEhw1cwpI6XbBEFBceYSD5qE9a-i4,28226
-fullwave25-1.4.2.dev2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
-fullwave25-1.4.2.dev2.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-fullwave25-1.4.2.dev2.dist-info/RECORD,,
+fullwave25-1.4.2.dev3.dist-info/METADATA,sha256=q0L2mArY9AQfnOaJKDYCLIke8U4wNM0w5TOm-EPxMIU,28226
+fullwave25-1.4.2.dev3.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fullwave25-1.4.2.dev3.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+fullwave25-1.4.2.dev3.dist-info/RECORD,,