k-Wave-python 0.6.1__tar.gz → 0.6.2__tar.gz

k_wave_python-0.6.2/.git

@@ -0,0 +1 @@
+gitdir: /Users/Walter/git/k-wave-python/.git/worktrees/kwave-v0.6.2

k_wave_python-0.6.2/CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is k-wave-python?
+
+Python implementation of the [k-Wave](http://www.k-wave.org/) acoustics toolbox for time-domain acoustic and ultrasound simulations. Two backends: a pure Python/NumPy/CuPy solver and C++ binaries (OMP/CUDA).
+
+## Commands
+
+```bash
+# Setup
+uv sync --extra dev --extra test
+uv run pre-commit install
+
+# Run tests
+uv run pytest                              # all tests
+uv run pytest tests/test_kgrid.py          # single file
+uv run pytest tests/test_kgrid.py::test_name  # single test
+uv run pytest -m integration               # MATLAB-reference tests only
+
+# Lint/format
+uv run ruff check . --fix
+uv run ruff format .
+uv run pre-commit run --all-files
+
+# Run an example
+uv run examples/ivp_homogeneous_medium.py
+
+# Build
+uv build
+```
+
+Always use `uv run` (not `uv run python`) for pytest, examples, and scripts.
+
+## Code Style
+
+- Line length: 140 (configured in `pyproject.toml` under `[tool.ruff]`)
+- Pre-commit hooks: ruff (lint + format), codespell, nb-clean
+- Ruff ignores F821 (nested function refs) and F722 (jaxtyping annotations)
+- Type annotations use `beartype` + `jaxtyping`
+
+## Architecture
+
+### Entry point
+
+`kwave/kspaceFirstOrder.py` — `kspaceFirstOrder()` is the unified API. It accepts `kgrid`, `medium`, `source`, `sensor` and dispatches to the appropriate backend.
+
+```
+kspaceFirstOrder(kgrid, medium, source, sensor, backend="python"|"cpp", device="cpu"|"gpu")
+```
+
+### Two backends
+
+- **Python backend** (`kwave/solvers/kspace_solver.py`): `Simulation` class implementing k-space pseudospectral method in NumPy/CuPy. Supports 1D/2D/3D. Uses CuPy for GPU when `device="gpu"`.
+- **C++ backend** (`kwave/solvers/cpp_simulation.py` + `kwave/executor.py`): Serializes to HDF5, invokes compiled C++ binary, reads results back. `save_only=True` writes HDF5 without running (for cluster jobs).
+
+### Core data classes
+
+- `kWaveGrid` (`kwave/kgrid.py`) — domain discretization, spacing, time array
+- `kWaveMedium` (`kwave/kmedium.py`) — sound speed, density, absorption, nonlinearity
+- `kSource` (`kwave/ksource.py`) — pressure/velocity sources with masks and signals
+- `kSensor` (`kwave/ksensor.py`) — sensor mask and recording configuration
+
+### Legacy path
+
+`kspaceFirstOrder2D()` / `kspaceFirstOrder3D()` in their respective files route through `kWaveSimulation` (`kwave/kWaveSimulation.py`) — a large legacy dataclass used by the C++ backend path. New code should use `kspaceFirstOrder()` directly.
+
+### PML handling
+
+When `pml_inside=False` (default), `kspaceFirstOrder()` expands the grid by `2*pml_size` before simulation and strips PML from full-grid output fields afterward. `pml_size="auto"` selects optimal sizes via `get_optimal_pml_size()`.
+
+### Key utilities
+
+- `kwave/utils/pml.py` — PML sizing (`get_pml()`, `get_optimal_pml_size()`)
+- `kwave/utils/mapgen.py` — geometry generators (`make_disc`, `make_ball`, `make_cart_circle`, etc.)
+- `kwave/utils/signals.py` — signal generation (tone bursts, filtering)
+- `kwave/utils/filters.py` — spatial smoothing, Gaussian filters
+- `kwave/utils/io.py` — HDF5 read/write
+- `kwave/utils/conversion.py` — unit conversion, `cart2grid`
+
+## Testing
+
+- Tests in `tests/`, configured via `[tool.pytest.ini_options]` in `pyproject.toml`
+- Integration tests (`@pytest.mark.integration`) compare against MATLAB reference data
+- Test fixtures in `tests/integration/conftest.py`: `load_matlab_ref` (fixture), `assert_fields_close` (helper function for field comparison)
+- MATLAB reference data for `@pytest.mark.integration` tests lives in `tests/matlab_test_data_collectors/python_testers/collectedValues/` (hardcoded in `conftest.py`)
+- `test_example_parity.py` (MATLAB-parity tests) reads `KWAVE_MATLAB_REF_DIR` (defaults to `~/git/k-wave-cupy/tests` if unset)
+
+## Naming Conventions
+
+- `backend="python"` or `"cpp"` (not "native")
+- `device="cpu"` or `"gpu"` (not `use_gpu` bool)
+- `quiet=True` to suppress output; `debug=True` for detailed output
+- `pml_size="auto"` for automatic PML sizing (not a separate boolean)

{k_wave_python-0.6.1 → k_wave_python-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: k-Wave-python
-Version: 0.6.1
+Version: 0.6.2
 Summary: Acoustics toolbox for time domain acoustic and ultrasound simulations in complex and tissue-realistic media.
 Project-URL: Homepage, http://www.k-wave.org/
 Project-URL: Documentation, https://waltersimson.com/k-wave-python/
@@ -179,31 +179,32 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Requires-Dist: beartype==0.22.9
-Requires-Dist: deepdiff==8.6.2
+Requires-Dist: deepdiff==9.0.0
 Requires-Dist: deprecated>=1.2.14
-Requires-Dist: h5py==3.15.1
-Requires-Dist: jaxtyping==0.3.2
-Requires-Dist: matplotlib==3.10.7
+Requires-Dist: h5py==3.16.0
+Requires-Dist: jaxtyping==0.3.7
+Requires-Dist: matplotlib==3.10.9
 Requires-Dist: numpy<2.3.0,>=1.22.2
 Requires-Dist: opencv-python==4.13.0.92
 Requires-Dist: scipy==1.15.3
 Requires-Dist: tqdm>=4.60
 Provides-Extra: dev
-Requires-Dist: pre-commit==4.5.1; extra == 'dev'
+Requires-Dist: pre-commit==4.6.0; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: furo==2024.8.6; extra == 'docs'
+Requires-Dist: furo==2025.12.19; extra == 'docs'
 Requires-Dist: sphinx-copybutton==0.5.2; extra == 'docs'
 Requires-Dist: sphinx-mdinclude==0.6.2; extra == 'docs'
-Requires-Dist: sphinx-tabs==3.4.7; extra == 'docs'
-Requires-Dist: sphinx-toolbox==3.8.0; extra == 'docs'
+Requires-Dist: sphinx-tabs==3.4.5; extra == 'docs'
+Requires-Dist: sphinx-toolbox==4.1.2; extra == 'docs'
+Requires-Dist: sphinx<9; extra == 'docs'
 Provides-Extra: example
-Requires-Dist: gdown==5.2.0; extra == 'example'
+Requires-Dist: gdown==6.0.0; extra == 'example'
 Provides-Extra: test
-Requires-Dist: coverage==7.10.6; extra == 'test'
+Requires-Dist: coverage==7.14.0; extra == 'test'
 Requires-Dist: phantominator; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-xdist; extra == 'test'
-Requires-Dist: requests==2.33.0; extra == 'test'
+Requires-Dist: requests==2.34.0; extra == 'test'
 Requires-Dist: testfixtures==8.3.0; extra == 'test'
 Description-Content-Type: text/markdown
 

{k_wave_python-0.6.1 → k_wave_python-0.6.2}/kwave/__init__.py

@@ -3,23 +3,45 @@ import json
 import logging
 import os
 import platform
+import stat
+import warnings
 from pathlib import Path
 from typing import List
 from urllib.request import urlretrieve
 
 # Test installation with:
 # python3 -m pip install -i https://test.pypi.org/simple/ --extra-index-url=https://pypi.org/simple/ k-Wave-python==0.3.0
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 
 # Constants and Configurations
 URL_BASE = "https://github.com/waltsims/"
-BINARY_VERSION = "v1.3.0"
-PREFIX = f"{URL_BASE}kspaceFirstOrder-{{}}-{{}}/releases/download/{BINARY_VERSION}/"
+BINARY_VERSION = "v1.4.1"
+# Pin both Windows binaries to v1.3.0. v1.4.x windows builds switched compiler /
+# OpenMP / FFT / CUDA runtime stacks and neither v1.4.x release ships its runtime
+# DLLs (cufft, cudart, vcomp, vcruntime140_1, fftw3f, etc.). v1.3.0 binaries are
+# self-contained with their Intel-era DLL bundle (listed in WINDOWS_DLLS below,
+# downloaded with the OMP request and used by both .exe files since they share
+# kwave/bin/windows/). OMP DLL bundling is fixed in kspacefirstorder-unified#14
+# (awaiting validation); CUDA DLL bundling is tracked in kspacefirstorder-unified#17.
+WINDOWS_OMP_VERSION = "v1.3.0"
+WINDOWS_CUDA_VERSION = "v1.3.0"
 PLATFORM = platform.system().lower()
 
 if PLATFORM not in ["linux", "windows", "darwin"]:
     raise NotImplementedError(f"k-wave-python is currently unsupported on this operating system: {PLATFORM}.")
 
+# darwin C++ binary is arm64-only; universal2 coverage tracked for v0.6.5
+DARWIN_BINARY_ARCH = "arm64"
+_darwin_unsupported = PLATFORM == "darwin" and platform.machine() != DARWIN_BINARY_ARCH
+if _darwin_unsupported:
+    warnings.warn(
+        f"k-wave-python's macOS C++ binary is {DARWIN_BINARY_ARCH}-only. "
+        f"Detected {platform.machine()} — the C++ backend (backend='cpp') will not run on this machine. "
+        "Use backend='python' instead. Universal2 (Intel + Apple Silicon) coverage is tracked for v0.6.5.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+
 # TODO: install directly in to /bin/ directory system directory is no longer needed
 # TODO: deprecate in 0.5.0
 BINARY_PATH = Path(__file__).parent / "bin" / PLATFORM
@@ -44,21 +66,24 @@ ARCHITECTURES = ["omp", "cuda"]
 
 
 def get_windows_release_urls(architecture: str) -> list:
+    version = WINDOWS_OMP_VERSION if architecture == "omp" else WINDOWS_CUDA_VERSION
     specific_filenames = [EXECUTABLE_PREFIX + architecture + ".exe"]
     if architecture == "omp":
         specific_filenames += WINDOWS_DLLS
-    release_urls = [PREFIX.format(architecture.upper(), PLATFORM.lower()) + filename for filename in specific_filenames]
-    return release_urls
+    base = f"{URL_BASE}kspaceFirstOrder-{architecture.upper()}-{PLATFORM.lower()}/releases/download/{version}/"
+    return [base + filename for filename in specific_filenames]
 
 
 URL_DICT = {
     "linux": {
-        "cuda": [URL_BASE + f"kspaceFirstOrder-CUDA-{PLATFORM}/releases/download/v1.3.1/{EXECUTABLE_PREFIX}CUDA"],
+        "cuda": [URL_BASE + f"kspaceFirstOrder-CUDA-{PLATFORM}/releases/download/{BINARY_VERSION}/{EXECUTABLE_PREFIX}CUDA"],
         "omp": [URL_BASE + f"kspaceFirstOrder-OMP-{PLATFORM}/releases/download/{BINARY_VERSION}/{EXECUTABLE_PREFIX}OMP"],
     },
     "darwin": {
         "cuda": [],
-        "omp": [URL_BASE + f"k-wave-omp-{PLATFORM}/releases/download/v0.3.0rc3/{EXECUTABLE_PREFIX}OMP"],
+        "omp": (
+            [] if _darwin_unsupported else [URL_BASE + f"k-wave-omp-{PLATFORM}/releases/download/{BINARY_VERSION}/{EXECUTABLE_PREFIX}OMP"]
+        ),
     },
     "windows": {architecture: get_windows_release_urls(architecture) for architecture in ARCHITECTURES},
 }
@@ -77,6 +102,31 @@ def _hash_file(filepath: str) -> str:
     return md5.hexdigest()
 
 
+def _ensure_executable(binary_filepath) -> None:
+    # Self-heal the executable bit on Linux/macOS. urlretrieve creates files
+    # at 0644, and prior versions of this package didn't fix that up, so users
+    # upgrading with a cached non-executable binary on disk would otherwise
+    # stay stuck (the cache check below returns True and skips re-download).
+    # Any OS-level failure here (broken symlink, read-only FS, wrong ownership,
+    # TOCTOU race) is degraded to a warning so it never aborts `import kwave`.
+    if PLATFORM == "windows":
+        return
+    try:
+        current_mode = os.stat(binary_filepath).st_mode
+        desired_mode = current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        if current_mode == desired_mode:
+            return
+        os.chmod(binary_filepath, desired_mode)
+    except OSError:  # pragma: no cover - defensive; degrades to warning, never fatal
+        # Don't abort import. The user can chmod +x manually or reinstall
+        # into a writable location.
+        logging.warning(
+            "kwave: cannot set executable bit on %s — backend='cpp' may fail with "
+            "Permission denied. Run `chmod +x` manually or reinstall.",
+            binary_filepath,
+        )
+
+
 def _is_binary_present(binary_name: str, binary_type: str) -> bool:
     binary_filepath = BINARY_PATH / binary_name
     binary_file_exists = os.path.exists(binary_filepath)
@@ -106,6 +156,8 @@ def _is_binary_present(binary_name: str, binary_type: str) -> bool:
     if existing_metadata["url"] not in latest_urls:
         return False
 
+    _ensure_executable(binary_filepath)
+
     # No need to check `version` field for now
     # because we version is already present in the URL
     return True
@@ -176,6 +228,7 @@ def download_binaries(system_os: str, bin_type: str):
         try:
             binary_filepath = os.path.join(BINARY_PATH, filename)
             urlretrieve(url, binary_filepath)
+            _ensure_executable(binary_filepath)
             _record_binary_metadata(binary_version=binary_version, binary_filepath=binary_filepath, binary_url=url, filename=filename)
 
         except TimeoutError:

{k_wave_python-0.6.1/.claude/worktrees/add-agent-cli → k_wave_python-0.6.2}/kwave/compat.py

@@ -70,5 +70,9 @@ def options_to_kwargs(simulation_options=None, execution_options=None):
             kwargs["num_threads"] = opts.num_threads
         if opts.device_num is not None:
             kwargs["device_num"] = opts.device_num
+        # Read _binary_path directly: the property auto-resolves to a default,
+        # so it can't distinguish a user-set path from one.
+        if opts._binary_path is not None:
+            kwargs["binary_path"] = opts._binary_path
 
     return kwargs

{k_wave_python-0.6.1 → k_wave_python-0.6.2}/kwave/enums.py

@@ -1,5 +1,17 @@
 from enum import Enum
 
+
+class AlphaMode(str, Enum):
+    """Controls which absorption/dispersion terms are included in the equation of state."""
+
+    NO_ABSORPTION = "no_absorption"
+    NO_DISPERSION = "no_dispersion"
+    STOKES = "stokes"
+
+    def __str__(self):
+        return self.value
+
+
 ################################################################
 # literals that link the discrete cosine and sine transform types with
 # their type definitions in the functions dtt1D, dtt2D, and dtt3D

{k_wave_python-0.6.1/.claude/worktrees/add-agent-cli → k_wave_python-0.6.2}/kwave/kWaveSimulation_helper/create_absorption_variables.py

@@ -12,19 +12,19 @@ def create_absorption_variables(kgrid: kWaveGrid, medium: kWaveMedium, equation_
     # define the lossy derivative operators and proportionality coefficients
     """
     Selects and returns absorption and dispersion operators and coefficients for the given medium based on the equation of state.
-    
+
     Parameters:
         kgrid (kWaveGrid): Grid object providing wavenumber array via `kgrid.k`.
         medium (kWaveMedium): Medium properties used to compute absorption/dispersion coefficients.
         equation_of_state (str): One of `"absorbing"`, `"stokes"`, or `"lossless"` determining which variables to produce.
-    
+
     Returns:
         tuple: (nabla1, nabla2, tau, eta)
             - nabla1: First-order absorption operator or `None` when not applicable.
             - nabla2: Dispersion operator or `None` when not applicable.
             - tau: Absorbing coefficient or `None` when not applicable.
             - eta: Dispersive coefficient or `None` when not applicable.
-    
+
     Behavior:
         - "absorbing": returns (nabla1, nabla2, tau, eta) computed for an absorbing medium.
         - "stokes": returns (None, None, tau, None) where `tau` is the Stokes absorbing coefficient.
@@ -127,4 +127,4 @@ def apply_alpha_filter(medium, nabla1, nabla2):
     # shift the parameters back
     nabla1 = np.fft.ifftshift(nabla1)
     nabla2 = np.fft.ifftshift(nabla2)
-    return nabla1, nabla2
+    return nabla1, nabla2

{k_wave_python-0.6.1 → k_wave_python-0.6.2}/kwave/kgrid.py

@@ -108,7 +108,7 @@ class kWaveGrid(object):
     @t_array.setter
     def t_array(self, t_array):
         # check for 'auto' input
-        if t_array == "auto":
+        if isinstance(t_array, str) and t_array == "auto":
             # set values to auto
             self.Nt = "auto"
             self.dt = "auto"

{k_wave_python-0.6.1/.claude/worktrees/add-agent-cli → k_wave_python-0.6.2}/kwave/kmedium.py

@@ -1,50 +1,65 @@
 import logging
 from dataclasses import dataclass
-from typing import List
+from typing import List, Optional, Sequence, Union
 
 import numpy as np
 
-import kwave.utils.checks
+from kwave.enums import AlphaMode
+
+
+def _to_alpha_mode(value):
+    """Normalize a value to AlphaMode. Accepts None, AlphaMode, or a valid string."""
+    if value is None or isinstance(value, AlphaMode):
+        return value
+    try:
+        return AlphaMode(value)
+    except (ValueError, TypeError):
+        raise ValueError(
+            f"medium.alpha_mode must be an AlphaMode enum value or one of 'no_absorption', 'no_dispersion', 'stokes', got {value!r}"
+        ) from None
 
 
 @dataclass
 class kWaveMedium(object):
+    """
+    Medium properties for k-Wave simulations.
+
+    Note: For heterogeneous medium parameters, medium.sound_speed and medium.density
+    must be given in matrix form with the same dimensions as kgrid. For homogeneous
+    medium parameters, these can be given as single numeric values. If the medium is
+    homogeneous and velocity inputs or outputs are not required, it is not necessary
+    to specify medium.density.
+    """
+
     # sound speed distribution within the acoustic medium [m/s] | required to be defined
-    sound_speed: np.array
+    sound_speed: Union[float, int, np.ndarray]
     # reference sound speed used within the k-space operator (phase correction term) [m/s]
-    sound_speed_ref: np.array = None
+    sound_speed_ref: Optional[Union[float, int, np.ndarray]] = None
     # density distribution within the acoustic medium [kg/m^3]
-    density: np.array = None
+    density: Optional[Union[float, int, np.ndarray]] = None
     # power law absorption coefficient [dB/(MHz^y cm)]
-    alpha_coeff: np.array = None
+    alpha_coeff: Optional[Union[float, int, np.ndarray]] = None
     # power law absorption exponent
-    alpha_power: np.array = None
+    alpha_power: Optional[Union[float, int, np.ndarray]] = None
     # optional input to force either the absorption or dispersion terms in the equation of state to be excluded;
-    # valid inputs are 'no_absorption' or 'no_dispersion'
-    alpha_mode: np.array = None
+    # valid inputs are AlphaMode.NO_ABSORPTION, AlphaMode.NO_DISPERSION, or the equivalent strings
+    alpha_mode: Optional[Union[AlphaMode, str]] = None
     # frequency domain filter applied to the absorption and dispersion terms in the equation of state
-    alpha_filter: np.array = None
+    alpha_filter: Optional[np.ndarray] = None
     # two element array used to control the sign of absorption and dispersion terms in the equation of state
-    alpha_sign: np.array = None
+    alpha_sign: Optional[np.ndarray] = None
     # parameter of nonlinearity
-    BonA: np.array = None
+    BonA: Optional[Union[float, int, np.ndarray]] = None
     # is the medium absorbing?
     absorbing: bool = False
     # is the medium absorbing stokes?
     stokes: bool = False
 
-    #  """
-    #     Note: For heterogeneous medium parameters, medium.sound_speed and
-    #     medium.density must be given in matrix form with the same dimensions as
-    #     kgrid. For homogeneous medium parameters, these can be given as single
-    #     numeric values. If the medium is homogeneous and velocity inputs or
-    #     outputs are not required, it is not necessary to specify medium.density.
-    # """
-
     def __post_init__(self):
         self.sound_speed = np.atleast_1d(self.sound_speed)
+        self.alpha_mode = _to_alpha_mode(self.alpha_mode)
 
-    def check_fields(self, kgrid_shape: np.ndarray) -> None:
+    def check_fields(self, kgrid_shape: Sequence[int]) -> None:
         """
         Check whether the given properties are valid
 
@@ -54,26 +69,21 @@ class kWaveMedium(object):
         Returns:
             None
         """
-        # check the absorption mode input is valid
-        if self.alpha_mode is not None:
-            assert self.alpha_mode in [
-                "no_absorption",
-                "no_dispersion",
-                "stokes",
-            ], "medium.alpha_mode must be set to 'no_absorption', 'no_dispersion', or 'stokes'."
+        # re-normalize alpha_mode in case it was reassigned as a plain string post-construction
+        self.alpha_mode = _to_alpha_mode(self.alpha_mode)
 
         # check the absorption filter input is valid
-        if self.alpha_filter is not None and not (self.alpha_filter.shape == kgrid_shape).all():
+        if self.alpha_filter is not None and self.alpha_filter.shape != tuple(kgrid_shape):
             raise ValueError("medium.alpha_filter must be the same size as the computational grid.")
 
         # check the absorption sign input is valid
-        if self.alpha_sign is not None and (not kwave.utils.checkutils.is_number(self.alpha_sign) or (self.alpha_sign.size != 2)):
-            raise ValueError(
-                "medium.alpha_sign must be given as a " "2 element numerical array controlling absorption and dispersion, respectively."
-            )
+        if self.alpha_sign is not None:
+            alpha_sign_arr = np.atleast_1d(self.alpha_sign)
+            if alpha_sign_arr.size != 2 or not np.issubdtype(alpha_sign_arr.dtype, np.number):
+                raise ValueError("medium.alpha_sign must be a 2 element numeric array controlling absorption and dispersion, respectively.")
 
         # check alpha_coeff is non-negative and real
-        if not np.all(np.isreal(self.alpha_coeff)) or np.any(self.alpha_coeff < 0):
+        if self.alpha_coeff is not None and (not np.all(np.isreal(self.alpha_coeff)) or np.any(self.alpha_coeff < 0)):
             raise ValueError("medium.alpha_coeff must be non-negative and real.")
 
     def is_defined(self, *fields) -> List[bool]:
@@ -102,7 +112,7 @@ class kWaveMedium(object):
             None
         """
         for f in fields:
-            assert getattr(self, f) is not None, f"The field {f} must be not be None"
+            assert getattr(self, f) is not None, f"The field {f} must not be None"
 
     def is_nonlinear(self) -> bool:
         """
@@ -141,13 +151,14 @@ class kWaveMedium(object):
         # enforce both absorption parameters
         self.ensure_defined("alpha_coeff", "alpha_power")
 
-        # check y is a scalar
-        assert np.isscalar(self.alpha_power), "medium.alpha_power must be scalar."
+        # check y is a scalar (np.isscalar rejects 0-d ndarrays — accept np.array(1.5) too)
+        is_scalar = np.isscalar(self.alpha_power) or (isinstance(self.alpha_power, np.ndarray) and self.alpha_power.size == 1)
+        assert is_scalar, "medium.alpha_power must be scalar."
 
         # check y is real and within 0 to 3
-        assert (
-            np.all(np.isreal(self.alpha_coeff)) and 0 <= self.alpha_power < 3
-        ), "medium.alpha_power must be a real number between 0 and 3."
+        assert np.all(np.isreal(self.alpha_coeff)) and 0 <= self.alpha_power < 3, (
+            "medium.alpha_power must be a real number between 0 and 3."
+        )
 
         # display warning if y is close to 1 and the dispersion term has not been set to zero
         if self.alpha_mode != "no_dispersion":
@@ -167,8 +178,10 @@ class kWaveMedium(object):
         self.ensure_defined("alpha_coeff")
 
         # give warning if y is specified
-        if self.alpha_power is not None and (self.alpha_power.size != 1 or self.alpha_power != 2):
-            logging.log(logging.WARN, "the axisymmetric code and stokes absorption assume alpha_power = 2, user value ignored.")
+        if self.alpha_power is not None:
+            ap = np.asarray(self.alpha_power)
+            if ap.size != 1 or not np.isclose(ap.item(), 2.0):
+                logging.warning("the axisymmetric code and stokes absorption assume alpha_power = 2, user value ignored.")
 
         # overwrite y value
         self.alpha_power = 2
@@ -176,12 +189,12 @@ class kWaveMedium(object):
         # don't allow medium.alpha_mode with the axisymmetric code
         if self.alpha_mode is not None and (self.alpha_mode in ["no_absorption", "no_dispersion"]):
             raise NotImplementedError(
-                "Input option medium.alpha_mode is not supported with the axisymmetric code " "or medium.alpha_mode = " "stokes" "."
+                "Input option medium.alpha_mode is not supported with the axisymmetric code or medium.alpha_mode = stokes."
             )
 
         # don't allow alpha_filter with stokes absorption (no variables are applied in k-space)
         assert self.alpha_filter is None, (
-            "Input option medium.alpha_filter is not supported with the axisymmetric code " "or medium.alpha_mode = 'stokes'. "
+            "Input option medium.alpha_filter is not supported with the axisymmetric code or medium.alpha_mode = 'stokes'. "
         )
 
     ##########################################

{k_wave_python-0.6.1 → k_wave_python-0.6.2}/kwave/kspaceFirstOrder.py

@@ -82,6 +82,40 @@ def _strip_pml(result, pml_size, ndim, suffixes=_FULL_GRID_SUFFIXES):
     }
 
 
+def _resolve_dtype(value):
+    """Normalize a dtype-like input to ``np.float32`` or ``np.float64``.
+
+    Accepts numpy dtypes/types (``np.float32``, ``np.float64``), strings
+    (``"float32"`` etc., plus MATLAB aliases ``"single"`` / ``"double"``),
+    Python ``float``, ``None`` (default → float64), and the legacy MATLAB
+    ``"off"`` alias for float64.  Anything that resolves to a non-float32 /
+    non-float64 dtype raises ``ValueError`` — the solver isn't validated
+    for ``float16`` / complex dtypes.
+
+    Cupy dtypes (``cp.float32``, ``cp.float64``) work for free because cupy
+    re-exports numpy's scalar types.  Torch / JAX dtypes are not accepted —
+    they live in different ecosystems and don't translate via ``np.dtype()``;
+    the error message points the user at the equivalent numpy dtype.
+    """
+    if value is None or value == "off":
+        return np.float64
+    try:
+        resolved = np.dtype(value).type
+    except TypeError as e:
+        framework = getattr(type(value), "__module__", "").split(".")[0]
+        hint = ""
+        if framework in ("torch", "jax", "jaxlib", "tensorflow"):
+            hint = f" {framework}.dtype objects aren't supported; pass the equivalent numpy dtype (np.float32 / np.float64)."
+        raise ValueError(
+            f"dtype must be a numpy dtype, type, or string (e.g. 'float32', 'single'), got {value!r}.{hint}"
+        ) from e
+    if resolved is np.float32:
+        return np.float32
+    if resolved is np.float64:
+        return np.float64
+    raise ValueError(f"dtype must resolve to float32 or float64; got {resolved.__name__} from {value!r}")
+
+
 def kspaceFirstOrder(
     kgrid: kWaveGrid,
     medium: kWaveMedium,
@@ -96,12 +130,14 @@ def kspaceFirstOrder(
     smooth_p0: bool = True,
     backend: str = "python",
     device: str = "cpu",
+    dtype=None,
     save_only: bool = False,
     data_path: Optional[str] = None,
     quiet: bool = False,
     debug: bool = False,
     num_threads: Optional[int] = None,
     device_num: Optional[int] = None,
+    binary_path: Optional[str] = None,
 ) -> dict:
     """Run a k-Wave simulation.
 
@@ -142,6 +178,24 @@ def kspaceFirstOrder(
         device: ``"cpu"`` or ``"gpu"``.  For ``backend="python"`` this
             selects NumPy (cpu) vs CuPy (gpu).  For ``backend="cpp"`` it
             selects the OMP vs CUDA binary.  Default ``"cpu"``.
+        dtype: Numerical precision for state arrays in the Python backend.
+            Accepts dtype-like input — a numpy dtype (``np.float32``,
+            ``np.float64``; cupy aliases like ``cp.float32`` work since cupy
+            re-exports numpy's scalar types), a string (``"float32"``,
+            ``"float64"``, ``"single"``, ``"double"``), a Python type
+            (``float``), or ``None`` for the default (float64).  The
+            MATLAB-style alias ``"off"`` is accepted as a synonym for
+            float64 to ease migration from the legacy
+            ``SimulationOptions.data_cast``.  Torch / JAX dtypes are not
+            accepted; pass the numpy equivalent (e.g. ``np.float32`` for
+            ``torch.float32``).
+            ``np.float32`` uses roughly half the memory and is faster on
+            most hardware, at the cost of reduced numerical accuracy.
+            Only ``float32`` and ``float64`` are supported; other dtypes
+            raise ``ValueError``.  Has no effect on ``backend="cpp"`` (the
+            C++ binary uses fixed internal precision regardless); a warning
+            is emitted if ``dtype`` resolves to anything other than float64
+            with the C++ backend.  Default ``None`` (float64).
         save_only: When ``True`` (``backend="cpp"`` only), write the HDF5
             input file and return without running the binary.  Useful for
             cluster submission.  Default ``False``.
@@ -154,6 +208,9 @@ def kspaceFirstOrder(
         num_threads: Thread count for the C++ OMP binary.  ``None`` uses all
             available cores.  Default ``None``.
         device_num: GPU device index for CUDA execution.  Default ``None``.
+        binary_path: Path to a custom C++ binary.  When ``None`` (default),
+            the binary bundled with ``k-wave-data`` is used.  Only applies
+            when ``backend="cpp"``.
 
     Returns:
         dict: Recorded sensor data keyed by field name (e.g.
@@ -167,6 +224,7 @@ def kspaceFirstOrder(
         raise ValueError(f"device must be 'cpu' or 'gpu', got {device!r}")
     if backend not in ("python", "cpp"):
         raise ValueError(f"Unknown backend: {backend!r}. Use 'python' or 'cpp'.")
+    dtype = _resolve_dtype(dtype)
 
     if isinstance(pml_size, str) and pml_size.lower() == "auto":
         pml_size = tuple(int(x) for x in get_optimal_pml_size(kgrid))
@@ -206,10 +264,23 @@ def kspaceFirstOrder(
             pml_size=pml_size,
             pml_alpha=pml_alpha,
             quiet=quiet,
+            dtype=dtype,
         ).run()
 
     elif backend == "cpp":
         from kwave.solvers.cpp_simulation import CppSimulation
+        from kwave.utils.checks import check_alpha_mode_cpp_compatible, warn_alpha_power_near_unity_cpp
+
+        check_alpha_mode_cpp_compatible(medium)
+        warn_alpha_power_near_unity_cpp(medium)
+
+        if dtype is not np.float64:
+            warnings.warn(
+                f"dtype={np.dtype(dtype).name!r} has no effect with backend='cpp'; the C++ binary "
+                "uses fixed internal precision regardless. Use backend='python' to control "
+                "computational precision.",
+                stacklevel=2,
+            )
 
         if not use_kspace:
             warnings.warn(
@@ -243,7 +314,7 @@ def kspaceFirstOrder(
             if not pml_inside:
                 result["pml_size"] = pml_size
             return result
-        result = cpp_sim.run(device=device, num_threads=num_threads, device_num=device_num, quiet=quiet, debug=debug, data_path=data_path)
+        result = cpp_sim.run(device=device, num_threads=num_threads, device_num=device_num, quiet=quiet, debug=debug, data_path=data_path, binary_path=binary_path)
 
     # --- Post-processing: strip PML from full-grid fields ---