waltsims · waltsims · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -3,59 +3,42 @@
 [![Support](https://img.shields.io/discord/1234942672418897960?style=flat&logo=discord)](https://discord.gg/your-invite-code)
 [![Documentation Status](https://readthedocs.org/projects/k-wave-python/badge/?version=latest)](https://k-wave-python.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/waltsims/k-wave-python/graph/badge.svg?token=6ofwtPiDNG)](https://codecov.io/gh/waltsims/k-wave-python)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/waltsims/k-wave-python/master)
 
-This project is a Python implementation of v1.4.0 of the [MATLAB toolbox k-Wave](http://www.k-wave.org/) as well as an
-interface to the pre-compiled v1.3 of k-Wave simulation binaries, which support NVIDIA sm 5.0 (Maxwell) to sm 9.0a (Hopper) GPUs.
-
-**New in v0.6.0:** Unified `kspaceFirstOrder()` API with a pure NumPy/CuPy solver. See the [API guide](https://k-wave-python.readthedocs.io/en/latest/get_started/new_api.html). The `kspaceFirstOrder()` API is experimental and may change before v1.0.0.
+A Python implementation of [k-Wave](http://www.k-wave.org/) — an acoustics toolbox for time-domain simulation of acoustic wave fields. Includes a pure NumPy/CuPy solver (`backend="python"`) and an interface to the pre-compiled k-Wave C++ binaries (`backend="cpp"`) with NVIDIA GPU support (sm 5.0–9.0a).
 
 ## Mission
 
-With this project, we hope to increase the accessibility and reproducibility of [k-Wave](http://www.k-wave.org/) simulations
-for medical imaging, algorithmic prototyping, and testing. Many tools and methods of [k-Wave](http://www.k-wave.org/) can
-be found here, but this project has and will continue to diverge from the original [k-Wave](http://www.k-wave.org/) APIs
-to leverage pythonic practices.
+Increase the accessibility and reproducibility of [k-Wave](http://www.k-wave.org/) simulations for medical imaging, algorithmic prototyping, and testing.
 
 ## Getting started
 
 ![](_static/example_bmode.png)
 
-A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/HEAD/examples/legacy/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
+A [collection of examples](../examples/) covers common simulation scenarios. Run any example locally:
+
+```bash
+uv run examples/ivp_homogeneous_medium.py
+```
 
-This example file steps through the process of:
- 1. Generating a simulation medium
- 2. Configuring a transducer
- 3. Running the simulation
- 4. Reconstructing the simulation
+No GPU required — all examples run on CPU with NumPy.
 
 ## Installation
 
-To install using [uv](https://docs.astral.sh/uv/) (recommended):
+Using [uv](https://docs.astral.sh/uv/) (recommended):
 
 ```bash
 uv add k-wave-python
-uv run python my_simulation.py
 ```
 
 Or with pip:
 
 ```bash
 pip install k-wave-python
 ```
-> **Note for MacOS:**
-> 
-> k-wave-python offers initial support for MacOS, but you will need to install the following dependencies using the [brew package manager](https://docs.brew.sh/Installation) along with the Python package:
-> ```bash
-> brew install fftw hdf5 zlib libomp
-> ```
-After installing the Python package, the required binaries will be downloaded and installed the first time you run a
-simulation.
 
 ## Development
 
-If you're enjoying k-Wave-python and want to contribute, development instructions can be
-found [here](https://k-wave-python.readthedocs.io/en/latest/development/development_environment.html).
+Development instructions can be found [here](https://k-wave-python.readthedocs.io/en/latest/development/development_environment.html).
 
 ## Related Projects
 
@@ -80,4 +63,4 @@ url = {https://github.com/waltsims/k-wave-python}
 ```
 ## Contact
 
-e-mail [wsimson@stanford.edu](mailto:wsimson@stanford.edu).
+e-mail [walter.a.simson@gmail.com](mailto:walter.a.simson@gmail.com).
diff --git a/docs/development/development_environment.rst b/docs/development/development_environment.rst
@@ -3,185 +3,64 @@ Development Environment
 
 Overview
 --------
-k-Wave-python is a Python interface to the k-Wave C++ binaries, which are required to run simulations. The binaries are automatically downloaded when the package runs for the first time.
+k-Wave-python provides both a pure Python/NumPy solver and an interface to pre-compiled C++ binaries. The Python backend works out of the box — no extra dependencies needed.
 
-Environment Setup with uv
--------------------------
+Environment Setup
+-----------------
+
+1. Install `uv <https://docs.astral.sh/uv/getting-started/installation/>`_
 
-1. Install uv
-Uv is "An extremely fast Python package and project manager, written in Rust." We would recommend that you use it. Installation instructions can be found `here <https://docs.astral.sh/uv/getting-started/installation/#installation-methods>`_.
+2. Clone and install:
 
-2. Clone the Repository
-~~~~~~~~~~~~~~~~~~~~~~~
 .. code-block:: bash
 
     git clone https://github.com/waltsims/k-wave-python
     cd k-wave-python
-
-3. Create and Activate Virtual Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. code-block:: bash
-
-    uv venv
-    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-4. Install Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~
-Install development and testing dependencies using uv:
-
-.. code-block:: bash
-
-    uv pip install -e '.[dev,test]'
-
-5. Configure Pre-commit Hooks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. code-block:: bash
-
-    pre-commit install
+    uv sync --extra dev --extra test
+    uv run pre-commit install
 
 Testing
 -------
 
-Prerequisites
-~~~~~~~~~~~~~
-- MATLAB installed locally (see `Alternative to MATLAB`_ if you don't have MATLAB)
-- `k-Wave <https://github.com/ucl-bug/k-wave>`_ installed in a parallel directory to k-wave-python
-
-**Directory structure for parallel installation:**
-
-.. code-block:: text
-
-    <parent_dir>/
-    ├── k-wave/
-    │   ├── k-Wave/
-    │   ├── LICENSE.txt
-    │   └── README.md
-    └── k-wave-python/
-        ├── kwave/
-        └── ...
-
-
-Running Tests
-~~~~~~~~~~~~~
-
-Full Test Suite
-^^^^^^^^^^^^^^^
-Generate reference files with MATLAB and run the complete Python test suite:
-
 .. code-block:: bash
-    cd k-wave-python/
-    make test
 
-Manual Test Execution
-^^^^^^^^^^^^^^^^^^^^^
-After reference generation:
+    uv run pytest
 
-.. code-block:: bash
+Most tests run without MATLAB. Tests that need MATLAB reference data will skip gracefully if the references are not available.
 
-    pytest
+.. note::
+   **Without MATLAB:** Download pre-generated references from
+   `GitHub CI <https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip>`_
+   and unpack into ``tests/matlab_test_data_collectors/python_testers/collectedValues/``.
+
+Test coverage:
 
-Test Coverage
-^^^^^^^^^^^^^
 .. code-block:: bash
 
-    coverage run
+    uv run coverage run
 
 Running Examples
 ~~~~~~~~~~~~~~~~
 
-Default (GPU-enabled)
-^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: bash
-
-    make run-examples
-    # or
-    MPLBACKEND=Agg python run_examples.py
-
-Force CPU Execution
-^^^^^^^^^^^^^^^^^^
 .. code-block:: bash
 
-    MPLBACKEND=Agg KWAVE_FORCE_CPU=1 python run_examples.py
-
-Test Architecture
------------------
-
-The test suite compares Python and MATLAB outputs through two methodologies:
-
-1. Unit Testing
-~~~~~~~~~~~~~~~
-- Tests k-Wave-python functions against their MATLAB counterparts
-- Reference outputs stored in ``.mat`` files
-- Generated by MATLAB scripts in ``tests/matlab_test_data_collectors/matlab_collectors/``
-- Master script: ``tests/matlab_test_data_collectors/run_all_collectors.m``
-- Output location: ``tests/matlab_test_data_collectors/python_testers/collectedValues/``
-
-.. _`Alternative to MATLAB`:
-
-.. note::
-   **Alternative to MATLAB:** If you don't have a local MATLAB installation, you can download pre-generated reference artifacts from `GitHub CI <https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip>`_.
-
-
-.. _`GitHub CI artifacts link`: https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip
-
-2. Integration Testing
-~~~~~~~~~~~~~~~~~~~~~~
-- Validates ``.h5`` files produced by k-Wave-python against original k-Wave outputs
-- Uses hash values from MATLAB examples stored in JSON files
-- Hash files location: ``tests/reference_outputs/``
-- These files are committed to the repository and only require updates for new k-Wave releases
-
-Generating MATLAB Reference Files
----------------------------------
-
-Process for Creating Reference Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Open target MATLAB example (e.g., ``example_pr_2D_TR_directional_sensors.m`` from the `k-Wave repository <https://github.com/ucl-bug/k-wave/blob/main/k-Wave/examples/example_pr_2D_TR_directional_sensors.m>`_)
-
-2. Locate ``kSpaceFirstOrder`` function call:
-
-   .. code-block:: matlab
-
-       input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false};
-       sensor_data = kspaceFirstOrder2D(kgrid, medium, source, sensor, input_args{:});
-
-3. Add save options to ``input_args``:
+    uv run examples/ivp_homogeneous_medium.py
 
-   .. code-block:: matlab
-
-       input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false, 'SaveToDisk', true, 'SaveToDiskExit', true};
+Force CPU (skip GPU even if available):
 
-4. Run modified example to generate ``.h5`` files in your ``tmp`` folder:
-
-   - Single function call: creates ``example_input.h5``
-   - Multiple calls: creates ``example_input_1.h5``, ``example_input_2.h5``, etc.
-
-5. Convert ``.h5`` files to JSON hashes using ``H5Summary``:
+.. code-block:: bash
 
-   - Single file: see `lines 92-95 <https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L92-L95>`_
-   - Multiple files: see `lines 97-106 <https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L97-L106>`_
+    KWAVE_FORCE_CPU=1 uv run examples/ivp_homogeneous_medium.py
 
-Publishing k-wave-python
------------------
+Publishing
+----------
 
-`uv <https://docs.astral.sh/uv/>`_ is used to build and publish k-wave-python to `PyPI <https://pypi.org/>`_.
+`uv <https://docs.astral.sh/uv/>`_ is used to build and publish to `PyPI <https://pypi.org/>`_.
 
 .. note::
-    This is only performed by developers with write access to the k-wave-python package on PyPI.
-
-The package can be built using:
+    Only for maintainers with PyPI write access.
 
 .. code-block:: bash
 
     uv build
-
-And pushed to the production index with:
-
-.. code-block:: bash
-
     uv publish --token $PYPI_TOKEN
-
-
-
-