Update docs to link ported examples, not legacy

- examples_guide.rst: replace legacy directory links with ported .py
  file links using :ghfile:
- first_simulation.rst: simplify "Next Steps" to link to examples_guide
  instead of individual legacy READMEs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: waltsims

docs/examples_guide.rst

@@ -1,179 +1,70 @@
-Examples: k-Wave-Python Step-by-Step
-=======================
+Examples
+========
 
-The k-Wave Python examples are organized to help you progress from basic wave physics to advanced applications. Each example demonstrates the four-component framework (Grid, Medium, Source, Sensor) with increasing complexity.
+k-Wave-python examples are organized by topic. Each example uses the ``setup()/run()`` pattern and can be run directly:
 
-Start with the :doc:`get_started/first_simulation` tutorial, then follow this suggested learning path:
+.. code-block:: bash
 
-Basic Wave Propagation (IVP - Initial Value Problems)
------------------------------------------------------
+   uv run python examples/ivp_homogeneous_medium.py
 
-**Start Here**: Learn fundamental wave physics using initial pressure distributions (the simplest source type).
+No GPU required — all examples run on CPU with NumPy.
 
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
+Start with the :doc:`get_started/first_simulation` tutorial, then explore by topic:
 
-   * - Example
-     - Core Concept
-     - Topics
-   * - :ghdir:`examples/legacy/ivp_photoacoustic_waveforms/`
-     - 2D vs 3D wave propagation physics
-     - **IVP** • Wave spreading • Compact support
+Initial Value Problems (IVP)
+----------------------------
 
-Simple Transducers & Sources
------------------------------
+Learn fundamental wave physics using initial pressure distributions.
 
-**Next Step**: Introduction to time-varying sources and practical transducer modeling.
+- :ghfile:`Homogeneous medium <examples/ivp_homogeneous_medium.py>` — simplest 2D simulation
+- :ghfile:`Heterogeneous medium <examples/ivp_heterogeneous_medium.py>` — spatially varying sound speed and density
+- :ghfile:`1D simulation <examples/ivp_1D_simulation.py>` — reflections at impedance boundaries
+- :ghfile:`3D simulation <examples/ivp_3D_simulation.py>` — extending to three dimensions
+- :ghfile:`Binary sensor mask <examples/ivp_binary_sensor_mask.py>` — defining sensor regions
+- :ghfile:`Recording particle velocity <examples/ivp_recording_particle_velocity.py>` — velocity field output
+- :ghfile:`Photoacoustic waveforms <examples/ivp_photoacoustic_waveforms.py>` — 2D vs 3D wave spreading
+- :ghfile:`Loading external image <examples/ivp_loading_external_image.py>` — image-based initial pressure
 
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
+Time-Varying Pressure Sources (TVSP)
+-------------------------------------
 
-   * - Example
-     - Core Concept
-     - Topics
-   * - :ghdir:`examples/legacy/us_defining_transducer/`
-     - Basic ultrasound transducer setup
-     - **US** • Transducer basics • Time-varying sources
-   * - :ghdir:`examples/legacy/at_circular_piston_3D/`
-     - Simple focused geometry
-     - **AT** • 3D focusing • Geometric sources
-   * - :ghdir:`examples/legacy/at_circular_piston_AS/`
-     - Computational efficiency with symmetry
-     - **AT** • Axisymmetric • Computational optimization
+Transducer-driven simulations with time-varying sources.
 
-Medical Imaging Applications
-----------------------------
+- :ghfile:`Monopole source <examples/tvsp_homogeneous_medium_monopole.py>` — single point source
+- :ghfile:`Dipole source <examples/tvsp_homogeneous_medium_dipole.py>` — dipole radiation pattern
+- :ghfile:`Steering linear array <examples/tvsp_steering_linear_array.py>` — beam steering with delays
+- :ghfile:`Snell's law <examples/tvsp_snells_law.py>` — refraction at material boundaries
+- :ghfile:`Doppler effect <examples/tvsp_doppler_effect.py>` — moving source frequency shift
+- :ghfile:`3D simulation <examples/tvsp_3D_simulation.py>` — time-varying source in 3D
+
+Sensor Directivity (SD)
+------------------------
+
+How sensor geometry affects measurements.
+
+- :ghfile:`Directivity modelling 2D <examples/sd_directivity_modelling_2D.py>` — finite sensor size effects
+- :ghfile:`Directivity modelling 3D <examples/sd_directivity_modelling_3D.py>` — 3D directivity
+- :ghfile:`Focused detector 2D <examples/sd_focussed_detector_2D.py>` — directional sensitivity
+- :ghfile:`Focused detector 3D <examples/sd_focussed_detector_3D.py>` — 3D focused sensors
+- :ghfile:`Directional array elements <examples/sd_directional_array_elements.py>` — multi-element arrays
+
+Photoacoustic Reconstruction (PR)
+----------------------------------
+
+Image reconstruction from sensor data.
+
+- :ghfile:`2D FFT line sensor <examples/pr_2D_FFT_line_sensor.py>` — FFT-based reconstruction
+- :ghfile:`3D FFT planar sensor <examples/pr_3D_FFT_planar_sensor.py>` — 3D FFT reconstruction
+
+Numerical Analysis (NA)
+------------------------
+
+Computational methods and optimization.
 
-**Practical Applications**: See how basic concepts combine into real-world medical imaging systems.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
-
-   * - Example
-     - Application
-     - Topics
-   * - :ghdir:`examples/legacy/us_beam_patterns/`
-     - Understanding acoustic beam formation
-     - **US** • Beam focusing • Field patterns
-   * - :ghdir:`examples/legacy/us_bmode_linear_transducer/`
-     - Complete ultrasound imaging pipeline
-     - **US** • Medical imaging • Signal processing
-   * - :ghdir:`examples/legacy/pr_2D_FFT_line_sensor/`
-     - Photoacoustic image reconstruction
-     - **PR** • Image reconstruction • FFT methods
-   * - :ghdir:`examples/legacy/pr_2D_TR_line_sensor/`
-     - Alternative reconstruction approach
-     - **PR** • Time reversal • Reconstruction
-
-Advanced Transducer Modeling (AT - Array Transducers)
------------------------------------------------------
-
-**Complex Geometries**: Learn sophisticated techniques for modeling complex transducer arrays using Cartesian space methods.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
-
-   * - Example
-     - Advanced Technique
-     - Topics
-   * - :ghdir:`examples/legacy/at_array_as_source/`
-     - kWaveArray for complex geometries
-     - **AT** • Array modeling • Anti-aliasing
-   * - :ghdir:`examples/legacy/at_array_as_sensor/`
-     - Complex sensor array geometries
-     - **AT** • Sensor arrays • Flexible positioning
-   * - :ghdir:`examples/legacy/at_linear_array_transducer/`
-     - Multi-element linear arrays
-     - **AT** • Linear arrays • Element spacing
-   * - :ghdir:`examples/legacy/at_focused_bowl_3D/`
-     - 3D focused ultrasound therapy
-     - **AT** • Therapeutic US • 3D focusing
-   * - :ghdir:`examples/legacy/at_focused_annular_array_3D/`
-     - Multi-element focused systems
-     - **AT** • Annular arrays • Complex focusing
-
-Advanced Imaging & Reconstruction (PR - Pressure/Photoacoustic Reconstruction)
--------------------------------------------------------------------------------
-
-**3D Reconstruction**: Advanced reconstruction techniques for photoacoustic and pressure field imaging.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
-
-   * - Example
-     - Reconstruction Method
-     - Topics
-   * - :ghdir:`examples/legacy/pr_3D_FFT_planar_sensor/`
-     - 3D FFT-based reconstruction
-     - **PR** • 3D imaging • Planar arrays
-   * - :ghdir:`examples/legacy/pr_3D_TR_planar_sensor/`
-     - 3D time reversal reconstruction
-     - **PR** • 3D time reversal • Volumetric imaging
-   * - :ghdir:`examples/legacy/us_bmode_phased_array/`
-     - Advanced ultrasound beamforming
-     - **US** • Phased arrays • Electronic steering
-
-Sensor Physics & Directivity (SD - Sensor Directivity)
-------------------------------------------------------
-
-**Sensor Modeling**: Understanding how sensor size, shape, and directivity affect measurements.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
-
-   * - Example
-     - Physics Concept
-     - Topics
-   * - :ghdir:`examples/legacy/sd_directivity_modelling_2D/`
-     - How sensor size affects measurements
-     - **SD** • Directivity • Finite sensor size
-   * - :ghdir:`examples/legacy/sd_focussed_detector_2D/`
-     - Directional sensor sensitivity
-     - **SD** • Focused detection • Sensor design
-   * - :ghdir:`examples/legacy/sd_focussed_detector_3D/`
-     - 3D focused sensor modeling
-     - **SD** • 3D detection • Sensor focusing
-
-Computational Optimization (NA - Numerical Analysis)
-----------------------------------------------------
-
-**Advanced Numerics**: Optimize simulations and understand computational aspects.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 40 20
-
-   * - Example
-     - Optimization Topic
-     - Topics
-   * - :ghdir:`examples/legacy/na_controlling_the_pml/`
-     - Boundary conditions and efficiency
-     - **NA** • PML boundaries • Computational domains
-
-Understanding the Prefixes
---------------------------
-
-- **IVP** = Initial Value Problems (wave propagation from initial pressure)
-- **US** = Ultrasound (medical and therapeutic ultrasound applications)  
-- **AT** = Array Transducers (complex geometries using Cartesian space methods)
-- **PR** = Pressure/Photoacoustic Reconstruction (image reconstruction techniques)
-- **SD** = Sensor Directivity (sensor physics and measurement effects)
-- **NA** = Numerical Analysis (computational optimization and methods)
-
-Learning Strategy
------------------
-
-1. **Start with IVP**: Understand basic wave physics
-2. **Move to simple US/AT**: Learn transducer basics
-3. **Apply to imaging**: See concepts in real applications (US, PR)
-4. **Master advanced AT**: Handle complex geometries
-5. **Understand sensors**: Learn about measurement physics (SD)
-6. **Optimize**: Improve computational efficiency (NA)
-
-Each example builds on the four-component framework, but with increasing sophistication in how the components are configured and used.
+- :ghfile:`Controlling the PML <examples/na_controlling_the_PML.py>` — boundary absorption settings
+- :ghfile:`Source smoothing <examples/na_source_smoothing.py>` — spatial filtering of sources
+- :ghfile:`Filtering part 1 <examples/na_filtering_part_1.py>` — grid-imposed frequency limits
+- :ghfile:`Filtering part 2 <examples/na_filtering_part_2.py>` — filtering source signals
+- :ghfile:`Filtering part 3 <examples/na_filtering_part_3.py>` — combined filtering
+- :ghfile:`Modelling nonlinearity <examples/na_modelling_nonlinearity.py>` — nonlinear wave propagation
+- :ghfile:`Optimising performance <examples/na_optimising_performance.py>` — speed and memory tips

docs/get_started/first_simulation.rst

@@ -187,29 +187,7 @@ What Just Happened?
 3. When waves reach the boundary sensors, pressure is recorded
 4. The result shows the acoustic wavefront arriving at different sensors over time
 
-Next Steps: Explore Real Applications
-------------------------------------
+Next Steps
+----------
 
-Now that you understand the four-component structure, explore these examples to see how the same framework applies to different applications:
-
-**Beginner Examples** (start here):
-
-- :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/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/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/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.
+Explore the :doc:`/examples_guide` to see the four-component framework applied to different problems — from heterogeneous media to beam steering, Doppler effects, and image reconstruction.