fullwave25 1.4.2.dev1__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-dev1"
+    __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/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(

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

fullwave/ultra/backend_2d.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import shutil
 import time
 from pathlib import Path
@@ -11,6 +12,11 @@ import numpy as np
 
 from fullwave.solver.binary_markers import check_binary_holds_source
 from fullwave.solver.source_type import HARD_RELEASED_AFTER, is_hard_held
+from fullwave.utils.gpu_memory import (
+    free_gpu_memory_bytes,
+    members_that_fit,
+    release_gpu_memory_pools,
+)
 
 from . import binary as binary_module
 from . import dat_io
@@ -23,9 +29,10 @@ from .backend import (
     to_host,
     work_directory,
 )
-from .errors import UltraUnsupportedError
+from .binary import OUTPUT_TAIL_CHARS
+from .errors import UltraBinaryError, UltraUnsupportedError
 from .time_axis import check_time_axis, delay_additive_signal
-from .writer_2d import write_run_directory_2d, write_sources_2d
+from .writer_2d import extension_cells, write_run_directory_2d, write_sources_2d
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -34,20 +41,125 @@ if TYPE_CHECKING:
 
     import fullwave
 
+logger = logging.getLogger("__main__." + __name__)
+
+FLOAT_BYTES = 4
+BYTES_PER_CELL_PER_MEMBER = 6 * FLOAT_BYTES  # pressure and two velocities at two time levels
+BYTES_PER_CELL_SHARED = 172  # material maps, sponge coefficients and sponge memory variables
+BYTES_PER_AXIS_CELL = 2 * FLOAT_BYTES
+BYTES_PER_COORDINATE = 2 * np.dtype(np.int32).itemsize
+STENCIL_TABLE_BYTES = 9 * 2 * FLOAT_BYTES
+
+
+def device_bytes_2d(
+    *,
+    n_x: int,
+    n_y: int,
+    n_t: int,
+    mod_t: int,
+    ncoords: int,
+    n_tic: int,
+    ncoordsout: int,
+    ncoords_add: int = 0,
+    n_tic_add: int = 0,
+    ncoordszero: int = 0,
+) -> tuple[int, int]:
+    """Return the GPU memory of a 2D batch, in bytes, without the CUDA context.
+
+    Parameters
+    ----------
+    n_x, n_y : int
+        Cells of the extended grid, which includes the sponge and the stencil margin.
+    n_t, mod_t : int
+        Number of time steps and sensor decimation in time.
+    ncoords, n_tic : int
+        Hard source cells and source length in steps.
+    ncoordsout : int
+        Sensor points.
+    ncoords_add, n_tic_add : int
+        Additive source cells and source length in steps.
+    ncoordszero : int
+        Cells held at zero pressure.
+
+    Returns
+    -------
+    tuple[int, int]
+        The bytes shared by all members and the bytes added by each member.
+    """
+    cells = n_x * n_y
+    frames = (n_t - 1) // mod_t
+    n_coordinates = ncoords + ncoordszero + ncoordsout + ncoords_add
+    per_member = (
+        BYTES_PER_CELL_PER_MEMBER * cells
+        + FLOAT_BYTES * ncoords * n_tic
+        + FLOAT_BYTES * ncoords_add * n_tic_add
+        + FLOAT_BYTES * frames * ncoordsout
+    )
+    shared = (
+        BYTES_PER_CELL_SHARED * cells
+        + BYTES_PER_AXIS_CELL * (n_x + n_y)
+        + BYTES_PER_COORDINATE * n_coordinates
+        + FLOAT_BYTES * ncoordsout
+        + STENCIL_TABLE_BYTES
+    )
+    return shared, per_member
+
 
 def _members_per_run(n_members: int, max_members_per_run: int | None) -> list[range]:
     """Split the members into the fewest runs of at most ``max_members_per_run``."""
     if max_members_per_run is None:
         return [range(n_members)]
-    if max_members_per_run < 1:
-        msg = f"max_members_per_run must be 1 or more, not {max_members_per_run}"
-        raise ValueError(msg)
     n_runs = -(-n_members // max_members_per_run)
     return [
         range(int(part[0]), int(part[-1]) + 1) for part in np.array_split(range(n_members), n_runs)
     ]
 
 
+def check_genout_files(
+    genout_paths: Sequence[Path], *, ncoordsout: int, rundir: Path, stdout: str
+) -> None:
+    """Check that every output file of a run is complete.
+
+    Parameters
+    ----------
+    genout_paths : sequence of Path
+        The output file of each batch member.
+    ncoordsout : int
+        Number of sensor points per frame.
+    rundir : Path
+        The run directory, named in the error message.
+    stdout : str
+        Standard output of the binary, of which the end goes into the error message.
+
+    Raises
+    ------
+    UltraBinaryError
+        If a file is missing or empty, does not hold whole ``float32`` frames, or differs in
+        size from the other files of the run.
+    """
+    frame_bytes = FLOAT_BYTES * ncoordsout
+    sizes = {path.name: path.stat().st_size if path.is_file() else None for path in genout_paths}
+    common_size = max((size for size in sizes.values() if size), default=0)
+    incomplete = [
+        name
+        for name, size in sizes.items()
+        if not size or size % frame_bytes != 0 or size != common_size
+    ]
+    if not incomplete:
+        return
+    descriptions = [
+        f"{name} (missing)" if sizes[name] is None else f"{name} ({sizes[name]} bytes)"
+        for name in incomplete
+    ]
+    msg = (
+        "The fullwave2-ultra binary exited with code 0 but its output is incomplete: "
+        f"{', '.join(descriptions)}. "
+        f"Each output file must be non-empty, a multiple of {frame_bytes} bytes and of equal size. "
+        f"Run directory: {rundir}. Last output of the binary:\n{stdout[-OUTPUT_TAIL_CHARS:]}"
+    )
+    raise UltraBinaryError(msg)
+
+
 class UltraBackend2D:
     """Write, run and read 2D fullwave2-ultra simulations of one medium and several transmits.
 
@@ -66,7 +178,7 @@ class UltraBackend2D:
     cuda_device_id : str | int | list | None
         One CUDA device.
     verify_gpu : bool
-        Check that the device is visible before the launch.
+        Check that the device is visible before the run.
     source_type : str
         ``"hard"`` sets the pressure at the source cells for the whole run.
         ``"hard_released_after"`` sets it while the signal plays, then lets the cells evolve
@@ -228,7 +340,10 @@ class UltraBackend2D:
         highpass_cutoff_mhz: float | None = None,
         bandpass_cutoff_mhz: tuple[float, float] | None = None,
     ) -> NDArray | list[Path]:
-        """Run the transmits, split into runs of at most ``max_members_per_run`` (None: one run).
+        """Run the transmits in runs of at most ``max_members_per_run`` (None: one run).
+
+        The free GPU memory can lower the limit, with a warning. The traces do not depend on
+        the split.
 
         Returns
         -------
@@ -272,6 +387,9 @@ class UltraBackend2D:
         if len(sources) == 0:
             msg = "run_batch needs at least one source."
             raise ValueError(msg)
+        if max_members_per_run is not None and max_members_per_run < 1:
+            msg = f"max_members_per_run must be 1 or more, not {max_members_per_run}"
+            raise ValueError(msg)
         n_t = check_time_axis(self.grid)
         transmits = [self._check_member(source, index=i) for i, source in enumerate(sources)]
         signals = [hard for hard, _ in transmits]
@@ -284,7 +402,19 @@ class UltraBackend2D:
             msg = f"the source has {n_steps} steps, more than the {n_t} of the simulation"
             raise ValueError(msg)
 
-        runs = _members_per_run(len(signals), max_members_per_run)
+        has_additive = self.source.n_sources_add > 0
+        if generate_input_only:
+            members_per_run_limit = max_members_per_run
+        else:
+            release_gpu_memory_pools()
+            members_per_run_limit = self._members_per_run_limit(
+                n_members=len(signals),
+                max_members_per_run=max_members_per_run,
+                n_t=n_t,
+                n_tic=signals[0].shape[1],
+                n_tic_add=additive_signals[0].shape[1] if has_additive else 0,
+            )
+        runs = _members_per_run(len(signals), members_per_run_limit)
         outputs = []
         for index, members in enumerate(runs):
             name = simulation_dir_name if len(runs) == 1 else f"{simulation_dir_name}_{index}"
@@ -292,7 +422,7 @@ class UltraBackend2D:
                 self._run_one(
                     name,
                     [signals[m] for m in members],
-                    [additive_signals[m] for m in members] if self.source.n_sources_add else None,
+                    [additive_signals[m] for m in members] if has_additive else None,
                     n_t=n_t,
                     load_results=load_results,
                     generate_input_only=generate_input_only,
@@ -304,6 +434,67 @@ class UltraBackend2D:
             return np.concatenate(outputs, axis=0)
         return [path for run_paths in outputs for path in run_paths]
 
+    def _members_per_run_limit(
+        self,
+        *,
+        n_members: int,
+        max_members_per_run: int | None,
+        n_t: int,
+        n_tic: int,
+        n_tic_add: int,
+    ) -> int | None:
+        """Return the most members one run may hold, or None when nothing limits it.
+
+        A run that does not fit into the free GPU memory ends with empty output files.
+        """
+        wanted = n_members if max_members_per_run is None else min(max_members_per_run, n_members)
+        free = free_gpu_memory_bytes([str(self.device)])
+        if free is None:
+            logger.warning(
+                "The free GPU memory is unknown, so the %d transmits per run are not checked "
+                "against it.",
+                wanted,
+            )
+            return max_members_per_run
+        shared_bytes, per_member_bytes = self._member_bytes(
+            n_t=n_t, n_tic=n_tic, n_tic_add=n_tic_add
+        )
+        fit = max(
+            members_that_fit(
+                free_bytes=free[str(self.device)],
+                shared_bytes=shared_bytes,
+                per_member_bytes=per_member_bytes,
+            ),
+            1,
+        )
+        if fit < wanted:
+            logger.warning(
+                "The free GPU memory fits %d transmits per run, not %d. "
+                "The %d transmits run in runs of at most %d.",
+                fit,
+                wanted,
+                n_members,
+                fit,
+            )
+        return min(wanted, fit)
+
+    def _member_bytes(self, *, n_t: int, n_tic: int, n_tic_add: int) -> tuple[int, int]:
+        """Return the GPU bytes shared by all members and the bytes added by each member."""
+        _, margin = extension_cells(ppw=self.grid.ppw, nbdy=self.nbdy)
+        n_x, n_y = (cells + 2 * margin for cells in self.medium.sound_speed.shape)
+        return device_bytes_2d(
+            n_x=n_x,
+            n_y=n_y,
+            n_t=n_t,
+            mod_t=self.sensor.sampling_modulus_time,
+            ncoords=len(self.source.incoords),
+            n_tic=n_tic,
+            ncoordsout=len(self.sensor.outcoords),
+            ncoords_add=len(self.source.incoords_add) if n_tic_add else 0,
+            n_tic_add=n_tic_add,
+            ncoordszero=len(self.medium.air_coords),
+        )
+
     def _run_one(
         self,
         simulation_dir_name: str | Path,
@@ -357,6 +548,9 @@ class UltraBackend2D:
         )
         self.last_run.update(run_seconds=time.perf_counter() - started, stdout=stdout)
         genout_paths = [rundir / dat_io.genout_name(m) for m in range(len(signals))]
+        check_genout_files(
+            genout_paths, ncoordsout=scalars["ncoordsout"], rundir=rundir, stdout=stdout
+        )
         if not load_results:
             return genout_paths
         traces = np.stack(

fullwave/ultra/binary.py

@@ -28,6 +28,8 @@ MARKER_AIR_WINDOW_2D = b"nzero0.dat"
 MARKER_SOURCE_RELEASE_2D = b"nszero0.dat"
 MARKER_HOLD_SOURCE_3D = b"nszero0.dat"
 
+OUTPUT_TAIL_CHARS = 2000
+
 
 class PreflightError(RuntimeError):
     """Raised when no usable CUDA device is visible."""
@@ -146,7 +148,11 @@ def run_binary(
         check=False,
     )
     if result.returncode != 0:
-        tail = (result.stderr or result.stdout)[-2000:]
-        msg = f"{Path(binary).name} failed (returncode={result.returncode}):\n{tail}"
+        stderr_tail = (result.stderr or "")[-OUTPUT_TAIL_CHARS:]
+        stdout_tail = (result.stdout or "")[-OUTPUT_TAIL_CHARS:]
+        msg = (
+            f"{Path(binary).name} failed (returncode={result.returncode}):\n"
+            f"stderr:\n{stderr_tail}\nstdout:\n{stdout_tail}"
+        )
         raise RuntimeError(msg)
     return result.stdout or ""

fullwave/ultra/writer_2d.py

@@ -19,6 +19,27 @@ if TYPE_CHECKING:
 SPONGE_WAVELENGTHS = 6
 
 
+def extension_cells(*, ppw: float, nbdy: int | None, m_stencil: int = 8) -> tuple[int, int]:
+    """Return the sponge width and the cells added on each side of the domain.
+
+    Parameters
+    ----------
+    ppw : float
+        Points per wavelength.
+    nbdy : int | None
+        Sponge width in cells; None gives ``ppw * SPONGE_WAVELENGTHS``.
+    m_stencil : int
+        Stencil half-width.
+
+    Returns
+    -------
+    tuple[int, int]
+        The sponge width ``nbdy`` and the extension ``mext = nbdy + m_stencil``.
+    """
+    nbdy = int(ppw * SPONGE_WAVELENGTHS) if nbdy is None else nbdy
+    return nbdy, nbdy + m_stencil
+
+
 def write_run_directory_2d(
     outdir: str | Path,
     *,
@@ -65,9 +86,8 @@ def write_run_directory_2d(
     """
     outdir = Path(outdir)
     outdir.mkdir(parents=True, exist_ok=True)
-    nbdy = int(ppw * SPONGE_WAVELENGTHS) if nbdy is None else nbdy
+    nbdy, mext = extension_cells(ppw=ppw, nbdy=nbdy, m_stencil=m_stencil)
     dx, dt, n_t = time_axis(c0=c0, omega0=omega0, dur=dur, ppw=ppw, cfl=cfl)
-    mext = nbdy + m_stencil
 
     c = extend_map(maps["cmap"], mext)
     rho = extend_map(maps["rmap"], mext)

fullwave/utils/gpu_memory.py

@@ -0,0 +1,109 @@
+"""Read the free GPU memory and release the CuPy memory pools."""
+
+from __future__ import annotations
+
+import gc
+import logging
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+logger = logging.getLogger("__main__." + __name__)
+
+GPU_MEMORY_FRACTION = 0.9
+GPU_MEMORY_RESERVE_BYTES = 512 * 1024**2
+
+
+def members_that_fit(*, free_bytes: int, shared_bytes: int, per_member_bytes: int) -> int:
+    """Return how many batch members fit into the free memory of a GPU.
+
+    Only ``GPU_MEMORY_FRACTION`` of the free memory is used, less ``GPU_MEMORY_RESERVE_BYTES``
+    for the CUDA context and for what the estimate does not count.
+
+    Parameters
+    ----------
+    free_bytes : int
+        The free memory of the GPU.
+    shared_bytes : int
+        The memory used once, whatever the number of members.
+    per_member_bytes : int
+        The memory each member adds.
+
+    Returns
+    -------
+    int
+        The count, which is zero or negative when not even one member fits.
+
+    """
+    usable_bytes = GPU_MEMORY_FRACTION * free_bytes - GPU_MEMORY_RESERVE_BYTES - shared_bytes
+    return int(usable_bytes // per_member_bytes)
+
+
+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
+
+
+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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.2-dev1
+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
@@ -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.dist-info → fullwave25-1.4.2.dev3.dist-info}/RECORD

@@ -1,12 +1,12 @@
-fullwave/__init__.py,sha256=yU0dwHvWMslDd0clb94ezpuzqrmnv-J3qBz8jgHdRRA,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
@@ -28,7 +28,7 @@ fullwave/solver/input_file_writer.py,sha256=tzi1MZF-KhNIstrhlu-2lTWGInRtbPaSSFNw
 fullwave/solver/launcher.py,sha256=pNZBecyANOtGP9rrG-kfa1HDrXH7qCT8BL4NCTmsRog,13272
 fullwave/solver/pml_builder.py,sha256=Pfy3AklZT-p6TX61A5ntFmpt2mJb5TDaV-gdtpjIwNo,87341
 fullwave/solver/shipped_database.py,sha256=lPqlgY-ShDyRqtH65m5RyNIMVlqswECVDNh5XCk1Yzg,3194
-fullwave/solver/solver.py,sha256=-TWt2DLz7d5Nk4A2JHCHOqk4n7C4WgSKwndphLhJuAM,99250
+fullwave/solver/solver.py,sha256=rMVmBB294f3b2PoQpSJWlEifzxPo9ssFOffzLJ5NkjE,97971
 fullwave/solver/source_type.py,sha256=iozo2wGuFLAbhRmXKETcmYV2I0UrA-AB3mnbFRp2s1o,11545
 fullwave/solver/utils.py,sha256=0Q9PKl-4hohWXGzuldqo2XubI-LEHMjs0kYgb4oTLC0,5561
 fullwave/solver/bins/_gpu/2d/num_relax=2/fullwave2_2d_2_relax_multi_gpu_cuda118,sha256=bIzyHFzr_bsIBSlCcRA3M9LlTSRrBVn6ASJHyozvcwU,1245432
@@ -44,9 +44,9 @@ fullwave/solver/bins/database/relaxation_params_database_num_relax=3_20260828_15
 fullwave/solver/bins/database/relaxation_params_database_num_relax=4_20260828_1456.mat,sha256=YfR8RaWQn2dDYiw9TACSUx27QUpKhO7iJQA8rAPLHZA,253928
 fullwave/solver/bins/database/relaxation_params_database_num_relax=4_20260828_1456_invalid_cells.json,sha256=-qA_p-S_3rr8Hl-fXfgvI6m2EED3duc_wW0RlKDUHoE,63983
 fullwave/ultra/__init__.py,sha256=O6-Dw5_UmmG6ikKQ8NCXrmkBjG_CHzWJpBDTwfUhcM0,356
-fullwave/ultra/backend.py,sha256=xse6Q1CuFYGLeljnGlNtlKfipUNvncq9OcMqtnaEqS4,15426
-fullwave/ultra/backend_2d.py,sha256=J4W2B83Fmky6Cn-z-qu3EgO_gJdpkWbGO0oGTWYR38E,14754
-fullwave/ultra/binary.py,sha256=PpEq6YIxRmmCyiNCjotDII4iVD_gYaRnf8g5hM6dPac,4615
+fullwave/ultra/backend.py,sha256=_L2B9OUNL8suime6bPp-GD89RYn4bg37jG3WZv6qnKI,18627
+fullwave/ultra/backend_2d.py,sha256=f_cK-W9dJeyRfbkGCfCJ60wwIRILhnHjMRwlGuWdW88,21552
+fullwave/ultra/binary.py,sha256=xouFNbwi3NMaH8kuAgk1GQeLGe8DZrwG0RDBftDav-8,4795
 fullwave/ultra/dat_io.py,sha256=mmHfMSsBFUeNSkDC4IMKwGMB_ryA5V_FYzlAG_G6Ht8,2170
 fullwave/ultra/dat_io_3d.py,sha256=ZVBdHe-caTHdofkHUqPlHZSWKlv793ll6juofH5W6y4,1183
 fullwave/ultra/errors.py,sha256=Z1uY2sdnxAA0_fzFf3QmYgR0ZyBJGmsdQyrzoLhyEFY,962
@@ -54,20 +54,21 @@ fullwave/ultra/factory.py,sha256=hfEAXz2D8EHscgsy2XFK3Iiom8dGdrT2o5yDFGk5qds,548
 fullwave/ultra/medium_to_aexp.py,sha256=_uOHDhH6lwQfj4sSgE_jd5Ujq5vCnXvdCdu6Fcx9QKE,1864
 fullwave/ultra/stencil.py,sha256=XG5rPZsJbKaFDkli2GVmFdeqP72QkwTIEZc_49vGmNE,4912
 fullwave/ultra/time_axis.py,sha256=KXsc2EaT6zo-Glh27nxxX50BfpC3oO8jkwbO6SgE3bg,1825
-fullwave/ultra/writer_2d.py,sha256=PxF_3xU2cVTMSg-_QUZuVutaoIXO0pPbjOz4P0jt8Ak,7037
+fullwave/ultra/writer_2d.py,sha256=QlVZyED8TwtbQQKZ40v0VnWm-DIgo735RCg_c9Ad4Jg,7645
 fullwave/ultra/writer_3d.py,sha256=gW-GcWWItdE43rcwx6YWn_O9edTwkiCeIcX1IIrJAz0,6985
 fullwave/utils/__init__.py,sha256=YKBUZnQ6E9AiT0tt4gL9HVapvcGv0lbcXXQyF-IWBXc,517
 fullwave/utils/check_functions.py,sha256=benZqFjOQF7aaQDTBGaOq-eplJ-dC8Dz4jcqPE-9HSk,1514
 fullwave/utils/coordinates.py,sha256=TEVQE9JXUIVFoKEyg8ZZMeGh31elbpecHnDgbljHQ14,4402
+fullwave/utils/gpu_memory.py,sha256=yitC9ZaVws5wBXjsaCuW7qGPDZlrbelYLsSDnxMilkQ,3420
 fullwave/utils/memory_tempfile.py,sha256=RqoFX67VCMIHNIDYWwHLCaS4dwSPK6eKsvElXX43Qjg,15083
 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.dev1.dist-info/METADATA,sha256=OqrNOXGpOzdvWtUv4yUCUq1fZtgBs5ipGbfNjaELV9o,26885
-fullwave25-1.4.2.dev1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
-fullwave25-1.4.2.dev1.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-fullwave25-1.4.2.dev1.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,,