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

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

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.5.2"
+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)

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)

fullwave/solver/input_file_writer.py

@@ -4,6 +4,8 @@ import concurrent.futures
 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
@@ -63,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.
 
@@ -123,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.")
@@ -138,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)
@@ -202,6 +211,7 @@ class InputFileWriter:
         *,
         is_static_map: bool = False,
         recalculate_pml: bool = True,
+        members: Sequence[fullwave.Source] | None = None,
     ) -> Path:
         r"""Run the input data generation and return the simulation directory path.
 
@@ -230,6 +240,11 @@ class InputFileWriter:
             set False if you are using the same PML parameters for each transmit event
             such as plane wave
             AND this is the second or later transmit event.
+        members : Sequence[fullwave.Source] | None
+            The transmits of a batch run, in order. Each member gives its own signals and
+            shares the coordinates of ``source``. The signals of all members are written one
+            after another, and nsims.dat holds the member count. None writes a single
+            transmit from ``source``.
 
         Returns
         -------
@@ -243,11 +258,19 @@ class InputFileWriter:
 
         self._init_pending_writes()
 
+        member_count_file = simulation_dir / "nsims.dat"
+        if members is None:
+            # A file left by an earlier batch run in this directory would turn this run into
+            # a batch.
+            member_count_file.unlink(missing_ok=True)
+        else:
+            self._queue_v_abs_write(np.int32, member_count_file, len(members))
+
         self._queue_ic_write(
             simulation_dir / "icmat.dat",
-            np.transpose(self.source.icmat),
+            np.transpose(self._signals("icmat", members)),
         )
-        p0_additive = getattr(self.source, "p0_additive", None)
+        p0_additive = self._signals("p0_additive", members)
         incoords_add = getattr(self.source, "incoords_add", None)
         if p0_additive is not None:
             self._queue_ic_write(
@@ -257,7 +280,7 @@ class InputFileWriter:
         if incoords_add is not None:
             self._queue_coords_write(simulation_dir / "icc_add.dat", incoords_add)
         for _vel_suffix, _vel_attr in (("u", "u0"), ("v", "v0"), ("w", "w0")):
-            _signal_vel = getattr(self.source, _vel_attr, None)
+            _signal_vel = self._signals(_vel_attr, members)
             _incoords_vel = getattr(self.source, f"incoords_{_vel_suffix}", None)
             if _signal_vel is not None:
                 self._queue_ic_write(
@@ -310,6 +333,44 @@ class InputFileWriter:
         logger.info(message)
         return simulation_dir
 
+    def _signals(
+        self,
+        name: str,
+        members: Sequence[fullwave.Source] | None,
+    ) -> np.ndarray | None:
+        """Return one source signal matrix, with the rows of every member stacked in order.
+
+        Parameters
+        ----------
+        name : str
+            The signal attribute of fullwave.Source: icmat, p0_additive, u0, v0 or w0.
+        members : Sequence[fullwave.Source] | None
+            The transmits of a batch run, or None for the single transmit of ``source``.
+
+        Returns
+        -------
+        np.ndarray | None
+            [n_points, n_t] for a single transmit, [n_members * n_points, n_t] for a batch,
+            or None when the source has no signal of this kind.
+
+        """
+        if members is None:
+            signal = getattr(self.source, name, None)
+        elif getattr(self.source, name, None) is None:
+            return None
+        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 ---
 
     def _set_d_mat(self) -> None:
@@ -867,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
@@ -1217,6 +1276,7 @@ class InputFileWriter:
             "ncoordsout",
             "ncoordszero",
             "nTic",
+            "hold_source",
             "modT",
             "modX",
             "modY",
@@ -1315,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),
@@ -1323,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))

fullwave/solver/launcher.py

@@ -1,5 +1,6 @@
 """Module for launching Fullwave simulation."""
 
+import copy
 import ctypes
 import logging
 import os
@@ -12,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__)
@@ -85,6 +87,26 @@ class Launcher:
         self.save_gpu_memory = save_gpu_memory
         logger.debug("Launcher instance created.")
 
+    def with_binary(self, path_fullwave_simulation_bin: Path) -> "Launcher":
+        """Return a copy of this launcher that runs another binary.
+
+        Parameters
+        ----------
+        path_fullwave_simulation_bin : Path
+            The binary of the copy.
+
+        Returns
+        -------
+        Launcher
+            The copy, with the same devices and memory settings.
+
+        """
+        error_msg = f"Fullwave simulation binary not found at {path_fullwave_simulation_bin}"
+        assert path_fullwave_simulation_bin.exists(), error_msg
+        launcher = copy.copy(self)
+        launcher._path_fullwave_simulation_bin = path_fullwave_simulation_bin
+        return launcher
+
     @staticmethod
     def _parse_cuda_device_id(cuda_device_id: str | int | list | None) -> str:
         """Parse the CUDA device ID input into a string format.
@@ -190,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)