# waltsims/k-wave-python architecture

> Architecture diagram of the GitHub repository waltsims/k-wave-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waltsims/k-wave-python
- Repository: https://github.com/waltsims/k-wave-python

## Overview

##### Project Type and Purpose
- This is a simulation library with a focus on acoustic wave propagation, reconstruction, and related signal processing.
- Its main use cases include medical imaging simulation, algorithm prototyping, and testing. The README and extensive examples clearly show that the project is centered on simulating wave physics and reconstructing images using various acoustic and reconstruction algorithms.

##### File Structure – Identify Main Components
- Core Library (kwave package):
- Modules such as kWaveSimulation.py, kspaceFirstOrder2D.py, kspaceFirstOrder3D.py, and kspaceFirstOrderAS.py represent central simulation engines.
- Submodules like kwave/kWaveSimulation_helper/ encapsulate helper functions for simulation (e.g., creating absorption variables, scaling source terms, saving to disk, etc.).
- The options folder (kwave/options/) holds simulation configuration options.
- The reconstruction directory contains modules for data post-processing including beamforming and other reconstruction techniques.
- The utils directory (kwave/utils/) includes a range of mathematical, data handling, and interfacing utilities (e.g., angular spectrum, filters, PML (perfectly matched layer) handling, plotting, etc.).
- Other files like data.py, enums.py, executor.py, kgrid.py, kmedium.py, ksensor.py, ksource.py, and ktransducer.py denote that the simulation involves detailed setup for simulation media, sensor/transducer configuration, and wave sources.
- Example Applications:
- The examples folder contains numerous notebooks and Python scripts that demonstrate various use cases, like B-mode imaging, directivity modelling, focused bowl simulations, and more. These exemplify how the core simulation functionalities are used.
- Testing and Continuous Integration:
- The tests folder, along with GitHub workflow files (.github/workflows/), pre-commit hooks, and other CI/CD configuration files, indicates a robust testing and validation framework.
- Documentation:
- The docs folder and the accompanying Read the Docs configuration file (.readthedocs.yaml) imply well-maintained project documentation.
- Development and Build Tools:
- Files such as Dockerfile, Makefile, pyproject.toml, and configuration files for code quality (e.g., ruff, pytest) show how the project is built, maintained, and tested.

##### Architectural Patterns and Component Interactions
- The design follows a layered or modular architecture:
- The lowest layer consists of utilities and helper functions that deal with numerical methods and data processing (inside kwave/utils/).
- The core simulation layer (kwave/kWaveSimulation, kWaveSimulation_helper, and other simulation-specific modules) builds on these utilities.
- The API exposes configurations (via options) and simulation control (via executor.py) to the user.
- Reconstruction and post-processing modules (kwave/reconstruction/) use the simulated data for imaging insights.
- Besides the core library, external components include:
- Pre-compiled simulation binaries that are invoked by the project for GPU-enabled simulation.
- External workflows (as seen in the GitHub actions) to run tests, build docs, and verify code quality.
- Example notebooks and scripts as entry points for new users to interact with the simulation engine.

a. Components to include:
- Core Simulation Engine (kwave package)
– kWaveSimulation and its helper modules (simulation setup, numerical scheme, simulation execution)
– Options/configuration submodules for simulation parameters.
– Data modules for the simulation grid (kgrid), medium (kmedium), sensor (ksensor), source (ksource), and transducer (ktransducer).
- Post-Processing and Reconstruction
– Reconstruction methods (beamform, conversion, shifted transform, etc.)
- Utility and Helper Functions
– Math, filtering, IO, PML, and other helper routines.
- Pre-compiled Binary Interface
– A component showing where and how the project integrates with the precompiled binaries (which handle GPU acceleration).
- Examples and User Applications
– Use case flow from simulation setup (in examples) to simulation execution and reconstruction.
- Testing and CI Infrastructure
- Documentation and Development Tools
– Documents, build scripts (Makefile, Dockerfile), and GitHub workflows.

b. Relationships and Data Flow:
- API layer that interacts with core simulation modules and then feeds into reconstruction utilities.
- That utility modules support both simulation and reconstruction.
- That outputs (simulation data, reconstructed images) are then used both by user interfaces (example notebooks) and validated by tests.

c. Visual Guidelines:

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Options and Configuration
    O1["Options/Configuration"]:::options

    %% Simulation Setup Subgraph
    subgraph "Simulation Setup"
        G1["kgrid.py (Simulation Grid)"]:::setup
        G2["kmedium.py (Medium Setup)"]:::setup
        G3["ksensor.py (Sensor Setup)"]:::setup
        G4["ksource.py (Source Setup)"]:::setup
        G5["ktransducer.py (Transducer Setup)"]:::setup
    end

    %% Core Simulation Engine Subgraph
    subgraph "Core Simulation Engine"
        C1["kWaveSimulation.py (Simulation Engine)"]:::core
        C2["kWaveSimulation_helper (Helper Modules)"]:::core
    end

    %% Utility Functions
    U1["Utility & Helper Functions"]:::utils

    %% GPU Binary Interface (Pre-compiled Binaries)
    GBI["GPU Binary Interface (Precompiled Binaries)"]:::external

    %% Reconstruction and Post-Processing
    R1["Reconstruction & Post-Processing"]:::recon

    %% Example Applications
    E1["Example Applications"]:::examples

    %% Testing & Continuous Integration Subgraph
    subgraph "Testing & CI"
        TC1["Tests (Unit/Integration)"]:::ci
        TC2["CI Workflows"]:::ci
    end

    %% Documentation Subgraph
    subgraph "Documentation"
        D1["Documentation Files"]:::docs
        D2["Docs Config (.readthedocs.yaml)"]:::docs
    end

    %% Development and Build Tools Subgraph
    subgraph "Build Tools & Dev"
        DB1["Dockerfile"]:::build
        DB2["Makefile"]:::build
        DB3["pyproject.toml (Project Config)"]:::build
    end

    %% Data Flow Connections
    O1 -->|"provides configuration"| C1
    G1 -->|"defines simulation grid"| C1
    %% Utilities support core and reconstruction
    U1 -->|"supports computations"| C1
    U1 -->|"supports post-processing"| R1
    %% Core Simulation Engine invokes GPU Binary interface
    C1 -->|"accelerates simulation"| GBI
    %% Core simulation feeds into reconstruction
    C1 -->|"simulation output"| R1
    %% Reconstruction produces results for examples
    R1 -->|"produces reconstructed data"| E1

    %% Testing and CI connections (dashed for validation pipelines)
    O1 ---|"validated by"| TC1
    C1 ---|"tested by"| TC1
    R1 ---|"verified by"| TC1
    C1 ---|"monitored by"| TC2

    %% Documentation and Build Tools support configuration
    D1 ---|"documents"| O1
    DB1 ---|"builds project"| O1

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef setup fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef options fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef recon fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef utils fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef examples fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef ci fill:#FCF3CF,stroke:#333,stroke-width:2px;
    classDef docs fill:#D6EAF8,stroke:#333,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#333,stroke-width:2px;

    %% Click Events
    click O1 "https://github.com/waltsims/k-wave-python/tree/master/kwave/options/"
    click G1 "https://github.com/waltsims/k-wave-python/blob/master/kwave/kgrid.py"
    click G2 "https://github.com/waltsims/k-wave-python/blob/master/kwave/kmedium.py"
    click G3 "https://github.com/waltsims/k-wave-python/blob/master/kwave/ksensor.py"
    click G4 "https://github.com/waltsims/k-wave-python/blob/master/kwave/ksource.py"
    click G5 "https://github.com/waltsims/k-wave-python/blob/master/kwave/ktransducer.py"
    click C1 "https://github.com/waltsims/k-wave-python/blob/master/kwave/kWaveSimulation.py"
    click C2 "https://github.com/waltsims/k-wave-python/tree/master/kwave/kWaveSimulation_helper/"
    click U1 "https://github.com/waltsims/k-wave-python/tree/master/kwave/utils/"
    click R1 "https://github.com/waltsims/k-wave-python/tree/master/kwave/reconstruction/"
    click E1 "https://github.com/waltsims/k-wave-python/tree/master/examples/"
    click TC1 "https://github.com/waltsims/k-wave-python/tree/master/tests/"
    click TC2 "https://github.com/waltsims/k-wave-python/tree/master/.github/workflows/"
    click D1 "https://github.com/waltsims/k-wave-python/tree/master/docs/"
    click D2 "https://github.com/waltsims/k-wave-python/blob/master/.readthedocs.yaml"
    click DB1 "https://github.com/waltsims/k-wave-python/tree/master/Dockerfile"
    click DB2 "https://github.com/waltsims/k-wave-python/tree/master/Makefile"
    click DB3 "https://github.com/waltsims/k-wave-python/blob/master/pyproject.toml"
```
