Merge branch 'waltsims:master' into benchmarks

.github/codecov.yml

@@ -0,0 +1,5 @@
+coverage:
+  status:
+    project:
+      default:
+        threshold: 1%

.github/workflows/pytest.yml

@@ -58,13 +58,23 @@ jobs:
           files: |
             ./collectedValues
           outPath: collectedValues.tar.gz
-
+      - name: upload reference values artifact
+        id: artifact-upload-step
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: matlab_reference_test_values
+          path: collectedValues.tar.gz
+          # overwrite: true
+      - name: Output artifact URL
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+        run:  echo 'Artifact URL is ${{ steps.artifact-upload-step.outputs.artifact-url }}'
   test:
     needs: collect_references
     strategy:
       matrix:
         os: [ "windows-latest", "ubuntu-latest" ] #, "macos-latest"]
-        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
+        python-version: [ "3.9", "3.10", "3.11", "3.12" ]
     runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v4

.github/workflows/test_example.yml

@@ -7,7 +7,7 @@ jobs:
     strategy:
       matrix:
         os: [ "windows-latest", "ubuntu-latest" ] #, "macos-latest"]
-        python-version: [ "3.8", "3.9", "3.10", "3.11"]
+        python-version: [ "3.9", "3.10", "3.11", "3.12"]
     runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v4

.github/workflows/test_optional_dependencies.yml

@@ -0,0 +1,23 @@
+name: test_optional_requirements
+
+on: [push, pull_request]
+
+jobs:
+    test_install:
+        strategy:
+            matrix:
+                os: [ "windows-latest", "ubuntu-latest" ] #, "macos-latest"]
+                python-version: [ "3.9", "3.10", "3.11", "3.12" ]
+                extra_requirements: [ "test", "examples", "docs", "dev", "all" ]
+        runs-on: ${{matrix.os}}
+        steps:
+            - uses: actions/checkout@v4
+            # Pull the cache based on the hash value
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+                  cache: 'pip'
+            - name: Install dependencies
+              run: |
+                  pip install '.[${{ matrix.extra_requirements }}]'

docs/README.md

@@ -33,7 +33,7 @@ After installation, run the B-mode reconstruction example in the `examples` dire
 ```bash
 git clone https://github.com/waltsims/k-wave-python
 cd k-wave-python
-git checkout v0.3.1
+git checkout v0.3.2
 pip install '.[example]' 
 python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
 ```
@@ -48,7 +48,7 @@ This example file steps through the process of:
 This example expects an NVIDIA GPU by default to simulate with k-Wave.
 
 To test the reconstruction on a machine with a GPU,
-set `RUN_SIMULATION` [on line 30 of `bmode_reconstruction_example.py`](https://github.com/waltsims/k-wave-python/blob/master/examples/bmode_reconstruction_example.py#L30)
+set `RUN_SIMULATION` [on line 29 of `us_bmode_linear_transducer.py`](https://github.com/waltsims/k-wave-python/blob/6d2ee982bece84fc6980da99b23600f5675d2fc5/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py#L29)
 to `True`, and the example will run without the pre-computed data.
 
 ## Development
@@ -68,6 +68,15 @@ found [here](https://k-wave-python.readthedocs.io/en/latest/development/developm
 
 The documentation for k-wave-python can be found [here](https://k-wave-python.readthedocs.io/en/latest/).
 
+## Citation
+```bibtex
+@software{k-Wave-Python,
+author = {Yagubbbayli, Farid and Sinden, David and Simson, Walter},
+license = {GPL-3.0},
+title = {{k-Wave-Python}},
+url = {https://github.com/waltsims/k-wave-python}
+}
+```
 ## Contact
 
 e-mail [[email protected]](mailto:[email protected]).

docs/development/development_environment.rst

@@ -2,31 +2,67 @@ Development Environment
 =======================
 
 Currently, this package serves as an interface to the cpp binaries of k-Wave.
-For this reason, the k-Wave binaries are packaged with the code in this repository.
-The k-Wave binaries can currently be found on the `k-Wave download page <http://www.k-wave.org/download.php>`_.
+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.
 
-In order to correctly set up your development environment for this repository, clone the repository from github, and install the project dependencies.
+To correctly set up your development environment for this repository, clone the repository from github, and install the project dependencies.
 
 .. code-block:: bash
 
     git clone https://github.com/waltsims/k-wave-python
     cd k-wave-python
-    pip install -e .
+    pip install -e '.[test,dev]'
 
-Next, download all k-Wave binaries from the `k-Wave download page <http://www.k-wave.org/download.php>`_.
+Test References
+=======================
 
-Lastly, place the contents of the linux-binaries, and windows-executables directories in the project directory structure under ``kwave/bin/linux/``, ``kwave/bin/darwin`` and ``kwave/bin/windows`` respectively.
-You will have to create the directory structure yourself.
+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:
 
-With this, you are ready to develop k-Wave-python.
-If you have any issues or questions, please post them on the `k-Wave-python discussions page <https://github.com/waltsims/k-wave-python/discussions>`_ to discuss. We look forward to interacting with you.
+- **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](https://github.com/waltsims/k-wave-python/actions/runs/7770639710/artifacts/1217868112)).
 
+- **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.
 
-Test References
-=======================
+**Matlab reference file generation** is a bit involved process. Below are the steps that describe the process.
 
-In order to ensure that the python interface is working correctly, we have created a set of tests that compare the output of the python interface to the output of the matlab interface.
-These tests are located in the ``tests`` directory. The comparison between ``matlab`` and ``python`` outputs are done in two ways:
+#. Open desired example in matlab, e.g. `example_pr_2D_TR_directional_sensors.m <https://github.com/ucl-bug/k-wave/blob/main/k-Wave/examples/example_pr_2D_TR_directional_sensors.m>`_
+#. Find the lines where the call to one of the `kSpaceFirstOrder-family` function is made. For example,
+
+    .. code-block:: python
+    
+        input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false};
+        sensor_data = kspaceFirstOrder2D(kgrid, medium, source, sensor, input_args{:});
+
+#. 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.
+#. 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
+#. Now it is time to turn the ``.h5`` files to the hashed ``.json`` files. This can be done with the ``H5Summary``.
+    * If you have a single ``.h5`` file, adapt the lines below and run the script:
+        https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L92-L95
+    * For multiple files, adapt the lines below:
+        https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L97-L106
+
+
+To run the tests, use the following command:    
+
+.. code-block:: bash
+
+    pytest 
+
+To run the tests with coverage, use the following command:
+
+.. code-block:: bash
 
-- Using ``.mat`` files. The files are generated by running Matlab scripts that are located in the ``tests/matlab_test_data_collectors`` directory.
-- Using ``.json`` files which are generated by hashing the Matlab variables. These are located at ``tests/reference_outputs/``. In order to regenerate the ``.json`` files, check the ``H5Summary`` class and its ``.save(...)`` method.
+    coverage run

examples/na_controlling_the_pml/README.md

@@ -1,6 +1,6 @@
 # Using An Ultrasound Transducer As A Sensor Example
 
-<a target="_blank" href="https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/na_controlling_the_pml/example_na_controlling_the_pml.ipynb">
+<a target="_blank" href="https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/na_controlling_the_pml/na_controlling_the_pml.ipynb">
   <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
 </a>
 

kwave/__init__.py

@@ -8,7 +8,7 @@
 
 # Test installation with:
 # python3 -m pip install -i https://test.pypi.org/simple/ --extra-index-url=https://pypi.org/simple/ k-Wave-python==0.3.0
-VERSION = '0.3.1'
+VERSION = '0.3.2'
 # Set environment variable to binaries to get rid of user warning
 # This code is a crutch and should be removed when kspaceFirstOrder
 # is refactored

kwave/options/simulation_options.py

@@ -254,26 +254,21 @@ def option_factory(kgrid: "kWaveGrid", options: SimulationOptions):
                     raise ValueError("Optional input ''pml_size'' must be a single numerical value.")
 
         if kgrid.dim == 1:
-            options.pml_x_alpha = 2
             options.pml_x_size = options.pml_size if options.pml_size else 20
             options.plot_scale = [-1.1, 1.1]
         elif kgrid.dim == 2:
-            options.pml_x_alpha = 2
-            options.pml_y_alpha = options.pml_x_alpha
-            if options.pml_size is None:
-                options.pml_x_size = 20
-                options.pml_y_size = 20
-            else:
-                options.pml_x_size = options.pml_size[0]
-                options.pml_y_size = options.pml_x_size
+            if (options.pml_size is not None): 
+                if (len(options.pml_size) == kgrid.dim):
+                    options.pml_x_size, options.pml_y_size = np.asarray(options.pml_size, dtype=int).ravel()
+                else:
+                    options.pml_x_size, options.pml_y_size = (options.pml_size[0], options.pml_size[0])
+            else: 
+                options.pml_x_size, options.pml_y_size = (20, 20)
             options.plot_scale = [-1, 1]
         elif kgrid.dim == 3:
-            if options.pml_size is not None and len(options.pml_size) == kgrid.dim:
-                options.pml_x_size, options.pml_y_size, options.pml_z_size = options.pml_size.ravel()
+            if ((options.pml_size is not None) and (len(options.pml_size) == kgrid.dim)):
+                options.pml_x_size, options.pml_y_size, options.pml_z_size = np.asarray(options.pml_size).ravel()
             else:
-                options.pml_x_alpha = 2
-                options.pml_y_alpha = options.pml_x_alpha
-                options.pml_z_alpha = options.pml_x_alpha
                 if options.pml_size is None:
                     options.pml_x_size = 10
                     options.pml_y_size = 10

pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Acoustics toolbox for time domain acoustic and ultrasound simulations in complex and tissue-realistic media."
 readme = "docs/README.md"
 license = { file = "LICENSE" }
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 authors = [
     { name = "Farid Yagubbayli", email = "[email protected]" },
     { name = "Walter Simson", email = "[email protected]"}
@@ -25,10 +25,10 @@ classifiers = [
 ]
 dependencies = [
     "h5py==3.10.0",
-    "scipy==1.10.1",
+    "scipy==1.12.0",
     "opencv-python==4.9.0.80",
     "deepdiff==6.7.1",
-    "matplotlib==3.7.2",
+    "matplotlib==3.8.3",
     "numpy>=1.22.2,<1.27.0",
     "nptyping==2.5.0",
     "beartype==0.16.4"
@@ -42,7 +42,7 @@ Bug-tracker = "https://github.com/waltsims/k-wave-python/issues"
 
 [project.optional-dependencies]
 test = ["pytest",
-        "coverage==7.4.1",
+        "coverage==7.4.3",
         "phantominator",
         "requests==2.31.0"]
 example = ["gdown==4.6.0"]
@@ -51,7 +51,7 @@ docs = ["m2r2==0.3.2",
     "sphinx-tabs==3.4.4",
     "sphinx-toolbox==3.5.0",
     "furo==2024.1.29"]
-dev = ["pre-commit==3.6.1"]
+dev = ["pre-commit==3.6.2"]
 
 [tool.hatch.version]
 path = "kwave/__init__.py"