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

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 is a bit involved process. Below are the steps that describe the process.

  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.

To run the tests, use the following command:

pytest

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

coverage run