From 51870945916cae27bdc6e02e6975bd1e25d7953c Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 16:52:19 +0100 Subject: [PATCH 01/29] Update README.md --- docs/README.md | 37 ++++++++++++------------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5c6b26a8..31dadb23 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,19 @@ # k-Wave-II: A MATLAB toolbox for the simulation of acoustic wave fields -!!! warning "Under Construction" - K‑Wave ii is currently under active development and not public yet. - Documentation, APIs, and features may change without notice. +!!! WARNING "Under Construction" + k‑Wave-ii is currently under active development. Documentation, APIs, and features may change without notice. [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE.md) [![codecov](https://codecov.io/gh/ucl-bug/k-wave-ii/graph/badge.svg?token=A8UMTDRF6T)](https://codecov.io/gh/ucl-bug/k-wave-ii) ![unit tests](https://github.com/ucl-bug/k-wave-ii/actions/workflows/tests.yml/badge.svg) ![code quality](https://github.com/ucl-bug/k-wave-ii/actions/workflows/code_quality.yml/badge.svg) ![build docs](https://github.com/ucl-bug/k-wave-ii/actions/workflows/docs.yml/badge.svg) [![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors-) -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 unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the bandlimited interpolant, which is useful for implementing staircase free sources, for example. +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 unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions and a known analytical form for the bandlimited interpolant, which is useful for implementing staircase-free sources, for example. -k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/k-wave) Toolbox, developed - -with the following aims: - -1. Re-engineering the code base to leverage object orientated programming -and differentiable functions for deep learning and coupled physics problems -2. Extending the algorithms to facilitate general boundary conditions on -arbitrary surfaces, and to increase performance for narrow-band simulations -3. Improving the development and release process to incorporate good -practice and advance long-term sustainability -4. Improving training, user engagement, and support. +k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/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 improve the development and release process to incorporate best practice, and to facilitate greater engagement of the user and contributor communities in its development. ## Releases -The current release is _XX.YY.ZZ (link to the Changelog/Release notes here)_. - -We aim to release a new version of the toolbox every May and November, with patches issued in-between as needed. If you want to use the latest features between releases, you can clone the [github repo](https://github.com/ucl-bug/k-wave-ii/tree/main) and use the `develop` branch. If you choose to do that, please keep in mind that those features might not be complete yet, and therefore we would appreciate your feedback and your patience. +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](https://github.com/ucl-bug/k-wave-ii/tree/main) and use the `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](#minimum-requirements)), until the latest one before the release was made. @@ -36,25 +23,25 @@ Every k-Wave-II release is tested with all releases of MATLAB after the minimum - k-Wave-II requires MATLAB 2022b or later. - No MATLAB toolboxes are required to use k-Wave-II. However, running the unit tests requires the signal processing toolbox for the reference `sinc` function. -- If importing the k-Wave-II namespace (using `import kwave.toolbox.*`) it is recommended that k-Wave-I is NOT on the MATLAB path to avoid naming conflicts. +- When importing the k-Wave-II namespace (`import kwave.toolbox.*`) it is recommended that k-Wave-I is NOT on the MATLAB path in order to avoid naming conflicts. ### Using k-Wave-II -For examples of how to use k-Wave-II, have a look at the [tutorials](helpfilesweb/Tutorials/SUMMARY.md) and the [toolbox classes documentation](helpfilesweb/Toolbox_Functions/SUMMARY.md). +For examples of how to use k-Wave-II, see the [tutorials](helpfilesweb/Tutorials/SUMMARY.md) and the [toolbox classes documentation](helpfilesweb/Toolbox_Functions/SUMMARY.md). ## Getting help -We are a very small team maintaining this toolbox, and we would like it to be community-driven and sustained as much as possible. +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](https://github.com/ucl-bug/k-wave-ii/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. And then, please consider contributing to the fix or improvement (see the section on [contributing](#contributing)). +If you would like to report a bug or request a new feature, first check the [existing issues](https://github.com/ucl-bug/k-wave-ii/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](#contributing)). -If you have a question or you need some help, please use the [discussions feature](https://github.com/ucl-bug/k-wave-ii/discussions) in the github repo. Hopefully someone from the community, either a maintainer, developer, or user will be able to assist you. +If you have a question or you need some help, please use the [discussions feature](https://github.com/ucl-bug/k-wave-ii/discussions) in the github repo. Hopefully someone from the community will be able to assist you. ## Contributing -The user community is very welcome 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](CONTRIBUTING.md). +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](CONTRIBUTING.md). Anyone who submits code that is accepted into the toolbox will automatically be added to the list of contributors below. -We also welcome further involvement by people wishing to review developers' code contributions and help the community of developers grow. Please contact the maintainers if you are interested in becoming a code reviewer. +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, building on foundational work by Bradley Treeby, Ben Cox, and Jiri Jaros. Its ongoing development is guided and maintained by [the UCL Biomedical Ultrasound Group](http://bug.medphys.ucl.ac.uk/). From 0f3caa80630961a47bf571c3f44945dffe661d2b Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 19:30:36 +0100 Subject: [PATCH 02/29] Update CONTRIBUTING.md I've changed this quite a bit to lower both the apparent and actual barriers to getting users started on contributing. I've slightly relaxed the requirements for very small contributions, while maintaining them for significant contributions. --- docs/CONTRIBUTING.md | 139 ++++++++++++++++++++++++++----------------- 1 file changed, 86 insertions(+), 53 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 66f64f46..a82b8e98 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,75 +1,121 @@ # Contributor guidelines +We welcome contributions from users with all levels of experience. + +Our aim with k-Wave-II is to keep the barriers to contributing as low as possible while maintaining a tidy and functioning codebase. If something in this guide feels like overkill for your contribution, please feel free to proceed in the simplest way that works and ask for help if needed; the maintainers are happy to guide you. For larger or more complex contributions, following the workflow described here will be important. + +If you would like to contribute but are new to it, these are some good ways to get started: + +- Improve documentation (clarifications, typos, missing explanations) +- Add or refine examples and tutorials +- Suggest small usability improvements +- Improve error messages or warnings +- Help answer or triage issues + +If you are unsure whether something is a suitable contribution, please open an issue or a draft pull request. We are happy to discuss ideas and help you get started. + +Before beginning work on a substantial contribution, please read these Contributor Guidelines and: + +* [developerIntroduction.md](developerIntroduction.md) +* [coding standard.md](codingStandard.md) + ## Development Workflow -The k\-Wave-II development workflow follows [git-flow](https://nvie.com/posts/a-successful-git-branching-model/), modernised for an open-source project to [use forks](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) instead of branches: +The k-Wave-II development workflow follows a git-flow style organisation (main/develop/feature branches), adapted for open-source development using forks. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) + +### Getting started (minimal workflow) + +For most contributions, the simplest workflow is: -- The `main` branch is used only for releases. Any code development branches off and eventually merges back into the `develop` branch, via feature branches. For more details on this workflow, see the [maintainer guidelines](maintainerDocs.md) -- Start by [creating a fork](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#creating-your-own-copy-of-a-project) of the GitHub k-Wave-II repo. Make sure you copy all branches, not only the default. Now you have your own copy of the whole repo on GitHub. - You can manage that fork as you please, but it is good practice to keep its `main`, `develop`, and feature branches in synch with the upstream k-Wave-II repo, and do your development on different branches. -- Clone the fork locally to work on your code changes +* [Fork the repository](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#creating-your-own-copy-of-a-project). Copy all branches if possible. Now you have your own copy of the whole repo on GitHub. +* Clone your fork to your local machine, so you can work locally on code changes: + +``` +git clone ``` -git clone https://github.com/YOUR-USER-NAME/k-wave-ii +* Create a new branch from `develop`, choosing a descriptive name, ideally starting with the number of the issue you are working on. + ``` -- Any code development you would like to contribute to k-Wave-II, has to relate to an already reported issue in the upstream repo. For existing issues under active development, an appropriate feature branch would already exist. Those are descriptively named, starting with the issue number, e.g., `62-implement-pml-class`. If an appropriate feature branch does not exist, [open an issue](../#getting-help) in the upstream repo to request one. You will then need to re-synch your fork and `git pull` to get that branch locally. -- Create a branch off the feature branch you want to contribute to, and switch to it, e.g. +git checkout develop +git switch -c ``` -git checkout 62-implement-pml-class -git switch -c 75-implement-pml-class-getters +* Make the changes and open a pull request to the upstream repository. + +### Issues and feature branches + +- For anything beyond a trivial fix, please link your work to an existing issue. If there is no suitable issue, please [open an issue](../#getting-help) in the upstream repo. +- For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue: ``` -Note that, in this case, your development refers to a different issue (`75` in this fictional example), that should ideally be a [sub-issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues) of the larger feature issue (`62` in this example). -If you want to work on the parent issue directly, use its number instead, together with something that identifies you in the name of the branch, e.g. +git branch -r ``` -git switch -c 62-implement-pml-class-YOUR_USER_NAME +- Where a relevant feature branch exists, create a branch off the feature branch you want to contribute to, and switch to it, e.g. ``` +git checkout 62-implement-a-new-feature +git switch -c 75-implement-a-new-feature-my-part +``` +or to work on a parent issue directly, please use a branch name that identifies you: +e.g. +``` +git switch -c 62-implement-a-new-feature- +``` + +### Development good practice -- [Set up a development environment](#setting-up-a-development-environment). This is not needed for the matlab code to run, but for the various tools you will need for development. -- **Now that you are ready to code, please read the [developers intro](developerIntroduction.md) and [coding standard](codingStandard.md)!** -- Commit to that branch locally and regularly push your work to the same named branch on the fork. -- Label commit messages with the issue number, e.g., `git commit -m "#62: Basic class structure"` -- If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR) from your branch in your fork, to the feature branch in the upstream repo. Likewise, when you think the branch is ready for merging, open a (normal) PR, or convert your draft one to a normal PR, and request a code review. +- Commit to your branch locally and regularly push your work to the same named branch on the fork. +- Label commit messages with the issue number, e.g., +``` +git commit -m "#62: Basic class structure"` +``` +- If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). +- When your branch is ready for merging, open a (normal) PR, or convert your draft one to one, and request a code review. +- Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others. -For experienced git users, `git rebase` should be avoided if multiple people might be contributing to a branch (use `git merge` instead). +### Setting up a Development Environment -## Setting up a Development Environment +For small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. For more substantial development work, we recommend the following setup: -**1. Create and activate an environment** -Use an environment manager to create and activate a python environment. +#### 1. Create and activate an environment -For example, with [conda](https://docs.conda.io/projects/conda/en/latest/index.html): +Use an environment manager to create and activate an environment. For example, with [conda](https://docs.conda.io/projects/conda/en/latest/index.html): ```bash conda create -n kwave conda activate kwave ``` -**2. Install dependencies** -Install packages defined in `requirements.txt`: +#### 2. Install dependencies +Install packages defined in `requirements.txt`, which contain tools used for documentation and development: ``` pip install -r requirements.txt ``` -This installs [`mkdocs`](https://www.mkdocs.org/) used to build the documentation (see [Writing and Building the Documentation](developerIntroduction.md#writing-and-building-the-documentation)). - -If you want to skip the pre-commit checks when you commit a change, you can use `git commit --no-verify`. However, the same tests will be run automatically on the CI when you push your changes to GitHub, and they will fail at that point if they identify any required fixes. We strongly suggest you fix any issues identified by pre-commit locally, before committing and pushing to the repository. - -**3. Install pre-commit** -We use [pre-commit](https://pre-commit.com/) which runs automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. - -Install and enable it with: - -```bash -pre-commit install +k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. If you want to skip the pre-commit checks when you commit a change, you can use ``` +git commit --no-verify +``` +However, the same tests will be run automatically during Continuous Integration (CI) when you push your changes to GitHub, and they will fail if any fixes are required. For this reason, we recommend fixing any issues identified by pre-commit locally before committing and pushing to the repository. -To run pre-commit manually: +To run pre-commit manually on the files that have changed use: ```bash pre-commit run ``` +or to run it on all files, use +``` +pre-commit run -a +``` +### Conditions for merging a PR + +Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are -By default, the pre-commit checks will be run only on the files that changed. If you want to run it on all files, use `pre-commit run -a` instead. +- For new features (functions or classes), please add appropriate tests. See the [developer docs](../developerIntroduction#testing-framework) for more details. +- All tests should pass. Running tests locally is encouraged but not required as CI will run them automatically when you open a pull request. +- [Update the documentation](../developerIntroduction#writing-and-building-the-documentation) and make sure it builds and looks right. +- Add examples and/or tutorials for substantial new functionality. +- One approving code review from a maintainer is required. + +The code review step is crucial in order to guarantee the quality of code contributions from the community. It is an iterative process, and you will have to address the reviewer's comments and any concerns. Please remember that these comments are intended to improve the software, and should not be taken as a judgement on coding ability. ## AI and LLM Use @@ -77,22 +123,9 @@ AI tools can be valuable for learning, exploring ideas, and accelerating work. W * Understand what you submit. Be able to explain and defend any contribution you make. If you cannot, it is not ready to submit. * Stay in the driver's seat. Use AI to support your learning and work, not to replace the effort and critical thinking that make you a better developer. -* Engage meaningfully. Low-effort, AI-generated submissions (issues, PRs, or proposals) without genuine personal engagement are not acceptable. - -Maintainers may ask contributors to explain their work. This is part of our commitment to learning and quality—not a test of whether you used AI, but whether you understood and own what you contributed. - -## Conditions for merging a PR - -Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. -The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are - -- If adding a new function or class, add appropriate tests. See the [developer docs](../developerIntroduction#testing-framework) for more details. -- All tests, existing or new, should pass. You should strive to run the tests locally before you open the PR, in order to catch errors early, but the Github Actions automation on the k-Wave-II repo will run them automatically as well when you open a PR. -- [Update the documentation](../developerIntroduction#writing-and-building-the-documentation) and make sure it builds and looks right. -- Add examples and/or tutorials if you added more substantial functionality. -- One approving code review by one of the maintainers. +* Engage meaningfully. Low-effort, AI-generated submissions (issues, PRs, or proposals) without genuine personal engagement will not be accepted. -The code review step is a crucial one, to guarantee the quality of code contributions from the community. It is an iterative process, and you will have to address the reviewer's comments and any concerns. Keep in mind that those comments are given in good faith and not as judgement on anyone's coding ability, and are meant to support our community of developers in creating the best software we can, for all of us to use. Seasoned developers would testify to how much they have learned and improved in their work by receiving reviews on their codes. +Maintainers may ask contributors to explain their work. This is part of our commitment to learning and quality — it is not a test of whether you used AI but whether you understand what you contributed. ## Legal and Licensing From afb8cf6cd88104f5bd41f7bb939d3d013f170500 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 19:38:27 +0100 Subject: [PATCH 03/29] Update README.md minor URL update --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 31dadb23..5fb98e50 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bu ## 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](https://github.com/ucl-bug/k-wave-ii/tree/main) and use the `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. +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](https://github.com/ucl-bug/k-wave-ii/tree/develop) and use the `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](#minimum-requirements)), until the latest one before the release was made. From 97a801aeb29ab42226e7e95508921787969c4ed5 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 19:45:26 +0100 Subject: [PATCH 04/29] Update CONTRIBUTING.md Tiny change to a title --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a82b8e98..29f08feb 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -23,7 +23,7 @@ Before beginning work on a substantial contribution, please read these Contribut The k-Wave-II development workflow follows a git-flow style organisation (main/develop/feature branches), adapted for open-source development using forks. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) -### Getting started (minimal workflow) +### Getting started as a contributor For most contributions, the simplest workflow is: From a715961be9ececd212233f0ac2371c6cb78e0958 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 21:24:16 +0100 Subject: [PATCH 05/29] Update README.md Added instructions on how to install matlab and create the documentation. --- docs/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/README.md b/docs/README.md index 5fb98e50..7b4807a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,20 @@ Every k-Wave-II release is tested with all releases of MATLAB after the minimum ## Getting started +### Installation + +- From the [k-Wave-II GitHub page](https://github.com/ucl-bug/k-wave-ii), find the green Code button and either [clone the repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) 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()` 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)`. +``` +>> import kwave.toolbox.* +``` + ### Minimum requirements - k-Wave-II requires MATLAB 2022b or later. From e601ac1adb3ca26b344c0135d2205d3221073d46 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 21:32:58 +0100 Subject: [PATCH 06/29] Update README.md Minor re-wording and rearrangements. --- docs/README.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7b4807a5..d6db0525 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,12 +11,6 @@ k\-Wave-II is an open\-source MATLAB toolbox used to solve partial differential k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/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 improve the development and release process to incorporate best practice, and to facilitate greater engagement of the user and contributor communities in its development. -## 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](https://github.com/ucl-bug/k-wave-ii/tree/develop) and use the `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](#minimum-requirements)), until the latest one before the release was made. - ## Getting started ### Installation @@ -28,20 +22,23 @@ Every k-Wave-II release is tested with all releases of MATLAB after the minimum ``` >> 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)`. +- 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 2022b or later. - No MATLAB toolboxes are required to use k-Wave-II. However, running the unit tests requires the signal processing toolbox for the reference `sinc` function. -- When importing the k-Wave-II namespace (`import kwave.toolbox.*`) it is recommended that k-Wave-I is NOT on the MATLAB path in order to avoid naming conflicts. -### Using k-Wave-II +## Releases -For examples of how to use k-Wave-II, see the [tutorials](helpfilesweb/Tutorials/SUMMARY.md) and the [toolbox classes documentation](helpfilesweb/Toolbox_Functions/SUMMARY.md). +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](https://github.com/ucl-bug/k-wave-ii/tree/develop) and use the `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](#minimum-requirements)), until the latest one before the release was made. ## Getting help @@ -58,7 +55,7 @@ Users are encouraged to contribute to the code and open pull requests for new fe 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, building on foundational work by Bradley Treeby, Ben Cox, and Jiri Jaros. Its ongoing development is guided and maintained by [the UCL Biomedical Ultrasound Group](http://bug.medphys.ucl.ac.uk/). +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](http://bug.medphys.ucl.ac.uk/). ## Contributors From 99dba5189731bca6e93c9657132159cc1fff47bd Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 21:43:25 +0100 Subject: [PATCH 07/29] Update CONTRIBUTING.md Link update. --- docs/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 29f08feb..608a502b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -109,9 +109,9 @@ pre-commit run -a Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are -- For new features (functions or classes), please add appropriate tests. See the [developer docs](../developerIntroduction#testing-framework) for more details. +- For new features (functions or classes), please add appropriate tests. See the [developer docs](developerIntroduction.md) for more details. - All tests should pass. Running tests locally is encouraged but not required as CI will run them automatically when you open a pull request. -- [Update the documentation](../developerIntroduction#writing-and-building-the-documentation) and make sure it builds and looks right. +- [Update the documentation](developerIntroduction.md#writing-and-building-the-documentation) and make sure it builds and looks right. - Add examples and/or tutorials for substantial new functionality. - One approving code review from a maintainer is required. From 17ef1b401fc1e5fb0936cf4babf07de9447c73e2 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 21:45:49 +0100 Subject: [PATCH 08/29] Update codingStandard.md Minor typo --- docs/codingStandard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/codingStandard.md b/docs/codingStandard.md index 7d144e99..374c104a 100644 --- a/docs/codingStandard.md +++ b/docs/codingStandard.md @@ -1,6 +1,6 @@ # Coding Standard -MATLAB coding standard used for k\-Wave II. +MATLAB coding standard used for k-Wave-II. ## Naming From bc5a2a23c11f0fb843539b9e72c7e09b9ed1ed87 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 21:46:49 +0100 Subject: [PATCH 09/29] Update CONTRIBUTING.md typo --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 608a502b..4673a297 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -17,7 +17,7 @@ If you are unsure whether something is a suitable contribution, please open an i Before beginning work on a substantial contribution, please read these Contributor Guidelines and: * [developerIntroduction.md](developerIntroduction.md) -* [coding standard.md](codingStandard.md) +* [codingStandard.md](codingStandard.md) ## Development Workflow From 40a2c77da62d4e49efefa92dc51cd1a2d3605b76 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 22:02:37 +0100 Subject: [PATCH 10/29] Update developerIntroduction.md Few minor changes. --- docs/developerIntroduction.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/developerIntroduction.md b/docs/developerIntroduction.md index b7529134..b7a6a5c7 100644 --- a/docs/developerIntroduction.md +++ b/docs/developerIntroduction.md @@ -1,20 +1,20 @@ # Developer Introduction -Introduction to k\-Wave II for developers. +Introduction to k-Wave-II for developers. ## Overview -k\-Wave II is an open\-source MATLAB toolbox used to solve differential equations, with a particular focus on wave problems in acoustics. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the band\-limited interpolant, which is useful for implementing stair\-case free sources, for example. +k-Wave-II is an open\-source MATLAB toolbox used to solve differential equations, with a particular focus on wave problems in acoustics. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the band\-limited interpolant, which is useful for implementing stair\-case free sources, for example. -The main components of the toolbox are written using an object\-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be re\-used multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. +The main components of the toolbox are written using an object-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be re-used multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. The software is written with the following four guiding principles, in decreasing order of importance: -1. **The code is accurate.** The solvers should avoid narrow scope assumptions which are not always applicable. The code should also implement appropriate input validation and error handling, and be covered by appropriate tests (see [Testing Framework](#testing-framework) (testingFramework.md) for further details). -2. **The code is easy to use.** Careful thought should be given to the class interfaces and default values, and the user\-facing API should be as stable as possible over time. All code should be well documented, and the documentation should include user examples and tutorials. Code should also provide sufficient feedback and warnings to guide users. -3. **The code is sustainable.** The development, testing, and release workflows should be sufficiently automated that it is straightforward to implement new features and bug fixes. All code should follow the [Coding Standard](codingStandard.md). +1. **The code is accurate.** The solvers should avoid narrow scope assumptions which are not always applicable. The code should also implement appropriate input validation and error handling, and be covered by appropriate tests (see [Testing Framework](#testing-framework) for further details). +2. **The code is easy to use.** Careful thought should be given to the class interfaces and default values, and the user-facing API should be as stable as possible over time. All code should be well-documented, and the documentation should include user examples and tutorials. Code should also provide sufficient feedback and warnings to guide users. +3. **The code is sustainable.** The development, testing, and release workflows should be sufficiently automated that it is straightforward to implement new features and bug fixes. All code should follow the [Coding Standard](codingStandard.md). 4. **The code is fast.** Code should be profiled regularly, and where possible, refactored to improve computational efficiency. ## Repository Structure @@ -24,15 +24,15 @@ The code is grouped into [package folders](https://uk.mathworks.com/help/matlab/ ``` ├── .github │ ├── ISSUE_TEMPLATE (GitHub issue templates) - │ ├── PULL_REQUEST_TEMPLATE (GitHub pull request template) - │ └── workflows (GitHub actions) + │ ├── pull_request_template (GitHub pull request template) + │ └── workflows (GitHub actions) ├── +kwave │ ├── +devtools (Developer tools) | ├── +docfiles (Documentation files) │ │ └── +general (Additional Documentation Pages) │ ├── +legacy (Copy of k-Wave I) │ ├── +tests (Tests) - │ │ ├── +legacy (Regression tests against k-Wave I) + │ │ ├── +legacy (Regression tests against k-Wave-I) │ │ ├── +linting (Linting tests) │ │ └── +unit (Unit tests) │ ├── +toolbox (Main classes and functions) @@ -43,14 +43,13 @@ The code is grouped into [package folders](https://uk.mathworks.com/help/matlab/ └── helpfilesweb (Created and populated at md documentation generation time) ``` -## Writing And Building The Documentation +## Writing and Building the Documentation -Part of the success of k\-Wave can be attributed to the good documentation, both of the individual functions and classes, and the examples. All code should be documented as outlined in the [Coding Standard](codingStandard.md). It can often be easiest to start with the [documentation template](helpfilesweb/classDocsExample.md). +Part of the success of k-Wave can be attributed to the good documentation, both of the individual functions and classes, and the examples. All code should be documented as outlined in the [Coding Standard](codingStandard.md). It can often be easiest to start with the documentation template `docs/helpfilesweb/Utility_Functions/classDocsExample.md`. When adding a new class or function, examples should be added. If the code usage is relatively straightforward, examples can be included directly in the help documentation for that class or function. For more complex classes (e.g., the solver classes), longer tutorials or examples should be provided. -1. **Tutorials:** These are worked examples stored as `.m` files in the `kwave.tutorials` name space. For tutorials, each block of code should be surrounded by a discussion guiding the user through the example. The discussion should be written using [publishing markup](https://uk.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html)[*](#note). Similar to k\-Wave I, concepts introduced in other tutorials do not need to be re\-introduced. Try and focus on a relatively small number of new concepts in each tutorial. The tutorial code should generally run fast on basic hardware (< 1 min). -2. **Examples:** These are illustrative examples stored as `.m` files in the `kwave.examples` name space. Examples have a wider scope than tutorials, and may demonstrate a real\-world simulation using realistic grid sizes for example (so do not necessarily need to run fast). Examples should contain a comprehensive description of what the example does in the description of the file, but does not need to have long step\-by\-step. +**Tutorials:** These are worked examples stored as `.m` files in the `kwave.tutorials` name space. For tutorials, each block of code should be surrounded by a discussion guiding the user through the example. The discussion should be written using [publishing markup](https://uk.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html)[*](#note). Similar to k-Wave-I, concepts introduced in other tutorials do not need to be re-introduced. Focus on a small number of new concepts in each tutorial. The tutorial code should generally run fast on basic hardware (< 1 min). Please remember to also add the new class, function or tutorial/example file in the appropriate section header file (`Toolbox_Functions.m`, `Tutorials.m` or `Utility_Functions.m`). @@ -61,7 +60,7 @@ According to the matlab documentation, This means that all the text within a section (starting with `%%`) has to come in one continuous area of `%`s in order for it to render. If executable code is interleaved with it, the rest of the text is not rendered. A workaround is to include the code we want to run in the comments area, and duplicate it after each block in order for it to run and produce the plots. Please have a look at the existing tutorials for examples. -### Building The Documentation +### Building the Documentation _MATLAB R2023b or later is required to build the documentation._ @@ -76,20 +75,19 @@ mkdocs serve --livereload ``` and viewed in a browser in `http://127.0.0.1:8000/` for debugging purposes (watch the output of the above command for this address). -## Logging And Errors +## Logging and Errors Logging messages help users understand code settings and status, and help developers debug code. In k\-Wave\-II, all logging messages (including warnings and errors) should be printed using the `kwave.toolbox.Logger` class. This provides a consistent interface, allow adjusting the verbosity of the output messages, and allows piping the logging messages to an external file. -## Toolboxes And External Code +## Toolboxes and External Code The core functionality of k\-Wave\-II should not depend on any MATLAB toolboxes. This is to minimise the requirements for non\-academic users who must purchase a MATLAB license to use k\-Wave. Tests can (and do) depend on additional toolboxes, as this dependency is fulfilled by the GitHub runners (both private and public). - If considering using other external code or libraries (e.g., from the file exchange), this should be flagged first on the issue or pull request. This way, a discussion can be had about the cost of introducing the dependency, and any potential licensing issues. ## Testing Framework -k\-Wave uses the [class\-based unit testing framework](https://uk.mathworks.com/help/matlab/class-based-unit-tests.html). There are several test levels (defined in `kwave.tests.TestType`), each of which lives in its own namespace: +k-Wave-II uses the [class\-based unit testing framework](https://uk.mathworks.com/help/matlab/class-based-unit-tests.html). There are several test levels (defined in `kwave.tests.TestType`), each of which lives in its own namespace: - **`+unit`:** Unit tests validate individual components of a function or class in isolation. - **`+linting`:** Linting checks assess code for stylistic and syntactical correctness. @@ -104,7 +102,6 @@ Each top level class or function should have at least one corresponding unit tes The filenames for all tests should start with `Test`. Unit tests should be named `TestClassName` or `TestFunctionName`. Other tests should be given sensible descriptive names. - The linting tests check for code complexity using [cylomatic complexity](https://uk.mathworks.com/help/matlab/matlab_prog/measure-code-complexity-using-cyclomatic-complexity.html), which is a measure of the decision structure complexity of the code. The complexity of all files changed in a pull request is automatically added to pull requests as part of the code checks action. While a particular number isn't enforced, both developers and reviewers should consider whether a re\-factoring is appropriate if the cylomatic complexity is above 10. To run the tests locally, call: From 5d449cf3ab1c880ce940fb5546e22940a5db9c26 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Thu, 28 May 2026 22:19:42 +0100 Subject: [PATCH 11/29] Update maintainerDocs.md Small changes, as we will allow PRs into develop for minor fixes. Not everything tiny change must rigidly go through a feature branch. --- docs/maintainerDocs.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/maintainerDocs.md b/docs/maintainerDocs.md index 820a2652..ed027dcb 100644 --- a/docs/maintainerDocs.md +++ b/docs/maintainerDocs.md @@ -1,8 +1,6 @@ # Maintainer guidelines -The [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) workflow is summarised in the following graph, taken from Vincent Driessen's blog post. The only difference between this model and the one we are using in k-Wave-II, is that contributors do not commit changes directly into the feature branches, but they open Pull Requests (PRs) into them from their own forks of the repo. - -Toolbox releases distributed via Matlab are built from the `main` branch (`master` in the graph), and this is what most users are expected to use. If someone wants access to the latest features, they will need to check out and use the `develop` branch, therefore this branch should be in a usable state, even if it does not have the full, release-ready functionality. All other branches are for development purposes. +The [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) workflow is summarised in the following graph, taken from Vincent Driessen's blog post. We largely follow this model, in which `main` ('master' on this figure) is reserved for releases and the default branch is `develop`. Toolbox releases distributed via Matlab are built from the `main` branch, and this is what most users are expected to use. If someone wants access to the latest features, they will need to check out and use the `develop` branch, therefore this branch should be in a usable state, even if it does not have the full, release-ready functionality. All other branches are for development purposes. As noted in the [contributor guidelines](CONTRIBUTING.md), one difference between this model and the one we are using in k-Wave-II, is that contributors do not commit changes directly into `develop` or the feature branches, but they open Pull Requests (PRs) into them from their own forks of the repo. ![alt text](git-model.png "The git-flow workflow by Vincent Driessen") @@ -13,12 +11,11 @@ Maintainers should review issues regularly and place them appropriately in the r Feature branches should branch off `develop` and bugfix branches off whichever is the most stable branch the bug is found in. - ## Development All the branches of the repo are protected, meaning that contributors (including maintainers) cannot commit changes directly to them, they can only open PRs. Additionally, only maintainers can create branches in the main repo. -Therefore all development is done in contributors' forks, on branches that they have branched off feature branches in their fork. When they are ready to merge their changes, they open a PR into the main repo's corresponding feature branch, and request a code review from the maintainers or code reviewers. +Therefore all development is done in contributors' forks, on branches that they have branched off feature branches or `develop` in their fork. When they are ready to merge their changes, they open a PR into the main repo's corresponding feature branch or `develop`, and request a code review from the maintainers or code reviewers. When reviewing contributors' PRs, follow the checklist in the PR template, and check items off as you progress. You should check that @@ -26,18 +23,18 @@ When reviewing contributors' PRs, follow the checklist in the PR template, and c - All tests, existing or new, pass. - Documentation is updated and builds correctly. -You should also review the code changes themselves. Please be constructive and respectful in your comments and support contributors to improve their code. Once they address your concerns, resolve the conversation and when you are satisfied with the code changes overall, approve them. +You should also review the code changes themselves. Please be constructive and kind in your comments and support contributors to improve their code. When they have addressed your concerns resolve the conversation, and when you are satisfied with the code changes overall approve them. *If you think you need to take over development on someone else's PR, always ask them first.* -Only maintainers can merge PRs into the feature branch. Merges need at least one approving review and all the automated tests to pass. You should also make sure that you have ticked all the checkboxes on the template. Once all this is done you can merge, using [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits). Individual commits will still be accessible on GitHub in the (now closed) PR. +Only maintainers can merge PRs into a feature branch or `develop`. Merges need at least one approving review and all the automated tests to pass. You should also make sure that you have ticked all the checkboxes on the template. Once all this is done you can merge, using [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits). Individual commits will still be accessible on GitHub in the (now closed) PR. ## Branch management -Once a feature reaches a certain maturity, maintainers can choose to merge the related branch into `develop`, to let adventurous users try it out. You will probably have to resolve some conflicts at that point. +Once a feature reaches a certain maturity, maintainers can choose to merge the related branch into `develop`, to let adventurous users try it out. They will probably have to resolve some conflicts at that point. Then development can continue in the feature branch, or if it is complete, the maintainers can lock the branch and prevent further commits to it. Feature branches should not be deleted (and cannot be deleted once locked). From e3825977417237c0949c74888fd72ae6ce8fc042 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 29 May 2026 08:58:25 +0100 Subject: [PATCH 12/29] Update README.md Updated minimum requirements date --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index d6db0525..7c8aa735 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,7 +31,7 @@ k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bu ### Minimum requirements -- k-Wave-II requires MATLAB 2022b or later. +- k-Wave-II requires MATLAB R2023b or later. - No MATLAB toolboxes are required to use k-Wave-II. However, running the unit tests requires the signal processing toolbox for the reference `sinc` function. ## Releases From ba9b6b08fb5c44a3c5693a8520abd6387840f989 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 09:21:42 +0100 Subject: [PATCH 13/29] Update docs/CONTRIBUTING.md Co-authored-by: Stella Prins <30465823+stellaprins@users.noreply.github.com> --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4673a297..5773a9d0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -21,7 +21,7 @@ Before beginning work on a substantial contribution, please read these Contribut ## Development Workflow -The k-Wave-II development workflow follows a git-flow style organisation (main/develop/feature branches), adapted for open-source development using forks. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) +The k-Wave-II development workflow follows a git-flow style organisation (`main`/`develop`/`feature` branches), adapted for open-source development using forks. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) ### Getting started as a contributor From 9ac3eee8d4badeae18bf45b93531c9e4328cdf76 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 09:34:25 +0100 Subject: [PATCH 14/29] Update docs/README.md Co-authored-by: Stella Prins <30465823+stellaprins@users.noreply.github.com> --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 7c8aa735..3fee0a1b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # k-Wave-II: A MATLAB toolbox for the simulation of acoustic wave fields !!! WARNING "Under Construction" - k‑Wave-ii is currently under active development. Documentation, APIs, and features may change without notice. + k‑Wave-II is currently under active development. Documentation, APIs, and features may change without notice. [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE.md) [![codecov](https://codecov.io/gh/ucl-bug/k-wave-ii/graph/badge.svg?token=A8UMTDRF6T)](https://codecov.io/gh/ucl-bug/k-wave-ii) ![unit tests](https://github.com/ucl-bug/k-wave-ii/actions/workflows/tests.yml/badge.svg) ![code quality](https://github.com/ucl-bug/k-wave-ii/actions/workflows/code_quality.yml/badge.svg) ![build docs](https://github.com/ucl-bug/k-wave-ii/actions/workflows/docs.yml/badge.svg) [![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors-) From aec33c910d427ed0b984dd2eb38cd854c786f3b1 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 09:35:02 +0100 Subject: [PATCH 15/29] Update CONTRIBUTING.md Minor changes following Stella's comments. --- docs/CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5773a9d0..9ccbfe21 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -43,7 +43,7 @@ git switch -c ### Issues and feature branches -- For anything beyond a trivial fix, please link your work to an existing issue. If there is no suitable issue, please [open an issue](../#getting-help) in the upstream repo. +- For anything beyond a trivial fix, please link your work to an existing issue. If there is no suitable issue, please open an issue in the upstream repo. - For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue: ``` git branch -r @@ -96,7 +96,7 @@ git commit --no-verify ``` However, the same tests will be run automatically during Continuous Integration (CI) when you push your changes to GitHub, and they will fail if any fixes are required. For this reason, we recommend fixing any issues identified by pre-commit locally before committing and pushing to the repository. -To run pre-commit manually on the files that have changed use: +To run pre-commit locally before committing files, it will first have to be installed (see above). To run pre-commit manually on the files that have changed use: ```bash pre-commit run @@ -105,6 +105,7 @@ or to run it on all files, use ``` pre-commit run -a ``` + ### Conditions for merging a PR Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are From 48d6ce9c4650dc2e2e05f8a67782a057ef70d864 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 09:36:07 +0100 Subject: [PATCH 16/29] Update docs/developerIntroduction.md Co-authored-by: Stella Prins <30465823+stellaprins@users.noreply.github.com> --- docs/developerIntroduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developerIntroduction.md b/docs/developerIntroduction.md index b7a6a5c7..561a3aba 100644 --- a/docs/developerIntroduction.md +++ b/docs/developerIntroduction.md @@ -7,7 +7,7 @@ Introduction to k-Wave-II for developers. k-Wave-II is an open\-source MATLAB toolbox used to solve differential equations, with a particular focus on wave problems in acoustics. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the band\-limited interpolant, which is useful for implementing stair\-case free sources, for example. -The main components of the toolbox are written using an object-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be re-used multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. +The main components of the toolbox are written using an object-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be reused multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. The software is written with the following four guiding principles, in decreasing order of importance: From 4d99289be5853b5ffb04d838e0ecf5268c791ade Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 10:03:36 +0100 Subject: [PATCH 17/29] Update CONTRIBUTING.md Added a bit more description on conda. --- docs/CONTRIBUTING.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9ccbfe21..48c8d4e0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -76,29 +76,28 @@ For small contributions (e.g., documentation updates, minor fixes), you may not #### 1. Create and activate an environment -Use an environment manager to create and activate an environment. For example, with [conda](https://docs.conda.io/projects/conda/en/latest/index.html): +Use an environment manager to create and activate an environment. This provides an isoloated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. To create an environment from the terminal use: -```bash +``` conda create -n kwave conda activate kwave ``` +Environments are not tied to any particular folder or repository. The environment (here `kwave`) will remain active until you deactivate it (`conda deactivate`) or close the terminal. + #### 2. Install dependencies -Install packages defined in `requirements.txt`, which contain tools used for documentation and development: +Once your clean environment is activated, install packages defined in `requirements.txt`, which contain tools used for documentation and development: ``` pip install -r requirements.txt ``` +This will only need to be done the first time. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. -k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. If you want to skip the pre-commit checks when you commit a change, you can use -``` -git commit --no-verify -``` -However, the same tests will be run automatically during Continuous Integration (CI) when you push your changes to GitHub, and they will fail if any fixes are required. For this reason, we recommend fixing any issues identified by pre-commit locally before committing and pushing to the repository. +#### 3. Pre-commit -To run pre-commit locally before committing files, it will first have to be installed (see above). To run pre-commit manually on the files that have changed use: +k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. (It is one of the packages installed above.) It is a good idea to run pre-commit locally before committing files. To run pre-commit manually on the files that have changed use: -```bash +``` pre-commit run ``` or to run it on all files, use @@ -106,6 +105,12 @@ or to run it on all files, use pre-commit run -a ``` +If you want to skip the pre-commit checks when you commit a change, you can use +``` +git commit --no-verify +``` +However, the same tests will be run automatically during Continuous Integration (CI) when you push your changes to GitHub, and they will fail if any fixes are required. For this reason, we recommend fixing any issues identified by pre-commit locally before committing and pushing to the repository. + ### Conditions for merging a PR Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are From be44d337e94009bd49bb8c477b2dfb2359a37558 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 10:19:12 +0100 Subject: [PATCH 18/29] Update CONTRIBUTING.md minor changes --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 48c8d4e0..0ee2f133 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -91,7 +91,7 @@ Once your clean environment is activated, install packages defined in `requireme ``` pip install -r requirements.txt ``` -This will only need to be done the first time. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. +Installing the dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. #### 3. Pre-commit From d0e0f1d9254a319aa68d936a85fa529236d0d20f Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 10:31:17 +0100 Subject: [PATCH 19/29] Update CONTRIBUTING.md Small changes to pre-commit description. --- docs/CONTRIBUTING.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 0ee2f133..2ca20635 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -95,7 +95,9 @@ Installing the dependencies will only need to be done once. For subsequent sessi #### 3. Pre-commit -k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. (It is one of the packages installed above.) It is a good idea to run pre-commit locally before committing files. To run pre-commit manually on the files that have changed use: +k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. + +To run pre-commit manually on the files that have changed use: ``` pre-commit run @@ -104,12 +106,7 @@ or to run it on all files, use ``` pre-commit run -a ``` - -If you want to skip the pre-commit checks when you commit a change, you can use -``` -git commit --no-verify -``` -However, the same tests will be run automatically during Continuous Integration (CI) when you push your changes to GitHub, and they will fail if any fixes are required. For this reason, we recommend fixing any issues identified by pre-commit locally before committing and pushing to the repository. +If you want to skip the pre-commit checks when you commit a change you can use `git commit --no-verify`, but this is not recommended as the same tests will be run automatically in CI when you push your changes to GitHub, and they will fail if any issues remain. ### Conditions for merging a PR From 76173637bef953ed6688e25f05ae5d09c9007de9 Mon Sep 17 00:00:00 2001 From: bencox Date: Tue, 2 Jun 2026 10:33:46 +0100 Subject: [PATCH 20/29] pre-commit changes --- docs/CONTRIBUTING.md | 4 ++-- docs/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2ca20635..40eafe36 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributor guidelines -We welcome contributions from users with all levels of experience. +We welcome contributions from users with all levels of experience. Our aim with k-Wave-II is to keep the barriers to contributing as low as possible while maintaining a tidy and functioning codebase. If something in this guide feels like overkill for your contribution, please feel free to proceed in the simplest way that works and ask for help if needed; the maintainers are happy to guide you. For larger or more complex contributions, following the workflow described here will be important. @@ -41,7 +41,7 @@ git switch -c ``` * Make the changes and open a pull request to the upstream repository. -### Issues and feature branches +### Issues and feature branches - For anything beyond a trivial fix, please link your work to an existing issue. If there is no suitable issue, please open an issue in the upstream repo. - For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue: diff --git a/docs/README.md b/docs/README.md index 3fee0a1b..60949c9c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,12 +21,12 @@ k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bu - 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`. +- For examples of how to use k-Wave-II, and templates to build upon, see the tutorials in `kwave/tutorials`. ### Minimum requirements From 6c63ade554fa4cf6d560e31250b008bc895492df Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Tue, 2 Jun 2026 12:04:52 +0100 Subject: [PATCH 21/29] Remove no-commit-to-branch hook from pre-commit config (#249) (#251) * Remove no-commit-to-branch hook from pre-commit config * Remove push trigger from pre-commit workflow Co-authored-by: Stella Prins <30465823+stellaprins@users.noreply.github.com> --- .github/workflows/pre-commit.yml | 4 ---- .pre-commit-config.yaml | 4 ---- 2 files changed, 8 deletions(-) diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 23f9ba0d..c3f1e032 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -2,10 +2,6 @@ name: pre-commit on: pull_request: - push: - branches: - - main - - develop jobs: pre-commit: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 12193f43..ccc45323 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -20,10 +20,6 @@ repos: - id: mixed-line-ending args: - --fix=lf - - id: no-commit-to-branch - args: - - --branch=main - - --branch=develop - id: trailing-whitespace - repo: https://github.com/codespell-project/codespell rev: v2.4.1 From 27be9affe77e328317819aa5e8bb5e306f5878bc Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Wed, 3 Jun 2026 12:10:20 +0100 Subject: [PATCH 22/29] Update docs/CONTRIBUTING.md Co-authored-by: Stella Prins <30465823+stellaprins@users.noreply.github.com> --- docs/CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 40eafe36..af9491e7 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -97,7 +97,8 @@ Installing the dependencies will only need to be done once. For subsequent sessi k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. -To run pre-commit manually on the files that have changed use: +To enable `pre-commit`, first install it: + ``` pre-commit run From 5c187237f51d4d8ceab298780fbd13393f4e2095 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 5 Jun 2026 14:18:30 +0100 Subject: [PATCH 23/29] Updated README.md again, minor tweaks. --- docs/README.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 60949c9c..ac14666f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,9 +7,14 @@ [![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors-) -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 unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions and a known analytical form for the bandlimited interpolant, which is useful for implementing staircase-free sources, for example. +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](https://github.com/ucl-bug/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 improve the development and release process to incorporate best practice, and to facilitate greater engagement of the user and contributor communities in its development. +k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/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 @@ -32,11 +37,11 @@ k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bu ### Minimum requirements - k-Wave-II requires MATLAB R2023b or later. -- No MATLAB toolboxes are required to use k-Wave-II. However, running the unit tests requires the signal processing toolbox for the reference `sinc` function. +- 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](https://github.com/ucl-bug/k-wave-ii/tree/develop) and use the `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. +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](https://github.com/ucl-bug/k-wave-ii/tree/develop) 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](#minimum-requirements)), until the latest one before the release was made. From 351241e74ea5eb175d5477105024f3d72efd1802 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 5 Jun 2026 14:22:01 +0100 Subject: [PATCH 24/29] changed BUG website address to github as UCL website is broken at the moment. --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index ac14666f..272e4dfc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -60,7 +60,7 @@ Users are encouraged to contribute to the code and open pull requests for new fe 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](http://bug.medphys.ucl.ac.uk/). +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](https://github.com/ucl-bug). ## Contributors From 4362c97acfebbaf38b4f51a1d81ee1b33355a2cc Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 5 Jun 2026 14:39:12 +0100 Subject: [PATCH 25/29] Small updates to CONTRIBUTING.md --- docs/CONTRIBUTING.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index af9491e7..97188bbf 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,11 +6,10 @@ Our aim with k-Wave-II is to keep the barriers to contributing as low as possibl If you would like to contribute but are new to it, these are some good ways to get started: -- Improve documentation (clarifications, typos, missing explanations) - Add or refine examples and tutorials -- Suggest small usability improvements -- Improve error messages or warnings - Help answer or triage issues +- Improve documentation (clarifications, typos, missing explanations) +- Suggest small usability improvements If you are unsure whether something is a suitable contribution, please open an issue or a draft pull request. We are happy to discuss ideas and help you get started. @@ -21,7 +20,7 @@ Before beginning work on a substantial contribution, please read these Contribut ## Development Workflow -The k-Wave-II development workflow follows a git-flow style organisation (`main`/`develop`/`feature` branches), adapted for open-source development using forks. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) +The k-Wave-II development workflow follows a git-flow style organisation (`main`/`develop`/`feature` branches), adapted for open-source development using forks. The default branch is `develop`. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) ### Getting started as a contributor @@ -61,23 +60,22 @@ git switch -c 62-implement-a-new-feature- ### Development good practice -- Commit to your branch locally and regularly push your work to the same named branch on the fork. -- Label commit messages with the issue number, e.g., +- To make it easier for a reviewer to see what changes you have made to the code, commit to your branch locally, labelling commit messages with the issue number, e.g., ``` git commit -m "#62: Basic class structure"` ``` +- Regularly push your work to the same named branch on the fork. - If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). -- When your branch is ready for merging, open a (normal) PR, or convert your draft one to one, and request a code review. +- When your branch is ready for merging, open a (normal) PR, or convert your draft to one, and request a code review. - Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others. ### Setting up a Development Environment -For small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. For more substantial development work, we recommend the following setup: +For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. For more substantial development work, we recommend the following setup: #### 1. Create and activate an environment -Use an environment manager to create and activate an environment. This provides an isoloated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. To create an environment from the terminal use: - +Using an environment manager to create and activate an environment provides an isoloated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. To create an environment from the terminal use: ``` conda create -n kwave conda activate kwave @@ -87,23 +85,21 @@ Environments are not tied to any particular folder or repository. The environmen #### 2. Install dependencies -Once your clean environment is activated, install packages defined in `requirements.txt`, which contain tools used for documentation and development: +Once your clean environment is activated, install the packages listed in `requirements.txt`, which contain tools (dependencies) used for documentation and development. This can be done in one step: ``` pip install -r requirements.txt ``` -Installing the dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. +Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. #### 3. Pre-commit -k-Wave-II uses [pre-commit](https://pre-commit.com/) to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. - -To enable `pre-commit`, first install it: - +One of the dependencies installed above is [pre-commit](https://pre-commit.com/). k-Wave-II uses `pre-commit` to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. +To run pre-commit on just the files you changed use ``` pre-commit run ``` -or to run it on all files, use +or to run it on all files use ``` pre-commit run -a ``` From 58563f92bea6724c922b3ab156a8ef9c44955eaa Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 5 Jun 2026 14:50:01 +0100 Subject: [PATCH 26/29] small update to CONTRIBUTING.md --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 97188bbf..a92695ab 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -89,7 +89,7 @@ Once your clean environment is activated, install the packages listed in `requir ``` pip install -r requirements.txt ``` -Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. +(although on a mac you may have to run `conda install pip` first). Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. #### 3. Pre-commit From 655e33deda57568d7cbddfc512ce9bf03e4e7890 Mon Sep 17 00:00:00 2001 From: bencox Date: Fri, 5 Jun 2026 14:53:01 +0100 Subject: [PATCH 27/29] pre-commit whitespace changes --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a92695ab..390a106f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -95,7 +95,7 @@ pip install -r requirements.txt One of the dependencies installed above is [pre-commit](https://pre-commit.com/). k-Wave-II uses `pre-commit` to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. -To run pre-commit on just the files you changed use +To run pre-commit on just the files you changed use ``` pre-commit run ``` From 53f6b8c23be32a6d556478c181c90170a8095db5 Mon Sep 17 00:00:00 2001 From: Ben Cox Date: Fri, 5 Jun 2026 16:11:19 +0100 Subject: [PATCH 28/29] Quite significant re-ordering of CONTRIBUTING.md to make it easier for beginners --- docs/CONTRIBUTING.md | 94 ++++++++++++++++++++++---------------------- 1 file changed, 46 insertions(+), 48 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 390a106f..00605963 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -13,7 +13,7 @@ If you would like to contribute but are new to it, these are some good ways to g If you are unsure whether something is a suitable contribution, please open an issue or a draft pull request. We are happy to discuss ideas and help you get started. -Before beginning work on a substantial contribution, please read these Contributor Guidelines and: +Before beginning work on a contribution, please read all of this page (Contributor Guidelines), and for more substantial contributions please read: * [developerIntroduction.md](developerIntroduction.md) * [codingStandard.md](codingStandard.md) @@ -22,90 +22,88 @@ Before beginning work on a substantial contribution, please read these Contribut The k-Wave-II development workflow follows a git-flow style organisation (`main`/`develop`/`feature` branches), adapted for open-source development using forks. The default branch is `develop`. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md) -### Getting started as a contributor +For most contributions, following these eight steps will make contributing seamless: -For most contributions, the simplest workflow is: +### 1. Fork and clone the k-Wave-II repository * [Fork the repository](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#creating-your-own-copy-of-a-project). Copy all branches if possible. Now you have your own copy of the whole repo on GitHub. * Clone your fork to your local machine, so you can work locally on code changes: - ``` git clone ``` -* Create a new branch from `develop`, choosing a descriptive name, ideally starting with the number of the issue you are working on. +### 2. Set up a development environment + +For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. However, a development environment provides an isolated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. +* To create an environment from the terminal use: ``` -git checkout develop -git switch -c +conda create -n kwave +conda activate kwave +``` +Environments are not tied to any particular folder or repository. The environment (here `kwave`) will remain active until you deactivate it (`conda deactivate`) or close the terminal. + +### 3. Install dependencies + +* Once your clean environment is activated, install the packages listed in `requirements.txt`, which contain tools (dependencies) used for documentation and development. This can be done in one step: +``` +pip install -r requirements.txt ``` -* Make the changes and open a pull request to the upstream repository. +(On a mac you may have to run `conda install pip` first). Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. -### Issues and feature branches +### 4. Create a branch -- For anything beyond a trivial fix, please link your work to an existing issue. If there is no suitable issue, please open an issue in the upstream repo. -- For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue: +* If your fork is not newly created, make sure your fork is up to date with the upstream repository (`k-wave-ii`). +* Create a new branch from `develop`, choosing a descriptive name. For anything beyond a trivial fix, please use the number of the issue you are working on at the start of the branch name. If there is no suitable issue, please open an issue in the upstream repo. +``` +git checkout develop +git switch -c +``` +For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue: ``` git branch -r ``` -- Where a relevant feature branch exists, create a branch off the feature branch you want to contribute to, and switch to it, e.g. +Where a relevant feature branch exists, create a branch off the feature branch you want to contribute to, and switch to it, e.g. ``` git checkout 62-implement-a-new-feature git switch -c 75-implement-a-new-feature-my-part ``` -or to work on a parent issue directly, please use a branch name that identifies you: -e.g. +or to work on a parent issue directly, please use a branch name that identifies you, e.g. ``` git switch -c 62-implement-a-new-feature- ``` -### Development good practice +### 5. Make your changes -- To make it easier for a reviewer to see what changes you have made to the code, commit to your branch locally, labelling commit messages with the issue number, e.g., -``` -git commit -m "#62: Basic class structure"` -``` -- Regularly push your work to the same named branch on the fork. -- If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). -- When your branch is ready for merging, open a (normal) PR, or convert your draft to one, and request a code review. -- Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others. +* Now you are ready to make the changes you want to make to the code or documentation. -### Setting up a Development Environment +### 6. Run pre-commit checks -For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. For more substantial development work, we recommend the following setup: +One of the dependencies installed above is [pre-commit](https://pre-commit.com/). k-Wave-II uses `pre-commit` to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when pull requests are made. Running `pre-commit` locally allows small issues, such as trailing whitespace, to be fixed. These would otherwise cause the CI checks to fail. -#### 1. Create and activate an environment - -Using an environment manager to create and activate an environment provides an isoloated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. To create an environment from the terminal use: +* To run pre-commit on all files use ``` -conda create -n kwave -conda activate kwave +pre-commit run -a ``` -Environments are not tied to any particular folder or repository. The environment (here `kwave`) will remain active until you deactivate it (`conda deactivate`) or close the terminal. - -#### 2. Install dependencies +### 7. Add, commit, push -Once your clean environment is activated, install the packages listed in `requirements.txt`, which contain tools (dependencies) used for documentation and development. This can be done in one step: +* Once you have made your changes and `pre-commit` has corrected anything it finds, add and commit the changed files to your local repo. To make it easier for a reviewer to see what changes you have made, please label commit messages with the issue number and a short description. ``` -pip install -r requirements.txt +git add . +git commit -m "# Short description of my changes" +``` +* Push the added files to the remote repository (your fork): +``` +git push -u origin ``` -(although on a mac you may have to run `conda install pip` first). Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there. -#### 3. Pre-commit +### 8. Pull request -One of the dependencies installed above is [pre-commit](https://pre-commit.com/). k-Wave-II uses `pre-commit` to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when changes are pushed to GitHub (e.g. on push or pull request). Running `pre-commit` locally allows you to catch and fix issues early, such as trailing whitespace, that would otherwise cause the CI checks to fail. +* When your branch is ready for merging, go to GitHub `k-wave-ii` and open a pull request (new pull request → compare across forks) to merge your changes into the `develop` branch of the upstream `k-wave-ii` repository. -To run pre-commit on just the files you changed use -``` -pre-commit run -``` -or to run it on all files use -``` -pre-commit run -a -``` -If you want to skip the pre-commit checks when you commit a change you can use `git commit --no-verify`, but this is not recommended as the same tests will be run automatically in CI when you push your changes to GitHub, and they will fail if any issues remain. +The most likely cause of CI test failure for small changes is `pre-commit`; see below how to fix these failures before you commit. If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others. -### Conditions for merging a PR +## Conditions for Merging a PR Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are From 26a30ec4598da4197165cc333298a57884adec23 Mon Sep 17 00:00:00 2001 From: bencox Date: Fri, 5 Jun 2026 16:11:57 +0100 Subject: [PATCH 29/29] pre-commit whitespace changes --- docs/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 00605963..31495e5d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -34,7 +34,7 @@ git clone ### 2. Set up a development environment -For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. However, a development environment provides an isolated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. +For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. However, a development environment provides an isolated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment. * To create an environment from the terminal use: ``` conda create -n kwave @@ -53,7 +53,7 @@ pip install -r requirements.txt ### 4. Create a branch * If your fork is not newly created, make sure your fork is up to date with the upstream repository (`k-wave-ii`). -* Create a new branch from `develop`, choosing a descriptive name. For anything beyond a trivial fix, please use the number of the issue you are working on at the start of the branch name. If there is no suitable issue, please open an issue in the upstream repo. +* Create a new branch from `develop`, choosing a descriptive name. For anything beyond a trivial fix, please use the number of the issue you are working on at the start of the branch name. If there is no suitable issue, please open an issue in the upstream repo. ``` git checkout develop git switch -c @@ -99,7 +99,7 @@ git push -u origin ### 8. Pull request -* When your branch is ready for merging, go to GitHub `k-wave-ii` and open a pull request (new pull request → compare across forks) to merge your changes into the `develop` branch of the upstream `k-wave-ii` repository. +* When your branch is ready for merging, go to GitHub `k-wave-ii` and open a pull request (new pull request → compare across forks) to merge your changes into the `develop` branch of the upstream `k-wave-ii` repository. The most likely cause of CI test failure for small changes is `pre-commit`; see below how to fix these failures before you commit. If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others.