Restructure examples: flatten ported/, drop example_ prefix, parametrize tests

.github/workflows/generate-notebooks.yml

@@ -0,0 +1,43 @@
+name: Generate Notebooks
+
+on:
+  push:
+    branches: [master]
+    paths: ['examples/*.py']
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install jupytext
+        run: pip install 'jupytext>=1.16,<2'
+
+      - name: Generate notebooks
+        run: |
+          mkdir -p notebooks
+          for py in examples/*.py; do
+            [ -f "$py" ] || continue
+            basename=$(basename "$py")
+            jupytext --to notebook "$py" --output "notebooks/${basename%.py}.ipynb"
+          done
+
+      - name: Commit notebooks
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git pull --rebase origin master
+          git add notebooks/
+          if git diff --cached --quiet; then
+            echo "No notebook changes"
+          else
+            git commit -m "Auto-generate notebooks from examples [skip ci]"
+            git push origin HEAD:master
+          fi

.github/workflows/run-examples.yml

@@ -4,6 +4,10 @@ on:
   schedule:
     - cron: '0 0 * * 1'  # Every Monday at 00:00 UTC
   workflow_dispatch:      # Manual trigger
+  pull_request:
+    paths:
+      - 'examples/*.py'
+      - '.github/workflows/run-examples.yml'
 
 jobs:
   discover-examples:
@@ -14,8 +18,8 @@ jobs:
       - 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]')
+          # Find ported examples (exclude legacy/ and hidden files)
+          EXAMPLES=$(find examples -maxdepth 1 -name "*.py" -not -path "*/\.*" | jq -R -s -c 'split("\n")[:-1]')
           echo "examples=$EXAMPLES" >> "$GITHUB_OUTPUT"
 
   run-examples:

docs/README.md

@@ -21,7 +21,7 @@ to leverage pythonic practices.
 
 ![](_static/example_bmode.png)
 
-A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/HEAD/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
+A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/HEAD/examples/legacy/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
 
 This example file steps through the process of:
  1. Generating a simulation medium

docs/examples_guide.rst

@@ -17,7 +17,7 @@ Basic Wave Propagation (IVP - Initial Value Problems)
    * - Example
      - Core Concept
      - Topics
-   * - :ghdir:`examples/ivp_photoacoustic_waveforms/`
+   * - :ghdir:`examples/legacy/ivp_photoacoustic_waveforms/`
      - 2D vs 3D wave propagation physics
      - **IVP** • Wave spreading • Compact support
 
@@ -33,13 +33,13 @@ Simple Transducers & Sources
    * - Example
      - Core Concept
      - Topics
-   * - :ghdir:`examples/us_defining_transducer/`
+   * - :ghdir:`examples/legacy/us_defining_transducer/`
      - Basic ultrasound transducer setup
      - **US** • Transducer basics • Time-varying sources
-   * - :ghdir:`examples/at_circular_piston_3D/`
+   * - :ghdir:`examples/legacy/at_circular_piston_3D/`
      - Simple focused geometry
      - **AT** • 3D focusing • Geometric sources
-   * - :ghdir:`examples/at_circular_piston_AS/`
+   * - :ghdir:`examples/legacy/at_circular_piston_AS/`
      - Computational efficiency with symmetry
      - **AT** • Axisymmetric • Computational optimization
 
@@ -55,16 +55,16 @@ Medical Imaging Applications
    * - Example
      - Application
      - Topics
-   * - :ghdir:`examples/us_beam_patterns/`
+   * - :ghdir:`examples/legacy/us_beam_patterns/`
      - Understanding acoustic beam formation
      - **US** • Beam focusing • Field patterns
-   * - :ghdir:`examples/us_bmode_linear_transducer/`
+   * - :ghdir:`examples/legacy/us_bmode_linear_transducer/`
      - Complete ultrasound imaging pipeline
      - **US** • Medical imaging • Signal processing
-   * - :ghdir:`examples/pr_2D_FFT_line_sensor/`
+   * - :ghdir:`examples/legacy/pr_2D_FFT_line_sensor/`
      - Photoacoustic image reconstruction
      - **PR** • Image reconstruction • FFT methods
-   * - :ghdir:`examples/pr_2D_TR_line_sensor/`
+   * - :ghdir:`examples/legacy/pr_2D_TR_line_sensor/`
      - Alternative reconstruction approach
      - **PR** • Time reversal • Reconstruction
 
@@ -80,19 +80,19 @@ Advanced Transducer Modeling (AT - Array Transducers)
    * - Example
      - Advanced Technique
      - Topics
-   * - :ghdir:`examples/at_array_as_source/`
+   * - :ghdir:`examples/legacy/at_array_as_source/`
      - kWaveArray for complex geometries
      - **AT** • Array modeling • Anti-aliasing
-   * - :ghdir:`examples/at_array_as_sensor/`
+   * - :ghdir:`examples/legacy/at_array_as_sensor/`
      - Complex sensor array geometries
      - **AT** • Sensor arrays • Flexible positioning
-   * - :ghdir:`examples/at_linear_array_transducer/`
+   * - :ghdir:`examples/legacy/at_linear_array_transducer/`
      - Multi-element linear arrays
      - **AT** • Linear arrays • Element spacing
-   * - :ghdir:`examples/at_focused_bowl_3D/`
+   * - :ghdir:`examples/legacy/at_focused_bowl_3D/`
      - 3D focused ultrasound therapy
      - **AT** • Therapeutic US • 3D focusing
-   * - :ghdir:`examples/at_focused_annular_array_3D/`
+   * - :ghdir:`examples/legacy/at_focused_annular_array_3D/`
      - Multi-element focused systems
      - **AT** • Annular arrays • Complex focusing
 
@@ -108,13 +108,13 @@ Advanced Imaging & Reconstruction (PR - Pressure/Photoacoustic Reconstruction)
    * - Example
      - Reconstruction Method
      - Topics
-   * - :ghdir:`examples/pr_3D_FFT_planar_sensor/`
+   * - :ghdir:`examples/legacy/pr_3D_FFT_planar_sensor/`
      - 3D FFT-based reconstruction
      - **PR** • 3D imaging • Planar arrays
-   * - :ghdir:`examples/pr_3D_TR_planar_sensor/`
+   * - :ghdir:`examples/legacy/pr_3D_TR_planar_sensor/`
      - 3D time reversal reconstruction
      - **PR** • 3D time reversal • Volumetric imaging
-   * - :ghdir:`examples/us_bmode_phased_array/`
+   * - :ghdir:`examples/legacy/us_bmode_phased_array/`
      - Advanced ultrasound beamforming
      - **US** • Phased arrays • Electronic steering
 
@@ -130,13 +130,13 @@ Sensor Physics & Directivity (SD - Sensor Directivity)
    * - Example
      - Physics Concept
      - Topics
-   * - :ghdir:`examples/sd_directivity_modelling_2D/`
+   * - :ghdir:`examples/legacy/sd_directivity_modelling_2D/`
      - How sensor size affects measurements
      - **SD** • Directivity • Finite sensor size
-   * - :ghdir:`examples/sd_focussed_detector_2D/`
+   * - :ghdir:`examples/legacy/sd_focussed_detector_2D/`
      - Directional sensor sensitivity
      - **SD** • Focused detection • Sensor design
-   * - :ghdir:`examples/sd_focussed_detector_3D/`
+   * - :ghdir:`examples/legacy/sd_focussed_detector_3D/`
      - 3D focused sensor modeling
      - **SD** • 3D detection • Sensor focusing
 
@@ -152,7 +152,7 @@ Computational Optimization (NA - Numerical Analysis)
    * - Example
      - Optimization Topic
      - Topics
-   * - :ghdir:`examples/na_controlling_the_pml/`
+   * - :ghdir:`examples/legacy/na_controlling_the_pml/`
      - Boundary conditions and efficiency
      - **NA** • PML boundaries • Computational domains
 

docs/get_started/first_simulation.rst

@@ -194,22 +194,22 @@ Now that you understand the four-component structure, explore these examples to
 
 **Beginner Examples** (start here):
 
-- :ghfile:`Photoacoustic Waveforms <examples/ivp_photoacoustic_waveforms/README.md>` - See how 2D and 3D wave propagation differs
-- :ghfile:`Defining Transducers <examples/us_defining_transducer/README.md>` - Learn about ultrasound transducers
+- :ghfile:`Photoacoustic Waveforms <examples/legacy/ivp_photoacoustic_waveforms/README.md>` - See how 2D and 3D wave propagation differs
+- :ghfile:`Defining Transducers <examples/legacy/us_defining_transducer/README.md>` - Learn about ultrasound transducers
 
 **Medical Imaging Applications**:
 
-- :ghfile:`B-mode Linear Transducer <examples/us_bmode_linear_transducer/README.md>` - Full B-mode ultrasound imaging pipeline
-- :ghfile:`2D FFT Line Sensor <examples/pr_2D_FFT_line_sensor/README.md>` - Photoacoustic image reconstruction
+- :ghfile:`B-mode Linear Transducer <examples/legacy/us_bmode_linear_transducer/README.md>` - Full B-mode ultrasound imaging pipeline
+- :ghfile:`2D FFT Line Sensor <examples/legacy/pr_2D_FFT_line_sensor/README.md>` - Photoacoustic image reconstruction
 
 **Advanced Transducer Modeling**:
 
-- :ghfile:`Array as Source <examples/at_array_as_source/README.md>` - Complex array transducers without staircasing
-- :ghfile:`Focused Bowl 3D <examples/at_focused_bowl_3D/README.md>` - Focused ultrasound applications
+- :ghfile:`Array as Source <examples/legacy/at_array_as_source/README.md>` - Complex array transducers without staircasing
+- :ghfile:`Focused Bowl 3D <examples/legacy/at_focused_bowl_3D/README.md>` - Focused ultrasound applications
 
 **Acoustic Field Analysis**:
 
-- :ghfile:`Beam Patterns <examples/us_beam_patterns/README.md>` - Understand beam formation and focusing
-- :ghfile:`Focused Detector 2D <examples/sd_focussed_detector_2D/README.md>` - Sensor directivity effects
+- :ghfile:`Beam Patterns <examples/legacy/us_beam_patterns/README.md>` - Understand beam formation and focusing
+- :ghfile:`Focused Detector 2D <examples/legacy/sd_focussed_detector_2D/README.md>` - Sensor directivity effects
 
 Each example builds on the same four-component framework but demonstrates different aspects of acoustic simulation. The key insight is that no matter how complex the application, every k-Wave simulation follows this same logical structure.