fullwave25 1.4.2.dev0__tar.gz → 1.4.2.dev2__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.2-dev0
+Version: 1.4.2-dev2
 Summary: Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities
 Author: Masashi Sode, Gianmarco Pinton
 Maintainer: Masashi Sode
@@ -25,7 +25,7 @@ Requires-Dist: tomli>=2.3.0
 Requires-Dist: tqdm>=4.67.1
 Provides-Extra: dev
 Requires-Dist: line-profiler>=5.0.1; extra == 'dev'
-Requires-Dist: pre-commit==4.1.0; extra == 'dev'
+Requires-Dist: pre-commit==4.6.2; extra == 'dev'
 Requires-Dist: pytest>=8.3.5; extra == 'dev'
 Requires-Dist: ruff>=0.12.9; extra == 'dev'
 Provides-Extra: examples
@@ -270,7 +270,7 @@ The arrays are `l7_4` (linear, 128 elements, 5.208 MHz), `c5_2v` (curved, 49.57
 
 The transmits are `plane_wave(angle_deg=...)`, `focus(focus_m=...)`, `diverging(virtual_source_m=...)` and `synthetic_aperture(element)`. Each takes `apodization` and `pulse`. Set `transducer.active_source_elements` first to use part of the aperture.
 
-Every transducer is additive by default, which is what the calibrated setups use. Pass `source_type="clamped"` for a hard source.
+The source type is `"hard_released_after"` by default: the transducer assigns its pressure while the drive signal plays, then the source cells evolve freely. `"hard"` assigns it for the whole run, so the cells stay at zero pressure after the drive ends. `"soft"` adds the signal to the field, and is what the calibrated setups use. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
 
 `transducer.apply_transducer_stack(...)` paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built. `fullwave.TransducerStack` holds the values.
 
@@ -389,6 +389,61 @@ Please see the following examples for more advanced usage.
 
 ---
 
+## Experimental: fullwave2-ultra backend
+
+`Solver(..., use_ultra=True)` runs the simulation with the fullwave2-ultra binary instead of the fullwave25 solver binary. It is experimental and the API may change.
+
+The fullwave2-ultra backend is optimized for speed at ppw = 6 (`Grid.ppw`); a larger ppw runs, but more slowly, and gives a warning.
+
+fullwave25 does not ship the fullwave2-ultra binaries. Get them from <https://github.com/pinton-lab/fullwave2-ultra> or contact the Pinton lab.
+
+Point the solver to the binary with `path_fullwave_simulation_bin` or with the environment variable `FW2U_BATCH_BIN`. Either can be the binary file or the folder that contains it. The binary name is `bench_2d_batch` for a 2D grid and `bench_3d_opt` for a 3D grid.
+
+```python
+from pathlib import Path
+
+import fullwave
+
+solver = fullwave.Solver(
+    work_dir=Path("./outputs/ultra"),
+    grid=grid,  # 2D or 3D fullwave.Grid
+    medium=medium,  # fullwave.Medium with alpha_power == 1 everywhere
+    source=source,
+    sensor=sensor,
+    path_fullwave_simulation_bin=Path("/path/to/fullwave2-ultra/bin"),
+    use_ultra=True,
+)
+traces = solver.run()  # (n_sensors, n_frames)
+# 2D only: traces = solver.run_batch(sources)  # (n_transmits, n_sensors, n_frames)
+```
+
+In 2D, `run_batch` treats `max_members_per_run` as an upper bound that the free GPU memory can lower, and it keeps the requested value, with a warning, when the free memory cannot be read. The native path uses an explicit `max_members_per_run` as given.
+
+Supported now:
+
+- 2D grids with `run` and `run_batch`, including air cells.
+- 3D grids with `run`, including air cells.
+- Additive sources (`p0_additive`) and `source_type="soft"` in 2D and 3D.
+- The three source types in 2D and 3D, as on the native path: `"hard"` holds the source cells at zero pressure after `p0` ends, `"hard_released_after"` lets them evolve freely, and `"soft"` (and `p0_additive`) add to the pressure.
+
+`UltraUnsupportedError` is raised for:
+
+- `run_batch` in 3D.
+- Velocity sources, and sources that are not pressure sources.
+- Sparse-grid sensors, `is_static_map`, and `record_whole_domain`.
+- Media other than `fullwave.Medium` (exponential attenuation), and `alpha_power` other than 1.
+- `use_pml=False`, `m_spatial_order` other than 8, `use_gpu=False`, and an invalid `source_type`.
+- In 2D, a binary that does not read the files for air cells, for the additive channel, or for releasing the source (with such a binary, pad `p0` to `grid.nt`).
+- In 3D, air cells with a binary that does not read `icczero.dat` and `nzero0.dat`, and additive sources with a binary that does not read `ncoords_add.dat` and `icmat_add.dat`.
+
+This list will grow as the backend does.
+
+The backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency). Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
+
+Options that only tune the native solver are ignored with a warning, once per process: `pml_layer_thickness_px`, `n_transition_layer`, `pml_alpha_entrance`, `exponential_attenuation_pml_thickness_px` (use `ultra_sponge_thickness_px` instead), `use_gpu_pml`, `save_gpu_memory`, `write_maps_the_solver_does_not_read`, `use_isotropic_relaxation=False`, and a `cuda_device_id` that lists more than one device (the run uses the first one listed). `use_exponential_attenuation=False`, the native default, also warns that the backend runs the exponential attenuation model, whose attenuation is frequency-independent, not the relaxation model, whose attenuation is frequency-dependent. Pass `use_exponential_attenuation=True` to silence it.
+
+---
+
 ## Attention
 
 - The simulation grid is defined as follows:

{fullwave25-1.4.2.dev0 → fullwave25-1.4.2.dev2}/README.md

@@ -229,7 +229,7 @@ The arrays are `l7_4` (linear, 128 elements, 5.208 MHz), `c5_2v` (curved, 49.57
 
 The transmits are `plane_wave(angle_deg=...)`, `focus(focus_m=...)`, `diverging(virtual_source_m=...)` and `synthetic_aperture(element)`. Each takes `apodization` and `pulse`. Set `transducer.active_source_elements` first to use part of the aperture.
 
-Every transducer is additive by default, which is what the calibrated setups use. Pass `source_type="clamped"` for a hard source.
+The source type is `"hard_released_after"` by default: the transducer assigns its pressure while the drive signal plays, then the source cells evolve freely. `"hard"` assigns it for the whole run, so the cells stay at zero pressure after the drive ends. `"soft"` adds the signal to the field, and is what the calibrated setups use. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
 
 `transducer.apply_transducer_stack(...)` paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built. `fullwave.TransducerStack` holds the values.
 
@@ -348,6 +348,61 @@ Please see the following examples for more advanced usage.
 
 ---
 
+## Experimental: fullwave2-ultra backend
+
+`Solver(..., use_ultra=True)` runs the simulation with the fullwave2-ultra binary instead of the fullwave25 solver binary. It is experimental and the API may change.
+
+The fullwave2-ultra backend is optimized for speed at ppw = 6 (`Grid.ppw`); a larger ppw runs, but more slowly, and gives a warning.
+
+fullwave25 does not ship the fullwave2-ultra binaries. Get them from <https://github.com/pinton-lab/fullwave2-ultra> or contact the Pinton lab.
+
+Point the solver to the binary with `path_fullwave_simulation_bin` or with the environment variable `FW2U_BATCH_BIN`. Either can be the binary file or the folder that contains it. The binary name is `bench_2d_batch` for a 2D grid and `bench_3d_opt` for a 3D grid.
+
+```python
+from pathlib import Path
+
+import fullwave
+
+solver = fullwave.Solver(
+    work_dir=Path("./outputs/ultra"),
+    grid=grid,  # 2D or 3D fullwave.Grid
+    medium=medium,  # fullwave.Medium with alpha_power == 1 everywhere
+    source=source,
+    sensor=sensor,
+    path_fullwave_simulation_bin=Path("/path/to/fullwave2-ultra/bin"),
+    use_ultra=True,
+)
+traces = solver.run()  # (n_sensors, n_frames)
+# 2D only: traces = solver.run_batch(sources)  # (n_transmits, n_sensors, n_frames)
+```
+
+In 2D, `run_batch` treats `max_members_per_run` as an upper bound that the free GPU memory can lower, and it keeps the requested value, with a warning, when the free memory cannot be read. The native path uses an explicit `max_members_per_run` as given.
+
+Supported now:
+
+- 2D grids with `run` and `run_batch`, including air cells.
+- 3D grids with `run`, including air cells.
+- Additive sources (`p0_additive`) and `source_type="soft"` in 2D and 3D.
+- The three source types in 2D and 3D, as on the native path: `"hard"` holds the source cells at zero pressure after `p0` ends, `"hard_released_after"` lets them evolve freely, and `"soft"` (and `p0_additive`) add to the pressure.
+
+`UltraUnsupportedError` is raised for:
+
+- `run_batch` in 3D.
+- Velocity sources, and sources that are not pressure sources.
+- Sparse-grid sensors, `is_static_map`, and `record_whole_domain`.
+- Media other than `fullwave.Medium` (exponential attenuation), and `alpha_power` other than 1.
+- `use_pml=False`, `m_spatial_order` other than 8, `use_gpu=False`, and an invalid `source_type`.
+- In 2D, a binary that does not read the files for air cells, for the additive channel, or for releasing the source (with such a binary, pad `p0` to `grid.nt`).
+- In 3D, air cells with a binary that does not read `icczero.dat` and `nzero0.dat`, and additive sources with a binary that does not read `ncoords_add.dat` and `icmat_add.dat`.
+
+This list will grow as the backend does.
+
+The backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency). Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
+
+Options that only tune the native solver are ignored with a warning, once per process: `pml_layer_thickness_px`, `n_transition_layer`, `pml_alpha_entrance`, `exponential_attenuation_pml_thickness_px` (use `ultra_sponge_thickness_px` instead), `use_gpu_pml`, `save_gpu_memory`, `write_maps_the_solver_does_not_read`, `use_isotropic_relaxation=False`, and a `cuda_device_id` that lists more than one device (the run uses the first one listed). `use_exponential_attenuation=False`, the native default, also warns that the backend runs the exponential attenuation model, whose attenuation is frequency-independent, not the relaxation model, whose attenuation is frequency-dependent. Pass `use_exponential_attenuation=True` to silence it.
+
+---
+
 ## Attention
 
 - The simulation grid is defined as follows:

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

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

{fullwave25-1.4.2.dev0 → fullwave25-1.4.2.dev2}/fullwave/medium.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import logging
 from collections import OrderedDict
-from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -93,8 +93,6 @@ def _upload_arrays_multi_gpu(
     dict mapping name -> CuPy array on *target_device*.
 
     """
-    from concurrent.futures import as_completed  # noqa: PLC0415
-
     import cupy as cp  # noqa: PLC0415
 
     n_gpus = cp.cuda.runtime.getDeviceCount()

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

@@ -21,6 +21,8 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 
+from tqdm import tqdm
+
 logger = logging.getLogger("__main__." + __name__)
 
 GITHUB_REPO = "pinton-lab/fullwave25"
@@ -28,7 +30,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.6"
+BINARY_RELEASE_TAG = "fullwave_bin_v1.7"
 
 
 def _download_url(filename: str, tag: str) -> str:
@@ -36,39 +38,34 @@ def _download_url(filename: str, tag: str) -> str:
 
 
 def _download_binary(url: str, dest: Path) -> None:
-    """Download *url* to *dest*, showing a tqdm progress bar when available."""
+    """Download *url* to *dest*, showing a tqdm progress bar."""
     dest.parent.mkdir(parents=True, exist_ok=True)
     tmp = dest.with_suffix(".download_tmp")
     try:
+
+        class _Hook:
+            def __init__(self) -> None:
+                self._bar: tqdm | None = None
+
+            def __call__(self, block: int, block_size: int, total: int) -> None:  # noqa: ARG002
+                if self._bar is None:
+                    self._bar = tqdm(
+                        total=total if total > 0 else None,
+                        unit="B",
+                        unit_scale=True,
+                        desc=dest.name,
+                    )
+                self._bar.update(block_size)
+
+            def close(self) -> None:
+                if self._bar is not None:
+                    self._bar.close()
+
+        hook = _Hook()
         try:
-            from tqdm import tqdm  # noqa: PLC0415
-
-            class _Hook:
-                def __init__(self) -> None:
-                    self._bar: tqdm | None = None
-
-                def __call__(self, block: int, block_size: int, total: int) -> None:  # noqa: ARG002
-                    if self._bar is None:
-                        self._bar = tqdm(
-                            total=total if total > 0 else None,
-                            unit="B",
-                            unit_scale=True,
-                            desc=dest.name,
-                        )
-                    self._bar.update(block_size)
-
-                def close(self) -> None:
-                    if self._bar is not None:
-                        self._bar.close()
-
-            hook = _Hook()
-            try:
-                urllib.request.urlretrieve(url, tmp, reporthook=hook)  # noqa: S310
-            finally:
-                hook.close()
-
-        except ImportError:
-            urllib.request.urlretrieve(url, tmp)  # noqa: S310
+            urllib.request.urlretrieve(url, tmp, reporthook=hook)  # noqa: S310
+        finally:
+            hook.close()
 
         tmp.rename(dest)
         dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)

fullwave25-1.4.2.dev2/fullwave/solver/binary_markers.py

@@ -0,0 +1,87 @@
+"""Find out whether a solver binary reads an input file, by the file name in its bytes."""
+
+import mmap
+from functools import lru_cache
+from pathlib import Path
+from typing import NamedTuple
+
+HOLD_SOURCE_MARKER = b"hold_source.dat"
+DEFAULT_FIX = "rebuild the binary, or set FULLWAVE25_BINARY_TAG to the release that has it"
+
+
+class HoldSourceUnsupportedError(RuntimeError):
+    """Raised when the binary cannot hold the hard source after the drive ends."""
+
+
+class _FileStamp(NamedTuple):
+    """A file with the size and modification time that tell whether it changed."""
+
+    path: Path
+    size: int
+    mtime_ns: int
+
+
+@lru_cache(maxsize=64)
+def _find(stamp: _FileStamp, marker: bytes) -> bool:
+    if stamp.size == 0:
+        return False
+    with stamp.path.open("rb") as file, mmap.mmap(file.fileno(), 0, access=mmap.ACCESS_READ) as mm:
+        return mm.find(marker) != -1
+
+
+def binary_has_marker(binary: str | Path, *, marker: bytes) -> bool:
+    """Return whether the bytes of ``binary`` contain ``marker``.
+
+    Parameters
+    ----------
+    binary : str | Path
+        The solver binary.
+    marker : bytes
+        The name of the input file the binary reads.
+
+    Returns
+    -------
+    bool
+        True when the binary contains the name. The answer is cached until the file changes.
+
+    """
+    path = Path(binary).resolve()
+    stat = path.stat()
+    return _find(_FileStamp(path=path, size=stat.st_size, mtime_ns=stat.st_mtime_ns), marker)
+
+
+def check_binary_holds_source(
+    binary: str | Path,
+    *,
+    marker: bytes = HOLD_SOURCE_MARKER,
+    error_type: type[Exception] = HoldSourceUnsupportedError,
+    fix: str = DEFAULT_FIX,
+) -> None:
+    """Refuse a binary that would release the hard source cells when the drive ends.
+
+    Parameters
+    ----------
+    binary : str | Path
+        The solver binary.
+    marker : bytes, optional
+        The name of the input file that tells the binary to hold the source.
+    error_type : type[Exception], optional
+        The exception to raise.
+    fix : str, optional
+        What to do to get a binary that reads the file, worded for the message.
+
+    Raises
+    ------
+    Exception
+        ``error_type``, when the binary does not contain ``marker``.
+
+    """
+    if binary_has_marker(binary, marker=marker):
+        return
+    message = (
+        f"{Path(binary).name} does not read {marker.decode()}, so it releases the hard source "
+        "cells when the drive signal ends and source_type='hard' would not hold them. "
+        f"Use a binary that reads it: {fix}. "
+        "source_type='hard_released_after' needs no such binary."
+    )
+    raise error_type(message)

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

@@ -5,6 +5,7 @@ import logging
 import os
 import time
 from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
 import numpy as np
@@ -64,6 +65,7 @@ class InputFileWriter:
         exponential_attenuation_pml_interior_offset_px: int = 0,
         use_gpu: bool = False,
         write_maps_the_solver_does_not_read: bool = False,
+        hold_hard_source: bool = False,
     ) -> None:
         """Initialize the InputGeneratorBase instance.
 
@@ -124,6 +126,11 @@ class InputFileWriter:
             which an older solver binary needs. The record the skipped maps
             replace is impedance_constraint.dat, and this writer always writes it
             on the relaxation path.
+        hold_hard_source : bool, optional
+            Whether the hard source cells stay at zero pressure after the drive ends.
+            True writes the flag file ``hold_source.dat``, which the solver reads to keep
+            the cells at zero for the rest of the run; the signals are written as given.
+            False, the default, lets the solver release the cells when the signal ends.
 
         """
         logger.debug("Initializing InputFileWriter instance.")
@@ -139,6 +146,7 @@ class InputFileWriter:
         self.use_isotropic_relaxation = use_isotropic_relaxation
         self.write_maps_the_solver_does_not_read = write_maps_the_solver_does_not_read
         self.use_gpu = use_gpu
+        self.hold_hard_source = hold_hard_source
 
         if validate_input:
             check_functions.check_path_exists(self.path_fullwave_simulation_bin)
@@ -347,10 +355,21 @@ class InputFileWriter:
 
         """
         if members is None:
-            return getattr(self.source, name, None)
-        if getattr(self.source, name, None) is None:
+            signal = getattr(self.source, name, None)
+        elif getattr(self.source, name, None) is None:
             return None
-        return np.concatenate([getattr(member, name) for member in members], axis=0)
+        else:
+            signal = np.concatenate([getattr(member, name) for member in members], axis=0)
+        return signal
+
+    @property
+    def _holds_the_source(self) -> bool:
+        """Whether the solver keeps the hard source cells at zero after the drive ends."""
+        return (
+            self.hold_hard_source
+            and self.source.n_sources > 0
+            and self.source.icmat.shape[1] < self.grid.nt
+        )
 
     # --- constructor utils ---
 
@@ -909,8 +928,6 @@ class InputFileWriter:
             (c_min_val, c_max_val) of the sound speed.
 
         """
-        from concurrent.futures import ThreadPoolExecutor, as_completed  # noqa: PLC0415
-
         import cupy as cp  # noqa: PLC0415
 
         sound_speed_np = self.medium.sound_speed
@@ -1259,6 +1276,7 @@ class InputFileWriter:
             "ncoordsout",
             "ncoordszero",
             "nTic",
+            "hold_source",
             "modT",
             "modX",
             "modY",
@@ -1357,7 +1375,6 @@ class InputFileWriter:
             self._queue_v_abs_write(np.float32, save_path, var)
 
     def _save_coords_params(self, simulation_dir: Path) -> None:
-        nt_ic = self.source.icmat.shape[1]
         var_list = [
             ("nX", self.grid.nx),
             ("nY", self.grid.ny),
@@ -1365,9 +1382,11 @@ class InputFileWriter:
             ("ncoords", self.source.n_sources),
             ("ncoordsout", self.sensor.n_sensors),
             ("ncoordszero", self.medium.n_air),
-            ("nTic", nt_ic),
+            ("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))

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

@@ -13,6 +13,7 @@ from time import time
 import numpy as np
 from numpy.typing import NDArray
 
+from .cuda_utils import find_consecutive_gpus_without_peer_access
 from .utils import load_dat_data
 
 logger = logging.getLogger("__main__." + __name__)
@@ -211,8 +212,6 @@ class Launcher:
             )
             return
         try:
-            from .cuda_utils import find_consecutive_gpus_without_peer_access  # noqa: PLC0415
-
             pairs = find_consecutive_gpus_without_peer_access(device_ids)
         except (AttributeError, NameError, OSError, RuntimeError, ctypes.ArgumentError) as error:
             logger.debug("Peer access check skipped: %s", error)