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.

Environment Setup with uv

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.

2. Clone the Repository

git clone https://github.com/waltsims/k-wave-python
cd k-wave-python

3. Create and Activate Virtual Environment

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

4. Install Dependencies

Install development and testing dependencies using uv:

uv pip install -e '.[dev,test]'

5. Configure Pre-commit Hooks

pre-commit install

Testing

Prerequisites

  • MATLAB installed locally (see Alternative to MATLAB if you don’t have MATLAB)

  • k-Wave installed in a parallel directory to k-wave-python

Directory structure for parallel installation:

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

Manual Test Execution

After reference generation:

pytest

Test Coverage

coverage run

Running Examples

Default (GPU-enabled)

make run-examples
# or
MPLBACKEND=Agg python run_examples.py

Force CPU Execution

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/

Note

Alternative to MATLAB: If you don’t have a local MATLAB installation, you can download pre-generated reference artifacts from GitHub CI.

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)

  2. Locate kSpaceFirstOrder function call:

    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:

    input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false, 'SaveToDisk', true, 'SaveToDiskExit', true};

  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:

Publishing k-wave-python

Hatch is used to publish k-wave-python to PyPI.

Note

This is only performed by developers with write access to the k-wave-python package on PyPI.

The package can be built using:

hatch build

And pushed to the production index with:

hatch publish -u __token__