v0.6.3rc1: hardware validation across macOS / Windows / Linux + GPUs

[waltsims]

Tracking pre-release validation of v0.6.3rc1 before promoting to stable v0.6.3. The binary install path was substantially rewritten — first release on the unified binary pipeline (kspacefirstorder-unified v1.4.2). Validating that the URL flip, rename-on-download, 16-arch CUDA binary, and Windows multi-arch fix all behave correctly on real hardware.

Install

pip install --pre k-wave-python
# or pinned:
pip install k-wave-python==0.6.3rc1

Smoke test recipe (any platform)

# 1. Confirm install + binary download
python -c "import kwave; print(kwave.__version__, kwave.BINARY_VERSION)"
# expected: 0.6.3rc1 v1.4.2

# 2. Confirm binaries landed at the expected paths (rename-on-download verified)
python -c "import kwave, os; print(sorted(p for p in os.listdir(kwave.BINARY_PATH) if not p.endswith('.json')))"
# expected on linux/darwin: ['kspaceFirstOrder-CUDA', 'kspaceFirstOrder-OMP']  (no -linux / -darwin suffix)
# expected on windows:     ['kspaceFirstOrder-CUDA.exe', 'kspaceFirstOrder-OMP.exe', plus the 19 shared DLLs]

# 3. Run an OMP example end-to-end
uv run examples/ivp_homogeneous_medium.py   # or whatever your env runner is

# 4. If GPU available: run the same example with backend='cpp', device='gpu'
# (or use any example that exercises the CUDA path)

Validation matrix

macOS

• Apple Silicon (arm64) + OMP — primary supported config; downloads kspaceFirstOrder-OMP-darwin and runs cleanly. Verified 2026-06-21 on M1 (macOS 15.1): 0.6.3rc1 installs from --pre, binary lands at the expected path, python and cpp backends both run and agree bit-for-bit (corr=1.0, 0 diff) on an on-grid sensor.
• Apple Silicon (arm64) — Homebrew runtime deps present — the darwin OMP binary is not self-contained: otool -L shows it links fftw, hdf5, zlib, libomp at hardcoded /opt/homebrew/opt/... paths, so backend="cpp" fails at launch with dyld: Library not loaded … unless they're installed. Confirm a clean machine follows the documented brew install fftw hdf5 zlib libomp (docs index / docs/get_started/new_api.rst) and that the cpp backend then runs. (Consider bundling via @rpath/delocate so this isn't a manual prerequisite.)
• Intel Mac (x86_64) + OMP — should emit the _darwin_unsupported RuntimeWarning at import time; no CUDA path (URL_DICT['darwin']['cuda'] is [])

Linux

• Linux + OMP (no GPU) — kspaceFirstOrder-OMP downloads, example runs on CPU
• Linux + CUDA on Turing (RTX 20xx / T4) — exercises sm_75 SASS section
• Linux + CUDA on Ampere (A100 / RTX 30xx) — exercises sm_80 or sm_86
• Linux + CUDA on Ada (RTX 40xx / L40) — exercises sm_89
• Linux + CUDA on Hopper (H100 / H200) — exercises sm_90 / sm_90a
• Linux + CUDA on Blackwell consumer (RTX 50xx / RTX PRO 6000) — exercises sm_120 / sm_120a (the new arch)
• Linux + CUDA on Blackwell datacenter (B200 / GB200) — exercises sm_100 / sm_100a (the new arch)
• Linux + CUDA on Volta (V100) — should emit the runtime cc<7.5 warning, binary load expected to fail with no kernel image is available for execution on the device (the warning's role is to tell users why)
• Linux + CUDA on Pascal (GTX 10xx / P100) — same: runtime warning + expected binary load failure

Windows

• Windows + OMP (no CUDA) — kspaceFirstOrder-OMP-windows.exe + 19 shared DLLs download, example runs
• Windows + CUDA on Turing (RTX 20xx) — kspaceFirstOrder-CUDA-windows.exe (14.8 MB) + cudart64_13.dll + cufft64_12.dll download; GPU example runs. Proves the v1.4.1 Windows regression (sm_75-only 3.4 MB binary) is fixed.
• Windows + CUDA on Ampere / Ada / Hopper / Blackwell — any one card sufficient; same flow

What success looks like

For each row above:

• Install completes (binaries download to the expected paths)
• python -c "import kwave" runs without unexpected warnings (or with the expected runtime cc<7.5 warning for Maxwell/Pascal/Volta)
• An example (any IVP / OMP / CUDA example as appropriate) runs to completion and produces sensible output

If any row fails, comment on this issue with:

• Platform + GPU model + compute capability
• Output of pip show k-wave-python and python -c "import kwave; print(kwave.__version__, kwave.BINARY_VERSION, kwave.BINARY_PATH)"
• The actual error / unexpected behavior

What this gates

Promoting to stable v0.6.3. Once the matrix is reasonably covered (at minimum: one Linux + CUDA per supported arch family, one Windows + CUDA, one macOS + OMP, one Linux + OMP), I'll prep the one-line promotion PR.

Related

• Pre-release: https://github.com/waltsims/k-wave-python/releases/tag/v0.6.3rc1
• Unified release: https://github.com/waltsims/kspacefirstorder-unified/releases/tag/v1.4.2
• Consolidation tracking: Consolidate 5 mirror repos into unified (execute plan 08) kspacefirstorder-unified#13
• Closes Flip BINARY_VERSION URLs to unified after mirror consolidation #738 once stable v0.6.3 ships

[waltsims]

@faridyagubbayli can you try on Windows?

[waltsims]

Linux + OMP (no GPU) — smoke test result

Machine: Linux x86_64 (cpu-k-wave-tester, kernel 6.8.0-71-generic, Ubuntu); no GPU / no nvidia-smi; os.cpu_count() = 1
Date: 2026-06-21
Python: 3.12.3 in a fresh uv venv
Tested: k-wave-python==0.6.3rc1, kwave.BINARY_VERSION == 'v1.4.2'

Install — PASS

uv pip install --pre k-wave-python==0.6.3rc1

Resolved 24 packages, installed in ~1.1 s. No build steps (pure-wheel install).

Version sanity — PASS

$ .venv/bin/python -c "import kwave; print(kwave.__version__, kwave.BINARY_VERSION)"
0.6.3rc1 v1.4.2

Binary download + rename-on-download — PASS (the critical v0.6.3rc1 check)

kwave.BINARY_PATH = /tmp/kwp-063rc1-smoke/.venv/lib/python3.12/site-packages/kwave/bin/linux

Files after first import (excluding *.json manifests):

['kspaceFirstOrder-CUDA', 'kspaceFirstOrder-OMP']

Bare backend names, no -linux suffix ✓. The manifest JSONs confirm the source URL had the suffix and the new rename-on-download logic stripped it:

{"url": "https://github.com/waltsims/kspacefirstorder-unified/releases/download/v1.4.2/kspaceFirstOrder-OMP-linux",
 "version": "v1.4.2",
 "file_hash": "4c4fbea5ada8b25d0d6150bb2a1f5f1a"}

Executable bit + binary works — PASS

mode: 0o100755
exec bit (user): True
size: 4776248 bytes

./kspaceFirstOrder-OMP --help exited 0 and printed the expected banner:

┌───────────────────────────────────────────────────────────────┐
│                   kspaceFirstOrder-OMP v1.3                   │
├───────────────────────────────────────────────────────────────┤
│                             Usage                             │
...
│ -i <file_name>                │ HDF5 input file               │
│ -o <file_name>                │ HDF5 output file              │
│ -t <num_threads>              │ Number of CPU threads         │

Example: ivp_homogeneous_medium.py via C++ OMP — PASS

Pulled the example from master and called run(backend="cpp", device="cpu", quiet=True):

import ivp_homogeneous_medium as ex
result = ex.run(backend="cpp", device="cpu", quiet=True)

Output:

backend=cpp device=cpu
elapsed_s=3.49           # python-visible wall time for the kspaceFirstOrder call
p.shape=(604, 50)        # 604 timesteps x 50 Cartesian-circle sensor points
p.dtype=float32
p.min=-1.16357
p.max=1.4054
p.mean=0.0061783
p.std=0.235378
finite_all=True

Total Python process time including imports + HDF5 round-trip: ~12.5 s. No warnings, no NaNs/Infs.

Verdict

PASS — k-wave-python 0.6.3rc1 installs cleanly on Linux x86_64, downloads the v1.4.2 unified binaries, correctly renames them on download (no -linux suffix on disk), sets the executable bit, and runs an end-to-end 2D IVP example via the C++ OMP backend with sensible sensor output.

[waltsims]

Linux + cpp/OMP — cross-backend numerical validation (follow-up)

Beyond the smoke test above (binary download + exec bit + single example), I also ran a head-to-head cpp vs python (NumPy) comparison on this Linux x86_64 machine to confirm the cpp/OMP path is producing the same answer as the in-process Python reference.

Setup

• k-wave-python 0.6.3rc1 on Python 3.12, kwave.BINARY_VERSION = v1.4.2
• 2D IVP, 128×128 grid, dx=dy=0.1 mm, homogeneous c0=1500, ρ0=1000
• Smoothed disk source (r=5 px), 10-pt line sensor, Nt=200, PML default
• Identical inputs to both backends via kspaceFirstOrder(kgrid, medium, source, sensor, backend=..., device="cpu", quiet=True)

Numerical agreement (sensor p)

metric	value
Max abs diff	1.94e-07
L∞-relative	1.18e-06
L2-relative	1.01e-06
Field peak (‖py‖∞)	1.64e-01

The two backends agree to ~6.5 significant figures at the field's peak — exactly the float32 round-off floor (cpp binary's internal precision is f32; python defaults to f64). For comparison, the project's rtol=1e-10/atol=1e-12 MATLAB-parity tolerance assumes f64-vs-f64; the cpp-vs-py disagreement at ~1e-6 is the expected f32 truncation noise, not a structural divergence.

Verdict

Cross-backend agreement on the propagating wavefield is at the FFT/float32 noise floor on this Linux box. Both backends are computing the same physics; the cpp side just truncates internally. Linux + cpp/OMP is validated for v0.6.3rc1.

Side-finding

The comparison surfaced a latent shape-convention bug in the cpp backend unrelated to this release: cpp returns sensor p as (Nt, n_sensor) while python returns the documented (n_sensor, Nt) (_fix_output_order trigger condition misses the cpp layout). Filed as #760 — does not block v0.6.3 promotion.

[waltsims]

Docs should describe dynamically linked libs required for k-wave-python cpp.