Development Environment

Currently, this package serves as an interface to the cpp binaries of k-Wave. For this reason, binaries are required to run simulations with k-Wave-python. The binaries are downloaded by k-Wave-python when the package is run for the first time.

To correctly set up your development environment for this repository, clone the repository from github, and install the project dependencies.

git clone https://github.com/waltsims/k-wave-python
cd k-wave-python
pip install -e '.[dev,test]'

This installs all the dependencies for development, and testing.

Ensure pre-commit is configured by running the following command:

pre-commit install

Running Tests

Assuming matlab is installed locally, and k-wave <https://github.com/ucl-bug/k-wave> is installed in a parallel directory, testing can be performed using the make file located in the project root. .. code-block:: bash

make test

This process will first generate refernce files in matlab and run the complete python test suite against them.

To run the tests manually after reference generation, use the following command:

pytest

To run the tests with coverage, use the following command:

coverage run

To run all examples, to ensure they still run after changes use the following command: .. code-block:: bash

make run-examples

or

MPLBACKEND=Agg python run_examples.py

If you want to force the examples to run on the cpu:

MPLBACKEND=Agg KWAVE_FORCE_CPU=1 python run_examples.py

Test References

Tests compare the outputs of the python and the matlab interfaces. These tests are located in the tests directory. The comparison between matlab and python outputs are done in two ways:

  • Unit testing: k-Wave-python functions that have a direct counterpart in original k-Wave are tested by comparing the outputs of the two functions. The output of the original k-Wave functions are stored in .mat files. These files can be generated by running the corresponding MATLAB scripts located in the tests/matlab_test_data_collectors/matlab_collectors/ directory by running tests/matlab_test_data_collectors/run_all_collectors.m. After running the scripts, the reference files can be found in tests/matlab_test_data_collectors/python_testes/collectedValues/.

Note

If you do not have MATLAB installed to generate the reference files, you can download recently generated reference file outputs from the GitHub CI and place them in the python_testers/collectedValues/ directory. The latest reference files can be found in the artifacts of the latest CI run of pytest.yml (e.g. here).

  • Integration testing: k-Wave-python tests output .h5 files that are passed to the k-Wave binaries and ensures that they match the output of the original k-Wave. This testing compares the output for many of the example scripts from the original k-Wave package. Hash values of the reference output .h5 file from MATLAB examples are generated and stored in .json files in tests/reference_outputs/. These .json files are stored in the code repository and do not need to be regenerated. Since these files are generated from the original k-Wave package, they only need to be updated when a new release of k-Wave is made.

Matlab reference file generation can be described in the following steps.

  1. Open desired example in matlab, e.g. example_pr_2D_TR_directional_sensors.m

  2. Find the lines where the call to one of the kSpaceFirstOrder-family function is made. For example,

    input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false};
sensor_data = kspaceFirstOrder2D(kgrid, medium, source, sensor, input_args{:});

  3. Update the input_args field by adding two new options - {'SaveToDisk', true, 'SaveToDiskExit': true}. These options will ensure that we a .h5 file will be created and saved in your tmp folder, while avoiding to run the actual simulation.

  4. Run the modified example. You will find created files in your tmp folder. Usually exact file name depends on how many calls are made to the kSpaceFirstOrder-family function in the example:

    • If there is only a single call, created file name will be example_input.h5

    • If there are two or more calls, created files will have names like example_input_1.h5, example_input_2.h5, example_input_3.h5 and so on

  5. Now it is time to turn the .h5 files to the hashed .json files. This can be done with the H5Summary.