k-Wave-python 0.6.0__tar.gz → 0.6.1__tar.gz

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.claude/settings.local.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(python:*)",
+      "Bash(uv run python:*)",
+      "Bash(PYTHONPATH=. uv run:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "WebSearch",
+      "WebFetch(domain:www.k-wave.org)",
+      "WebFetch(domain:nanobind.readthedocs.io)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(git remote:*)",
+      "Bash(gh pr:*)",
+      "mcp__greptile__list_pull_requests",
+      "mcp__greptile__trigger_code_review",
+      "mcp__greptile__list_code_reviews",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/ivp_photoacoustic_waveforms/ivp_photoacoustic_waveforms.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/pr_2D_FFT_line_sensor/pr_2D_FFT_line_sensor.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/pr_2D_TR_line_sensor/pr_2D_TR_line_sensor.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_array_as_sensor/at_array_as_sensor.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_array_as_source/at_array_as_source.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/sd_directivity_modelling_2D/sd_directivity_modelling_2D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/sd_focussed_detector_2D/sd_focussed_detector_2D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/sd_focussed_detector_3D/sd_focussed_detector_3D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_circular_piston_3D/at_circular_piston_3D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_circular_piston_AS/at_circular_piston_AS.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_focused_bowl_AS/at_focused_bowl_AS.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_focused_bowl_3D/at_focused_bowl_3D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_focused_annular_array_3D/at_focused_annular_array_3D.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/at_linear_array_transducer/at_linear_array_transducer.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/pr_3D_FFT_planar_sensor/pr_3D_FFT_planar_sensor.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/pr_3D_TR_planar_sensor/pr_3D_TR_planar_sensor.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/us_defining_transducer/us_defining_transducer.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/us_beam_patterns/us_beam_patterns.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/us_bmode_phased_array/us_bmode_phased_array.py)",
+      "Bash(KWAVE_DEVICE=cpu uv run python examples/checkpointing/checkpoint.py)",
+      "Bash(KWAVE_FORCE_CPU=1 uv run python examples/pr_2D_FFT_line_sensor/pr_2D_FFT_line_sensor.py)",
+      "mcp__greptile__list_merge_request_comments"
+    ]
+  }
+}

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.git

@@ -0,0 +1 @@
+gitdir: /Users/Walter/git/k-wave-python/.git/worktrees/add-agent-cli

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing Guidelines
+
+Thanks for your interest in contributing an example to k-wave-python!
+
+##  Issues
+
+### Create a new issue
+
+If you would like to contribute to this project, search to see if a related issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.
+
+### Solve an open issue
+
+Have a look through our existing issues to find one that interests you.
+You can narrow down the search using labels as filters.
+If you find an issue to work on, you are welcome to open a PR with a fix.
+
+## Make changes
+
+Fork k-wave-python and make changes you would like to contribute to your fork.
+
+## Open a Pull-Request
+
+* Complete the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request.
+
+* [Link PR to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
+
+* Don't forget to click the checkbox to [allow maintainer edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so you PR can be updated before a merge.
+
+

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. Windows/Linux]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/ISSUE_TEMPLATE/code_enhancement.md

@@ -0,0 +1,28 @@
+---
+name: Code Enhancement
+about: Suggest changes to improve code quality, reduce complexity, and increase efficiency
+title: "[ENHANCE] Brief description of enhancement"
+labels: enhancement
+assignees: ''
+
+---
+
+## Description of the Enhancement
+Provide a clear and concise description of what you want to happen. Explain the current state and the exact changes. 
+
+## Justification for the Enhancement
+<!-- Explain why these changes should be made. How do they benefit the project? -->
+1. **Reduces Complexity**: Detail how the changes simplify the code, e.g. reducing the number of lines or eliminating redundant functions.
+2. **Improves Efficiency**: Describe how the changes will enhance performance, e.g. decreasing execution time, or reducing memory consumption.
+3. **Improve Readability**: Describe how readability benefits from changes. 
+
+## Impact of Changes
+<!-- Discuss any possible impacts this change might have on other parts of the project. -->
+List any other components or modules that might be affected by these changes.
+
+## Screenshots/Examples
+<!-- Add screenshot or other means of showing improvement-->
+If applicable, add screenshots, code snippets, or links to help illustrate the enhancement. 
+
+## Additional Context
+Add any other context or information about the enhancement here.

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/ISSUE_TEMPLATE/example.md

@@ -0,0 +1,17 @@
+---
+name: Example
+about: Request an example to help others get started
+title: "[Example]"
+labels: example
+assignees: ''
+
+---
+
+**Describe the example**
+What example do you wish was included in k-wave-python?  What functionality of principle should it display?
+
+**Sources**
+If applicable, add sources of the example from literature or other projects.
+
+**Additional context**
+Add any other context about the example here.

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '[Feature]'
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/codecov.yml

@@ -0,0 +1,5 @@
+coverage:
+  status:
+    project:
+      default:
+        threshold: 1%

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.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 

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/link-check.yml

@@ -0,0 +1,35 @@
+name: Markdown Link Validator
+
+on:
+  pull_request:
+  push:
+    branches: [ main, master ]
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Check links with lychee
+        # See https://github.com/lycheeverse/lychee-action
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            --max-concurrency 20
+            --exclude-path "docs/get_started/legacy_licenses/"
+            --exclude-link-local
+            --exclude "https://doi.org/"
+            --exclude "https://pubs.aip.org"
+            --exclude "https://www.gnu.org"
+            --exclude "https://fsf.org"
+            --exclude "http://www.k-wave.org"
+            "**/*.md" "**/*.rst"
+          fail: true

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/pytest.yml

@@ -0,0 +1,124 @@
+name: pytest
+
+on: [push, pull_request]
+
+jobs:
+  collect_references:
+    name: collect_references
+    outputs:
+      MATLAB_REFS_HASH: ${{ steps.matlab-refs-hash.outputs.MATLAB_REFS_HASH }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+        with:
+          path: k-Wave-python
+      # Calculate hash value that will be used as a cache key
+      - name: Calculate matlab references hash
+        id: matlab-refs-hash
+        run: | 
+          MATLAB_REFS_HASH=$(find ./k-Wave-python/tests/matlab_test_data_collectors/matlab_collectors -type f | xargs sha1sum | sha1sum |  awk '{ print $1 }');
+          echo "MATLAB_REFS_HASH=$MATLAB_REFS_HASH" >> $GITHUB_OUTPUT
+      # Pull cache if exists, otherwise cache will be created at the specified path
+      - name: Cache collected references
+        uses: actions/cache@v3
+        id: matlab-refs-cache
+        env:
+          cache-name: cache-matlab-references
+        with:
+            key: ${{ steps.matlab-refs-hash.outputs.MATLAB_REFS_HASH }}
+            path: ./collectedValues.tar.gz
+      - name: Checkout reference k-Wave repo
+        uses: actions/checkout@v4
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+        with:
+          repository: ucl-bug/k-wave
+          path: k-wave
+          ref: v1.4.0
+      - name: setup MATLAB
+        uses: matlab-actions/setup-matlab@v1
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+      - name: run reference generation
+        uses: matlab-actions/run-command@v1
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+        with:
+          command: |
+            ls;
+            pwd;
+            if exist('k-wave/k-Wave'); ls 'k-wave/k-Wave'; end;
+            addpath('k-Wave-python','k-wave/k-Wave');
+            cd k-Wave-python/tests/matlab_test_data_collectors;
+            run_all_collectors;
+      - name: Compress generated references
+        uses: a7ul/tar-action@v1.1.0
+        if: ${{ steps.matlab-refs-cache.outputs.cache-hit != 'true' }}
+        with:
+          command: c
+          cwd: ./k-Wave-python/tests/matlab_test_data_collectors/matlab_collectors/
+          files: |
+            ./collectedValues
+          outPath: collectedValues.tar.gz
+      - name: Upload reference values artifact
+        id: artifact-upload-step
+        uses: actions/upload-artifact@v4
+        with:
+          name: matlab_reference_test_values
+          path: collectedValues.tar.gz
+          # overwrite: true
+          
+      - name: Output artifact URL
+        run:  echo 'Artifact URL is ${{ steps.artifact-upload-step.outputs.artifact-url }}'
+  test:
+    needs: collect_references
+    strategy:
+      matrix:
+        os: [ "windows-latest", "ubuntu-latest" , "macos-latest"]
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
+    runs-on: ${{matrix.os}}
+    steps:
+      - uses: actions/checkout@v4
+      # Pull the cache based on the hash value
+      - name: Cache collected references
+        uses: actions/cache@v3
+        id: cache-matlab-refs
+        env:
+          cache-name: cache-matlab-references
+        with:
+            key: ${{ needs.collect_references.outputs.MATLAB_REFS_HASH }}
+            path: ./collectedValues.tar.gz
+            fail-on-cache-miss: true
+            enableCrossOsArchive: true
+      # Now we have the references archive available in this job, proceed by unpacking it
+      - name: unpack collectedValues
+        uses: a7ul/tar-action@v1.1.0
+        with:
+          command: x
+          cwd: ./tests/matlab_test_data_collectors/python_testers/
+          files: ${{github.workspace}}/collectedValues.tar.gz
+      - name: where are the files?
+        run: |
+          ls ./tests/matlab_test_data_collectors/python_testers/
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          pip install '.[test]'
+      - name: Test with pytest
+        run: |
+          coverage run 
+      - name: Create coverage report
+        run: |
+          coverage xml
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          env_vars: ${{matrix.os}},${{ matrix.python-version }}
+          fail_ci_if_error: true
+          flags: ${{matrix.os}},${{ matrix.python-version }}
+          name: ${{matrix.os}},${{ matrix.python-version }}
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/ruff.yml

@@ -0,0 +1,9 @@
+name: Ruff
+on: [push, pull_request]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v3
+      - uses: astral-sh/ruff-action@v1

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.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 }}" 

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/test_example.yml

@@ -0,0 +1,29 @@
+name: test_example
+
+on: workflow_dispatch  # disabled: gdown fails due to Google Drive bot detection
+
+jobs:
+  test_example:
+    strategy:
+      matrix:
+        os: [ "windows-latest", "ubuntu-latest" , "macos-latest"]
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
+    runs-on: ${{matrix.os}}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          pip install -e '.[example]'
+      - name: Run example script
+        run: |
+          python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
+      - name: Upload example results
+        uses: actions/upload-artifact@v4
+        with:
+          name: example_bmode_reconstruction_results_${{ matrix.os }}_${{ matrix.python-version }}
+          path: ${{ github.workspace }}/example_bmode.png

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/test_optional_dependencies.yml

@@ -0,0 +1,29 @@
+name: test_optional_requirements
+
+on:
+  push:
+    paths:
+      - 'pyproject.toml'
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+
+jobs:
+    test_install:
+        strategy:
+            matrix:
+                os: [ "windows-latest", "ubuntu-latest" , "macos-latest"]
+                python-version: [ "3.10", "3.11", "3.12", "3.13" ]
+                extra_requirements: [ "test", "examples", "docs", "dev", "all" ]
+        runs-on: ${{matrix.os}}
+        steps:
+            - uses: actions/checkout@v4
+            # Pull the cache based on the hash value
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+                  cache: 'pip'
+            - name: Install dependencies
+              run: |
+                  pip install '.[${{ matrix.extra_requirements }}]'

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/.github/workflows/test_pages.yml

@@ -0,0 +1,18 @@
+name: test_pages
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+        cache: 'pip'
+    - name: Build and Commit
+      uses: waltsims/pages@pyproject.toml-support
+      with:
+        pyproject_toml_deps: ".[docs]"

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

{k_wave_python-0.6.0 → k_wave_python-0.6.1/.claude/worktrees/add-agent-cli}/docs/README.md

@@ -8,7 +8,7 @@
 This project is a Python implementation of v1.4.0 of the [MATLAB toolbox k-Wave](http://www.k-wave.org/) as well as an
 interface to the pre-compiled v1.3 of k-Wave simulation binaries, which support NVIDIA sm 5.0 (Maxwell) to sm 9.0a (Hopper) GPUs.
 
-**New in v0.6.0:** Unified `kspaceFirstOrder()` API with a pure NumPy/CuPy solver. See the [API guide](https://k-wave-python.readthedocs.io/en/latest/get_started/new_api.html).
+**New in v0.6.0:** Unified `kspaceFirstOrder()` API with a pure NumPy/CuPy solver. See the [API guide](https://k-wave-python.readthedocs.io/en/latest/get_started/new_api.html). The `kspaceFirstOrder()` API is experimental and may change before v1.0.0.
 
 ## Mission
 

k_wave_python-0.6.1/.claude/worktrees/add-agent-cli/docs/conf.py

@@ -0,0 +1,101 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+from kwave import __version__
+
+project = "k-Wave-python"
+copyright = "2024, Walter Simson, Farid Yagubbayli"
+author = "Walter Simson, Farid Yagubbayli"
+version = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx_toolbox.code",
+    "sphinx_copybutton",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_mdinclude",
+    "sphinx.ext.extlinks",  # Enables :ghfile: external links
+]
+
+# Provide a simple GitHub branch/sha fallback for linking to example files.
+# Priority: explicit override via _GITHUB_BRANCH →
+#           READTHEDOCS_GIT_IDENTIFIER (commit) →
+#           READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME →
+#           "master".
+import os
+
+
+def _detect_current_branch() -> str:
+    """Return a branch/commit identifier for GitHub links with minimal logic.
+
+    Order: _GITHUB_BRANCH override → READTHEDOCS_GIT_IDENTIFIER (commit) →
+    READTHEDOCS_GIT_BRANCH / GITHUB_REF_NAME → "master".
+    """
+    return (
+        os.getenv("_GITHUB_BRANCH")
+        or os.getenv("READTHEDOCS_GIT_IDENTIFIER")
+        or os.getenv("READTHEDOCS_GIT_BRANCH")
+        or os.getenv("GITHUB_REF_NAME")
+        or "master"
+    )
+
+
+_GITHUB_BRANCH = _detect_current_branch()
+
+# Define an extlink so we can write :ghfile:`examples/foo.py` in .rst/.md
+extlinks = {
+    "ghfile": (
+        f"https://github.com/waltsims/k-wave-python/blob/{_GITHUB_BRANCH}/%s",
+        "%s",  # pass-through caption
+    ),
+    "ghdir": (
+        f"https://github.com/waltsims/k-wave-python/tree/{_GITHUB_BRANCH}/%s",
+        "%s",
+    ),
+}
+
+source_suffix = [".rst", ".md"]
+templates_path = ["_templates"]
+exclude_patterns = ["README.md", "_build", "Thumbs.db", ".DS_Store"]
+
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "furo"
+html_theme_options = {
+    "source_repository": "https://github.com/waltsims/k-wave-python",
+    "source_branch": _GITHUB_BRANCH,
+    "source_directory": "docs/",
+}
+
+html_static_path = ["_static"]
+
+# -- Options for todo extension ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+
+todo_include_todos = True
+
+# -- Options for autodoc ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+
+# Don't show class signature with the class' name.
+autodoc_class_signature = "separated"
+
+# Remove module name from object names
+add_module_names = False