k-Wave-python 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

{k_wave_python-0.6.1.dist-info → k_wave_python-0.6.2.dist-info}/METADATA

@@ -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.dist-info → k_wave_python-0.6.2.dist-info}/RECORD

@@ -1,23 +1,23 @@
-kwave/__init__.py,sha256=fT86NYPN8sEBD2O91DMdswhNuVcnye2JPj0ZjId61Bg,7008
-kwave/compat.py,sha256=KscnU7yPF4jLfEj9PIeQdIiIn8eQGDgtsTsL6sE9l9U,2923
+kwave/__init__.py,sha256=zoHNedvJIeMioBhOiLFVCGvfhFYX3L2YYHCL3jjllxk,9674
+kwave/compat.py,sha256=2qr4XhKTNbB-RZjg6pYpUnnkObUyR78maMNsJKuzL3A,3158
 kwave/data.py,sha256=WA0bMA7ScwW3HMyt15GkQOfWctcguFN8NHwALiXwO2I,2623
-kwave/enums.py,sha256=tptEv0ZDcXEd2k5S-3cM21YudmagMQm2oYx52MwZDPk,470
+kwave/enums.py,sha256=lF8RV6gn5IAFuT38CMUc5dakHSwAOaqHtmuvyYkXdk4,738
 kwave/executor.py,sha256=LqCJ8speh6R26p0ezaWEktwWEhA9Q75sJydDwRT-oqU,6367
 kwave/kWaveSimulation.py,sha256=0M61nrIpf_k1BLq9-3bPkj0xN4jQ3MPPjX1_-LSsnfc,68030
-kwave/kgrid.py,sha256=WYICT1g6KES5Gr8SMZG47Wc-mKn-uzg-DsmEECae61I,23197
-kwave/kmedium.py,sha256=CS3deWUuyVksC3D5L_Z6UlS7_-0VJX5oDsTCVKUUc4E,9046
+kwave/kgrid.py,sha256=RPCfqpwHcV7jZ2qgrG_nOMu42jnNERIWM9axq5FH8qY,23226
+kwave/kmedium.py,sha256=ZLnUGbkn23EJotJh2oggam4Q4K-fFMzL2yHpM6JbTeA,9953
 kwave/ksensor.py,sha256=_7KAQK8uCJmFwqxhg-Lio8ojGrU-9on634JnZ11wXmY,4269
 kwave/ksource.py,sha256=twIQ774Zo7mP8yYqhSVl2PW6Y-cp3TSvYtAt6QN2_iw,19596
-kwave/kspaceFirstOrder.py,sha256=c73hZUd5f3qFyzAwExbewGO6CAmLvXJQaWI2lMm_3AU,12017
-kwave/kspaceFirstOrder2D.py,sha256=nA-dN3zEsZy4QazxsMBNa5DcBeFjudrh5lIeBAukMSU,16551
-kwave/kspaceFirstOrder3D.py,sha256=tWB4KvDRflYZ8rqVpwwtdiCfq7AJ87PGJ-n1qv_QkH8,17463
+kwave/kspaceFirstOrder.py,sha256=aFu-JKeuTuVAYvz3deLzo63-XF6gJrytmR7dXN3om5U,15754
+kwave/kspaceFirstOrder2D.py,sha256=w401i3bq_K8oRXopGWIF5CKISyqWRar6B4m9BiMeFH4,16741
+kwave/kspaceFirstOrder3D.py,sha256=D-nWqLTX_c9ky7OqACkOKJrYfKJ09jFundSMDITUKyk,17653
 kwave/kspaceFirstOrderAS.py,sha256=NR-RaUD96cfoy3rw3eELkDZfeF4s3vakcM5TP4pIroc,17515
 kwave/kspaceLineRecon.py,sha256=hSw7ZTxDRPzsS_gk4zeBwk1wefIybEsRbuK0JDY0JxA,5727
 kwave/kspacePlaneRecon.py,sha256=-0anuLC5IUCFx3drvEKdpzUMFb0lCFBrPeni2QyS8r0,5879
 kwave/ktransducer.py,sha256=ypcNWmrQxGa0MXjOuyktvZgzs-7wFobS1fGobNi2GfU,31413
 kwave/recorder.py,sha256=SaDaL1dsnYpsDZ7wfqCWrX0xz8_mtavtpvL8WpbKLAE,5307
 kwave/kWaveSimulation_helper/__init__.py,sha256=pvq2XTaC-yTWSl96AA2h3Iam-wbs5EAaYGDd4ckyTqs,619
-kwave/kWaveSimulation_helper/create_absorption_variables.py,sha256=7Du_Q3Jzr_RiSjhEHF-afdQL_Q5Dds1Xj0Sc-Fmivqg,4926
+kwave/kWaveSimulation_helper/create_absorption_variables.py,sha256=W_jsWquHRCLM5TVF95LG3WkWxwrc2228ki7jF5s92f8,4915
 kwave/kWaveSimulation_helper/display_simulation_params.py,sha256=ROqXjd4MDlJRZZ_ZrNZ3zL7_Ido_gA9dowTwMs1X_lw,3310
 kwave/kWaveSimulation_helper/expand_grid_matrices.py,sha256=qTkKQDQhifbE59iejxKlWx6BvZad83SuU7w3X0HA_Rs,11237
 kwave/kWaveSimulation_helper/retract_transducer_grid_size.py,sha256=jLLAtsRMDi8lVF6SOfkNj7MxBtfhXQZ1AeObSnIkN84,945
@@ -32,15 +32,15 @@ kwave/reconstruction/beamform.py,sha256=JjdYqV-ge2HfQpnR6QwoyQkF3WdbuowTXblchOuj
 kwave/reconstruction/time_reversal.py,sha256=77O9ZS-ZpRCV4Z0ZIm41qzwGGsbnsP4x688qRhEpIz0,6258
 kwave/reconstruction/tools.py,sha256=-F9k7Sbc2qvun1cygc4sHVZdFKP4zaD2p_B4aN_efWQ,2397
 kwave/solvers/__init__.py,sha256=-cfkyK8i0lhgyJx5p-JyK9_5XLVdIdBnjsdQ_Y0AHGw,176
-kwave/solvers/cpp_simulation.py,sha256=mCnsDszHJIJAH-pZA4UDL0QPB-O3V-JY_R8NyBlB050,15060
-kwave/solvers/kspace_solver.py,sha256=uonTccGA5Otfz0spc2FvKMkyMzTazkAjhNjQ8ik0xH4,35380
+kwave/solvers/cpp_simulation.py,sha256=XAZhFz71BBPRmmAbdOJzQ4QsbwUidkAtdW3ee6TfSeM,16768
+kwave/solvers/kspace_solver.py,sha256=6AjIpkpw08197QNjnE3Io_481nc9GwHLQGZYbjSajkU,41488
 kwave/solvers/native.py,sha256=lQoCOPss1kedTpT6BIN5A22XtKdVlSNRuowB_61QqaA,1152
 kwave/solvers/validation.py,sha256=7Zn_EqmDqceD4rTGccHwsjFJIImPXfcDqTwj-nPa7vI,5062
 kwave/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kwave/utils/angular_spectrum.py,sha256=ciEYcM_Vv-CdKdCzwjMxL5NVpCvmjEzYh7LYoelw0p4,15220
 kwave/utils/angular_spectrum_cw.py,sha256=XgENMdku_5gEY2SLXOqyLs6NarkGIPZZW6GbvjJ0mjQ,11319
 kwave/utils/atten_comp.py,sha256=GGH0UBJQu_QG8K_NpyR2Ouwb0CORWZ3LqRTOF7DWrLA,11446
-kwave/utils/checks.py,sha256=VUdPHGKUP9D81-NZk8XgJFGotlG8gOcw9XMryQ5BGJc,9979
+kwave/utils/checks.py,sha256=zKFnM4XJU2McJgMIIK5GvfXxDIPzryrkx86AlVb-2BY,12788
 kwave/utils/colormap.py,sha256=avgY4Gj2ozswvy_cW3w6rCGbpMiz2vkSgaCINSvz0zE,2440
 kwave/utils/conversion.py,sha256=E3qQbEdac0j1VSUGqPiRcxwds6NNcBmSZ3DHv9b8ZcU,17683
 kwave/utils/data.py,sha256=rMZCDT1USQxtiPssvABw4fTxArxgypwh7uLWSrqHIOs,5758
@@ -49,17 +49,17 @@ kwave/utils/filters.py,sha256=eXcvOQyY2Rgn4Azszg0SRuk9pENyB6EshGs7JuIsYDA,22836
 kwave/utils/interp.py,sha256=3n4TtNiL2YVuDk0Mixe_CPpQIsA3tQ2cjPuJOcfh5F8,15326
 kwave/utils/io.py,sha256=FAPU-2wgxkkFNEDS5ONC2s_iD6w2lEOf3LwTGlMa8-w,16631
 kwave/utils/kwave_array.py,sha256=uxQGWvsESuhI5Yl62qus4hbEGtcLE0Xp6v5ZjZnnLj0,39505
-kwave/utils/mapgen.py,sha256=kHghj_mxsGFMW1cPBw4cgmDbw-IcgLko0Fpnkdwry9Y,116073
-kwave/utils/math.py,sha256=fKS1g7XvOs6qQ6R5Ykss1hu9vant1VbemuBcNuiQBT0,13843
+kwave/utils/mapgen.py,sha256=Gzwzr_oT1RPegFLtlrPct3kX1xfxd8ffpebJBmjK3jE,115847
+kwave/utils/math.py,sha256=zzbOEbl-M1RQxVY7xwJYfDn3VPgDda7L6RaeUZ6evwk,13810
 kwave/utils/matlab.py,sha256=FUN8aVQ1eewC4tgMjcbynxj-kp1jyWxXpXEiNS-iXTM,5655
 kwave/utils/matrix.py,sha256=RFQYJ7As7sLRj6iW1hoci0xxDvBoKibtYQ5J4nrcSkQ,14120
-kwave/utils/plot.py,sha256=MU6Pl4GYIZttePNfky1bEqdFyDb1W1_omlAtWfbd3b8,1496
+kwave/utils/plot.py,sha256=xDPa41z7JJKMN9jDpLJqiYEsHRcp7MmcLk3v3CqRP5I,1496
 kwave/utils/pml.py,sha256=ijlwgxwXbBgl1V7x5B-r9stqIXOj-DEnJBsO5y-Wl5M,6282
 kwave/utils/sharpness_filters.py,sha256=mG0oiOVuKJB6Dn_d-44Vrf-48JmYxr6XN4uBmIC9Ji8,3799
 kwave/utils/signals.py,sha256=R4FNEc6RWKzkJoiPaALdiEcxZqwkAJx7Dd1UDv_HgBI,28767
 kwave/utils/tictoc.py,sha256=lHAsEspcfw2AzYBgiOQgeUOEjuKMJHf8D7wcbl4wev0,1426
-kwave/utils/typing.py,sha256=uu_dCUIlHiyov4avdOZ2BfloOuFiXzQwzQ51tixcIZc,1028
-k_wave_python-0.6.1.dist-info/METADATA,sha256=fPhqtF7JuR1pig23dOxlEdCXgNrxw6o8eO4tdZIes3s,13392
-k_wave_python-0.6.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-k_wave_python-0.6.1.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-k_wave_python-0.6.1.dist-info/RECORD,,
+kwave/utils/typing.py,sha256=s2_yfomloEkTxQy6cvvSuSI1o7e5DvdUa3nGpnyZQUs,1562
+k_wave_python-0.6.2.dist-info/METADATA,sha256=6WZri4_-b-BBgnWsal5A2FF2oMSxdcYoTQLdH1dQFEI,13435
+k_wave_python-0.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+k_wave_python-0.6.2.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+k_wave_python-0.6.2.dist-info/RECORD,,

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:

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

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

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

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"

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'. "
         )
 
     ##########################################

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

kwave/kspaceFirstOrder2D.py

@@ -217,6 +217,11 @@ def kspaceFirstOrder2D(
 
         return run_python_backend(kgrid, medium, source, sensor, simulation_options, execution_options)
 
+    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)
+
     # Currently we only support binary execution, meaning all simulations must be saved to disk.
     if not simulation_options.save_to_disk:
         if execution_options.is_gpu_simulation: