Merge branch 'master' into dependabot/pip/sphinx-toolbox-3.9.0

Author: waltsims

.github/workflows/codespell.yml

@@ -0,0 +1,25 @@
+name: Spell Check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  spellcheck:
+    name: Spell Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      
+      - name: Install codespell
+        run: pip install codespell
+      
+      - name: Run codespell
+        run: codespell --config .codespellrc 

.github/workflows/run-examples.yml

@@ -0,0 +1,56 @@
+name: Run K-Wave Examples
+
+on:
+  schedule:
+    - cron: '0 0 * * 1'  # Every Monday at 00:00 UTC
+  workflow_dispatch:      # Manual trigger
+
+jobs:
+  discover-examples:
+    runs-on: ubuntu-latest
+    outputs:
+      example_paths: ${{ steps.find-examples.outputs.examples }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: find-examples
+        run: |
+          # Find all Python files in examples subdirectories
+          EXAMPLES=$(find examples -name "*.py" -not -path "*/\.*" | jq -R -s -c 'split("\n")[:-1]')
+          echo "examples=$EXAMPLES" >> "$GITHUB_OUTPUT"
+
+  run-examples:
+    needs: discover-examples
+    runs-on: ubuntu-latest
+    timeout-minutes: 60  # 1 hour timeout per example
+    strategy:
+      fail-fast: false  # Continue running other examples even if one fails
+      matrix:
+        example: ${{ fromJson(needs.discover-examples.outputs.example_paths) }}
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'  # Matches requires-python from pyproject.toml
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Install the package with example dependencies
+          pip install -e ".[example]"
+
+      - name: Run example
+        env:
+          KWAVE_FORCE_CPU: 1
+        run: |
+          echo "Running example: ${{ matrix.example }}"
+          python "${{ matrix.example }}" 

.pre-commit-config.yaml

@@ -17,6 +17,13 @@ repos:
       args: [ --fix ]
     # Run the formatter.
     - id: ruff-format
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    additional_dependencies:
+      - tomli
+    args: [--write-changes]
 # - repo: https://github.com/pre-commit/pre-commit-hooks
 #   rev: v4.5.0  # Use the ref you want to point at
 #   hooks:

docs/development/development_environment.rst

@@ -24,11 +24,12 @@ Ensure pre-commit is configured by running the following command:
 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.
+This process will first generate reference files in matlab and run the complete python test suite against them.
 
 To run the tests manually after reference generation, use the following command:    
 
@@ -43,7 +44,9 @@ 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
@@ -87,7 +90,7 @@ These tests are located in the ``tests`` directory. The comparison between ``mat
 #. 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
+    .. code-block:: matlab
     
         input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false};
         sensor_data = kspaceFirstOrder2D(kgrid, medium, source, sensor, input_args{:});

docs/reconstruction/index.rst

@@ -0,0 +1,19 @@
+Reconstruction
+=============
+
+This module provides functionality for reconstructing acoustic fields from recorded sensor data.
+
+.. toctree::
+   :maxdepth: 2
+
+   time_reversal
+   beamform
+   converter
+   shifted_transform
+   tools
+
+Migration Notes
+-------------
+
+The time reversal reconstruction functionality has been moved to the :class:`TimeReversal` class.
+See :doc:`time_reversal` for migration guidelines and examples. 

docs/reconstruction/time_reversal.rst

@@ -0,0 +1,80 @@
+Time Reversal Reconstruction
+========================
+
+The :class:`TimeReversal` class provides functionality for time reversal reconstruction in photoacoustic imaging.
+It handles the reconstruction of initial pressure distributions from recorded sensor data.
+
+.. tip::
+   **Migration from Legacy Time Reversal**
+   
+   Previous versions used ``sensor.time_reversal_boundary_data`` directly with ``kspaceFirstOrder2D/3D``.
+   This approach is now deprecated. Instead, use the new :class:`TimeReversal` class:
+
+   .. code-block:: python
+
+      # Old approach (deprecated)
+      sensor.time_reversal_boundary_data = sensor_data
+      p0_recon = kspaceFirstOrder2D(kgrid, source, sensor, medium, simulation_options, execution_options)
+
+      # New approach
+      sensor.recorded_pressure = sensor_data  # Store recorded data
+      tr = TimeReversal(kgrid, medium, sensor)
+      p0_recon = tr(kspaceFirstOrder2D, simulation_options, execution_options)
+
+Class Documentation
+-----------------
+
+.. autoclass:: kwave.reconstruction.time_reversal.TimeReversal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Key Features
+-----------
+
+- Automatic compensation for half-plane recording
+- Support for both 2D and 3D reconstructions
+- Input validation and error checking
+- Clean interface separating data recording from reconstruction
+
+Example Usage
+------------
+
+Here's a complete example showing forward simulation and time reversal reconstruction:
+
+.. code-block:: python
+
+   import numpy as np
+   from kwave import *
+
+   # Setup grid and medium
+   kgrid = kWaveGrid([64, 64], [0.1e-3, 0.1e-3])
+   medium = kWaveMedium(sound_speed=1500)
+   kgrid.makeTime(medium.sound_speed)
+
+   # Create initial pressure
+   source = kSource()
+   source.p0 = np.zeros(kgrid.N)
+   source.p0[32, 32] = 1
+
+   # Setup sensor
+   sensor = kSensor()
+   sensor.mask = np.zeros(kgrid.N)
+   sensor.mask[0, :] = 1  # Line sensor
+
+   # Forward simulation
+   sensor_data = kspaceFirstOrder2D(kgrid, source, sensor, medium, 
+                                  simulation_options, execution_options)
+   sensor.recorded_pressure = sensor_data["p"].T
+
+   # Time reversal reconstruction
+   tr = TimeReversal(kgrid, medium, sensor)
+   p0_recon = tr(kspaceFirstOrder2D, simulation_options, execution_options)
+
+Notes
+-----
+
+- The compensation factor (default=2.0) accounts for energy loss when recording over a half-plane
+- The time array must be explicitly defined (not 'auto') for time reversal
+- The sensor mask must have at least one active point
+- The sensor mask shape must match the grid dimensions 

examples/at_array_as_sensor/at_array_as_sensor.ipynb

@@ -16,8 +16,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import matplotlib.pyplot as plt\n",
     "import matplotlib as mpl\n",
+    "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "\n",
     "from kwave.data import Vector\n",
@@ -28,10 +28,10 @@
     "from kwave.kspaceFirstOrder2D import kspaceFirstOrder2D\n",
     "from kwave.options.simulation_execution_options import SimulationExecutionOptions\n",
     "from kwave.options.simulation_options import SimulationOptions\n",
+    "from kwave.utils.colormap import get_color_map\n",
     "from kwave.utils.conversion import cart2grid\n",
     "from kwave.utils.kwave_array import kWaveArray\n",
     "from kwave.utils.mapgen import make_cart_circle, make_disc\n",
-    "from kwave.utils.colormap import get_color_map\n",
     "from kwave.utils.signals import reorder_binary_sensor_data"
    ]
   },
@@ -119,7 +119,7 @@
     "combined_sensor_data = karray.combine_sensor_data(kgrid, sensor_data)\n",
     "\n",
     "\n",
-    "# create pml mask (re-use default size of 20 grid points from simulation_options)\n",
+    "# create pml mask (reuse default size of 20 grid points from simulation_options)\n",
     "pml_size = simulation_options.pml_x_size  # 20 [grid_points]\n",
     "pml_mask = np.zeros((N.x, N.y), dtype=bool)\n",
     "pml_mask[:pml_size, :] = 1\n",
@@ -142,7 +142,7 @@
    "outputs": [],
    "source": [
     "%matplotlib inline\n",
-    "# create pml mask (re-use default size of 20 grid points from simulation_options)\n",
+    "# create pml mask (reuse default size of 20 grid points from simulation_options)\n",
     "pml_size = simulation_options.pml_x_size  # 20 [grid_points]\n",
     "pml_mask = np.zeros((N.x, N.y), dtype=bool)\n",
     "pml_mask[:pml_size, :] = 1\n",

examples/at_array_as_sensor/at_array_as_sensor.py

@@ -1,5 +1,5 @@
-import matplotlib.pyplot as plt
 import matplotlib as mpl
+import matplotlib.pyplot as plt
 import numpy as np
 
 from kwave.data import Vector
@@ -10,9 +10,9 @@
 from kwave.kspaceFirstOrder2D import kspaceFirstOrder2D
 from kwave.options.simulation_execution_options import SimulationExecutionOptions
 from kwave.options.simulation_options import SimulationOptions
+from kwave.utils.colormap import get_color_map
 from kwave.utils.conversion import cart2grid
 from kwave.utils.kwave_array import kWaveArray
-from kwave.utils.colormap import get_color_map
 from kwave.utils.mapgen import make_cart_circle, make_disc
 from kwave.utils.signals import reorder_binary_sensor_data
 
@@ -76,7 +76,7 @@ def main():
     # VISUALIZATION
     # =========================================================================
 
-    # create pml mask (re-use default size of 20 grid points from simulation_options)
+    # create pml mask (reuse default size of 20 grid points from simulation_options)
     pml_size = simulation_options.pml_x_size  # 20 [grid_points]
     pml_mask = np.zeros((N.x, N.y), dtype=bool)
     pml_mask[:pml_size, :] = 1

examples/at_array_as_source/at_array_as_source.ipynb

@@ -29,8 +29,8 @@
     "from kwave.kspaceFirstOrder2D import kspace_first_order_2d_gpu\n",
     "from kwave.options.simulation_execution_options import SimulationExecutionOptions\n",
     "from kwave.options.simulation_options import SimulationOptions\n",
-    "from kwave.utils.kwave_array import kWaveArray\n",
     "from kwave.utils.colormap import get_color_map\n",
+    "from kwave.utils.kwave_array import kWaveArray\n",
     "from kwave.utils.signals import tone_burst\n"
    ]
   },
@@ -169,6 +169,7 @@
    "outputs": [],
    "source": [
     "from matplotlib import rc\n",
+    "\n",
     "rc('animation', html='jshtml', embed_limit=10**3)\n",
     "%matplotlib notebook\n",
     "\n",

examples/at_array_as_source/at_array_as_source.py

@@ -11,8 +11,8 @@
 from kwave.kspaceFirstOrder2D import kspace_first_order_2d_gpu
 from kwave.options.simulation_execution_options import SimulationExecutionOptions
 from kwave.options.simulation_options import SimulationOptions
-from kwave.utils.kwave_array import kWaveArray
 from kwave.utils.colormap import get_color_map
+from kwave.utils.kwave_array import kWaveArray
 from kwave.utils.signals import tone_burst