k-Wave-II: A MATLAB toolbox for the simulation of acoustic wave fields

k-Wave-II is an open-source MATLAB toolbox used to solve partial differential equations, with a particular focus on wave problems in biomedical ultrasound. The principal solvers are based on the k-space-corrected pseudospectral time domain method.

k-Wave-II is a major re-write of the original k-Wave Toolbox, developed with the aim of making k-Wave sustainable in the long term. The specific objectives are: - to re-engineer the code base leveraging object orientated programming, - to retain the ease-of-use and low barrier-to-entry of k-Wave-I, - to facilitate greater engagement of the user and contributor communities in code development, - to improve the development and release process to incorporate best practice, - and to make k-Wave easier for AI-agents to interact with, eg. for generating training datasets.

Getting started

Installation

• From the k-Wave-II GitHub page, find the green Code button and either clone the repo or download a zip file of the current version of the codebase.
• Open Matlab.
• Add the location of the k-wave files to the Matlab path, eg. using addpath(<path-to-kwave>) on the Matlab command line, or the Set Path button on the Home tab.
• Generate the help files, if required, from the Matlab command line. This can take several minutes to run but only needs to be done once as the help files documentation will then be stored.

>> kwave.devtools.GenerateDocumentation

• Import the kwave namespace. This avoids having to prepend all function calls with kwave.toolbox, eg. kgrid = Grid(Nx,dx) rather than kgrid = kwave.toolbox.Grid(Nx,dx). (If you do this, ensure k-Wave-I is not on the Matlab path to avoid naming conflicts.)

>> import kwave.toolbox.*

• For examples of how to use k-Wave-II, and templates to build upon, see the tutorials in kwave/tutorials.

Minimum requirements

• k-Wave-II requires MATLAB R2023b or later.
• No MATLAB toolboxes are required to use k-Wave-II. (Although note that if you want to run the unit tests locally you will require the signal processing toolbox for the reference sinc function.)

Releases

k-Wave-II is currently in a pre-release state. We aim, in due course, to release a new version of the toolbox every six months, with patches issued in-between as needed. To use the latest features between releases, you can clone the github repo and use the default develop branch. Please bear in mind that features on the develop branch may not be complete yet, and, in that context, we appreciate your feedback, contributions, and patience.

Every k-Wave-II release is tested with all releases of MATLAB after the minimum (see Minimum requirements), until the latest one before the release was made.

Getting help

We are a very small team maintaining this toolbox, and we would like it to be community-driven and therefore sustainable.

If you would like to report a bug or request a new feature, first check the existing issues in the github repo and contribute to the discussion if it is already reported. If it is not, please open a new issue, using the appropriate template. Also please consider contributing to the fix or improvement (see the section on contributing).

If you have a question or you need some help, please use the discussions feature in the github repo. Hopefully someone from the community will be able to assist you.

Contributing

Users are encouraged to contribute to the code and open pull requests for new features and bug fixes. New developers should read the developer docs first, starting with the contributor guidelines. Anyone who submits code that is accepted into the toolbox will automatically be added to the list of contributors below.

We also encourage involvement by those able to review developers' code contributions. Please contact the maintainers if you are interested in becoming a code reviewer.

Development lead

k‑Wave‑II builds on long‑standing collaborations and the contributions of many researchers to k-Wave-I, including foundational work by Bradley Treeby, Ben Cox, and Jiri Jaros. Its ongoing development is guided and maintained by the UCL Biomedical Ultrasound Group.

Contributors

Bradley Treeby	Ben Cox	Jiri Jaros	ellymartin	MatthewJohnKing	Antonio Stanziola
ellwise	Devaraj Gopinathan	Ilektra Christidi	David Stansby	Stella Prins	Arindam Saha
Mashy Green	nicolin

The grid above is generated with all-contributors using information from GitHub. If you’d like to request a change contact the maintainers.