fullwave25 1.4.2.dev2__py3-none-any.whl → 1.4.2.dev4__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-dev4"
 
 VERSION = __version__  # for convenience
 logger.info("Fullwave version: %s", __version__)

fullwave/beamformer/beamformer.py

@@ -14,6 +14,14 @@ class Beamformer:
     For faster implementations, consider using libraries such as
     mach beamformer: https://github.com/Forest-Neurotech/mach
 
+    Conventions: ``axial_position_m`` is the depth below the probe face, so
+    depth 0 is the face row ``face_row_px`` (``Transducer.face_row_px``, the
+    first medium row, one row in front of the receiver row).
+    ``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
@@ -31,6 +39,7 @@ class Beamformer:
         axial_position_m: np.ndarray,
         num_elements: int,
         transducer_coordinates: np.ndarray,
+        face_row_px: int,
         f_number: float = 1.0,
     ) -> None:
         """Initialize the beamformer with simulation and transducer parameters.
@@ -46,11 +55,14 @@ 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.
+            Depths (m) below the probe face 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).
+        face_row_px : int
+            Grid row of the probe face (depth 0), for example
+            ``Transducer.face_row_px``.
         f_number : float, optional
             F-number for aperture calculation, by default 1.0.
 
@@ -62,6 +74,7 @@ class Beamformer:
         self.axial_position_m = axial_position_m
         self.num_elements = num_elements
         self.transducer_coordinates = transducer_coordinates
+        self.face_row_px = face_row_px
         self.f_number = f_number
 
     def run(self, signals: np.ndarray) -> np.ndarray:
@@ -76,13 +89,17 @@ class Beamformer:
         Returns
         -------
         np.ndarray
-            Beamformed image. Shape: [n_axial, n_lateral, n_transmit].
+            Beamformed image. Shape: [n_axial, n_lateral, n_transmit]. Row 0
+            of the first axis is the first depth of ``axial_position_m``, which
+            is measured from the probe face.
 
         """
         # signals: [n_elements, n_time, n_transmit]
         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(
@@ -101,12 +118,13 @@ class Beamformer:
                 desc="Lateral positions",
                 total=len(self.lateral_position_m),
             ):
-                for i_axial, axial in tqdm(
+                for i_axial, depth in tqdm(
                     enumerate(self.axial_position_m),
                     desc="Axial positions",
                     total=len(self.axial_position_m),
                     leave=False,
                 ):
+                    axial = self.face_row_px * self.dx + depth
                     fcen = np.array(
                         [
                             int(axial / self.dx),
@@ -133,7 +151,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/solver/input_file_writer.py

@@ -293,6 +293,7 @@ class InputFileWriter:
                     _incoords_vel,
                 )
         self._queue_coords_write(simulation_dir / "icc.dat", self.source.incoords)
+        self._save_drive_params(simulation_dir, members)
         self._copy_simulation_bin_file(simulation_dir)
 
         if not self.use_exponential_attenuation:
@@ -1275,8 +1276,6 @@ class InputFileWriter:
             "ncoords_w",
             "ncoordsout",
             "ncoordszero",
-            "nTic",
-            "hold_source",
             "modT",
             "modX",
             "modY",
@@ -1374,6 +1373,27 @@ class InputFileWriter:
             save_path = simulation_dir / f"{var_name}.dat"
             self._queue_v_abs_write(np.float32, save_path, var)
 
+    def _save_drive_params(
+        self,
+        simulation_dir: Path,
+        members: Sequence[fullwave.Source] | None = None,
+    ) -> None:
+        """Write the drive length and the hold flag of this transmit.
+
+        Every transmit folder gets its own files, never a link to the shared
+        static-map files, and a flag left by an earlier run is removed when the
+        hold is off. The members of a batch share one length, which can exceed the
+        length of the source, so the drive length is the one of the members.
+        """
+        drive_length_file = simulation_dir / "nTic.dat"
+        hold_flag_file = simulation_dir / "hold_source.dat"
+        drive_length_file.unlink(missing_ok=True)
+        hold_flag_file.unlink(missing_ok=True)
+        drive_source = self.source if members is None else members[0]
+        self._queue_v_abs_write(np.int32, drive_length_file, drive_source.icmat.shape[1])
+        if self._holds_the_source:
+            self._queue_v_abs_write(np.int32, hold_flag_file, 1)
+
     def _save_coords_params(self, simulation_dir: Path) -> None:
         var_list = [
             ("nX", self.grid.nx),
@@ -1382,11 +1402,8 @@ class InputFileWriter:
             ("ncoords", self.source.n_sources),
             ("ncoordsout", self.sensor.n_sensors),
             ("ncoordszero", self.medium.n_air),
-            ("nTic", self.source.icmat.shape[1]),
             ("modT", self.sensor.sampling_modulus_time),
         ]
-        if self._holds_the_source:
-            var_list.append(("hold_source", 1))
         n_sources_add = getattr(self.source, "n_sources_add", 0)
         if n_sources_add > 0:
             var_list.append(("ncoords_add", n_sources_add))

fullwave/solver/solver.py

@@ -1,6 +1,7 @@
 """solver module."""
 
 import contextlib
+import copy
 import logging
 import os
 import time
@@ -22,6 +23,7 @@ from fullwave.solver.source_type import (
     is_hard_held,
     is_soft,
 )
+from fullwave.ultra import attenuation_parameters as power_law_attenuation
 from fullwave.ultra import backend, binary, factory
 from fullwave.utils import (
     check_functions,
@@ -470,10 +472,12 @@ class Solver:
         verify_gpu: bool = True,
         use_gpu_pml: bool = False,
         pml_alpha_entrance: float | None = None,
-        source_type: str = HARD_RELEASED_AFTER,
+        source_type: str | None = None,
         write_maps_the_solver_does_not_read: bool = False,
         use_ultra: bool = False,
         ultra_sponge_thickness_px: int | None = None,
+        ultra_attenuation_parameters: str | Path | None = None,
+        ultra_unlimited_materials: bool = False,
     ) -> None:
         """Initialize a Solver instance for the fullwave simulation.
 
@@ -599,12 +603,14 @@ class Solver:
             relaxation path. Set it to True for a solver binary that predates
             that record. Such a binary stops with an error on kappax.dat rather
             than returning a wrong answer.
-        source_type : str, optional
-            How the source drives the field. "hard_released_after", the default,
-            assigns the source pressure while the drive signal plays, then lets the
-            source cells evolve freely. "hard" assigns it for the whole run, so the
-            cells stay at zero pressure after the signal ends. "soft" adds the signal
-            to the field. ``use_ultra`` follows the same three values.
+        source_type : str | None, optional
+            How the source drives the field. None, the default, takes the type of the
+            ``transducer`` when one is given, and "hard_released_after" otherwise. A
+            value that differs from the transducer's type raises ValueError.
+            "hard_released_after" assigns the source pressure while the drive signal
+            plays, then lets the source cells evolve freely. "hard" assigns it for the
+            whole run, so the cells stay at zero pressure after the signal ends.
+            "soft" adds the signal to the field. ``use_ultra`` follows the same three values.
         use_ultra : bool, optional
             Experimental. Run a user-supplied fullwave2-ultra binary (not shipped; pass it
             as ``path_fullwave_simulation_bin`` or set ``FW2U_BATCH_BIN``): ``bench_2d_batch``
@@ -620,6 +626,13 @@ class Solver:
             Width of the absorbing sponge of the ``use_ultra`` backend, in cells.
             None, the default, gives 6 wavelengths in 2D and 4 wavelengths in 3D.
             Used only with ``use_ultra=True``.
+        ultra_attenuation_parameters : str | Path, optional
+            Power-law attenuation for the ``use_ultra`` backend. Give "centered", "author",
+            or the path of a parameter file. Needs ``use_ultra=True`` and
+            ``use_exponential_attenuation=False``.
+        ultra_unlimited_materials : bool, optional
+            If True, allow any number of distinct materials (uses more GPU memory). Needs
+            ``ultra_attenuation_parameters``.
 
         Raises
         ------
@@ -630,9 +643,28 @@ class Solver:
             and transducer) are defined simultaneously.
 
         """
+        source_type = self._resolve_source_type(source_type=source_type, transducer=transducer)
         self.ultra = None
+        power_law_attenuation.check_unlimited_materials(
+            unlimited_materials=ultra_unlimited_materials,
+            parameters=ultra_attenuation_parameters,
+            use_ultra=use_ultra,
+        )
+        if ultra_attenuation_parameters is not None:
+            request = power_law_attenuation.check_request(
+                parameters=ultra_attenuation_parameters,
+                use_ultra=use_ultra,
+                use_exponential_attenuation=use_exponential_attenuation,
+                binary=path_fullwave_simulation_bin,
+                is_3d=grid.is_3d,
+                unlimited_materials=ultra_unlimited_materials,
+            )
+            ultra_attenuation_parameters = request.parameter_file
+            path_fullwave_simulation_bin = request.binary
         if use_ultra:
             self._init_ultra(
+                attenuation_parameters=ultra_attenuation_parameters,
+                unlimited_materials=ultra_unlimited_materials,
                 work_dir=work_dir,
                 grid=grid,
                 medium=medium,
@@ -813,7 +845,12 @@ class Solver:
             logger.error(error_msg)
             raise ValueError(error_msg)
         self.source_type = source_type
-        if is_soft(source_type) and self.source.p0_additive is not None:
+        source_is_the_transducers = source is None and transducer is not None
+        if is_soft(source_type) and source_is_the_transducers:
+            logger.info(
+                "source_type=%s, the transducer's source is driven by addition", source_type
+            )
+        elif is_soft(source_type) and self.source.p0_additive is not None:
             error_msg = (
                 "this source already carries an additive signal. source_type='soft' "
                 "converts a hard source into a soft one, and this source holds no "
@@ -824,7 +861,7 @@ class Solver:
             raise ValueError(error_msg)
         if not is_soft(source_type) and self.source.p0_additive is not None:
             self._warn_if_the_additive_signal_was_not_scaled()
-        if is_soft(source_type):
+        if is_soft(source_type) and not source_is_the_transducers:
             self.source = as_additive_source(
                 self.source,
                 self.grid,
@@ -898,11 +935,15 @@ class Solver:
         verify_gpu: bool,
         nbdy: int | None,
         options: dict,
+        attenuation_parameters: Path | None,
+        unlimited_materials: bool,
     ) -> None:
         """Set up the experimental fullwave2-ultra backend (see ``fullwave.ultra``)."""
         backend.warn_experimental()
         backend.warn_ppw_above_speed_optimum(ppw=grid.ppw)
-        backend.check_solver_options(**options)
+        backend.check_solver_options(
+            **options, has_attenuation_parameters=attenuation_parameters is not None
+        )
         binary_name = binary.BINARY_NAME_3D if grid.is_3d else binary.BINARY_NAME_2D
         ultra_binary = binary.resolve_binary(path_fullwave_simulation_bin, name=binary_name)
         self._check_input(grid, medium, source, sensor, transducer, ultra_binary)
@@ -924,8 +965,48 @@ class Solver:
             cuda_device_id=cuda_device_id,
             verify_gpu=verify_gpu,
             source_type=options["source_type"],
+            attenuation_parameters=attenuation_parameters,
+            unlimited_materials=unlimited_materials,
         )
 
+    @staticmethod
+    def _resolve_source_type(
+        *, source_type: str | None, transducer: fullwave.Transducer | None
+    ) -> str:
+        """Return the source type of the run.
+
+        Parameters
+        ----------
+        source_type : str | None
+            The Solver's own argument.
+        transducer : fullwave.Transducer | None
+            The transducer that drives the run, if any.
+
+        Returns
+        -------
+        str
+            The transducer's type when the argument is None and a transducer is given,
+            the argument when it is given, and "hard_released_after" otherwise.
+
+        Raises
+        ------
+        ValueError
+            If the argument differs from the transducer's type.
+        """
+        if transducer is None:
+            return HARD_RELEASED_AFTER if source_type is None else source_type
+        if source_type is None:
+            return transducer.source_type
+        if source_type != transducer.source_type:
+            error_msg = (
+                f"Solver source_type {source_type!r} differs from the transducer's "
+                f"source_type {transducer.source_type!r}. Set the source type in one "
+                "place, on the Transducer, and leave the Solver's source_type unset."
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+        return source_type
+
     def _warn_if_the_additive_signal_was_not_scaled(self) -> None:
         """Say so when an additive signal was built by hand and may carry no scale.
 
@@ -1541,8 +1622,10 @@ class Solver:
         Parameters
         ----------
         sources : Sequence[fullwave.Source]
-            The transmits, in order. Each one must have the same source coordinates,
-            the same signal kinds and the same signal length as the Solver's source.
+            The transmits, in order. Each one must have the same source coordinates
+            and the same signal kinds as the Solver's source. The signals may differ in
+            length and are padded with trailing zeros to the longest drive; with
+            ``use_ultra=True`` they must have one length.
             The Solver's ``source_type`` applies to every transmit.
         simulation_dir_name : str | Path
             The directory name of the simulation under the work directory.
@@ -1604,7 +1687,7 @@ class Solver:
                 highpass_cutoff_mhz=highpass_cutoff_mhz,
                 bandpass_cutoff_mhz=bandpass_cutoff_mhz,
             )
-        members = self._batch_members(sources)
+        members = self._batch_members(self._pad_to_longest_drive(sources))
         # The sensor and the sizing below need the extended grid and medium.
         self.pml_builder.run(use_pml=self.use_pml)
         sensor = self._output_sensor(
@@ -1647,6 +1730,43 @@ class Solver:
             return [path for run_paths in outputs for path in run_paths]
         return np.concatenate(outputs, axis=0)
 
+    def _pad_to_longest_drive(self, sources: Sequence[fullwave.Source]) -> list[fullwave.Source]:
+        """Return the transmits with every signal padded with zeros to the longest drive.
+
+        The longest drive is the longest signal among the transmits and the Solver's
+        source. The transmits are copied; the given sources stay as they are.
+
+        Parameters
+        ----------
+        sources : Sequence[fullwave.Source]
+            The transmits, in order.
+
+        Returns
+        -------
+        list[fullwave.Source]
+            The transmits, with signals of equal length.
+
+        """
+        names = ("p0", "p0_additive", "u0", "v0", "w0")
+        reference = [self.source] if getattr(self, "source", None) is not None else []
+        padded = []
+        for source in sources:
+            member = copy.copy(source)
+            for name in names:
+                signal = getattr(member, name, None)
+                if signal is None:
+                    continue
+                length = max(
+                    np.shape(getattr(other, name, None))[-1]
+                    for other in [*sources, *reference]
+                    if getattr(other, name, None) is not None
+                )
+                if np.shape(signal)[-1] < length:
+                    pad = [(0, 0)] * (np.ndim(signal) - 1) + [(0, length - np.shape(signal)[-1])]
+                    setattr(member, name, np.pad(signal, pad))
+            padded.append(member)
+        return padded
+
     def _batch_members(self, sources: Sequence[fullwave.Source]) -> list[fullwave.Source]:
         """Check the transmits of a batch against the Solver's source and return them.
 
@@ -1730,7 +1850,10 @@ class Solver:
                 return f"the {kind} signal is present in only one of them"
             if expected is None:
                 continue
-            if np.shape(found) != np.shape(expected):
+            if (
+                np.shape(found)[:-1] != np.shape(expected)[:-1]
+                or np.shape(found)[-1] < np.shape(expected)[-1]
+            ):
                 return f"the {kind} signal shape {np.shape(found)} != {np.shape(expected)}"
             expected_coords = getattr(self.source, coords, None)
             found_coords = getattr(member, coords, None)