Merge branch 'master' into dependabot/pip/numpy-gte-1.22.2-and-lt-2.2.0

.github/workflows/pytest.yml

@@ -74,7 +74,7 @@ jobs:
     strategy:
       matrix:
         os: [ "windows-latest", "ubuntu-latest" , "macos-latest"]
-        python-version: [ "3.9", "3.10", "3.11", "3.12" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
     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.9", "3.10", "3.11", "3.12"]
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
     runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v4

.github/workflows/test_pages.yml

@@ -10,7 +10,7 @@ jobs:
         fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
     - uses: actions/setup-python@v5
       with:
-        python-version: '3.9'
+        python-version: '3.10'
         cache: 'pip'
     - name: Build and Commit
       uses: waltsims/[email protected]

.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 sphinx:
    configuration: docs/conf.py
 python:

Makefile

@@ -0,0 +1,44 @@
+# Define the Python interpreter and MATLAB command
+PYTHON = python
+MATLAB = matlab
+
+# Define the directories and files
+EXAMPLES_DIR = examples
+TESTS_DIR = tests
+MATLAB_SCRIPT = tests/matlab_test_data_collectors/run_all_collectors.m
+KWAVE_MATLAB_PATH = $(abspath ../k-wave) # Get absolute path of k-wave directory
+
+# Define the artifact directory
+COLLECTED_VALUES_DIR = $(abspath tests/matlab_test_data_collectors/python_testers/collectedValues)
+
+# Default target
+all: run-examples test
+
+# Target to run all examples
+run-examples:
+	@echo "Running all examples..."
+	@MPLBACKEND=Agg $(PYTHON) run_examples.py
+
+# Target to run pytest, which depends on running the MATLAB script first
+test: $(COLLECTED_VALUES_DIR)
+	@echo "Running pytest..."
+	@pytest $(TESTS_DIR)
+
+# Target to run the MATLAB script and create the artifact directory
+$(COLLECTED_VALUES_DIR): 
+	@echo "Running MATLAB script to collect values..."; \
+	$(MATLAB) -batch "run('$(MATLAB_SCRIPT)');"; \
+# Clean target (optional) - cleans Python caches and collected values
+clean: clean-python clean-collected_values
+
+clean-python:
+	@echo "Cleaning Python cache files..."
+	@find . -name '*.pyc' -delete
+	@find . -name '__pycache__' -delete
+
+# Clean collected values directory
+clean-collected_values:
+	@echo "Cleaning collected values directory..."
+	@rm -rf $(COLLECTED_VALUES_DIR)
+
+.PHONY: all run-examples run-tests clean-python clean-collected_values clean

docs/development/development_environment.rst

@@ -21,6 +21,46 @@ 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:    
+
+.. code-block:: bash
+
+    pytest 
+
+To run the tests with coverage, use the following command:
+
+.. code-block:: bash
+
+    coverage run
+
+To run all examples, to ensure they still run after changes use the following command:
+.. code-block:: bash
+    make run-examples
+
+or
+
+.. code-block:: bash
+
+    MPLBACKEND=Agg python run_examples.py
+
+
+
+If you want to force the examples to run on the cpu:
+
+.. code-block:: bash
+
+    MPLBACKEND=Agg KWAVE_FORCE_CPU=1 python run_examples.py
+
+
 Test References
 =======================
 
@@ -42,7 +82,7 @@ These tests are located in the ``tests`` directory. The comparison between ``mat
   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.
+**Matlab reference file generation** can be described in the following steps.
 
 #. 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,
@@ -63,14 +103,3 @@ These tests are located in the ``tests`` directory. The comparison between ``mat
         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
-
-    coverage run

examples/README.md

@@ -9,15 +9,15 @@ Every example has a short readme.md file which briefly describes the purpose of
 - [Array as a sensor](at_array_as_sensor/) ([original example](http://www.k-wave.org/documentation/example_at_array_as_sensor.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_array_as_sensor/at_array_as_sensor.ipynb))
 - [Array as a source](at_array_as_source/) ([original example](http://www.k-wave.org/documentation/example_at_array_as_source.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_array_as_source/at_array_as_source.ipynb))
 - [Linear array transducer](at_linear_array_transducer/)
-([original example](http://www.k-wave.org/documentation/example_at_linear_array_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_linear_array_transducer/at_linear_array_transducer.ipynb))
+  ([original example](http://www.k-wave.org/documentation/example_at_linear_array_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_linear_array_transducer/at_linear_array_transducer.ipynb))
 - [Photoacoustic Waveforms](ivp_photoacoustic_waveforms/) ([original example](http://www.k-wave.org/documentation/example_ivp_photoacoustic_waveforms.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/ivp_photoacoustic_waveforms/ivp_photoacoustic_waveforms.ipynb))
 - [Controlling the PML](na_controlling_the_pml/)
-([original example](http://www.k-wave.org/documentation/example_na_controlling_the_pml.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/na_controlling_the_pml/na_controlling_the_pml.ipynb))
+  ([original example](http://www.k-wave.org/documentation/example_na_controlling_the_pml.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/na_controlling_the_pml/na_controlling_the_pml.ipynb))
 - [Defining An Ultrasound Transducer Example](us_defining_transducer) ([original example](http://www.k-wave.org/documentation/example_us_defining_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_defining_transducer/us_defining_transducer.ipynb))
 - [Simulating Ultrasound Beam Patterns](us_beam_patterns/)([original example](http://www.k-wave.org/documentation/example_us_beam_patterns), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_beam_patterns/us_beam_patterns.ipynb))
 - [Linear transducer B-mode](us_bmode_linear_transducer/) ([original example](http://www.k-wave.org/documentation/example_us_bmode_linear_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb))
 - [Phased array B-mode](us_bmode_phased_array/)
-([original example](http://www.k-wave.org/documentation/example_us_bmode_phased_array.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_phased_array/us_bmode_phased_array.ipynb))
+  ([original example](http://www.k-wave.org/documentation/example_us_bmode_phased_array.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_phased_array/us_bmode_phased_array.ipynb))
 - [Circular piston transducer](at_circular_piston_3D/) ([original example](http://www.k-wave.org/documentation/example_at_piston_and_bowl_transducers.php#heading3), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_circular_piston_3D/at_circular_piston_3D.ipynb))
 
 - [Circular piston transducer (axisymmetric)](at_circular_piston_AS/) ([original example](http://www.k-wave.org/documentation/example_at_piston_and_bowl_transducers.php#heading4), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_circular_piston_AS/at_circular_piston_AS.ipynb))
@@ -28,22 +28,25 @@ Every example has a short readme.md file which briefly describes the purpose of
 
 - [Focused annular array](at_focused_annular_array_3D/) ([original example](http://www.k-wave.org/documentation/example_at_piston_and_bowl_transducers.php#heading7), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/at_focused_annular_array_3D/at_focused_annular_array_3D.ipynb))
 
-- [Focussed Detector In 2D Example](at_focused_annular_array_3D/) ([original example](http://www.k-wave.org/documentation/example_sd_focussed_detector_2D.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/sd_focussed_detector_2D/sd_focussed_detector_2D.ipynb))
+- [Focussed Detector In 2D Example](sd_focussed_detector_2D/) ([original example](http://www.k-wave.org/documentation/example_sd_focussed_detector_2D.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/sd_focussed_detector_2D/sd_focussed_detector_2D.ipynb))
 
+- [Focussed Detector In 3D Example](sd_focussed_detector_3D/) ([original example](http://www.k-wave.org/documentation/example_sd_focussed_detector_3D.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/sd_focussed_detector_3D/sd_focussed_detector_3D.ipynb))
+
+- [Modelling Sensor Directivity In 2D Example](sd_directivity_modelling_2D/) ([original example](http://www.k-wave.org/documentation/example_sd_directivity_modelling_2D.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/sd_directivity_modelling_2D/sd_directivity_modelling_2D.ipynb))
 
 ## Contributing new examples
 
 When adding a new example notebook, follow these steps:
 
 1. Search the [list of examples](https://docs.google.com/spreadsheets/d/1-x13iIez84AEyjjHMOe2GoC8FSyzUFHoy9R7VKttTlo/edit?usp=sharing) to find an open example.
 1. Claim your example by opening an "Example" issue on GitHub.
-3. Fork and clone the repository and create a branch for your new example.
-2. Create an example sub-directory using the name from the hyperlink of the original k-wave example if it exists (e.g. for http://www.k-wave.org/documentation/example_ivp_loading_external_image.php name the directory "ivp_loading_external_image).
-3. Add your example notebook to your example directory.
-4. Create a Python script that mirrors your example notebook in the same directory. Using `nbconvert` is an easy way to convert to a Python script using ` jupyter nbconvert --to python --RegexRemovePreprocessor.patterns="^%" <notebook_path>`
-5. Add a README.md file to your example directory briefly describing the concept or principle the example is meant to display and linking to the origonal k-wave example page if it exists.
-6. Include a link in the `README.md` in the examples directory to a colab notebook for your example.
-7. Add a your example to the list on this `README.md` and add a colab badge [using html](https://openincolab.com/) OR copy the pure markdown version above.
-8. Open a pull request that [closes the open issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) from your forked example branch and name pull request "[Example] \<name of your example\>".
+1. Fork and clone the repository and create a branch for your new example.
+1. Create an example sub-directory using the name from the hyperlink of the original k-wave example if it exists (e.g. for http://www.k-wave.org/documentation/example_ivp_loading_external_image.php name the directory "ivp_loading_external_image).
+1. Add your example notebook to your example directory.
+1. Create a Python script that mirrors your example notebook in the same directory. Using `nbconvert` is an easy way to convert to a Python script using ` jupyter nbconvert --to python --RegexRemovePreprocessor.patterns="^%" <notebook_path>`
+1. Add a README.md file to your example directory briefly describing the concept or principle the example is meant to display and linking to the origonal k-wave example page if it exists.
+1. Include a link in the `README.md` in the examples directory to a colab notebook for your example.
+1. Add a your example to the list on this `README.md` and add a colab badge [using html](https://openincolab.com/) OR copy the pure markdown version above.
+1. Open a pull request that [closes the open issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) from your forked example branch and name pull request "[Example] \<name of your example\>".
 
 Thanks for contributing to k-wave-python!

examples/sd_directivity_modelling_2D/README.md

@@ -0,0 +1,7 @@
+# Modelling Sensor Directivity In 2D Example
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/sd_directivity_modelling_2D/sd_directivity_modelling_2D.ipynb)
+
+This example demonstrates how the sensitivity of a large single element detector varies with the angular position of a point-like source.
+
+To read more, visit the [original example page](http://www.k-wave.org/documentation/example_sd_directivity_modelling_2D.php).