{"id":45019348,"url":"https://github.com/pinton-lab/fullwave25","last_synced_at":"2026-02-22T02:11:24.907Z","repository":{"id":321848463,"uuid":"1085335402","full_name":"pinton-lab/fullwave25","owner":"pinton-lab","description":"Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities","archived":false,"fork":false,"pushed_at":"2026-02-19T00:41:09.000Z","size":82183,"stargazers_count":39,"open_issues_count":8,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-19T06:55:19.952Z","etag":null,"topics":["fdtd","finite-difference","simulation","ultrasound"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinton-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T22:40:33.000Z","updated_at":"2026-02-19T04:12:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pinton-lab/fullwave25","commit_stats":null,"previous_names":["pinton-lab/fullwave25"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/pinton-lab/fullwave25","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinton-lab%2Ffullwave25","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinton-lab%2Ffullwave25/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinton-lab%2Ffullwave25/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinton-lab%2Ffullwave25/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinton-lab","download_url":"https://codeload.github.com/pinton-lab/fullwave25/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinton-lab%2Ffullwave25/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29703293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T23:35:04.139Z","status":"online","status_checked_at":"2026-02-22T02:00:08.193Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fdtd","finite-difference","simulation","ultrasound"],"created_at":"2026-02-19T02:03:00.462Z","updated_at":"2026-02-22T02:11:24.898Z","avatar_url":"https://github.com/pinton-lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities\n\n\u003ca href=\"https://doi.org/10.5281/zenodo.17625780\"\u003e\u003cimg src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.17625780.svg\" alt=\"DOI\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pepy.tech/projects/fullwave25\"\u003e\u003cimg src=\"https://static.pepy.tech/personalized-badge/fullwave25?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=GREY\u0026right_color=BLUE\u0026left_text=PyPI+Downloads\" alt=\"PyPI Downloads\"\u003e\u003c/a\u003e\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/153Sx9D_5zTlF7UtlKHlyz_CTJnLIAI6s)\n\nFullwave 2.5 is a Python package for high-fidelity ultrasound wave propagation simulation with the following features:\n\n- State-of-the-art attenuation modelling capabilities for ultrasound wave propagation in complex biological tissues\n  - Heterogeneous power law attenuation ($\\alpha=\\alpha_0 f^\\gamma$) modeling, where **both the attenuation coefficient $\\alpha_0$ and exponent $\\gamma$ can vary** spatially.\n- High-performance simulation engine\n  - High accuracy staggered-grid finite-difference time-domain (FDTD) scheme (8th-order in space and 4th-order in time).\n  - 2D and 3D ultrasound wave propagation simulation.\n  - Multiple GPU execution support.\n- Easy-to-use Python interface with CUDA/C backend\n  - Python wrapper for easy usability and extensibility, with the core simulation engine implemented in CUDA/C for high performance on NVIDIA GPUs.\n  - It offers a user experience similar to [k-Wave](http://www.k-wave.org/) and [k-wave-python](https://github.com/waltsims/k-wave-python), while providing advanced attenuation modeling capabilities and multi-GPU support in FDTD simulations.\n\n| Computational medium                     | Wave propagation                                                           |\n| ---------------------------------------- | -------------------------------------------------------------------------- |\n| \u003cimg src=\"figs/medium.png\" width=\"600\"/\u003e | \u003cimg src=\"figs/linear_transducer_focused_abdominal_wall.gif\" width=\"200\"/\u003e |\n\nBuilding upon the original Fullwave 2 simulator, Fullwave 2.5 enhances its capabilities to model ultrasound wave propagation in media where **both the attenuation coefficient and exponent can vary spatially**. This enables more accurate simulations of biological tissues, which often exhibit complex attenuation behaviours that cannot be captured by uniform exponent models.\n\nThe library is designed with a Python wrapper for ease of use and extensibility, while the core simulation engine is implemented in CUDA/C to leverage high-performance computing on NVIDIA GPUs. Fullwave 2.5 supports 2D and 3D simulations, including multi-GPU execution for enhanced performance.\n\n## Special Thanks\n\nThis repository design was inspired by [k-wave-python](https://github.com/waltsims/k-wave-python). We appreciate the great work of the k-wave-python development team.\nThis repository would not have been possible without them.\n\nPlease check their repository for additional ultrasound simulation tools and resources.\nTheir comprehensive tools have significantly contributed to the ultrasound research community.\n\n## Theoretical Background\n\nFullwave 2.5 models multiple relaxation processes to approximate frequency-dependent power-law attenuation in heterogeneous media.\nIt solves the stretched-coordinate pressure-velocity formulation using a staggered-grid finite-difference schemes with 8th-order accuracy in space and 4th-order accuracy in time.\nThe formulation is expressed as follows:\n\n$$\\nabla_1 p + \\rho \\cfrac{\\partial {\\bf{v}}}{\\partial t} = 0$$\n$$\\nabla_2 \\cdot {\\bf{v}} + \\kappa \\cfrac{\\partial p}{\\partial t} = 0$$\n\nThe stretched-coordinate derivatives, denoted by $\\nabla_1$ and $\\nabla_2$, control frequency-dependent power-law attenuation and dispersion by selecting the optimal relaxation parameters.\n\nThe following figure illustrates the performance of the attenuation modeling in Fullwave 2.5.\nThe graph shows a comparison of the target power-law attenuation $\\alpha=\\alpha_0 f^\\gamma$ (red line) and the simulated attenuation (black dots) for various spatially varying attenuation coefficients ($\\alpha_0 =$ 0.25, 0.5, and 0.75) and exponents ($\\gamma =$ 0.4, 0.7, 1.0, 1.3, and 1.6).\n\n![attenuation modeling performance](./figs/attenuation_modeling.svg)\n\n## Citation\n\nFullwave 2.5 is developed and maintained by [Pinton Lab](https://github.com/pinton-lab) at the University of North Carolina at Chapel Hill.\n\nIf you use Fullwave 2.5 in your research, please cite this repository as:\n\n```bibtex\n@software{Sode2025-fullwave25,\n  author = {Sode, Masashi and Pinton, Gianmarco},\n  title = {{Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities}},\n  year = {2025},\n  month = oct,\n  doi = {10.5281/zenodo.17497689},\n  url = {https://github.com/pinton-lab/fullwave25},\n}\n\n@ARTICLE{Pinton2021-to,\n  title        = {A fullwave model of the nonlinear wave equation with multiple\n                  relaxations and relaxing perfectly matched layers for\n                  high-order numerical finite-difference solutions},\n  author       = {Pinton, Gianmarco},\n  journaltitle = {arXiv [physics.med-ph]},\n  date         = {2021-06-22},\n  eprint       = {2106.11476},\n  eprinttype   = {arXiv},\n  eprintclass  = {physics.med-ph},\n  url          = {http://arxiv.org/abs/2106.11476},\n}\n\n```\n\n---\n\n## Hardware prerequisites\n\n- This system operates in a Linux environment.\n  - If you need a Windows environment, please consider using [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux 2).\n- This simulation requires an NVIDIA GPU to execute.\n- You may need multiple GPUs for 3D simulation.\n\n## Technical recommendations\n\n- We recommend setting up an SSH key for GitHub, if you haven't done already. The repository changes over time to fix bugs and add new features. You can keep your local repository up to date by pulling the latest changes from GitHub. Cloning through SSH is more convenient than HTTPS in the long run.\n  - for ssh key generation\n    - please see: [Generating a new SSH key and adding it to the ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)\n  - for ssh key registration to your github account\n    - please see: [Adding a new SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)\n- after that, you can clone the repository through\n\n  ```sh\n  git clone git@github.com:pinton-lab/fullwave-python.git\n  ```\n\n## Technical references\n\n- If you are not familiar with the tools below, please refer to the provided links.\n  - VSCode\n    - [Official Visual Studio Code documentation](https://code.visualstudio.com/docs)\n    - [Visual Studio Code Tutorial for Beginners by Udacity](https://www.udacity.com/blog/2025/09/visual-studio-code-tutorial-for-beginners-productivity-tips-and-extensions.html)\n  - Git\n    - [Git Tutorial by GeeksForGeeks](https://www.geeksforgeeks.org/git/git-tutorial/)\n    - [Git Tutorial by W3 schools](https://www.w3schools.com/git/default.asp)\n    - [Using Git source control in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview)\n  - UV\n    - [Python UV: The Ultimate Guide to the Fastest Python Package Manager](https://www.datacamp.com/tutorial/python-uv)\n\n---\n\n## installation for users\n\n```sh\npip install fullwave25\n```\n\n## Troubleshooting\n\nIf `ffmpeg` is not installed on your system, please install it using the package manager of your Linux distribution.\n`ffmpeg` is used for video writing in plotting functions.\n\nplease see the installation guide below.\nreference: [FFmpeg Installation Guide](https://ffmpeg.org/download.html)\n\n```sh\n# for Ubuntu/Debian\nsudo apt install ffmpeg\n```\n\nAdditionally, if you encounter any issues related to `cv2` (OpenCV) during the installation, please install it separately using linux package manager or pip.\n\nplease see the installation guide below.\n`cv2` is used fro video writing in plotting functions.\n\nreference: [Installing OpenCV on Linux: A Comprehensive Guide](https://linuxvox.com/blog/install-opencv-linux/)\n\n```sh\n# using apt for Ubuntu/Debian\nsudo apt install python3-opencv\n\n# using pip\npip install opencv-python\n```\n\n## installation for development\n\nWe use [uv](https://docs.astral.sh/uv/) for package project and virtual environment management.\n\nIf uv is not installed, run below.\n\n```sh\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nRun below to install the development environment.\n\n```sh\ngit clone git@github.com:pinton-lab/fullwave25.git\ncd fullwave25\nmake install-all-extras # for running examples\n# or\nmake install # for the core library installation\n```\n\nTo test the installation, run\n\n```sh\nmake test\n```\n\n---\n\n## Tutorial: Basic Usage\n\nPlease start from [example_simple_plane_wave.ipynb](https://github.com/pinton-lab/fullwave25/blob/main/examples/simple_plane_wave/example_simple_plane_wave.ipynb).\n\nor try the Google Colab tutorial.\nYou don't need to install or set up a GPU environment on your local machine in order to run the simulation.\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/153Sx9D_5zTlF7UtlKHlyz_CTJnLIAI6s)\n\nHere are the main steps to run the Fullwave simulation\n\n1. Define the computational grid.\n2. Define the properties of the acoustic medium.\n3. Define the acoustic source.\n4. Define the sensor.\n5. Execute the simulation.\n\n## New simulation development instruction\n\n- after the [installation](#installation)\n- make a directory for your simulation under your favorite path.\n  - e.g. `examples/my_simulation/`\n- make a `.py` file or copy the example files below to use the boilerplate.\n  - 2D plane wave\n    - [examples/simple_plane_wave/simple_plane_wave_demo.py](https://github.com/pinton-lab/fullwave25/blob/main/examples/simple_plane_wave/simple_plane_wave.py)\n  - 3D plane wave\n    - [examples/wave_3d/simple_plane_wave_3d.py](https://github.com/pinton-lab/fullwave25/blob/main/examples/wave_3d/simple_plane_wave_3d.py)\n- after that follow [Usage 2D](#tutorial-basic-usage) to define the simulation code.\n\n## Tutorial: Advanced Usages\n\nPlease see the following examples for more advanced usage.\n\n- 2D plane wave\n  - Basic usage\n    - [Simple plane wave](https://github.com/pinton-lab/fullwave25/blob/main/examples/simple_plane_wave/simple_plane_wave.py) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/153Sx9D_5zTlF7UtlKHlyz_CTJnLIAI6s)\n      - \u003cimg src=\"figs/simple_plane_wave.gif\" width=\"200\"/\u003e\n    - [Simple plane wave with air](https://github.com/pinton-lab/fullwave25/blob/main/examples/simple_plane_wave/simple_plane_wave.py) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1AnTaT6ZtwyIEcOvGgpn5srB4LWPfYKh0)\n      \u003c!-- - \u003cimg src=\"figs/simple_plane_wave_with_air.gif\" width=\"200\"/\u003e --\u003e\n  - Linear transducer\n    - [Linear transducer](https://github.com/pinton-lab/fullwave25/blob/main/examples/linear_transducer/linear_transducer.py)\n    - [Linear transducer (plane wave transmit) with animation settings](https://github.com/pinton-lab/fullwave25/blob/main/examples/linear_transducer/linear_transducer_animation.py)\n      \u003c!-- - \u003cimg src=\"figs/linear_transducer.gif\" width=\"200\"/\u003e --\u003e\n    - [Linear transducer (focused transmit) with animation settings](https://github.com/pinton-lab/fullwave25/blob/main/examples/linear_transducer/linear_transducer_animation.py)\n      - \u003cimg src=\"figs/linear_transducer_focused.gif\" width=\"200\"/\u003e\n    - [Linear transducer (focused transmit) with abdominal wall](https://github.com/pinton-lab/fullwave25/blob/main/examples/linear_transducer/linear_transducer.py) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1zlviYe0qBy0JLifFuA2MqUkavJKUQrNb)\n      - \u003cimg src=\"figs/linear_transducer_focused_abdominal_wall.gif\" width=\"200\"/\u003e\n    - linear transducer plane wave compounding\n      - [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1LXlkpYhIfQtaPhNDJ1vONTDSdiLBhkEP)\n    - linear transducer full synthetic aperture\n      - [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1_jVULK2mglOx8__gWYHGhNVxYLhAGNF5)\n  - Convex transducer\n    - [Convex transducer with abdominal wall](https://github.com/pinton-lab/fullwave25/blob/main/examples/convex_transducer/convex_transducer_abdominal_wall.py)\n      - \u003cimg src=\"figs/convex_transducer_abdominal_wall.gif\" width=\"200\"/\u003e\n- 3D plane wave\n  - Basic usage\n    - [Simple plane wave in 3D](https://github.com/pinton-lab/fullwave25/blob/main/examples/wave_3d/simple_plane_wave_3d.py)\n      \u003ctable\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" colspan=\"2\"\u003eComputational medium\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" colspan=\"2\"\u003e\u003cimg src=\"figs/medium_3d.png\" width=\"600\"/\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" \u003ex-y slice propagation\u003c/td\u003e\n          \u003ctd style=\"text-align: center;\" \u003ex-z slice propagation\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" \u003e\u003cimg src=\"figs/wave_propagation_x-y.gif\" width=\"300\"/\u003e\u003c/td\u003e\n          \u003ctd style=\"text-align: center;\" \u003e\u003cimg src=\"figs/wave_propagation_x-z.gif\" width=\"300\"/\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n      \u003c/table\u003e\n    - [Simple plane wave in 3D with air inclusion](https://github.com/pinton-lab/fullwave25/blob/main/examples/wave_3d/simple_plane_wave_3d_with_air.py)\n      \u003ctable\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\"  colspan=\"2\"\u003eComputational medium with air inclusion\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\"  colspan=\"2\"\u003e\u003cimg src=\"figs/medium_3d_air.png\" width=\"600\"/\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" \u003ex-y slice propagation\u003c/td\u003e\n          \u003ctd style=\"text-align: center;\" \u003ex-z slice propagation\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd style=\"text-align: center;\" \u003e\u003cimg src=\"figs/wave_propagation_x-y_air.gif\" width=\"300\"/\u003e\u003c/td\u003e\n          \u003ctd style=\"text-align: center;\" \u003e\u003cimg src=\"figs/wave_propagation_x-z_air.gif\" width=\"300\"/\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n      \u003c/table\u003e\n\n- Medium builder usage\n  - Medium builder is a utility to create computational medium from simple geometric operations. This is especially useful when you want to create complex heterogeneous media.\n  - [simple medium builder usage](https://github.com/pinton-lab/fullwave25/blob/main/examples/medium_builder/medium_builder_example.py) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/169aHbXRt_-aXFEdf2pfPkwH4-niJvrfL)\n  - [simple medium builder usage with abdominal wall](https://github.com/pinton-lab/fullwave25/blob/main/examples/medium_builder/medium_builder_abdominal_example.py)\n  - [medium builder in 3D](https://github.com/pinton-lab/fullwave25/blob/main/examples/medium_builder/medium_builder_example_3d.py)\n\n---\n\n## Attention\n\n- The simulation grid is defined as follows:\n  - (x, y, z) = (depth, lateral, elevational).\n    - This order is due to the efficiency of the multiple-GPU execution.\n    - Multi-GPU domain decomposition is processed in the depth dimension.\n  - The index of the input coordinates (i.e. the acoustic source location) is defined in C-array order (i.e. row-major) within the simulation, regardless of your setup. This is to improve the efficiency of multi-GPU development.\n  - This might be confusing, so please be careful when you define the source and source signal definition.\n- GPU memory requirement\n  - A 3D simulation requires a lot of GPU memory.\n    - Please reduce the grid size or use multiple GPUs if you run out of memory.\n    - You can check GPU memory usage with the 'nvidia-smi' or 'nvtop' commands.\n- Multi-GPU execution\n  - The current implementation supports multiple GPU execution in 2D and 3D simulations.\n  - Our implementation demonstrates linear performance scaling with the number of GPUs.\n- Before 3D simulation:\n  - If you want to run a 3D simulation, it is recommended that you start with a 2D simulation first to understand the basic usage.\n  - The 3D simulation code is similar to the 2D code, but some plot functions are unavailable in 3D.\n  - The 3D simulation takes longer to run, so starting with 2D will help you debug your code faster.\n\n## Note for developers\n\n- Contributions are welcome!\n- When developing something new, please create a new branch such as `TYPE/BRANCH_NAME`.\n  - TYPE can be `feature`, `bugfix`, `hotfix`, `docs`, `refactor`, `release`, `test`, or `experiment`.\n  - `BRANCH_NAME` should be descriptive of the feature or fix you are working on.\n  - see also: [GitHub Branching Name Best Practices](https://dev.to/jps27cse/github-branching-name-best-practices-49ei)\n- Please write clear and concise commit messages.\n- please see [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n---\n\n## Authors\n\n- Masashi Sode (GitHub: [MasashiSode](https://github.com/MasashiSode))\n- Gianmarco Pinton (GitHub: [gfpinton](https://github.com/gfpinton))\n\n## Maintainers\n\n- Masashi Sode (GitHub: [MasashiSode](https://github.com/MasashiSode))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinton-lab%2Ffullwave25","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinton-lab%2Ffullwave25","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinton-lab%2Ffullwave25/lists"}