fullwave25 1.2.2.dev0__tar.gz → 1.2.3__tar.gz

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/.bumpversion.toml

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

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullwave25
-Version: 1.2.2.dev0
+Version: 1.2.3
 Summary: Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities
 Author: Masashi Sode, Gianmarco Pinton
 Maintainer: Masashi Sode

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/__init__.py

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

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/grid.py

@@ -183,9 +183,9 @@ class Grid:
             else "  Grid spacing (grid.dx, grid.dy): "
         )
         grid_spacing_str = (
-            f"({self.dx * 1e3:.2e} m, {self.dy * 1e3:.2e} m, {self.dz * 1e3:.2e} m)"
+            f"({self.dx * 1e3:.2e} mm, {self.dy * 1e3:.2e} mm, {self.dz * 1e3:.2e} mm)"
             if self.is_3d
-            else f"({self.dx * 1e3:.2e} m, {self.dy * 1e3:.2e} m)"
+            else f"({self.dx * 1e3:.2e} mm, {self.dy * 1e3:.2e} mm)"
         )
 
         num_grid_points_str_desc = (
@@ -203,7 +203,7 @@ class Grid:
             f"  Speed of sound (grid.c0): {self.c0} m/s\n"
             f"  Points per wavelength (PPW) (grid.ppw): {self.ppw}\n"
             f"  Courant-Friedrichs-Lewy (CFL) number (grid.cfl): {self.cfl}\n"
-            f"  Wavelength (grid.wavelength): {self.wavelength * 1e3:.2e} m\n"
+            f"  Wavelength (grid.wavelength): {self.wavelength * 1e3:.2e} mm\n"
             + grid_spacing_str_desc
             + grid_spacing_str
             + "\n"

fullwave25-1.2.3/fullwave/solver/binary_manager.py

@@ -0,0 +1,150 @@
+"""Binary manager for fullwave solver executables.
+
+Handles locating, caching, and downloading solver binaries from GitHub releases.
+
+Priority order when resolving a binary:
+1. Bundled binary (shipped with the package or dev install).
+2. Local cache at ``~/.cache/fullwave25/bins/``.
+3. Download from the GitHub release pinned by ``BINARY_RELEASE_TAG``.
+
+Binaries are versioned independently from the Python package — update
+``BINARY_RELEASE_TAG`` only when new binaries are published.
+
+The release tag can be overridden at runtime with the environment variable
+``FULLWAVE25_BINARY_TAG`` (e.g. ``export FULLWAVE25_BINARY_TAG=v1.2.2``).
+"""
+
+import logging
+import os
+import stat
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+logger = logging.getLogger("__main__." + __name__)
+
+GITHUB_REPO = "pinton-lab/fullwave25"
+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.1"
+
+
+def _download_url(filename: str, tag: str) -> str:
+    return f"https://github.com/{GITHUB_REPO}/releases/download/{tag}/{filename}"
+
+
+def _download_binary(url: str, dest: Path) -> None:
+    """Download *url* to *dest*, showing a tqdm progress bar when available."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(".download_tmp")
+    try:
+        try:
+            from tqdm import tqdm
+
+            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
+
+        tmp.rename(dest)
+        dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        logger.info("Binary saved to %s", dest)
+
+    except Exception:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def ensure_binary(local_path: Path) -> Path:
+    """Return an executable path for the solver binary.
+
+    Parameters
+    ----------
+    local_path:
+        The expected bundled path (as computed by ``_retrieve_fullwave_simulation_path``).
+
+    Returns
+    -------
+    Path
+        Resolved path to an executable binary.
+
+    Raises
+    ------
+    RuntimeError
+        If the binary cannot be found locally and the download fails.
+
+    """
+    # 1. Bundled binary present (dev install or package that still ships binaries).
+    if local_path.exists():
+        logger.debug("Using bundled binary: %s", local_path)
+        return local_path
+
+    filename = local_path.name
+
+    # Resolve the required tag first so cache lookup is always tag-specific.
+    # This ensures that when BINARY_RELEASE_TAG is bumped (e.g. after a package
+    # update) the old cached binary is not silently reused — each tag gets its
+    # own subdirectory under CACHE_DIR.
+    tag = os.environ.get("FULLWAVE25_BINARY_TAG", BINARY_RELEASE_TAG)
+    cached = CACHE_DIR / tag / filename
+
+    # 2. Previously downloaded and cached for this exact tag.
+    if cached.exists():
+        logger.debug("Using cached binary: %s", cached)
+        return cached
+
+    # 3. Download from GitHub releases.
+    url = _download_url(filename, tag)
+
+    logger.info(
+        "Binary '%s' not found locally. Downloading from GitHub release '%s' …",
+        filename,
+        tag,
+    )
+
+    try:
+        _download_binary(url, cached)
+    except urllib.error.HTTPError as e:
+        msg = (
+            f"Could not download binary '{filename}' from:\n  {url}\n"
+            f"HTTP error: {e.code} {e.reason}\n\n"
+            "Possible fixes:\n"
+            f"  • Check that release '{tag}' exists and contains '{filename}'.\n"
+            f"  • Override the tag:  export FULLWAVE25_BINARY_TAG=<tag>\n"
+            f"  • Place the binary manually at:  {cached}\n"
+        )
+        raise RuntimeError(msg) from e
+    except Exception as e:
+        msg = (
+            f"Failed to download binary '{filename}' from:\n  {url}\n"
+            f"Error: {e}\n\n"
+            f"  • Place the binary manually at:  {cached}\n"
+            f"  • Or override the tag:  export FULLWAVE25_BINARY_TAG=<tag>\n"
+        )
+        raise RuntimeError(msg) from e
+
+    return cached

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/solver/input_file_writer.py

@@ -160,6 +160,15 @@ class InputFileWriter:
             simulation_dir / "icmat.dat",
             np.transpose(self.source.icmat),
         )
+        p0_additive = getattr(self.source, "p0_additive", None)
+        incoords_add = getattr(self.source, "incoords_add", None)
+        if p0_additive is not None:
+            self._queue_ic_write(
+                simulation_dir / "icmat_add.dat",
+                np.transpose(p0_additive),
+            )
+        if incoords_add is not None:
+            self._queue_coords_write(simulation_dir / "icc_add.dat", incoords_add)
         self._queue_coords_write(simulation_dir / "icc.dat", self.source.incoords)
         self._copy_simulation_bin_file(simulation_dir)
 
@@ -1035,6 +1044,9 @@ class InputFileWriter:
             ("nTic", nt_ic),
             ("modT", self.sensor.sampling_modulus_time),
         ]
+        n_sources_add = getattr(self.source, "n_sources_add", 0)
+        if n_sources_add > 0:
+            var_list.append(("ncoords_add", n_sources_add))
         if self.is_3d:
             var_list.extend(
                 [

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/solver/launcher.py

@@ -30,6 +30,7 @@ class Launcher:
         is_3d: bool = False,
         use_gpu: bool = True,
         cuda_device_id: str | int | list | None = None,
+        save_gpu_memory: bool = False,
     ) -> None:
         """Initialize a FullwaveLauncher instance.
 
@@ -50,6 +51,17 @@ class Launcher:
             for multiple GPUs, provide a list of device IDs.
             example 1: [0, 1] for using GPU 0 and GPU 1. or "0,1" as a string.
             example 2: 2 for using GPU 2 or "2" as a string.
+        save_gpu_memory : bool, optional
+            Whether to save GPU memory by using ICMAT_MEMORY_SAVING flag in the simulation.
+            The simulation does not load initial conditions into GPU memory and
+            it loads the slice of the wavefield needed for the current time step
+            from CPU memory at each time step.
+            Defaults to False. If True, it may significantly reduce GPU memory usage,
+            but it may also increase the simulation time
+            due to the overhead of data transfer between CPU and GPU
+            depending on the hardware and the simulation settings.
+            useful in 3D simulations with large grid sizes
+            where GPU memory is a limiting factor.
 
         """
         self._path_fullwave_simulation_bin = path_fullwave_simulation_bin
@@ -58,6 +70,7 @@ class Launcher:
         self.is_3d = is_3d
         self.use_gpu = use_gpu
         self.cuda_device_id = self._configure_cuda_device_id(cuda_device_id)
+        self.save_gpu_memory = save_gpu_memory
         logger.debug("Launcher instance created.")
 
     @staticmethod
@@ -203,7 +216,12 @@ class Launcher:
             logger.info("Running simulation...")
             with (simulation_dir / "fw2_execution.log").open("w", encoding="utf-8") as file:
                 time_start = time()
-                os.environ["CUDA_VISIBLE_DEVICES"] = self.cuda_device_id
+                env = os.environ.copy()
+                env["CUDA_VISIBLE_DEVICES"] = self.cuda_device_id
+                if self.save_gpu_memory:
+                    env["ICMAT_MEMORY_SAVING"] = "1"
+                else:
+                    env["ICMAT_MEMORY_SAVING"] = "0"
                 subprocess.run(  # noqa: S603
                     command,
                     check=True,
@@ -211,6 +229,7 @@ class Launcher:
                     stdout=file,
                     stderr=file,
                     text=True,
+                    env=env,
                     # check=False,
                 )
                 time_passed = time() - time_start

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/solver/pml_builder.py

@@ -317,10 +317,17 @@ class PMLBuilder:
         extended_grid_shape = tuple(
             s + 2 * self.num_boundary_points for s in self.source_org.grid_shape
         )
+        incoords_add_ext = (
+            self.source_org.incoords_add + self.num_boundary_points
+            if getattr(self.source_org, "incoords_add", None) is not None
+            else None
+        )
         self.extended_source = fullwave.Source(
             p0=self.source_org.p0,
             coords=self.source_org.incoords + self.num_boundary_points,
             grid_shape=extended_grid_shape,
+            p0_additive=self.source_org.p0_additive,
+            coords_additive=incoords_add_ext,
         )
         logger.debug("building extended source for pml...done")
 
@@ -1582,10 +1589,17 @@ class PMLBuilderExponentialAttenuation(PMLBuilder):
         extended_grid_shape = tuple(
             s + 2 * self.num_boundary_points for s in self.source_org.grid_shape
         )
+        incoords_add_ext = (
+            self.source_org.incoords_add + self.num_boundary_points
+            if getattr(self.source_org, "incoords_add", None) is not None
+            else None
+        )
         self.extended_source = fullwave.Source(
             p0=self.source_org.p0,
             coords=self.source_org.incoords + self.num_boundary_points,
             grid_shape=extended_grid_shape,
+            p0_additive=self.source_org.p0_additive,
+            coords_additive=incoords_add_ext,
         )
         extended_sensor_grid_shape = tuple(
             s + 2 * self.num_boundary_points for s in self.sensor_org.grid_shape

{fullwave25-1.2.2.dev0 → fullwave25-1.2.3}/fullwave/solver/solver.py

@@ -16,6 +16,7 @@ from fullwave.utils import (
     check_functions,
 )
 
+from .binary_manager import ensure_binary
 from .cuda_utils import get_cuda_architecture, retrieve_cuda_version
 
 logger = logging.getLogger("__main__." + __name__)
@@ -326,6 +327,7 @@ class Solver:
         use_exponential_attenuation: bool = False,
         use_isotropic_relaxation: bool = True,
         cuda_device_id: str | int | list | None = None,
+        save_gpu_memory: bool = False,
     ) -> None:
         """Initialize a Solver instance for the fullwave simulation.
 
@@ -401,6 +403,17 @@ class Solver:
             for multiple GPUs, provide a list of device IDs.
             example 1: [0, 1] for using GPU 0 and GPU 1. or "0,1" as a string.
             example 2: 2 for using GPU 2 or "2" as a string.
+        save_gpu_memory : bool, optional
+            Whether to save GPU memory by using ICMAT_MEMORY_SAVING flag in the simulation.
+            The simulation does not load initial conditions into GPU memory and
+            it loads the slice of the wavefield needed for the current time step
+            from CPU memory at each time step.
+            Defaults to False. If True, it may significantly reduce GPU memory usage,
+            but it may also increase the simulation time
+            due to the overhead of data transfer between CPU and GPU
+            depending on the hardware and the simulation settings.
+            useful in 3D simulations with large grid sizes
+            where GPU memory is a limiting factor.
 
         Raises
         ------
@@ -417,6 +430,7 @@ class Solver:
         self.medium: fullwave.Medium
         self.grid: fullwave.Grid
         self.input_file_writer: InputFileWriter
+        self.save_gpu_memory = save_gpu_memory
 
         self.run_on_memory = run_on_memory
         if run_on_memory:
@@ -461,13 +475,14 @@ class Solver:
         self.n_relax_mechanisms = medium.n_relaxation_mechanisms
 
         if path_fullwave_simulation_bin is None:
-            path_fullwave_simulation_bin = _retrieve_fullwave_simulation_path(
+            local_path = _retrieve_fullwave_simulation_path(
                 use_gpu=use_gpu,
                 is_3d=self.is_3d,
                 use_exponential_attenuation=self.use_exponential_attenuation,
                 use_isotropic_relaxation=use_isotropic_relaxation,
                 n_relax_mechanisms=self.n_relax_mechanisms,
             )
+            path_fullwave_simulation_bin = ensure_binary(local_path)
         else:
             check_functions.check_path_exists(path_fullwave_simulation_bin)
 
@@ -538,6 +553,7 @@ class Solver:
             is_3d=self.is_3d,
             use_gpu=self.use_gpu,
             cuda_device_id=self.cuda_device_id,
+            save_gpu_memory=self.save_gpu_memory,
         )
 
         if use_exponential_attenuation: