Skip to content

Commit 96441a4

Browse files
waltsimsdjpscoderabbitai[bot]
authored
Improve documentation with pedagogical approach (#625)
* Improve documentation with pedagogical approach - Add conceptual introductions to four core components (Grid, Medium, Source, Sensor) - Create comprehensive "Your First Simulation" tutorial - Add pedagogical examples guide organized by concept complexity - Reorganize main documentation structure with clear learning progression - Explain example naming conventions (IVP, US, AT, PR, SD, NA) - Maintain focus on four-component framework throughout * Fix index * Fix links * use :ghfile: * fix links * Restructure * update index * Fix badge * fix link * ignore license links * try again * 3rd time * Update README.md this link should pass the link checker * Update link-check.yml - explicitly exclude problematic link * 📝 Add docstrings to `feature/improve-documentation-pedagogical` (#638) Docstrings generation was requested by @waltsims. * #625 (comment) The following files were modified: * `docs/conf.py` Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * simplify conf.py * Fix docs formatting * remove refferences to gpuArray * Make links more robust. * clean docs * fix char * update uv lock * fix docs --------- Co-authored-by: Walter Simson <waltsims@users.noreply.github.com> Co-authored-by: David Sinden <djps@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent e1311b3 commit 96441a4

File tree

56 files changed

+2830
-106
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+2830
-106
lines changed

‎.github/workflows/link-check.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Markdown Link Validator
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [ main, master ]
7+
8+
jobs:
9+
linkChecker:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: read
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 1
18+
19+
- name: Check links with lychee
20+
# See https://github.com/lycheeverse/lychee-action
21+
uses: lycheeverse/lychee-action@v2
22+
with:
23+
# Check all markdown and reStructuredText files
24+
args: >-
25+
--verbose
26+
--no-progress
27+
--max-concurrency 12
28+
--max-retries 3
29+
--retry-wait-time 4
30+
--accept 200,206,403,429
31+
--exclude-path "docs/get_started/legacy_licenses/gpl-3.0.rst"
32+
"**/*.md" "**/*.rst"
33+
# Fail the build on any broken link
34+
fail: true
35+
env:
36+
# Exclude localhost and badges
37+
LY_CHEE_EXCLUDE: "http://localhost,https://localhost,https://127.0.0.1,https://img.shields.io"

‎docs/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# k-Wave-python
1+
# k-wave-python
22

3-
[![Support](https://dcbadge.vercel.app/api/server/Yq5Qj6D9vN?style=flat)](https://discord.gg/Yq5Qj6D9vN)
3+
[![Support](https://img.shields.io/discord/1234942672418897960?style=flat&logo=discord)](https://discord.gg/your-invite-code)
44
[![Documentation Status](https://readthedocs.org/projects/k-wave-python/badge/?version=latest)](https://k-wave-python.readthedocs.io/en/latest/?badge=latest)
55
[![codecov](https://codecov.io/gh/waltsims/k-wave-python/graph/badge.svg?token=6ofwtPiDNG)](https://codecov.io/gh/waltsims/k-wave-python)
66
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/waltsims/k-wave-python/master)
@@ -19,7 +19,7 @@ to leverage pythonic practices.
1919

2020
![](_static/example_bmode.png)
2121

22-
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/master/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
22+
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).
2323

2424
This example file steps through the process of:
2525
1. Generating a simulation medium

‎docs/conf.py‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,46 @@
2323
"sphinx.ext.napoleon",
2424
"sphinx.ext.viewcode",
2525
"sphinx_mdinclude",
26+
"sphinx.ext.extlinks", # Enables :ghfile: external links
2627
]
2728

29+
# Provide a simple GitHub branch/sha fallback for linking to example files.
30+
# Priority: explicit override via _GITHUB_BRANCH →
31+
# READTHEDOCS_GIT_IDENTIFIER (commit) →
32+
# READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME →
33+
# "master".
34+
import os
35+
36+
37+
def _detect_current_branch() -> str:
38+
"""Return a branch/commit identifier for GitHub links with minimal logic.
39+
40+
Order: _GITHUB_BRANCH override → READTHEDOCS_GIT_IDENTIFIER (commit) →
41+
READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME → "master".
42+
"""
43+
return (
44+
os.getenv("_GITHUB_BRANCH")
45+
or os.getenv("READTHEDOCS_GIT_IDENTIFIER")
46+
or os.getenv("READTHEDOCS_GIT_BRANCH")
47+
or os.getenv("GITHUB_REF_NAME")
48+
or "master"
49+
)
50+
51+
52+
_GITHUB_BRANCH = _detect_current_branch()
53+
54+
# Define an extlink so we can write :ghfile:`examples/foo.py` in .rst/.md
55+
extlinks = {
56+
"ghfile": (
57+
f"https://github.com/waltsims/k-wave-python/blob/{_GITHUB_BRANCH}/%s",
58+
"%s", # pass-through caption
59+
),
60+
"ghdir": (
61+
f"https://github.com/waltsims/k-wave-python/tree/{_GITHUB_BRANCH}/%s",
62+
"%s",
63+
),
64+
}
65+
2866
source_suffix = [".rst", ".md"]
2967
templates_path = ["_templates"]
3068
exclude_patterns = ["README.md", "_build", "Thumbs.db", ".DS_Store"]
@@ -36,9 +74,10 @@
3674
html_theme = "furo"
3775
html_theme_options = {
3876
"source_repository": "https://github.com/waltsims/k-wave-python",
39-
"source_branch": "master",
77+
"source_branch": _GITHUB_BRANCH,
4078
"source_directory": "docs/",
4179
}
80+
4281
html_static_path = ["_static"]
4382

4483
# -- Options for todo extension ----------------------------------------------

‎docs/examples_guide.rst‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
Examples: k-Wave-Python Step-by-Step
2+
=======================
3+
4+
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.
5+
6+
Start with the :doc:`get_started/first_simulation` tutorial, then follow this suggested learning path:
7+
8+
Basic Wave Propagation (IVP - Initial Value Problems)
9+
-----------------------------------------------------
10+
11+
**Start Here**: Learn fundamental wave physics using initial pressure distributions (the simplest source type).
12+
13+
.. list-table::
14+
:header-rows: 1
15+
:widths: 40 40 20
16+
17+
* - Example
18+
- Core Concept
19+
- Topics
20+
* - :ghdir:`examples/ivp_photoacoustic_waveforms/`
21+
- 2D vs 3D wave propagation physics
22+
- **IVP** • Wave spreading • Compact support
23+
24+
Simple Transducers & Sources
25+
-----------------------------
26+
27+
**Next Step**: Introduction to time-varying sources and practical transducer modeling.
28+
29+
.. list-table::
30+
:header-rows: 1
31+
:widths: 40 40 20
32+
33+
* - Example
34+
- Core Concept
35+
- Topics
36+
* - :ghdir:`examples/us_defining_transducer/`
37+
- Basic ultrasound transducer setup
38+
- **US** • Transducer basics • Time-varying sources
39+
* - :ghdir:`examples/at_circular_piston_3D/`
40+
- Simple focused geometry
41+
- **AT** • 3D focusing • Geometric sources
42+
* - :ghdir:`examples/at_circular_piston_AS/`
43+
- Computational efficiency with symmetry
44+
- **AT** • Axisymmetric • Computational optimization
45+
46+
Medical Imaging Applications
47+
----------------------------
48+
49+
**Practical Applications**: See how basic concepts combine into real-world medical imaging systems.
50+
51+
.. list-table::
52+
:header-rows: 1
53+
:widths: 40 40 20
54+
55+
* - Example
56+
- Application
57+
- Topics
58+
* - :ghdir:`examples/us_beam_patterns/`
59+
- Understanding acoustic beam formation
60+
- **US** • Beam focusing • Field patterns
61+
* - :ghdir:`examples/us_bmode_linear_transducer/`
62+
- Complete ultrasound imaging pipeline
63+
- **US** • Medical imaging • Signal processing
64+
* - :ghdir:`examples/pr_2D_FFT_line_sensor/`
65+
- Photoacoustic image reconstruction
66+
- **PR** • Image reconstruction • FFT methods
67+
* - :ghdir:`examples/pr_2D_TR_line_sensor/`
68+
- Alternative reconstruction approach
69+
- **PR** • Time reversal • Reconstruction
70+
71+
Advanced Transducer Modeling (AT - Array Transducers)
72+
-----------------------------------------------------
73+
74+
**Complex Geometries**: Learn sophisticated techniques for modeling complex transducer arrays using Cartesian space methods.
75+
76+
.. list-table::
77+
:header-rows: 1
78+
:widths: 40 40 20
79+
80+
* - Example
81+
- Advanced Technique
82+
- Topics
83+
* - :ghdir:`examples/at_array_as_source/`
84+
- kWaveArray for complex geometries
85+
- **AT** • Array modeling • Anti-aliasing
86+
* - :ghdir:`examples/at_array_as_sensor/`
87+
- Complex sensor array geometries
88+
- **AT** • Sensor arrays • Flexible positioning
89+
* - :ghdir:`examples/at_linear_array_transducer/`
90+
- Multi-element linear arrays
91+
- **AT** • Linear arrays • Element spacing
92+
* - :ghdir:`examples/at_focused_bowl_3D/`
93+
- 3D focused ultrasound therapy
94+
- **AT** • Therapeutic US • 3D focusing
95+
* - :ghdir:`examples/at_focused_annular_array_3D/`
96+
- Multi-element focused systems
97+
- **AT** • Annular arrays • Complex focusing
98+
99+
Advanced Imaging & Reconstruction (PR - Pressure/Photoacoustic Reconstruction)
100+
-------------------------------------------------------------------------------
101+
102+
**3D Reconstruction**: Advanced reconstruction techniques for photoacoustic and pressure field imaging.
103+
104+
.. list-table::
105+
:header-rows: 1
106+
:widths: 40 40 20
107+
108+
* - Example
109+
- Reconstruction Method
110+
- Topics
111+
* - :ghdir:`examples/pr_3D_FFT_planar_sensor/`
112+
- 3D FFT-based reconstruction
113+
- **PR** • 3D imaging • Planar arrays
114+
* - :ghdir:`examples/pr_3D_TR_planar_sensor/`
115+
- 3D time reversal reconstruction
116+
- **PR** • 3D time reversal • Volumetric imaging
117+
* - :ghdir:`examples/us_bmode_phased_array/`
118+
- Advanced ultrasound beamforming
119+
- **US** • Phased arrays • Electronic steering
120+
121+
Sensor Physics & Directivity (SD - Sensor Directivity)
122+
------------------------------------------------------
123+
124+
**Sensor Modeling**: Understanding how sensor size, shape, and directivity affect measurements.
125+
126+
.. list-table::
127+
:header-rows: 1
128+
:widths: 40 40 20
129+
130+
* - Example
131+
- Physics Concept
132+
- Topics
133+
* - :ghdir:`examples/sd_directivity_modelling_2D/`
134+
- How sensor size affects measurements
135+
- **SD** • Directivity • Finite sensor size
136+
* - :ghdir:`examples/sd_focussed_detector_2D/`
137+
- Directional sensor sensitivity
138+
- **SD** • Focused detection • Sensor design
139+
* - :ghdir:`examples/sd_focussed_detector_3D/`
140+
- 3D focused sensor modeling
141+
- **SD** • 3D detection • Sensor focusing
142+
143+
Computational Optimization (NA - Numerical Analysis)
144+
----------------------------------------------------
145+
146+
**Advanced Numerics**: Optimize simulations and understand computational aspects.
147+
148+
.. list-table::
149+
:header-rows: 1
150+
:widths: 40 40 20
151+
152+
* - Example
153+
- Optimization Topic
154+
- Topics
155+
* - :ghdir:`examples/na_controlling_the_pml/`
156+
- Boundary conditions and efficiency
157+
- **NA** • PML boundaries • Computational domains
158+
159+
Understanding the Prefixes
160+
--------------------------
161+
162+
- **IVP** = Initial Value Problems (wave propagation from initial pressure)
163+
- **US** = Ultrasound (medical and therapeutic ultrasound applications)
164+
- **AT** = Array Transducers (complex geometries using Cartesian space methods)
165+
- **PR** = Pressure/Photoacoustic Reconstruction (image reconstruction techniques)
166+
- **SD** = Sensor Directivity (sensor physics and measurement effects)
167+
- **NA** = Numerical Analysis (computational optimization and methods)
168+
169+
Learning Strategy
170+
-----------------
171+
172+
1. **Start with IVP**: Understand basic wave physics
173+
2. **Move to simple US/AT**: Learn transducer basics
174+
3. **Apply to imaging**: See concepts in real applications (US, PR)
175+
4. **Master advanced AT**: Handle complex geometries
176+
5. **Understand sensors**: Learn about measurement physics (SD)
177+
6. **Optimize**: Improve computational efficiency (NA)
178+
179+
Each example builds on the four-component framework, but with increasing sophistication in how the components are configured and used.

0 commit comments

Comments
 (0)