fullwave25 1.4.2.dev1__tar.gz → 1.4.2.dev2__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.2-dev1
+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
@@ -417,6 +417,8 @@ 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.
@@ -430,12 +432,16 @@ Supported now:
 - 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`, the PML settings (set the sponge width with `exponential_attenuation_pml_thickness_px`), `m_spatial_order` other than 8, `use_gpu=False`, `save_gpu_memory`, and more than one GPU.
+- `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

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

@@ -376,6 +376,8 @@ 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.
@@ -389,12 +391,16 @@ Supported now:
 - 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`, the PML settings (set the sponge width with `exponential_attenuation_pml_thickness_px`), `m_spatial_order` other than 8, `use_gpu=False`, `save_gpu_memory`, and more than one GPU.
+- `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

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

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

@@ -1,11 +1,8 @@
 """solver module."""
 
 import contextlib
-import gc
 import logging
 import os
-import shutil
-import subprocess
 import time
 import warnings
 from collections.abc import Iterator, Sequence
@@ -30,6 +27,11 @@ from fullwave.utils import (
     check_functions,
     run_directory_in_memory,
 )
+from fullwave.utils.gpu_memory import (
+    free_gpu_memory_bytes,
+    members_that_fit,
+    release_gpu_memory_pools,
+)
 from fullwave.utils.signal_filter import apply_filter
 
 from .binary_manager import ensure_binary
@@ -74,48 +76,6 @@ def _split_evenly(members: list, largest: int) -> list[list]:
     return runs
 
 
-def _free_gpu_memory_bytes(device_ids: Sequence[str]) -> dict[str, int] | None:
-    """Return the free memory of each GPU in bytes, as nvidia-smi reports it.
-
-    Parameters
-    ----------
-    device_ids : Sequence[str]
-        The GPU indices, as nvidia-smi counts them.
-
-    Returns
-    -------
-    dict[str, int] | None
-        The free bytes of each GPU, or None when nvidia-smi cannot be run or does not
-        report every GPU.
-
-    """
-    wanted = [device.strip() for device in device_ids]
-    nvidia_smi_path = shutil.which("nvidia-smi")
-    if nvidia_smi_path is None:
-        return None
-    try:
-        found = subprocess.run(  # noqa: S603
-            [nvidia_smi_path, "--query-gpu=index,memory.free", "--format=csv,noheader,nounits"],
-            capture_output=True,
-            text=True,
-            check=True,
-            timeout=30,
-        ).stdout
-    except (OSError, subprocess.SubprocessError):
-        return None
-    free = {}
-    for line in found.splitlines():
-        index, _, mebibytes = line.partition(",")
-        if index.strip() in wanted:
-            try:
-                free[index.strip()] = int(float(mebibytes)) * 1024**2
-            except ValueError:
-                return None
-    if set(free) != set(wanted):
-        return None
-    return free
-
-
 COMPATIBLE_CUDA_ARCHITECTURES = [
     "sm_50",  # Maxwell: GTX 750, GTX 750 Ti
     "sm_52",  # Maxwell: GTX 980, GTX 970
@@ -513,6 +473,7 @@ class Solver:
         source_type: str = HARD_RELEASED_AFTER,
         write_maps_the_solver_does_not_read: bool = False,
         use_ultra: bool = False,
+        ultra_sponge_thickness_px: int | None = None,
     ) -> None:
         """Initialize a Solver instance for the fullwave simulation.
 
@@ -648,11 +609,17 @@ class Solver:
             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``
             for a 2D grid, ``bench_3d_opt`` for a 3D grid.
-            ``exponential_attenuation_pml_thickness_px`` sets the sponge width in cells.
-            A source with ``p0_additive`` and ``source_type="soft"`` are added to the pressure
-            through the binary's additive channel, which needs a binary that reads
-            ``ncoords_add.dat`` (and ``icmat_add.dat`` on a 3D grid). Unsupported options raise
-            ``UltraUnsupportedError``.
+            The backend runs the exponential attenuation model (frequency-independent:
+            the same attenuation at every frequency). A source with ``p0_additive`` and
+            ``source_type="soft"`` are added to the pressure through the binary's additive
+            channel, which needs a binary that reads ``ncoords_add.dat`` (and ``icmat_add.dat``
+            on a 3D grid). Options that only tune the native solver are ignored with a
+            warning; the README lists them.
+            Other unsupported options raise ``UltraUnsupportedError``.
+        ultra_sponge_thickness_px : int, optional
+            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``.
 
         Raises
         ------
@@ -676,21 +643,32 @@ class Solver:
                 run_on_memory=run_on_memory,
                 cuda_device_id=cuda_device_id,
                 verify_gpu=verify_gpu,
-                nbdy=exponential_attenuation_pml_thickness_px,
+                nbdy=ultra_sponge_thickness_px,
                 options={
                     "use_pml": use_pml,
                     "m_spatial_order": m_spatial_order,
-                    "pml_layer_thickness_px": pml_layer_thickness_px,
-                    "n_transition_layer": n_transition_layer,
                     "use_gpu": use_gpu,
-                    "use_gpu_pml": use_gpu_pml,
-                    "pml_alpha_entrance": pml_alpha_entrance,
                     "source_type": source_type,
-                    "save_gpu_memory": save_gpu_memory,
-                    "write_maps_the_solver_does_not_read": write_maps_the_solver_does_not_read,
+                    "use_exponential_attenuation": use_exponential_attenuation,
+                    "native_only_options": {
+                        "pml_layer_thickness_px": pml_layer_thickness_px,
+                        "n_transition_layer": n_transition_layer,
+                        "pml_alpha_entrance": pml_alpha_entrance,
+                        "exponential_attenuation_pml_thickness_px": (
+                            exponential_attenuation_pml_thickness_px
+                        ),
+                        "use_gpu_pml": use_gpu_pml,
+                        "save_gpu_memory": save_gpu_memory,
+                        "write_maps_the_solver_does_not_read": (
+                            write_maps_the_solver_does_not_read
+                        ),
+                        "use_isotropic_relaxation": use_isotropic_relaxation,
+                    },
                 },
             )
             return
+        if ultra_sponge_thickness_px is not None:
+            backend.warn_sponge_without_ultra()
         if exponential_attenuation_pml_thickness_px is not None and not use_exponential_attenuation:
             error_msg = (
                 "exponential_attenuation_pml_thickness_px belongs to the exponential "
@@ -968,31 +946,6 @@ class Solver:
         )
         logger.warning(message)
 
-    @staticmethod
-    def _release_gpu_memory_pools() -> None:
-        """Release all CuPy GPU memory pool blocks back to CUDA.
-
-        Call ``gc.collect()`` first so that Python releases references to
-        CuPy arrays, then drain both the device and pinned memory pools.
-        This prevents stale allocations from causing memory pressure when
-        subsequent operations allocate large GPU arrays.
-
-        The release is best effort. It does nothing when CuPy is absent, and
-        it does nothing when CuPy is present without a usable CUDA driver,
-        which is the case on a machine with no GPU.
-        """
-        gc.collect()
-        try:
-            import cupy as cp  # noqa: PLC0415
-        except ImportError:
-            return
-
-        try:
-            cp.get_default_memory_pool().free_all_blocks()
-            cp.get_default_pinned_memory_pool().free_all_blocks()
-        except cp.cuda.runtime.CUDARuntimeError as error:
-            logger.debug("GPU memory pools were not released: %s", error)
-
     @staticmethod
     def _check_input(
         grid: fullwave.Grid,
@@ -1420,10 +1373,10 @@ class Solver:
                 "Input data generation completed in %s. Skipping simulation execution.",
                 simulation_dir,
             )
-            self._release_gpu_memory_pools()
+            release_gpu_memory_pools()
             return simulation_dir
 
-        self._release_gpu_memory_pools()
+        release_gpu_memory_pools()
 
         if members is not None:
             return self._run_members(
@@ -1933,9 +1886,8 @@ class Solver:
     def _members_that_fit(self, sensor: fullwave.Sensor) -> int | None:
         """Return how many transmits the GPU memory estimate fits into the free memory.
 
-        The estimate of one GPU grows by the same amount for each transmit. The count
-        keeps 10 % of the free memory and 512 MiB free for the CUDA context and for
-        what the estimate does not count, and takes the smallest count over the GPUs.
+        The estimate of one GPU grows by the same amount for each transmit. The count is the
+        smallest over the GPUs.
 
         Parameters
         ----------
@@ -1948,18 +1900,21 @@ class Solver:
             The count, or None when the free memory cannot be read.
 
         """
-        free = _free_gpu_memory_bytes(self.fullwave_launcher.cuda_device_id.split(","))
+        free = free_gpu_memory_bytes(self.fullwave_launcher.cuda_device_id.split(","))
         if free is None:
             return None
         one = self._gpu_memory_bytes(sensor, n_members=1)
         two = self._gpu_memory_bytes(sensor, n_members=2)
-        reserve = 512 * 1024**2
         counts = []
         for (device, one_bytes, *_), (_, two_bytes, *_) in zip(one, two, strict=True):
-            per_member = max(two_bytes - one_bytes, 1)
-            shared = one_bytes - per_member
-            usable = 0.9 * free.get(device, 0) - reserve - shared
-            counts.append(int(usable // per_member))
+            per_member_bytes = max(two_bytes - one_bytes, 1)
+            counts.append(
+                members_that_fit(
+                    free_bytes=free.get(device, 0),
+                    shared_bytes=one_bytes - per_member_bytes,
+                    per_member_bytes=per_member_bytes,
+                )
+            )
         return min(counts)
 
     def _estimate_gpu_memory(

{fullwave25-1.4.2.dev1 → fullwave25-1.4.2.dev2}/fullwave/ultra/backend.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+import inspect
 import time
 import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 import numpy as np
 
@@ -36,15 +37,43 @@ if TYPE_CHECKING:
 CFL_LIMIT_3D = 0.30
 SPEED_OPTIMIZED_PPW = 6
 
+PACKAGE_DIR = Path(__file__).parents[1]
+
 _shown_warnings: set[str] = set()
 
 
+def _stacklevel_of_first_caller_outside_package() -> int:
+    """Return the ``warnings.warn`` stacklevel of the first frame outside the fullwave package."""
+    frame = inspect.currentframe()
+    stacklevel = 0
+    while frame is not None and Path(frame.f_code.co_filename).is_relative_to(PACKAGE_DIR):
+        frame = frame.f_back
+        stacklevel += 1
+    return stacklevel
+
+
 def _warn_once(*, name: str, message: str, category: type[Warning]) -> None:
-    """Warn with ``message`` the first time ``name`` is seen in this process."""
+    """Warn with ``message`` the first time ``name`` is seen in this process.
+
+    The warning points at the line of the user's code, however deep the call is.
+    """
     if name in _shown_warnings:
         return
     _shown_warnings.add(name)
-    warnings.warn(message, category, stacklevel=5)
+    warnings.warn(message, category, stacklevel=_stacklevel_of_first_caller_outside_package())
+
+
+def warn_sponge_without_ultra() -> None:
+    """Warn once per process that ``ultra_sponge_thickness_px`` needs ``use_ultra=True``."""
+    _warn_once(
+        name="sponge_without_ultra",
+        message=(
+            "ultra_sponge_thickness_px is ignored without use_ultra=True. The native "
+            "absorber is sized by pml_layer_thickness_px (relaxation model) or "
+            "exponential_attenuation_pml_thickness_px (exponential model)."
+        ),
+        category=UserWarning,
+    )
 
 
 def warn_ppw_above_speed_optimum(*, ppw: int) -> None:
@@ -72,6 +101,25 @@ def warn_experimental() -> None:
     )
 
 
+def warn_ignored(*, option: str, detail: str = "") -> None:
+    """Warn once per process that ``use_ultra=True`` ignores ``option``."""
+    suffix = f"; {detail}" if detail else ""
+    _warn_once(
+        name=f"ignored:{option}",
+        message=f"{option} is ignored with use_ultra=True{suffix}.",
+        category=UserWarning,
+    )
+
+
+def warn_one_device_only(*, device: int) -> None:
+    """Warn once per process that ``use_ultra=True`` runs on one GPU, the first one listed."""
+    _warn_once(
+        name="one_device_only",
+        message=f"cuda_device_id lists several GPUs; use_ultra=True runs on GPU {device} only.",
+        category=UserWarning,
+    )
+
+
 def refuse(message: str) -> None:
     """Raise ``UltraUnsupportedError`` with ``message``."""
     raise UltraUnsupportedError(message)
@@ -122,9 +170,12 @@ def single_device(cuda_device_id: str | int | list | None) -> int:
         devices = list(cuda_device_id)
     else:
         devices = [cuda_device_id]
-    if len(devices) != 1:
-        refuse("use_ultra=True runs on one GPU; give one cuda_device_id")
-    return int(devices[0])
+    if not devices:
+        refuse("cuda_device_id lists no device")
+    device = int(devices[0])
+    if len(devices) > 1:
+        warn_one_device_only(device=device)
+    return device
 
 
 def work_directory(
@@ -377,39 +428,70 @@ class UltraBackend3D:
         )
 
 
+SPONGE_HINT = "set the sponge width with ultra_sponge_thickness_px"
+
+
+class NativeOnlyOption(NamedTuple):
+    """An option of the native solver that ``use_ultra=True`` ignores."""
+
+    solver_default: object
+    hint: str = ""
+
+
+NATIVE_ONLY_OPTIONS: dict[str, NativeOnlyOption] = {
+    "pml_layer_thickness_px": NativeOnlyOption(solver_default=None, hint=SPONGE_HINT),
+    "n_transition_layer": NativeOnlyOption(solver_default=None, hint=SPONGE_HINT),
+    "pml_alpha_entrance": NativeOnlyOption(solver_default=None, hint=SPONGE_HINT),
+    "exponential_attenuation_pml_thickness_px": NativeOnlyOption(
+        solver_default=None, hint=SPONGE_HINT
+    ),
+    "use_gpu_pml": NativeOnlyOption(solver_default=False),
+    "save_gpu_memory": NativeOnlyOption(solver_default=False),
+    "write_maps_the_solver_does_not_read": NativeOnlyOption(solver_default=False),
+    "use_isotropic_relaxation": NativeOnlyOption(solver_default=True),
+}
+
+
+def warn_native_only_options(*, options: dict[str, object]) -> None:
+    """Warn once per process for each native-only option set to a non-default value."""
+    for name, option in NATIVE_ONLY_OPTIONS.items():
+        if options[name] != option.solver_default:
+            warn_ignored(option=name, detail=option.hint)
+
+
+def warn_relaxation_model_requested(*, use_exponential_attenuation: bool) -> None:
+    """Warn once per process when the relaxation model is requested, as the native default does."""
+    if use_exponential_attenuation:
+        return
+    _warn_once(
+        name="attenuation_model",
+        message=(
+            "use_ultra=True runs the exponential attenuation model, whose attenuation is "
+            "frequency-independent (the same at every frequency), not the relaxation model that "
+            "use_exponential_attenuation=False requests, whose attenuation is "
+            "frequency-dependent."
+        ),
+        category=UserWarning,
+    )
+
+
 def check_solver_options(
     *,
     use_pml: bool,
     m_spatial_order: int,
-    pml_layer_thickness_px: int | None,
-    n_transition_layer: int | None,
     use_gpu: bool,
-    use_gpu_pml: bool,
-    pml_alpha_entrance: float | None,
     source_type: str,
-    save_gpu_memory: bool,
-    write_maps_the_solver_does_not_read: bool,
+    native_only_options: dict[str, object],
+    use_exponential_attenuation: bool,
 ) -> None:
-    """Refuse the ``Solver`` options that ``use_ultra=True`` cannot honor."""
+    """Refuse the ``Solver`` options that ``use_ultra=True`` cannot honor; warn on the rest."""
     if not use_pml:
         refuse("use_pml=False is not supported by use_ultra=True")
-    if (
-        pml_layer_thickness_px is not None
-        or n_transition_layer is not None
-        or use_gpu_pml
-        or pml_alpha_entrance is not None
-    ):
-        refuse(
-            "PML settings do not apply to use_ultra=True; "
-            "set the sponge with exponential_attenuation_pml_thickness_px"
-        )
     if m_spatial_order != 8:
         refuse("use_ultra=True supports m_spatial_order=8 only")
     if not use_gpu:
         refuse("use_ultra=True needs the GPU")
     if source_type not in SOURCE_TYPES:
         refuse(f"source_type must be one of {SOURCE_TYPES}, not {source_type!r}")
-    if save_gpu_memory:
-        refuse("save_gpu_memory is not supported by use_ultra=True")
-    if write_maps_the_solver_does_not_read:
-        refuse("write_maps_the_solver_does_not_read does not apply to use_ultra=True")
+    warn_native_only_options(options=native_only_options)
+    warn_relaxation_model_requested(use_exponential_attenuation=use_exponential_attenuation)