fullwave25 1.4.0.dev0__tar.gz → 1.4.1.dev1__tar.gz

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/.bumpversion.toml

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

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.0-dev0
+Version: 1.4.1-dev1
 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.4.1.dev1/docker/Dockerfile

@@ -0,0 +1,59 @@
+# fullwave25 with the released solver binaries, for Linux systems whose glibc is older than
+# the binaries need (2.34, for example Ubuntu 20.04 or RHEL 8).
+#
+# Build from the repository root:
+#   docker build -f docker/Dockerfile -t fullwave25 .
+#
+# See docker/README.md for how to run it with Docker or Apptainer.
+
+FROM ubuntu:22.04
+
+# The release tag of the solver binaries, and the CUDA versions to include. The wrapper
+# picks the binary that matches the CUDA version of the host driver.
+ARG FULLWAVE_BIN_TAG=fullwave_bin_v1.5.2
+ARG FULLWAVE_BIN_CUDA_VERSIONS="118 124 129 130"
+ARG PYTHON_VERSION=3.12
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.9.9 /uv /usr/local/bin/uv
+
+ENV UV_PYTHON_INSTALL_DIR=/opt/python \
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    VIRTUAL_ENV=/opt/venv \
+    PATH=/opt/venv/bin:${PATH}
+RUN uv venv --python ${PYTHON_VERSION} /opt/venv
+
+COPY . /opt/fullwave25-src
+# The [ctk] extra installs the CUDA libraries and headers that CuPy needs at run time.
+RUN uv pip install --no-cache /opt/fullwave25-src \
+    && uv pip install --no-cache "cupy-cuda12x[ctk]==$(python -c "import importlib.metadata as m; print(m.version('cupy-cuda12x'))")"
+
+# Put the solver binaries where the installed package looks first, so a run needs no
+# download and works when the home directory is mounted from the host (Apptainer).
+RUN set -eu; \
+    bins="$(python -c "import importlib.util; print(importlib.util.find_spec('fullwave').submodule_search_locations[0])")/solver/bins"; \
+    url="https://github.com/pinton-lab/fullwave25/releases/download/${FULLWAVE_BIN_TAG}"; \
+    for cuda in ${FULLWAVE_BIN_CUDA_VERSIONS}; do \
+        for dim in 2d 3d; do \
+            mkdir -p "${bins}/gpu/${dim}" "${bins}/exponential_attenuation/gpu/${dim}"; \
+            curl -fsSL -o "${bins}/gpu/${dim}/fullwave2_${dim}_n_relax_multi_gpu_cuda${cuda}" \
+                "${url}/fullwave2_${dim}_n_relax_multi_gpu_cuda${cuda}"; \
+            curl -fsSL -o "${bins}/exponential_attenuation/gpu/${dim}/fullwave2_${dim}_exponential_attenuation_multi_gpu_cuda${cuda}" \
+                "${url}/fullwave2_${dim}_exponential_attenuation_multi_gpu_cuda${cuda}"; \
+        done; \
+    done; \
+    chmod 755 "${bins}"/gpu/*/* "${bins}"/exponential_attenuation/gpu/*/*; \
+    echo "${FULLWAVE_BIN_TAG}" > "${bins}/RELEASE_TAG"
+
+# A container started with --user has no home of its own, so the caches of CuPy,
+# matplotlib and numba go to /tmp. Apptainer sets HOME to the host home instead.
+ENV HOME=/tmp \
+    NUMBA_CACHE_DIR=/tmp/numba
+
+WORKDIR /work
+CMD ["python"]

fullwave25-1.4.1.dev1/docker/Dockerfile.dockerignore

@@ -0,0 +1,10 @@
+# Only the files needed to install the package go into the build context.
+*
+!fullwave
+!pyproject.toml
+!README.md
+!LICENSE
+fullwave/solver/bins/gpu
+fullwave/solver/bins/exponential_attenuation
+fullwave/solver/bins/_*
+**/__pycache__

fullwave25-1.4.1.dev1/docker/README.md

@@ -0,0 +1,78 @@
+# fullwave25 in a container
+
+The released solver binaries need glibc 2.34 or newer (for example Ubuntu 22.04, Debian 12 or RHEL 9). On an older system, such as Ubuntu 20.04 or RHEL 8, they stop at start with an error like:
+
+```text
+/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found
+```
+
+This image runs fullwave25 and the released solver binaries on such a system. The host needs only an NVIDIA driver for CUDA 12.0 or newer, and Docker with the NVIDIA Container Toolkit, or Apptainer.
+
+The image contains:
+
+- Ubuntu 22.04
+- Python 3.12 and fullwave25, installed from this repository checkout, with the CUDA 12 libraries that CuPy needs
+- the solver binaries of the release `fullwave_bin_v1.5.2`, for CUDA 11.8, 12.4, 12.9 and 13.0
+- `ffmpeg`, for the video export of the plotting functions
+
+## Build
+
+Run from the repository root:
+
+```sh
+docker build -f docker/Dockerfile -t fullwave25 .
+```
+
+To use another release of the solver binaries:
+
+```sh
+docker build -f docker/Dockerfile -t fullwave25 --build-arg FULLWAVE_BIN_TAG=<release tag> .
+```
+
+## Run with Docker
+
+Mount your working directory at `/work` and run your script there. The outputs are written to your working directory, owned by your user.
+
+```sh
+docker run --rm --gpus all --user "$(id -u):$(id -g)" \
+    -v "$PWD":/work fullwave25 python my_simulation.py
+```
+
+If `--gpus all` is not available, use `--device nvidia.com/gpu=all` (CDI).
+
+To use selected GPUs, pass them to fullwave25 as usual with `cuda_device_id` in `fullwave.Solver`.
+
+## Run with Apptainer
+
+Apptainer runs the same image without Docker. Build the image on a machine with Docker, and save it to a file:
+
+```sh
+docker save fullwave25 -o fullwave25.tar
+```
+
+Copy `fullwave25.tar` to the target machine, and convert it there:
+
+```sh
+apptainer build fullwave25.sif docker-archive://fullwave25.tar
+```
+
+The saved image is about 4.3 GB and the `.sif` file about 2.3 GB, and the conversion needs temporary space of several GB in addition. If `/tmp` is small, set `APPTAINER_TMPDIR` and `APPTAINER_CACHEDIR` to a folder on a larger disk.
+
+Then run your script. `--nv` gives the container the GPUs and the driver of the host. Apptainer mounts your home and the current directory by default.
+
+```sh
+apptainer exec --nv fullwave25.sif python my_simulation.py
+```
+
+If Apptainer prints `Error changing the container working directory`, your working directory is reached through a link to another disk. Run from its real path:
+
+```sh
+cd "$(pwd -P)"
+```
+
+## Check the installation
+
+```sh
+apptainer exec --nv fullwave25.sif python -c "import fullwave; print(fullwave.__version__)"
+docker run --rm --gpus all fullwave25 nvidia-smi -L
+```

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/fullwave/__init__.py

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

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/fullwave/solver/binary_manager.py

@@ -28,7 +28,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"
+BINARY_RELEASE_TAG = "fullwave_bin_v1.5.2"
 
 
 def _download_url(filename: str, tag: str) -> str:

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/fullwave/solver/cuda_utils.py

@@ -213,6 +213,42 @@ def cuCtxDetach(ctx):  # noqa: ANN001, ANN201, D103, N802
     return cuda.cuCtxDetach(ctx)
 
 
+@cuda_api_call
+def cuDeviceCanAccessPeer(can_access, dev, peer_dev):  # noqa: ANN001, ANN201, D103, N802
+    return cuda.cuDeviceCanAccessPeer(can_access, dev, peer_dev)
+
+
+def find_consecutive_gpus_without_peer_access(ordinals: list[int]) -> list[tuple[int, int]]:
+    """Return the consecutive GPU pairs that cannot access each other's memory directly.
+
+    Parameters
+    ----------
+    ordinals : list[int]
+        CUDA device ordinals as this process sees them, in the requested order.
+
+    Returns
+    -------
+    list[tuple[int, int]]
+        Each consecutive pair (a, b) of ``ordinals`` where a cannot access b or b
+        cannot access a.
+
+    """
+    cuInit(0)
+    pairs = []
+    for first, second in zip(ordinals, ordinals[1:], strict=False):
+        device_first = ctypes.c_int()
+        device_second = ctypes.c_int()
+        cuDeviceGet(ctypes.byref(device_first), first)
+        cuDeviceGet(ctypes.byref(device_second), second)
+        forward = ctypes.c_int()
+        backward = ctypes.c_int()
+        cuDeviceCanAccessPeer(ctypes.byref(forward), device_first, device_second)
+        cuDeviceCanAccessPeer(ctypes.byref(backward), device_second, device_first)
+        if not forward.value or not backward.value:
+            pairs.append((first, second))
+    return pairs
+
+
 # Main function to get CUDA device specs
 @lru_cache(maxsize=1)
 def get_cuda_device_specs() -> list[dict[str, Any]]:

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/fullwave/solver/launcher.py

@@ -1,5 +1,6 @@
 """Module for launching Fullwave simulation."""
 
+import ctypes
 import logging
 import os
 import re
@@ -79,6 +80,8 @@ class Launcher:
             cuda_device_id,
             verify_gpu=verify_gpu,
         )
+        if use_gpu and verify_gpu:
+            self._warn_if_gpus_lack_peer_access(self.cuda_device_id)
         self.save_gpu_memory = save_gpu_memory
         logger.debug("Launcher instance created.")
 
@@ -160,6 +163,49 @@ class Launcher:
                 message = f"CUDA device ID {device_id} does not exist."
                 raise ValueError(message)
 
+    @staticmethod
+    def _warn_if_gpus_lack_peer_access(device_id_str: str) -> None:
+        """Warn when consecutive GPUs of a multi-GPU run have no peer-to-peer access.
+
+        Without peer access (no NVLink, and a PCIe chipset or GPU that refuses it,
+        as on GeForce cards), a multi-GPU run is much slower than with peer access.
+
+        The binary runs with ``CUDA_VISIBLE_DEVICES`` set to ``device_id_str``. The
+        CUDA ordinals of this process name the same GPUs only when this process has
+        no ``CUDA_VISIBLE_DEVICES`` of its own, so the check is skipped otherwise.
+        It never raises: if the CUDA driver cannot answer, it logs at debug level.
+
+        Parameters
+        ----------
+        device_id_str : str
+            The CUDA device ID(s) in string format, for example "0,1,2,3".
+
+        """
+        device_ids = [int(device_id) for device_id in device_id_str.split(",")]
+        if len(device_ids) < 2:
+            return
+        if "CUDA_VISIBLE_DEVICES" in os.environ:
+            logger.debug(
+                "Peer access check skipped: CUDA_VISIBLE_DEVICES is set in this process.",
+            )
+            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)
+            return
+        if not pairs:
+            return
+        pair_text = ", ".join(f"GPU {first} <-> GPU {second}" for first, second in pairs)
+        logger.warning(
+            "No peer-to-peer access between %s. A multi-GPU run on these GPUs is much "
+            "slower than on GPUs with NVLink or PCIe peer access. Check with a short "
+            "run whether fewer GPUs give a faster simulation.",
+            pair_text,
+        )
+
     @staticmethod
     def _configure_cuda_device_id(
         cuda_device_id: str | int | list | None,

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fullwave25"
-version = "1.4.0-dev0" # Update via bump-my-version, not manually
+version = "1.4.1-dev1" # Update via bump-my-version, not manually
 description = "Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities"
 readme = "README.md"
 requires-python = ">=3.10"

{fullwave25-1.4.0.dev0 → fullwave25-1.4.1.dev1}/uv.lock

@@ -761,7 +761,7 @@ wheels = [
 
 [[package]]
 name = "fullwave25"
-version = "1.4.0.dev0"
+version = "1.4.1.dev1"
 source = { editable = "." }
 dependencies = [
     { name = "cupy-cuda12x" },