fullwave25 1.4.1.dev2__tar.gz → 1.4.2.dev0__tar.gz

{fullwave25-1.4.1.dev2 → fullwave25-1.4.2.dev0}/.bumpversion.toml

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

fullwave25-1.4.2.dev0/.claude/.gitignore

@@ -0,0 +1 @@
+*.pyc

fullwave25-1.4.2.dev0/.claude/20260911_1813_dead-code.md

@@ -0,0 +1,162 @@
+# Dead Code Report — fullwave25
+
+**Date:** 2026-09-11
+**Branch:** develop
+**Scope:** `fullwave/`, `tests/`, `examples/` (including the 6 example notebooks)
+
+## Method
+
+1. `ruff check` (config in `ruff.toml`, F/ARG rules enabled) — already clean, so no
+   unused imports, locals, or function arguments remain in the library.
+2. `vulture 2.16 --min-confidence 0` over `fullwave tests examples` — 77 findings.
+3. Every finding hand-verified against:
+   - the 6 example notebooks (vulture does **not** parse `.ipynb`),
+   - the `__all__` public API exports,
+   - README / docstring references,
+   - near-miss names (e.g. `ncoords` property vs the `ncoords.dat` solver file key,
+     `n_relaxation` vs `n_relaxation_mechanisms`, `gettempprefix` vs stdlib
+     `tempfile.gettempprefixb`).
+
+Result: 77 findings → **33 dead items in the library** (25 internal + 8 public API),
+**5+ dead test helpers**, the remainder confirmed false positives.
+
+---
+
+## A. Confirmed dead — internal/private (safe to delete, non-breaking)
+
+### A.1 The `n_coords_zero` family (standout finding)
+
+Four independent definitions, **zero callers anywhere** in the repo:
+
+| Location | Item |
+|---|---|
+| `fullwave/medium.py:587` | `Medium.n_coords_zero` |
+| `fullwave/medium.py:1075` | `MediumExponentialAttenuation.n_coords_zero` |
+| `fullwave/medium.py:1417` | `MediumRelaxationMaps.n_coords_zero` |
+| `fullwave/solver/pml_builder.py:490` | `PMLBuilder.n_coords_zero` (method) |
+
+### A.2 Stale class attributes
+
+| Location | Item | Evidence |
+|---|---|---|
+| `fullwave/medium.py:257` | `MediumRelaxationMaps.use_regression: bool = False` | defined once; never assigned in `__init__`, never read |
+| `fullwave/solver/pml_builder.py:166` | `n_relaxation: int` field annotation | never assigned or read; all other grep hits are the distinct, very much alive `n_relaxation_mechanisms` |
+
+### A.3 `fullwave/utils/numerical.py` — 6 of 8 functions dead
+
+Only two functions in this module are alive:
+
+- `matlab_round` (line 22) — used in `fullwave/solver/input_file_writer.py` (lines 776, 787, 837, 931) and `tests/solver/test_input_file_writer.py`.
+- `matlab_interp2easy` (line 36) — used in `fullwave/medium_builder/presets/domain_abdominal_wall.py:50`.
+
+Dead:
+
+| Location | Item | Evidence |
+|---|---|---|
+| `fullwave/utils/numerical.py:10` | `seed_everything` | only own def |
+| `fullwave/utils/numerical.py:17` | `normalize_255` | only own def |
+| `fullwave/utils/numerical.py:27` | `matlab_gaussian_filter` | only a commented-out call in `domain_abdominal_wall.py:131–134` |
+| `fullwave/utils/numerical.py:58` | `matlab_interp2easy_3d` | only own def (the 3D sibling of the used 2D version) |
+| `fullwave/utils/numerical.py:91` | `detect_envelope` | only own def |
+| `fullwave/utils/numerical.py:96` | `cut_domain` | only own def |
+
+### A.4 Private helpers, zero references beyond own defs
+
+| Location | Item |
+|---|---|
+| `fullwave/solver/pml_builder.py:695` | `_extend_arrays_sequential_gpu` |
+| `fullwave/solver/pml_builder.py:1475` | `_sort_relaxation_param_dict` |
+| `fullwave/medium_builder/medium_builder.py:122` | `MediumBuilder.register_domain_list` |
+| `fullwave/medium_builder/presets/domain_scatterer.py:164` | `_rescell3ds` (only call is commented out at line 116) |
+| `fullwave/utils/plot_utils.py:289` | `plot_wave_propagation_animation` |
+| `fullwave/utils/plot_utils.py:1123` | `plot_maximum_intensity_projection` |
+| `fullwave/utils/signal_process.py:13` | `signed_power_compression` |
+| `fullwave/utils/signal_process.py:35` | `reshape_whole_sensor_to_nx_ny_nt` |
+
+### A.5 Vendored `MemoryTempfile` (`fullwave/utils/memory_tempfile.py`)
+
+Vendored from mbello/memory-tempfile; the dead methods are part of the upstream API
+surface, so removal is optional and should keep the vendoring tidy (or be skipped):
+
+| Location | Item |
+|---|---|
+| line 125 | `found_mem_tempdir` |
+| line 136 | `using_mem_tempdir` |
+| line 148 | `get_usable_mem_tempdir_paths` |
+| line 170 | `gettempdirb` |
+| line 421 | `gettempprefix` |
+
+> Caution: line 443 calls the **stdlib** `tempfile.gettempprefixb()` inside the
+> separate `gettempprefixb` method (line 434) — do not conflate `gettempprefix`
+> (dead) with `gettempprefixb` (live, stdlib passthrough).
+
+**Category A total: 25 dead items.**
+
+---
+
+## B. Confirmed dead but public API (removal = semver break — needs deprecation first)
+
+| Location | Item | Notes |
+|---|---|---|
+| `fullwave/__init__.py:68` | `VERSION = __version__` | zero internal references; importable as `fullwave.VERSION` ("for convenience") |
+| `fullwave/grid.py:100` | `Grid.n_axial` | property; only a docstring mention in `fullwave/beamformer.py:79` |
+| `fullwave/grid.py:110` | `Grid.n_elevational` | property; same as above |
+| `fullwave/source.py:397` | `Source.ncoords` | the `ncoords` grep hits are the `ncoords.dat` solver-file key in `input_file_writer.py` (lines 1212, 1323), not this property |
+| `fullwave/transducer.py:675` | `Transducer.indexed_element_mask_input_px` | no references in library, tests, or notebooks |
+| `fullwave/transducer.py:1573` | `Transducer.element_surface_to_elemnt_id` | typo in the name; no references |
+| `fullwave/transducer.py:1893` | `LinearTransducer` (class) | legacy; the exercised path is `Transducer` + `TransducerGeometry` |
+| `fullwave/transducer.py:1942` | `make_p4_1c_trasnducer` (factory) | legacy; typo in the name |
+
+**Category B total: 8 dead items.**
+
+---
+
+## C. Confirmed NOT dead (vulture false positives — do not remove)
+
+| Item | Why it is alive |
+|---|---|
+| `Transducer.diverging` (`transducer.py:1221`) | Documented public API in `README.md:212`. Distinct from `transmit.diverging_delays` (`fullwave/transmit.py:147`) |
+| `Transducer.dict_source_index_to_location` (`transducer.py:1701`) | Used by 3 example notebooks |
+| `logging.Formatter.converter = time.gmtime` (`fullwave/__init__.py:22`) | Intentional logging idiom (force GMT timestamps) |
+| `matlab_round`, `matlab_interp2easy` (`numerical.py`) | Actively used — see A.3 |
+| `pytestmark` (`tests/test_cupy_equivalence.py:29`) | pytest module-level marker variable |
+| `return_value` flags (`test_signal_filter.py:188`, `test_solver.py:281–283`, `test_init.py:55/71/87`) | `mock.patch(..., return_value=...)` / `Mock(return_value=...)` — read dynamically by the mock machinery |
+| `check`, `shell` (`tests/solver/test_launcher.py:12/18/57/266/285`) | Dummy functions that must mimic `subprocess.run`'s call signature; parameters are intentionally unread |
+| `inst` (×11, `tests/solver/test_input_file_writer.py`) | Truly assigned-but-never-read patcher locals — dead but harmless (see D) |
+
+---
+
+## D. Dead test helpers (low priority, tests-only)
+
+| Location | Item |
+|---|---|
+| `tests/medium_builder/presets/test_domain_background.py:29` | `get_named_properties` |
+| `tests/solver/test_gpu_memory_estimate.py:66` | `_patch_binary` |
+| `tests/solver/test_pml_builder_zero_attenuation_gate.py:342` | `_build_with_coords` |
+| `tests/solver/test_signal_filter.py:17` | `_make_signal` |
+| `tests/test_source.py:297` | `_base_source` |
+| `tests/test_cupy_equivalence.py` (7 sites: lines 103, 159, 238, 550, 597, 632, 762) | `_patch` methods — defined but never called (zero `self._patch(...)` call sites) |
+| `tests/solver/test_input_file_writer.py` (11 sites, 100% confidence) | unused `inst` locals — assigned, never read; harmless cleanup |
+
+---
+
+## Recommended action plan
+
+1. **One non-breaking commit for category A** — nothing in A is referenced by any
+   notebook, test, or doc example. `n_coords_zero` (4 sites) and the six dead
+   `numerical.py` functions are the bulk of it.
+2. **Deprecation pass for category B** — add `DeprecationWarning`s (or remove in a
+   2.0.0) for `VERSION`, `Grid.n_axial/n_elevational`, `Source.ncoords`, and the four
+   transducer items. Check `__all__` and the README before removing each.
+3. **Optional:** tidy category D and the vendored `MemoryTempfile` methods.
+4. **CI guard (optional):** add vulture to the pre-commit / CI pipeline with a
+   baseline file to keep the count from regrowing.
+
+## Caveats
+
+- Vulture at 60% confidence can still miss dynamic dispatch (e.g. string-based
+  attribute access, `getattr`, notebook `ipynb` cells were checked manually but not
+  mechanically). Categories A and B were each verified by direct grep + notebook
+  token scan; treat any *new* vulture finding the same way before deleting.
+- The vendored `memory_tempfile.py` is third-party code; removals there are cosmetic.
+- This report is identification only — no code was changed.

fullwave25-1.4.2.dev0/.claude/20260916_1311_commit_message_of_the_input_generation_speedup.md

@@ -0,0 +1,13 @@
+Speed up input generation for large grids and pin fullwave_bin_v1.4.2
+
+Input generation for large 3D grids was slow and used a lot of memory. This change removes redundant whole-grid copies and computations, uses numexpr and threads for the remaining array work, and writes files in slabs. The generated input files are byte-identical.
+
+- medium: skip zero maps that are replaced right away, add compute_coefficients and build_coefficients(), and fix the CuPy backend in _make_the_lossless_voxels_lossless.
+- pml_builder: release the unpadded maps, apply ramps and the entrance frequency splice in place, compute coefficients with numexpr one task at a time, copy layer maps on threads, and log the main stages.
+- relaxation_parameters: use numexpr for the first-order attenuation scaling.
+- input_file_writer: write maps and the source matrix in slabs.
+- transmit: build each distinct source pulse once in signal_of.
+- fullwave: set the numexpr thread count to the detected cores, up to 64, unless a thread variable is set.
+- binary_manager: pin fullwave_bin_v1.4.2.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fullwave25-1.4.2.dev0/.claude/20260916_1311_pull_request_of_the_input_generation_speedup.md

@@ -0,0 +1,31 @@
+## Speed up input generation for large grids and pin fullwave_bin_v1.4.2
+
+### Summary
+
+Input generation for large 3D grids was slow and used a lot of memory. numexpr ran with its default of 16 threads, several whole-grid arrays were copied on one thread, and some arrays were computed only to be replaced. This PR removes that work. The generated input files are byte-identical before and after.
+
+### Changes
+
+- `MediumRelaxationMaps` no longer allocates zero maps that are replaced right away. A new `compute_coefficients` option and `build_coefficients()` method let the PML builder skip coefficients it overwrites.
+- The PML builder releases the unpadded relaxation maps once the padded maps exist.
+- PML ramps and the entrance frequency splice are applied in place on the boundary layers.
+- PML coefficients and the first-order attenuation scaling use numexpr, and layer maps are copied on threads.
+- Maps and the source matrix are written in slabs.
+- `signal_of` builds each distinct source pulse once.
+- At import, numexpr uses the detected cores up to 64, unless `NUMEXPR_MAX_THREADS`, `NUMEXPR_NUM_THREADS` or `OMP_NUM_THREADS` is set.
+- The CuPy backend of `Medium` works again. `_make_the_lossless_voxels_lossless` now uses the array's own module.
+- The main input generation stages are logged at info level.
+- `BINARY_RELEASE_TAG` is `fullwave_bin_v1.4.2`.
+
+### Verification
+
+- Input files for 2D and 3D test grids of up to 45 M padded cells are byte-identical before and after.
+- Peak host memory on the 45 M cell grid is 25 to 33 percent lower.
+- The tests for the medium, the PML builder, the input file writer, the relaxation parameters, the transmit, the pulse, the transducer, the source, the package init and the CuPy equivalence pass.
+
+### Notes for review
+
+- Importing `fullwave` changes the numexpr thread count when no thread variable is set.
+- `PMLBuilder.medium_org` now holds the medium as it was given.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

fullwave25-1.4.2.dev0/.claude/20260916_1405_commit_message_of_the_relaxation_memory_estimate.md

@@ -0,0 +1,10 @@
+Count relaxation GPU memory by the region-trimmed layout
+
+The GPU memory estimate of the relaxation solver counted every array over the whole slab, divided the sources by the number of GPUs, and counted only the hard source. The solver stores the higher mechanisms over the interior box and the momentum layer over the band only, and each GPU holds every source.
+
+- solver: _mem_relaxation counts the region-trimmed layout and takes band and interior cell counts, which default to the whole slab.
+- solver: read the interior box and the momentum layer hole from the absorbing layer maps along the center lines, and give each GPU its share.
+- solver: count every source kind and every zero pressure coordinate on each GPU, and log the estimate in GiB.
+- tests: update the relaxation formula tests and add region and 4 GPU cases.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fullwave25-1.4.2.dev0/.claude/20260916_1405_pull_request_of_the_relaxation_memory_estimate.md

@@ -0,0 +1,24 @@
+## Count relaxation GPU memory by the region-trimmed layout
+
+### Summary
+
+The GPU memory estimate for relaxation runs was about 2.5 times too high. It counted every array over the whole slab, but the solver stores the higher mechanisms over the interior box and the momentum absorbing layer over the band only. It also divided the sources by the number of GPUs and counted only the hard source, while each GPU holds every source.
+
+### Changes
+
+- `_mem_relaxation` counts the region-trimmed layout. New keyword arguments `band` and `interior` give the band and box cell counts, and each defaults to the whole slab.
+- New `_relaxation_regions` reads the interior box from the nonzero cells of `a_pml_u2` and above, and the hole from the zero cells of `a_pml_x1`, along the center lines of each axis.
+- New `_band_and_interior` gives each GPU its share, including its halo rows.
+- `_estimate_gpu_memory` counts every source kind and every zero pressure coordinate on each GPU, and logs the estimate in GiB.
+
+### Verification
+
+- `tests/solver/test_gpu_memory_estimate.py` is updated for the layout, with new cases for the regions and a 1407 × 659 × 659 grid on 4 GPUs. There the estimate is 17.3 to 18.4 GiB per GPU, close to the observed use, where the old estimate was 45 to 46 GiB.
+- On a 3D test grid, the box and hole read here match the ones the solver measures.
+
+### Notes for review
+
+- The log unit changes from GB to GiB. The values were already computed in GiB.
+- The estimate matches the counting in the solver's `gpu_memory_nrelax.cuh`.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

fullwave25-1.4.2.dev0/.claude/20260916_2152_commit_message_of_the_cuda_version_choice.md

@@ -0,0 +1,10 @@
+Choose the CUDA build from the driver version and the GPU architecture
+
+The solver refused a driver that supports a CUDA version newer than 13.1, although a driver also runs binaries built with an older CUDA version. The version choice also ignored the GPU architecture, and the result of the version and architecture check was discarded.
+
+- solver: _make_cuda_version_option takes the architecture and picks the newest CUDA version with a build for it that is not newer than the driver. It raises only where no such build exists.
+- solver: remove COMPATIBLE_CUDA_VERSIONS and COMPATIBLE_CUDA_RANGES, so the version and architecture set is the one table of builds.
+- solver: _retrieve_fullwave_simulation_path passes the architecture and raises where the version and architecture pair has no build.
+- tests: replace the refusal of a newer driver, and add cases for a newer driver, an architecture without a CUDA 13.0 build, a driver older than every build, and the binary path for a newer driver on sm_90.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fullwave25-1.4.2.dev0/.claude/20260916_2152_pull_request_of_the_cuda_version_choice.md

@@ -0,0 +1,25 @@
+## Choose the CUDA build from the driver version and the GPU architecture
+
+### Summary
+
+A driver that supports CUDA 13.2 was refused with `CUDA version 13.2 is not in the compatible ranges: [(11.8, 13.1)]`. The version the check reads is the newest CUDA version the driver supports, and a driver also runs binaries built with an older CUDA version, so the upper bound refused drivers that can run the builds. The version choice also ignored the GPU architecture, and `_retrieve_fullwave_simulation_path` discarded the result of `_check_compatible_set`.
+
+### Changes
+
+- `_make_cuda_version_option` takes a new keyword argument `cuda_arch`. On the GPU it picks the newest CUDA version in `COMPATIBLE_CUDA_VERSIONS_ARCHITECTURES_set` for that architecture that is not newer than the driver, and it raises only where no such build exists.
+- `COMPATIBLE_CUDA_VERSIONS` and `COMPATIBLE_CUDA_RANGES` are removed. The version and architecture set is the one table of builds. The list also named 13.1, which has no build in the set.
+- `_retrieve_fullwave_simulation_path` passes the architecture and raises where the version and architecture pair has no build.
+
+### Verification
+
+- `tests/solver/test_solver.py` passes, 33 tests on the CPU. The test that expected a refusal of a CUDA 14.0 driver is replaced. New cases cover a 13.2 driver on `sm_90` and a 14.0 driver on `sm_89`, both giving `cuda130`, and a 13.2 driver on `sm_61`, which gives `cuda129`. They also cover a driver older than every build, a 12.6 driver on `sm_120`, and the 3D binary path for a 13.2 driver on `sm_90`.
+- `ruff check` passes on both files.
+- `tests/solver/test_solver_generate_only.py` needs a GPU and was not run on one.
+
+### Notes for review
+
+- A driver that supports CUDA 13.2 on `sm_90` now resolves to the `cuda130` build, because the set lists `(13.0, "sm_90")`. The binary release must carry that file. If it does not, the download fails and names the file.
+- Nothing changes for `use_gpu=False`, or where the driver version has a build for the GPU architecture. A driver older than every build for its architecture, such as 12.6 on `sm_120`, now raises where it used to pick a version with no build.
+- The fallback warning now names the architecture.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

fullwave25-1.4.2.dev0/.claude/20260916_2203_commit_message_of_the_cuda_version_tests.md

@@ -0,0 +1,10 @@
+Tighten the CUDA version choice tests
+
+A mutation check showed three changes to the version choice that the tests did not catch.
+
+- tests: the CPU mode test uses a driver version with no build, so it checks that the version is returned unchecked.
+- tests: the two CPU path tests no longer patch `_check_compatible_set`, so they check that the pair check is skipped on the CPU.
+- tests: a path test on sm_61 with a 13.2 driver checks that the architecture reaches the version choice.
+- tests: correct the comment on the first sm_120 build.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fullwave25-1.4.2.dev0/.claude/20260916_2213_commit_message_of_the_blackwell_version_choice.md

@@ -0,0 +1,9 @@
+Run Blackwell GPUs on a CUDA 12.8 driver, and add sm_103
+
+The first build for a Blackwell GPU is CUDA 12.9, and a Blackwell GPU needs a driver of CUDA 12.8 or newer, so a 12.8 driver was refused. A build of the driver's CUDA major version runs on that driver through CUDA minor version compatibility.
+
+- solver: where no build for the architecture is as old as the driver, take the oldest build of the driver's CUDA major version and warn that it runs through minor version compatibility. An older build is still preferred.
+- solver: add sm_103 to COMPATIBLE_CUDA_ARCHITECTURES and (12.9, "sm_103") to the version and architecture set. The CUDA 12.9 binaries carry sm_103 device code.
+- tests: Blackwell architectures on a 12.8 driver, the preference for an older build, the oldest newer build of the major version, refusals across major versions, the Blackwell binary path, and a check that the architecture list and the set name the same GPUs.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fullwave25-1.4.2.dev0/.claude/20260916_2213_pull_request_of_the_blackwell_version_choice.md

@@ -0,0 +1,23 @@
+## Run Blackwell GPUs on a CUDA 12.8 driver, and add sm_103
+
+### Summary
+
+A Blackwell GPU needs a driver of CUDA 12.8 or newer, and its first build is CUDA 12.9. The version choice took only builds as old as the driver, so a Blackwell GPU on a 12.8 driver was refused. A program built with a CUDA 12 toolkit also runs on a driver of an older CUDA 12 version through CUDA minor version compatibility, where it needs no just-in-time compile. The CUDA 12.9 binaries hold precompiled device code for every Blackwell architecture. The architecture list also missed sm_103, which the version and architecture set already named for CUDA 13.0.
+
+### Changes
+
+- `_make_cuda_version_option` still prefers the newest build that is not newer than the driver. Where none exists, it takes the oldest build of the driver's CUDA major version and warns that it runs through minor version compatibility. It raises only where the architecture has neither.
+- `sm_103` is added to `COMPATIBLE_CUDA_ARCHITECTURES`, and `(12.9, "sm_103")` to `COMPATIBLE_CUDA_VERSIONS_ARCHITECTURES_set`.
+
+### Verification
+
+- `tests/solver/test_solver.py` passes, 45 tests on the CPU. New cases cover a 12.8 driver on sm_100, sm_101, sm_103, sm_120 and sm_121, which gives `cuda129` with the warning. They also cover a 12.6 driver on sm_89, which still gives `cuda124`, a 12.9 driver on sm_89, which gives `cuda129`, and an 11.4 driver on sm_89, which gives `cuda118`. A 10.2 driver on sm_89 and an 11.8 driver on sm_120 raise. Further cases cover the 2D binary path on sm_120 with a 12.8 driver, and a check that the architecture list and the set name the same GPUs.
+- 13 in-memory changes to the version choice each fail at least one test. They include taking the newest build of the major version, trying minor version compatibility before an older build, dropping the fallback, accepting any major version, and removing sm_103 from the list.
+- The device code entries of the CUDA 12.9 binaries were read from their fat binary sections. All are precompiled, and none is PTX.
+- `ruff check` passes. No Blackwell GPU ran a binary.
+
+### Notes for review
+
+- A driver of an older CUDA 11 version now runs the 11.8 build where it has no older build. CUDA 11 minor version compatibility needs driver 450.80.02 or newer, and a driver of CUDA 11.0 older than that is not checked here.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

fullwave25-1.4.2.dev0/.claude/CLAUDE.md

@@ -0,0 +1,286 @@
+# CLAUDE.md
+
+This file onboards Claude Code to the `fullwave25` project.
+
+You are assisting with a **Python wrapper around a CUDA/C++ ultrasound FDTD simulator** (Fullwave 2.5). The key goals are:
+
+- Make it easy to write, run, and debug ultrasound wave propagation simulations from Python.
+- Keep the Python API high level and "k-Wave-like", while delegating heavy computation to a GPU backend.
+- Preserve physical correctness (FDTD, power‑law attenuation) and performance (multi‑GPU, memory aware).
+
+---
+
+## 1. High‑level overview
+
+### 1.1 What this project does
+
+- Simulates 2D and 3D ultrasound wave propagation using a staggered‑grid FDTD scheme (8th order in space, 4th order in time).
+- Models attenuation using heterogeneous power‑law attenuation, \(\alpha = \alpha_0 f^\gamma\), where both \(\alpha_0\) and \(\gamma\) can vary spatially.
+- Provides a Python interface that:
+  - Builds computational grids and heterogeneous media.
+  - Configures acoustic sources (e.g., plane wave, linear/convex transducers).
+  - Configures sensors/receivers.
+  - Launches CUDA/C simulations on one or more NVIDIA GPUs.
+  - Handles basic visualization and movie export for wavefields and fields of view.
+- The Python package is published as `fullwave25` on PyPI (`pip install fullwave25`).
+
+The core numerical engine (FDTD + attenuation, domain decomposition, multi‑GPU scheduling) is implemented in CUDA/C and exposed via a Python wrapper.
+
+### 1.2 Intended users and workflows
+
+Typical users are ultrasound researchers and engineers who:
+
+- Want high‑fidelity ultrasound simulations in 2D or 3D.
+- Need heterogeneous, frequency‑dependent attenuation (e.g., abdominal wall, air inclusions, layered tissues).
+- Run experiments such as:
+  - Plane wave imaging and compounding.
+  - Linear and convex array imaging (including abdominal wall).
+  - 3D propagation examples with and without air inclusions.
+  - Medium design via simple geometric primitives ("medium builder").
+
+Common workflows:
+
+1. Install with `pip install fullwave25` (or from source for development).
+2. Start from a tutorial notebook (e.g., `examples/simple_plane_wave/example_simple_plane_wave.ipynb`) or Colab link.
+3. Define:
+   - Computational grid.
+   - Medium (density, sound speed, attenuation \(\alpha_0\), exponent \(\gamma\)).
+   - Source (transducer geometry, waveform).
+   - Sensor configuration.
+4. Run the simulation and visualize results (2D, 3D slices, movies).
+5. Iterate on parameters, medium structure, or transmit schemes (plane waves, focused beams, compounding, synthetic aperture).
+
+---
+
+## 2. Architecture and key components
+
+You should treat this project as:
+
+- A **Python front‑end** for configuration, I/O, plotting, and utilities.
+- A **CUDA/C backend** that runs the numerical solver.
+
+At a high level:
+
+- **Python layer**:
+  - Defines grid and medium structures.
+  - Sets up boundary conditions, attenuation parameters, and sources/sensors.
+  - Marshals data to/from GPU memory through C/CUDA bindings.
+  - Provides example scripts and notebooks that serve as templates for new simulations.
+  - Includes a "medium builder" utility to programmatically construct heterogeneous media.
+
+- **CUDA/C layer**:
+  - Implements the staggered‑grid FDTD solver with multiple relaxation processes.
+  - Implements stretched‑coordinate spatial derivatives (\(\nabla_1\), \(\nabla_2\)) for power‑law attenuation and dispersion.
+  - Handles multi‑GPU domain decomposition along depth (x) and coordinating MPI/CUDA or similar primitives.
+  - Manages memory layout with the convention (x, y, z) = (depth, lateral, elevational) for efficiency.
+
+When modifying code:
+
+- Assume the Python API should remain stable and user friendly; breaking changes should be deliberate and documented.
+- Keep in mind that cuda kernel is stored as a binary.
+
+### Claude usage
+
+- When changing logic, only edit:
+  - fullwave/\*
+  - tests/\*
+- Prefer plans first, then code.
+- Write small test drivers for new patterns
+
+---
+
+## 3. Conventions and gotchas
+
+### 3.1 Coordinate conventions
+
+- The simulation grid is ordered as:
+  - \(x\): depth
+  - \(y\): lateral
+  - \(z\): elevational
+- Domain decomposition for multi‑GPU execution happens in the **depth** dimension.
+- Internally, indices are in **C‑array order** (row‑major) regardless of how the user conceptualizes coordinates. This is a frequent source of confusion when placing sources and receivers.
+
+When writing helper code, comments, or new APIs, be explicit about:
+
+- Physical coordinates vs array indices.
+- The order (x, y, z) and how it maps to numpy arrays, C arrays, and GPU memory.
+
+### 3.2 GPU and system requirements
+
+- Linux environment is assumed. For Windows users, WSL2 is recommended.
+- NVIDIA GPU is required; multiple GPUs are recommended for realistic 3D runs.
+- GPU memory can be a hard constraint in 3D:
+  - Prefer down‑scaling grid sizes or enabling multi‑GPU.
+  - Encourage users to inspect usage via `nvidia-smi` or `nvtop`.
+
+When generating new examples or tests, keep GPU memory and runtime reasonable.
+
+### 3.3 Dependencies and system tools
+
+- Python package: `fullwave25` (PyPI).
+- Development environment uses `uv` for environment and dependency management.
+- Some plotting/animation functions depend on:
+  - `ffmpeg` for video encoding.
+  - `opencv-python` (`cv2`) for certain video writers.
+
+If code you write uses video output:
+
+- Make it fail gracefully if `ffmpeg` or `cv2` is missing.
+- Keep error messages explicit (e.g. "Install ffmpeg via `sudo apt install ffmpeg` on Ubuntu").
+
+---
+
+## 4. How to run and test
+
+### 4.1 User installation
+
+For typical users:
+
+```bash
+pip install fullwave25
+```
+
+If they need plotting video support:
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg
+sudo apt install python3-opencv   # or: pip install opencv-python
+```
+
+Encourage users to start from the basic examples:
+
+- `examples/simple_plane_wave/example_simple_plane_wave.ipynb`
+- Or the provided Google Colab notebook.
+
+### 4.2 Development setup
+
+Assume the developer has Git, Python, and an NVIDIA GPU.
+
+Recommended steps:
+
+```bash
+# Clone via SSH (preferred for frequent contributors)
+git clone git@github.com:pinton-lab/fullwave25.git
+cd fullwave25
+
+# Install uv if missing
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dev environment
+make install-all-extras    # full environment for running examples
+# or
+make install               # core library only
+
+# Verify everything
+make test
+```
+
+If adding new tests, hook them into the existing test runner so `make test` remains a single entry point.
+
+---
+
+## 5. Example‑driven usage patterns
+
+The examples directory is the main guide to intended usage. When in doubt, follow their structure.
+
+### 5.1 2D simulations
+
+Examples include:
+
+- Simple plane wave.
+- Plane wave with air inclusion.
+- Linear transducer (standard plane wave, focused transmit, abdominal wall).
+- Plane wave compounding and full synthetic aperture (via Colab scripts).
+- Convex transducer with abdominal wall.
+
+Patterns to preserve:
+
+- A clear sequence:
+  1. Define grid.
+  2. Define medium (including attenuation maps).
+  3. Define transducer/source.
+  4. Define receivers.
+  5. Run simulation.
+  6. Save/visualize outputs.
+
+### 5.2 3D simulations
+
+Examples include:
+
+- Simple 3D plane wave.
+- 3D plane wave with air inclusion.
+- 3D medium builder usage.
+
+In 3D:
+
+- Some plotting utilities from 2D are not available or are adapted to slice views (x–y, x–z slices).
+- Simulations are more expensive; any new 3D examples should keep domain sizes and timesteps moderate.
+
+### 5.3 Medium builder
+
+The medium builder provides a simple API for creating heterogeneous media via geometric compositions.
+
+When writing code that interacts with medium builder:
+
+- Treat it as the standard way to define complex heterogeneous media (e.g., abdominal wall, air pockets).
+- Keep the API compositional and declarative (define shapes, positions, and property maps rather than manually editing arrays).
+
+---
+
+## 6. How to ask Claude for help
+
+When using Claude Code on this repo, prefer **concrete** and **scoped** requests. Some useful patterns:
+
+- "Open `examples/simple_plane_wave/simple_plane_wave.py` and explain, in comments, how the grid, medium, and source are defined. Do not change any logic."
+- "I want to add a new example of a focused linear array in 3D with a heterogeneous abdominal wall. Starting from `examples/wave_3d/simple_plane_wave_3d.py`, propose the minimal modifications and file structure, then implement them."
+- "Given the coordinate convention (x=depth, y=lateral, z=elevational) and C‑array indexing, help me write a helper function that converts a physical coordinate (x_mm, y_mm, z_mm) into an index triple compatible with the solver."
+- "I'm running out of GPU memory in a 3D example. Suggest code changes (grid size, time steps, number of GPUs) that reduce memory usage but preserve physical fidelity as much as possible."
+- "Help refactor the medium builder so that it can load a 3D segmentation mask and assign per‑label attenuation parameters (\(\alpha_0\), \(\gamma\))."
+
+When you ask Claude to modify code:
+
+- Specify the target file(s) and functions.
+- State clearly whether public APIs may change.
+- Ask for minimal, well‑documented diffs.
+
+---
+
+## 7. Coding guidelines and constraints
+
+- **Numerical correctness first**: Do not change discretization, CFL conditions, or attenuation formulations without explicit intent and justification.
+- **Performance aware**:
+  - Avoid Python loops in inner loops; push heavy work into vectorized operations or existing CUDA kernels.
+  - Be careful with host–device copies; they are often the bottleneck.
+- **API design**:
+  - Favor explicit, keyword‑driven configuration over "magic" defaults, especially for physical parameters (e.g., attenuation, relaxation parameters).
+  - Maintain backward compatibility for documented examples where possible.
+
+---
+
+## 8. Things Claude should NOT do
+
+- Do not:
+  - Rewrite numerical schemes unless explicitly requested and scoped.
+  - Change coordinate conventions or index ordering.
+  - Introduce breaking changes to the Python API without a clear migration path.
+  - Add heavy dependencies just for convenience (especially in the core library).
+  - you don't need to run a test. Ask user to run the test.
+
+- Be cautious when:
+  - Changing I/O formats or directory structures that examples depend on.
+  - Touching anything related to the attenuation model or relaxation parameters.
+
+---
+
+## 9. Quick mental model
+
+You can think of `fullwave25` as:
+
+> "A Python‑driven, CUDA‑accelerated FDTD ultrasound simulator that handles realistic, heterogeneous attenuation for 2D/3D wave propagation, with examples mirroring k‑Wave‑style workflows."
+
+All code changes and suggestions should support this purpose: **high‑fidelity ultrasound simulations that remain practical and usable for researchers.**
+
+## 10. coding style
+
+follow ruff.toml